agents.document_modifiers.kg.kg_iterative_refinement.agent

Iterative Knowledge Graph Transformer Agent.

This module provides the IterativeGraphTransformer class which builds knowledge graphs iteratively from a sequence of documents. It processes documents one by one, starting with an initial graph and refining it with each subsequent document.

The agent is particularly useful for building comprehensive knowledge graphs from multiple related documents where later documents may add detail or context to earlier information.

Classes:

IterativeGraphTransformer: Main agent for iterative knowledge graph construction

Examples

Basic usage:

from haive.agents.document_modifiers.kg.kg_iterative_refinement import IterativeGraphTransformer
from haive.agents.document_modifiers.kg.kg_iterative_refinement.config import IterativeGraphTransformerConfig

config = IterativeGraphTransformerConfig()
agent = IterativeGraphTransformer(config)

documents = [
    "Marie Curie was a physicist born in Poland.",
    "She won two Nobel Prizes in different fields.",
    "Her daughter Irène also won a Nobel Prize."
]
result = agent.run({"contents": documents})
graph = result["graph_doc"]

With custom configuration:

config = IterativeGraphTransformerConfig(
    name="research_graph_builder",
    engines={"transformer": custom_llm_config}
)
agent = IterativeGraphTransformer(config)

See also

  • IterativeGraphTransformerConfig: Configuration class

  • IterativeGraphTransformerState: State management

Classes

IterativeGraphTransformer

Agent that builds knowledge graphs iteratively from documents.

Functions

build_agent()

Create a default IterativeGraphTransformer instance.

Module Contents

class agents.document_modifiers.kg.kg_iterative_refinement.agent.IterativeGraphTransformer(config=IterativeGraphTransformerConfig())

Bases: haive.core.engine.agent.agent.Agent[haive.agents.document_modifiers.kg.kg_iterative_refinement.config.IterativeGraphTransformerConfig]

Agent that builds knowledge graphs iteratively from documents.

This agent processes a sequence of documents to build a comprehensive knowledge graph. It starts by creating an initial graph from the first document, then iteratively refines and expands the graph with information from subsequent documents.

The iterative approach allows the agent to: 1. Build context progressively 2. Resolve entity references across documents 3. Accumulate relationships and properties 4. Maintain graph coherence throughout the process

Parameters:

config (haive.agents.document_modifiers.kg.kg_iterative_refinement.config.IterativeGraphTransformerConfig) – Configuration object containing agent settings and LLM configuration for the graph transformer.

llm_graph_transformer

The underlying GraphTransformer instance used to convert documents to graph representations.

Examples

Processing a series of related documents:

agent = IterativeGraphTransformer()
docs = [
    "Einstein developed the theory of relativity.",
    "The theory of relativity revolutionized physics.",
    "Einstein received the Nobel Prize in 1921."
]
result = agent.run({"contents": docs})

# Access the final knowledge graph
graph = result["graph_doc"]
nodes = graph.nodes  # List of entities
relationships = graph.relationships  # List of connections

With strict mode for validation:

config = IterativeGraphTransformerConfig(
    strict_mode=True,  # Enforce schema validation
    ignore_tool_usage=False  # Allow tool-based extraction
)
agent = IterativeGraphTransformer(config)

Note

The agent processes documents sequentially, so document order can affect the final graph structure. Consider ordering documents from general to specific for best results.

Raises:

  • ValueError – If no documents are provided for processing

  • TypeError – If document content is not in a supported format

Parameters:

config (haive.agents.document_modifiers.kg.kg_iterative_refinement.config.IterativeGraphTransformerConfig)

See also

Initialize the iterative graph transformer.

Sets up the graph transformer instance that will be used to process documents into knowledge graph representations.

Parameters:

config (haive.agents.document_modifiers.kg.kg_iterative_refinement.config.IterativeGraphTransformerConfig) – Agent configuration with transformer settings. Defaults to a new instance with default values.

generate_initial_summary(state, config)

Generate the initial knowledge graph from the first document.

Creates the foundational graph structure from the first document in the sequence. This graph will be iteratively refined with subsequent documents.

Parameters:

  • state (haive.agents.document_modifiers.kg.kg_iterative_refinement.state.IterativeGraphTransformerState) – Current state containing the list of documents to process. Must have at least one document in the ‘contents’ field.

  • config (langchain_core.runnables.RunnableConfig) – Runtime configuration for the operation.

Returns:

Command updating the state with the initial graph_doc and incrementing the index to 1.

Return type:

langgraph.types.Command

Note

The state normalizes various input formats (str, dict, Document) to Document objects before processing.

refine_summary(state, config)

Refine the knowledge graph with information from the next document.

Takes the existing graph and integrates new information from the current document. The refinement process preserves existing knowledge while adding new entities, relationships, and properties.

Parameters:

  • state (haive.agents.document_modifiers.kg.kg_iterative_refinement.state.IterativeGraphTransformerState) – Current state containing the existing graph and remaining documents. Must have a valid index pointing to the next document.

  • config (langchain_core.runnables.RunnableConfig) – Runtime configuration for the operation.

Returns:

Command updating the state with the refined graph_doc and incrementing the index.

Raises:

  • IndexError – If the index is out of bounds for the contents list.

  • TypeError – If the content at the current index is not a valid type.

Return type:

langgraph.types.Command

setup_workflow()

Set up the iterative graph building workflow.

Constructs a StateGraph that implements the following workflow: 1. Generate initial graph from the first document 2. Iteratively refine the graph with each subsequent document 3. Continue until all documents have been processed

The workflow uses conditional edges to determine when to stop refining based on the number of documents processed.

Note

This method is called automatically during agent initialization and does not need to be invoked manually.

Return type:

None

agents.document_modifiers.kg.kg_iterative_refinement.agent.build_agent()

Create a default IterativeGraphTransformer instance.

Returns:

IterativeGraphTransformer with default configuration.

Return type:

IterativeGraphTransformer