agentic-graphrag 0.0.2__tar.gz → 0.0.4__tar.gz

{agentic_graphrag-0.0.2 → agentic_graphrag-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-graphrag
-Version: 0.0.2
+Version: 0.0.4
 Summary: Agentic GraphRAG: graph-based retrieval-augmented generation with agentic reasoning.
 Keywords: graphrag,rag,knowledge-graph,agents,retrieval
 Author: Ashwin Mathur, Varun Mathur
@@ -14,25 +14,38 @@ Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: chonkie>=1.7
 Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: openinference-semantic-conventions
 Requires-Dist: charset-normalizer>=3.4
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: selectolax>=0.3.21
 Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: scipy>=1.14
 Requires-Dist: langgraph>=1.2 ; extra == 'agents'
-Requires-Dist: deepagents>=0.7 ; extra == 'agents'
+Requires-Dist: deepagents>=0.7.15 ; extra == 'agents'
 Requires-Dist: langchain-openai>=1.0 ; extra == 'agents'
+Requires-Dist: chonkie[code]>=1.7 ; extra == 'chunk-code'
+Requires-Dist: chonkie[neural]>=1.7 ; extra == 'chunk-neural'
+Requires-Dist: chonkie[semantic]>=1.7 ; extra == 'chunk-semantic'
+Requires-Dist: graspologic-native>=1.2.5 ; extra == 'community'
 Requires-Dist: docling>=2.0 ; extra == 'docling'
 Requires-Dist: sentence-transformers>=5 ; extra == 'embed-local'
+Requires-Dist: deepeval>=4.2.6 ; extra == 'eval'
+Requires-Dist: agentevals>=0.0.9 ; extra == 'eval'
+Requires-Dist: er-evaluation>=2.3.0 ; extra == 'eval'
+Requires-Dist: scikit-learn>=1.5 ; extra == 'eval'
+Requires-Dist: langchain-openai>=1.0 ; extra == 'eval'
+Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'eval'
+Requires-Dist: openinference-instrumentation-langchain>=0.1.76,<0.2 ; extra == 'eval'
 Requires-Dist: gliner2[local] ; extra == 'extract'
 Requires-Dist: transformers<4.56 ; extra == 'extract'
 Requires-Dist: protobuf ; extra == 'extract'
 Requires-Dist: baml-py>=0.226.1,<0.227 ; extra == 'llm'
-Requires-Dist: pymilvus>=2.5.3 ; extra == 'milvus'
-Requires-Dist: neo4j>=5.0 ; extra == 'neo4j'
+Requires-Dist: pymilvus>=3.0.0,<4 ; extra == 'milvus'
+Requires-Dist: neo4j>=5.22 ; extra == 'neo4j'
 Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'observability'
 Requires-Dist: opentelemetry-exporter-otlp>=1.20 ; extra == 'observability'
 Requires-Dist: opentelemetry-instrumentation-asyncio ; extra == 'observability'
-Requires-Dist: openinference-semantic-conventions ; extra == 'observability'
+Requires-Dist: openinference-instrumentation-langchain>=0.1.76,<0.2 ; extra == 'observability'
 Requires-Dist: qdrant-client>=1.12 ; extra == 'qdrant'
 Requires-Dist: fastembed>=0.4 ; extra == 'qdrant'
 Requires-Dist: weaviate-client>=4.9 ; extra == 'weaviate'
@@ -43,8 +56,13 @@ Project-URL: Documentation, https://ontogr.github.io/agentic-graphrag/
 Project-URL: Issues, https://github.com/ontogr/agentic-graphrag/issues
 Project-URL: Source, https://github.com/ontogr/agentic-graphrag
 Provides-Extra: agents
+Provides-Extra: chunk-code
+Provides-Extra: chunk-neural
+Provides-Extra: chunk-semantic
+Provides-Extra: community
 Provides-Extra: docling
 Provides-Extra: embed-local
+Provides-Extra: eval
 Provides-Extra: extract
 Provides-Extra: llm
 Provides-Extra: milvus
@@ -71,7 +89,7 @@ Description-Content-Type: text/markdown
 
 </div>
 
-Agentic GraphRAG is a modular, schema-driven system for building knowledge graphs from unstructured and structured data, retrieving evidence across graph and vector indexes, and answering questions with agentic reasoning.
+Agentic GraphRAG is a modular, schema-driven system. It builds knowledge graphs from unstructured and structured data. It retrieves evidence across graph and vector indexes. It answers questions with agentic reasoning.
 
 <p align="center">
   <img src="img/agentic_graphrag_pipeline.png" alt="Agentic GraphRAG pipeline from data loading through graph construction, storage, retrieval, and agentic reasoning" width="1200">
@@ -123,7 +141,7 @@ Documents keep their source URI, format, loader, content hash, and record identi
 
 Extraction produces mentions first, not graph nodes. Each mention keeps its source chunk, label, text span, confidence, and extractor provenance. Resolution then assigns canonical identities and merges aliases before storage.
 
-Relations are directed subject–predicate–object triples. The active schema constrains valid source type, relation type, and target type combinations, so invalid triples are removed before they reach the graph.
+Relations are directed subject–predicate–object triples. The active schema constrains valid source type, relation type, and target type combinations. The validation stage removes invalid triples before they reach the graph.
 
 ### Communities
 
@@ -153,12 +171,12 @@ Query:     question -> plan -> parallel retrieval -> verify -> cited answer
 
 `Graph.add()` is the single entry point for adding content. The complete pipeline is organized into these stages:
 
-1. **Load:** Select a loader by format, decode or parse the source, preserve source metadata, and apply `RAISE`, `SKIP`, or `QUARANTINE` per-source error handling.
+1. **Load:** Select a loader by format. Decode or parse the source. Preserve source metadata. Apply `RAISE`, `SKIP`, or `QUARANTINE` as the error policy for each source.
 2. **Chunk:** Use Docling's layout-aware chunking before flattening rich documents; use Chonkie for text and record documents.
 3. **Extract:** Run GLiNER locally against the active schema. Escalate weak results to a typed BAML extraction function when configured.
 4. **Validate:** Drop entities and triples that do not conform to the schema.
 5. **Resolve:** Apply exact, fuzzy, embedding, and LLM-verified comparison tiers. Ambiguous or failed comparisons do not merge.
-6. **Merge:** Resolve properties field by field, combine provenance, deduplicate repointed relations, and retain an audit trail.
+6. **Merge:** Resolve properties field by field. Combine provenance. Deduplicate repointed relations. Retain an audit trail.
 7. **Store:** Upsert canonical nodes and relations, then populate graph-native or dedicated vector indexes.
 
 The extraction cascade replaces a weak local result with the LLM result instead of combining two conflicting outputs. Exact matches use global store-backed lookup; more expensive fuzzy and LLM comparisons are blocked to a smaller candidate set.
@@ -178,7 +196,7 @@ The async `Embedder`, `GraphStore`, and `VectorStore` interfaces keep model and
 
 ### Graph storage
 
-The Neo4j backend supports local Neo4j and Aura over Bolt, managed read/write transactions, node and relation upserts, constraints, indexes, and native dense vector search. Dynamic labels and relation types are validated before Cypher interpolation.
+The Neo4j backend supports local Neo4j and Aura over Bolt, managed read/write transactions, node and relation upserts, constraints, indexes, and native dense vector search. The query builders validate dynamic labels and relation types before they interpolate them into Cypher.
 
 ### Vector storage
 
@@ -251,6 +269,9 @@ uv pip install "agentic-graphrag[llm,embed-local]"
 
 # Neo4j with a dedicated Qdrant vector store and OTLP tracing
 uv pip install "agentic-graphrag[neo4j,qdrant,observability]"
+
+# Hierarchical community detection
+uv pip install "agentic-graphrag[community]"
 ```
 
 | Extra | Adds |
@@ -264,6 +285,7 @@ uv pip install "agentic-graphrag[neo4j,qdrant,observability]"
 | `weaviate` | Weaviate dense and hybrid search |
 | `milvus` | Milvus/Zilliz dense and hybrid search |
 | `observability` | OpenTelemetry SDK and OTLP export |
+| `community` | Hierarchical Leiden community detection |
 
 ## Usage
 
@@ -278,11 +300,14 @@ from agrag.ingestion import Graph
 async def main() -> None:
     graph = await Graph.open()
 
-    files = await graph.add(source="./corpus/**/*.md")
-    text = await graph.add(text="Agentic GraphRAG turns evidence into a graph.")
+    files = await graph.add(source="./corpus/**/*.md", return_chunks=True)
+    text = await graph.add(
+        text="Agentic GraphRAG turns evidence into a graph.",
+        return_chunks=True,
+    )
 
-    print(files.documents, len(files.chunks))
-    print(text.documents, len(text.chunks))
+    print(files.ingestion.documents, len(files.chunks))
+    print(text.ingestion.documents, len(text.chunks))
 
 
 asyncio.run(main())
@@ -304,8 +329,8 @@ result = await graph.add(
     error_policy=ErrorPolicy.QUARANTINE,
 )
 
-for uri, reason in result.quarantined_items:
-    print(uri, reason)
+for item in result.ingestion.quarantined_items:
+    print(item.item_id, item.error_message)
 ```
 
 See the [documentation](https://ontogr.github.io/agentic-graphrag/) for guides and the generated API reference.

{agentic_graphrag-0.0.2 → agentic_graphrag-0.0.4}/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-Agentic GraphRAG is a modular, schema-driven system for building knowledge graphs from unstructured and structured data, retrieving evidence across graph and vector indexes, and answering questions with agentic reasoning.
+Agentic GraphRAG is a modular, schema-driven system. It builds knowledge graphs from unstructured and structured data. It retrieves evidence across graph and vector indexes. It answers questions with agentic reasoning.
 
 <p align="center">
   <img src="img/agentic_graphrag_pipeline.png" alt="Agentic GraphRAG pipeline from data loading through graph construction, storage, retrieval, and agentic reasoning" width="1200">
@@ -67,7 +67,7 @@ Documents keep their source URI, format, loader, content hash, and record identi
 
 Extraction produces mentions first, not graph nodes. Each mention keeps its source chunk, label, text span, confidence, and extractor provenance. Resolution then assigns canonical identities and merges aliases before storage.
 
-Relations are directed subject–predicate–object triples. The active schema constrains valid source type, relation type, and target type combinations, so invalid triples are removed before they reach the graph.
+Relations are directed subject–predicate–object triples. The active schema constrains valid source type, relation type, and target type combinations. The validation stage removes invalid triples before they reach the graph.
 
 ### Communities
 
@@ -97,12 +97,12 @@ Query:     question -> plan -> parallel retrieval -> verify -> cited answer
 
 `Graph.add()` is the single entry point for adding content. The complete pipeline is organized into these stages:
 
-1. **Load:** Select a loader by format, decode or parse the source, preserve source metadata, and apply `RAISE`, `SKIP`, or `QUARANTINE` per-source error handling.
+1. **Load:** Select a loader by format. Decode or parse the source. Preserve source metadata. Apply `RAISE`, `SKIP`, or `QUARANTINE` as the error policy for each source.
 2. **Chunk:** Use Docling's layout-aware chunking before flattening rich documents; use Chonkie for text and record documents.
 3. **Extract:** Run GLiNER locally against the active schema. Escalate weak results to a typed BAML extraction function when configured.
 4. **Validate:** Drop entities and triples that do not conform to the schema.
 5. **Resolve:** Apply exact, fuzzy, embedding, and LLM-verified comparison tiers. Ambiguous or failed comparisons do not merge.
-6. **Merge:** Resolve properties field by field, combine provenance, deduplicate repointed relations, and retain an audit trail.
+6. **Merge:** Resolve properties field by field. Combine provenance. Deduplicate repointed relations. Retain an audit trail.
 7. **Store:** Upsert canonical nodes and relations, then populate graph-native or dedicated vector indexes.
 
 The extraction cascade replaces a weak local result with the LLM result instead of combining two conflicting outputs. Exact matches use global store-backed lookup; more expensive fuzzy and LLM comparisons are blocked to a smaller candidate set.
@@ -122,7 +122,7 @@ The async `Embedder`, `GraphStore`, and `VectorStore` interfaces keep model and
 
 ### Graph storage
 
-The Neo4j backend supports local Neo4j and Aura over Bolt, managed read/write transactions, node and relation upserts, constraints, indexes, and native dense vector search. Dynamic labels and relation types are validated before Cypher interpolation.
+The Neo4j backend supports local Neo4j and Aura over Bolt, managed read/write transactions, node and relation upserts, constraints, indexes, and native dense vector search. The query builders validate dynamic labels and relation types before they interpolate them into Cypher.
 
 ### Vector storage
 
@@ -195,6 +195,9 @@ uv pip install "agentic-graphrag[llm,embed-local]"
 
 # Neo4j with a dedicated Qdrant vector store and OTLP tracing
 uv pip install "agentic-graphrag[neo4j,qdrant,observability]"
+
+# Hierarchical community detection
+uv pip install "agentic-graphrag[community]"
 ```
 
 | Extra | Adds |
@@ -208,6 +211,7 @@ uv pip install "agentic-graphrag[neo4j,qdrant,observability]"
 | `weaviate` | Weaviate dense and hybrid search |
 | `milvus` | Milvus/Zilliz dense and hybrid search |
 | `observability` | OpenTelemetry SDK and OTLP export |
+| `community` | Hierarchical Leiden community detection |
 
 ## Usage
 
@@ -222,11 +226,14 @@ from agrag.ingestion import Graph
 async def main() -> None:
     graph = await Graph.open()
 
-    files = await graph.add(source="./corpus/**/*.md")
-    text = await graph.add(text="Agentic GraphRAG turns evidence into a graph.")
+    files = await graph.add(source="./corpus/**/*.md", return_chunks=True)
+    text = await graph.add(
+        text="Agentic GraphRAG turns evidence into a graph.",
+        return_chunks=True,
+    )
 
-    print(files.documents, len(files.chunks))
-    print(text.documents, len(text.chunks))
+    print(files.ingestion.documents, len(files.chunks))
+    print(text.ingestion.documents, len(text.chunks))
 
 
 asyncio.run(main())
@@ -248,8 +255,8 @@ result = await graph.add(
     error_policy=ErrorPolicy.QUARANTINE,
 )
 
-for uri, reason in result.quarantined_items:
-    print(uri, reason)
+for item in result.ingestion.quarantined_items:
+    print(item.item_id, item.error_message)
 ```
 
 See the [documentation](https://ontogr.github.io/agentic-graphrag/) for guides and the generated API reference.

agentic_graphrag-0.0.4/agrag/agents/__init__.py

@@ -0,0 +1,19 @@
+"""Agentic layer: planner/researcher/verifier over SearchEngine.
+
+``build_agent`` lives in ``agrag.agents.build`` and is not re-exported here: it needs
+the ``agents`` extra to import, and this package must import on a base install.
+"""
+
+from agrag.agents.errors import AgentMissingExtraError
+from agrag.agents.ledger import Ledger
+from agrag.agents.result import AgentRunResult
+from agrag.agents.settings import AgentLLMSettings, AgentSettings
+
+
+__all__ = [
+    "AgentLLMSettings",
+    "AgentMissingExtraError",
+    "AgentRunResult",
+    "AgentSettings",
+    "Ledger",
+]

agentic_graphrag-0.0.4/agrag/agents/build.py

@@ -0,0 +1,276 @@
+"""Build the planner/researcher/verifier agent graph."""
+
+import importlib.util
+from contextlib import nullcontext
+from typing import Any
+
+from opentelemetry.trace import Tracer
+
+from agrag.agents.harness import ensure_harness_profile, model_provider_key
+from agrag.agents.ledger import Ledger
+from agrag.agents.middleware import ResearchAttemptLimiter, VerifierEvidenceMiddleware
+from agrag.agents.model import build_chat_model, build_model_middleware
+from agrag.agents.prompts import PLANNER_SYSTEM, SIMPLE_ANSWER_SYSTEM
+from agrag.agents.result import AgentRunResult
+from agrag.agents.settings import AgentLLMSettings, AgentSettings
+from agrag.agents.subagents import make_researcher_spec, make_verifier_spec
+from agrag.agents.tools import make_tools
+from agrag.agents.tracing import require_tracing, run_callbacks
+from agrag.common.data_models.graph_schema import GraphSchema
+from agrag.retrieval.filters import SearchFilters
+from agrag.retrieval.search_engine import SearchEngine
+
+
+def build_agent(
+    *,
+    engine: SearchEngine,
+    llm_settings: AgentLLMSettings,
+    agent_settings: AgentSettings | None = None,
+    filters: SearchFilters | None = None,
+    graph_schema: GraphSchema | None = None,
+    tracer: Tracer | None = None,
+) -> Any:
+    """Build the planner/researcher/verifier agent graph.
+
+    Constructs a LangGraph-based agent with three roles:
+    planner (decomposes the question), researcher (has tools),
+    and verifier (judges evidence sufficiency and returns a
+    structured verdict).
+
+    Each call to ``ainvoke`` creates a fresh ``Ledger`` so
+    citation numbering, identity mappings, and retrieved evidence
+    do not leak across runs, and a fresh ``ResearchAttemptLimiter``
+    so one question's retry budget does not spend another's.
+
+    Args:
+        engine: Retrieval to expose to the researcher subagent's
+            tools.
+        llm_settings: The model every subagent role calls, via
+            build_chat_model. With several clients, the remaining
+            ones compose per strategy through agent middleware.
+        agent_settings: Loop-level configuration; defaults from
+            environment. The recursion limit is enforced as the
+            LangGraph ``recursion_limit`` in the invoke config, and
+            ``max_research_attempts`` bounds how many times the
+            planner may re-research after an INSUFFICIENT verdict.
+        filters: Retrieval scope applied to every tool search,
+            e.g. document or tenant constraints. None searches
+            unfiltered. A non-empty scope also removes the
+            ``query_graph_directly`` tool, since a generated query
+            cannot be confined to a scope.
+        graph_schema: The schema the researcher prompt and the
+            ``query_graph_directly`` tool describe. None uses the
+            engine's own resolved schema; a value that differs from
+            the engine's raises, so the prompt cannot describe a
+            graph the engine does not search.
+        tracer: Receives OpenInference spans for every ``ainvoke``,
+            including the researcher and verifier subagents' tool and
+            model calls. None emits no spans. Spans carry the question,
+            tool inputs, and evidence text.
+
+    Returns:
+        An agent whose ``ainvoke`` returns an ``AgentRunResult``: the
+        run's ``messages`` plus its ``ledger``, which maps each
+        citation key in the answer back to its evidence. When
+        deepagents is not installed, a single-search-plus-synthesis
+        fallback with the same result shape.
+
+    Raises:
+        AgentMissingExtraError: ``tracer`` is set but the ``observability``
+            extra is not installed.
+        ValueError: ``graph_schema`` differs from the engine's schema.
+    """
+    if tracer is not None:
+        require_tracing()
+    settings = agent_settings or AgentSettings()
+    model = build_chat_model(llm_settings.clients[0])
+    middleware = build_model_middleware(
+        llm_settings.clients, strategy=llm_settings.strategy
+    )
+    schema = engine.graph_schema
+    if graph_schema is not None and graph_schema != schema:
+        raise ValueError(
+            "graph_schema does not match the engine's schema "
+            f"('{schema.name}'); the researcher prompt and the engine "
+            "must describe the same graph"
+        )
+
+    if importlib.util.find_spec("deepagents") is not None:
+        return _RunScopedAgent(
+            engine=engine,
+            model=model,
+            settings=settings,
+            middleware=middleware,
+            filters=filters,
+            graph_schema=schema,
+            model_provider=model_provider_key(llm_settings.clients[0].provider),
+            tracer=tracer,
+        )
+
+    # Fallback: a simple wrapper when deepagents is not installed,
+    # useful for unit testing without the full extra. If deepagents
+    # is present but broken, ainvoke raises its import error at call
+    # time instead of silently degrading here.
+    return _SimpleAgent(model=model, engine=engine, filters=filters, tracer=tracer)
+
+
+class _RunScopedAgent:
+    """Builds the deepagents graph fresh per run.
+
+    Each ``ainvoke`` call constructs the graph with a new
+    ``Ledger``, a new tool set, and a new
+    ``ResearchAttemptLimiter`` so citation state and the retry
+    budget do not span runs, and enforces the configured LangGraph
+    recursion limit.
+    """
+
+    def __init__(
+        self,
+        *,
+        engine: SearchEngine,
+        model: Any,
+        settings: AgentSettings,
+        middleware: list[Any] | None = None,
+        filters: SearchFilters | None = None,
+        graph_schema: GraphSchema | None = None,
+        model_provider: str = "",
+        tracer: Tracer | None = None,
+    ) -> None:
+        """Construct the wrapper."""
+        self._engine = engine
+        self._model = model
+        self._settings = settings
+        self._middleware = middleware or []
+        self._filters = filters
+        self._graph_schema = (
+            graph_schema if graph_schema is not None else engine.graph_schema
+        )
+        self._model_provider = model_provider
+        self._tracer = tracer
+
+    async def ainvoke(self, input_data: dict) -> AgentRunResult:
+        """Delegate to inner agent with a fresh Ledger and limiter.
+
+        Builds the planner with the researcher and verifier as
+        subagents. The planner sees the task tool for delegation and
+        carries the attempt limiter; the researcher carries the
+        caller's tools and the engine's schema summary; the verifier
+        returns a structured verdict.
+
+        Args:
+            input_data: Dict with ``messages`` key.
+
+        Returns:
+            The graph's final state with this run's ``ledger`` added.
+        """
+        from deepagents import create_deep_agent  # noqa: PLC0415
+
+        ensure_harness_profile(self._model_provider)
+        ledger = Ledger()
+        tools = make_tools(self._engine, ledger, filters=self._filters)
+        researcher = make_researcher_spec(tools, self._middleware, self._graph_schema)
+        verifier = make_verifier_spec(self._middleware)
+        limiter = ResearchAttemptLimiter(self._settings.max_research_attempts)
+        planner_system = PLANNER_SYSTEM.replace(
+            "{max_research_attempts}", str(self._settings.max_research_attempts)
+        )
+
+        # Annotated, not typed against deepagents' own SubAgent: importing
+        # that type here would make this module require the optional
+        # dependency at import time. The specs are SubAgent-shaped dicts.
+        subagents: list[Any] = [researcher, verifier]
+        agent = create_deep_agent(
+            model=self._model,
+            system_prompt=planner_system,
+            subagents=subagents,
+            middleware=[*self._middleware, limiter, VerifierEvidenceMiddleware(ledger)],
+        )
+        result = await agent.ainvoke(
+            input_data,
+            config={
+                "recursion_limit": self._settings.recursion_limit,
+                "callbacks": run_callbacks(self._tracer),
+            },
+        )
+        return {**result, "ledger": ledger}
+
+
+class _SimpleAgent:
+    """Fallback agent when deepagents is not installed.
+
+    Performs a single hybrid search per invocation, then one LLM
+    call to synthesize a cited answer from the results -- still no
+    agent loop, tool calls, or multi-client composition
+    (``build_model_middleware``'s fallback/round-robin strategies
+    wrap ``create_deep_agent``'s loop, not a bare model call, and
+    this class already only receives ``clients[0]``). There is no
+    agent loop, so ``AgentSettings.recursion_limit`` does not apply.
+    """
+
+    def __init__(
+        self,
+        *,
+        model: Any,
+        engine: SearchEngine,
+        filters: SearchFilters | None = None,
+        tracer: Tracer | None = None,
+    ) -> None:
+        """Construct a simple agent wrapper."""
+        self._model = model
+        self._engine = engine
+        self._filters = filters
+        self._tracer = tracer
+
+    async def ainvoke(self, input_data: dict) -> AgentRunResult:
+        """Run the agent with a fresh ledger (simplified path).
+
+        Creates a new ``Ledger`` and tool set per invocation so
+        citation state does not span runs. Runs one search, then one
+        LLM call to synthesize a cited answer from the results.
+
+        Args:
+            input_data: Dict with ``messages`` key.
+
+        Returns:
+            Dict with ``messages`` containing the answer and this run's
+            ``ledger``.
+        """
+        span_context = (
+            self._tracer.start_as_current_span("agrag.agents.run")
+            if self._tracer is not None
+            else nullcontext()
+        )
+        with span_context:
+            ledger = Ledger()
+            messages = input_data.get("messages", [])
+            if not messages:
+                return {"messages": [], "ledger": ledger}
+
+            question = messages[-1].get("content", "")
+            from agrag.retrieval.recipes import HYBRID  # noqa: PLC0415
+
+            results = await self._engine.search(question, HYBRID, filters=self._filters)
+            evidence = [ledger.render(r) for r in results]
+            if not evidence:
+                return {
+                    "messages": [
+                        {"role": "assistant", "content": "No relevant evidence found."}
+                    ],
+                    "ledger": ledger,
+                }
+
+            response = await self._model.ainvoke(
+                [
+                    {"role": "system", "content": SIMPLE_ANSWER_SYSTEM},
+                    {
+                        "role": "user",
+                        "content": f"Question: {question}\n\nEvidence:\n"
+                        + "\n".join(evidence),
+                    },
+                ],
+                config={"callbacks": run_callbacks(self._tracer)},
+            )
+            return {
+                "messages": [{"role": "assistant", "content": response.text}],
+                "ledger": ledger,
+            }

agentic_graphrag-0.0.4/agrag/agents/errors.py

@@ -0,0 +1,16 @@
+"""Errors raised by the agent layer."""
+
+
+class AgentMissingExtraError(Exception):
+    """Agent tracing needs a package extra that is not installed.
+
+    Attributes:
+        extra: The name of the package extra to install.
+    """
+
+    def __init__(self, extra: str) -> None:
+        """Bind the missing package extra to the error."""
+        super().__init__(
+            f"needs the {extra!r} extra: pip install 'agentic-graphrag[{extra}]'"
+        )
+        self.extra = extra

agentic_graphrag-0.0.4/agrag/agents/harness.py

@@ -0,0 +1,54 @@
+"""Process-global DeepAgents harness profile registration.
+
+Registers, once per process and per provider, the profile that trims
+DeepAgents' generic tool surface for this project's agent: the execute
+tool is excluded and the general-purpose subagent is disabled. The
+registration is a process-global side effect, so it is guarded against
+re-registration.
+"""
+
+_HARNESS_PROFILE_REGISTERED: set[str] = set()
+_AGENT_PROVIDER_TO_HARNESS_KEY = {
+    "anthropic": "anthropic",
+    "openai": "openai",
+    "openai-generic": "openai",
+    "google-ai": "google_genai",
+}
+
+
+def model_provider_key(provider: str) -> str:
+    """Return the DeepAgents provider key for a configured agent provider.
+
+    Args:
+        provider: The configured agent provider.
+
+    Returns:
+        The provider key used by DeepAgents harness profiles.
+    """
+    return _AGENT_PROVIDER_TO_HARNESS_KEY[provider]
+
+
+def ensure_harness_profile(provider: str) -> None:
+    """Register the harness profile for provider, once per process.
+
+    Args:
+        provider: The provider key DeepAgents resolves profiles by,
+            either a provider string such as ``"anthropic"`` or an
+            exact ``"provider:model"`` string.
+    """
+    if provider in _HARNESS_PROFILE_REGISTERED:
+        return
+    from deepagents import (  # noqa: PLC0415
+        GeneralPurposeSubagentProfile,
+        HarnessProfile,
+        register_harness_profile,
+    )
+
+    register_harness_profile(
+        provider,
+        HarnessProfile(
+            excluded_tools=frozenset({"execute"}),
+            general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False),
+        ),
+    )
+    _HARNESS_PROFILE_REGISTERED.add(provider)