harborrag-runtime 2.0.0a1__py3-none-any.whl

harborrag_runtime/__init__.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from harborrag_runtime.composition import CompositionRoot
+    from harborrag_runtime.sdk import HarborRAG, HarborRAGConfig
+
+__all__ = ["CompositionRoot", "HarborRAG", "HarborRAGConfig"]
+
+
+def __getattr__(name: str) -> Any:
+    """Load the composition root lazily so configuration utilities stay standalone."""
+    if name == "CompositionRoot":
+        from harborrag_runtime.composition import CompositionRoot
+
+        return CompositionRoot
+    if name in {"HarborRAG", "HarborRAGConfig"}:
+        from harborrag_runtime.sdk import HarborRAG, HarborRAGConfig
+
+        return {"HarborRAG": HarborRAG, "HarborRAGConfig": HarborRAGConfig}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

harborrag_runtime/agent/__init__.py

@@ -0,0 +1,37 @@
+"""Runtime agent orchestration and retrieval-tool adapters."""
+
+from harborrag_engine.agent import (
+    AgentCheckpoint,
+    AgentEvent,
+    AgentEventSink,
+    AgentRunIdentity,
+    AgentRunOptions,
+    AgentRunRepository,
+    AgentRunResult,
+    AgentRunStatus,
+    AgentService,
+    AgentStopReason,
+    AgentToolExecution,
+    AgentToolProvider,
+    AgentToolSpec,
+)
+
+from .checkpoint import DatabaseAgentRunRepository, InMemoryAgentRunRepository
+
+__all__ = [
+    "AgentCheckpoint",
+    "AgentEvent",
+    "AgentEventSink",
+    "AgentRunIdentity",
+    "AgentRunOptions",
+    "AgentRunRepository",
+    "AgentRunResult",
+    "AgentRunStatus",
+    "AgentService",
+    "AgentStopReason",
+    "AgentToolExecution",
+    "AgentToolProvider",
+    "AgentToolSpec",
+    "DatabaseAgentRunRepository",
+    "InMemoryAgentRunRepository",
+]

harborrag_runtime/agent/checkpoint.py

@@ -0,0 +1,115 @@
+"""Agent-run checkpoint contracts and runtime implementations."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from harborrag_core.contracts.errors import HarborConflictError
+from harborrag_core.ports.agent_runs import AgentCheckpoint, AgentRunIdentity, AgentRunRepository
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncEngine
+
+    from harborrag_runtime.config.settings import RuntimeSettings
+
+
+class InMemoryAgentRunRepository:
+    """Bounded process-local implementation for unit tests and local checks."""
+
+    def __init__(self, *, max_runs: int = 10_000) -> None:
+        if max_runs < 1:
+            raise ValueError("agent run repository bounds must be positive")
+        self._max_runs = max_runs
+        self._checkpoints: OrderedDict[str, AgentCheckpoint] = OrderedDict()
+        self._lock = asyncio.Lock()
+
+    async def create(self, checkpoint: AgentCheckpoint) -> None:
+        async with self._lock:
+            run_id = checkpoint.identity.run_id
+            self._checkpoints[run_id] = checkpoint
+            self._checkpoints.move_to_end(run_id)
+            while len(self._checkpoints) > self._max_runs:
+                self._checkpoints.popitem(last=False)
+
+    async def save_step(self, checkpoint: AgentCheckpoint) -> None:
+        async with self._lock:
+            run_id = checkpoint.identity.run_id
+            current = self._checkpoints.get(run_id)
+            if current is None or current.version != checkpoint.version - 1:
+                raise HarborConflictError(f"agent run {run_id!r} checkpoint version conflict")
+            self._checkpoints[run_id] = checkpoint
+            self._checkpoints.move_to_end(run_id)
+
+    async def get(self, identity: AgentRunIdentity) -> AgentCheckpoint | None:
+        async with self._lock:
+            checkpoint = self._checkpoints.get(identity.run_id)
+            if checkpoint is None:
+                return None
+            owner = checkpoint.identity
+            if (owner.tenant_id, owner.principal_id, owner.session_id) != (
+                identity.tenant_id,
+                identity.principal_id,
+                identity.session_id,
+            ):
+                return None
+            return checkpoint
+
+
+@dataclass(slots=True)
+class DatabaseAgentRunRepository:
+    """Runtime-owned SQL checkpoint plugin; production DSNs use PostgreSQL/asyncpg."""
+
+    repository: AgentRunRepository
+    engine: AsyncEngine
+
+    @classmethod
+    def configured(
+        cls,
+        settings: RuntimeSettings | None = None,
+    ) -> DatabaseAgentRunRepository:
+        """Migrate and open the configured control DB for a standalone process."""
+
+        from harborrag_adapters.repositories.database.control_plane.agent_runs import (
+            SqlAgentRunRepository,
+        )
+        from harborrag_adapters.repositories.database.control_plane.engine import (
+            create_control_plane_engine,
+            create_session_factory,
+        )
+        from harborrag_adapters.repositories.database.control_plane.migrations import (
+            run_migrations,
+        )
+        from harborrag_core.contracts.errors import HarborConfigurationError
+        from harborrag_runtime.config.settings import DEFAULT_CONTROL_DB_URL, RuntimeSettings
+
+        selected = settings or RuntimeSettings()
+        dsn = selected.control_db_url.get_secret_value()
+        if selected.env == "prod" and dsn == DEFAULT_CONTROL_DB_URL:
+            raise HarborConfigurationError(
+                "agent run checkpoints require HARBORRAG_CONTROL_DB_URL in production"
+            )
+        run_migrations(dsn)
+        engine = create_control_plane_engine(dsn)
+        repository = SqlAgentRunRepository(create_session_factory(engine))
+        return cls(repository=repository, engine=engine)
+
+    async def create(self, checkpoint: AgentCheckpoint) -> None:
+        await self.repository.create(checkpoint)
+
+    async def save_step(self, checkpoint: AgentCheckpoint) -> None:
+        await self.repository.save_step(checkpoint)
+
+    async def get(self, identity: AgentRunIdentity) -> AgentCheckpoint | None:
+        return await self.repository.get(identity)
+
+    async def aclose(self) -> None:
+        await self.engine.dispose()
+
+
+__all__ = [
+    "DatabaseAgentRunRepository",
+    "InMemoryAgentRunRepository",
+]

harborrag_runtime/agent/tool_specs.py

@@ -0,0 +1,207 @@
+"""Canonical read-tool schemas shared by the agent loop and the MCP server.
+
+These builders are the single definition of the retrieval tool surface. The MCP server
+renders the same schemas under its own policy bounds rather than restating them, because
+the two copies previously drifted -- ``max_nodes`` defaulted to the policy maximum in one
+and a hardcoded 20 in the other, equal only by coincidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from harborrag_core.chunking import PROJECTED_RELATION_TYPES
+from harborrag_core.retrieval import GraphDirection
+from harborrag_engine.retrieval import RetrievalLane
+
+_TENANT = {"type": "string", "minLength": 1, "maxLength": 128}
+# Only the predicates the projection actually emits. Offering the reserved members too
+# would let a caller filter on an edge type that can never match.
+_RELATIONS = [item.value for item in PROJECTED_RELATION_TYPES]
+_DIRECTIONS = [item.value for item in GraphDirection]
+_DEFAULT_MAX_RESULTS = 20
+
+# Every graph tool below takes a node selector. This sentence is the only thing that tells
+# a caller how to obtain one, so it is repeated verbatim in each description rather than
+# stated once in a place the model may not read.
+_SELECTOR_HINT = (
+    "Node selectors accept a chunk_id returned by vector_search (chunk IDs and Chunk "
+    "node keys are the same value), a node_key from an earlier graph result, or an exact "
+    "full node title. Titles are unset on chunk nodes and are never matched partially."
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeAgentToolSpec:
+    name: str
+    description: str
+    input_schema: dict[str, object]
+    capability: str = "read"
+
+
+def _relationship_types() -> dict[str, object]:
+    return {
+        "type": "array",
+        "items": {"type": "string", "enum": list(_RELATIONS)},
+        "uniqueItems": True,
+        "default": [],
+    }
+
+
+def vector_search_schema(
+    *,
+    max_results: int = _DEFAULT_MAX_RESULTS,
+    tenant: dict[str, object] | None = None,
+) -> dict[str, object]:
+    return {
+        "type": "object",
+        "required": ["query", "tenant_id"],
+        "properties": {
+            "query": {"type": "string", "minLength": 1},
+            "tenant_id": dict(tenant or _TENANT),
+            "top_k": {"type": "integer", "minimum": 1, "maximum": max_results, "default": 5},
+            "lane": {
+                "type": "string",
+                "enum": [item.value for item in RetrievalLane],
+                "default": RetrievalLane.HYBRID.value,
+            },
+            "filters": {"type": "object"},
+        },
+        "additionalProperties": False,
+    }
+
+
+def graph_triplet_schema(
+    *,
+    max_results: int = _DEFAULT_MAX_RESULTS,
+    tenant: dict[str, object] | None = None,
+) -> dict[str, object]:
+    return {
+        "type": "object",
+        "required": ["tenant_id"],
+        "properties": {
+            "tenant_id": dict(tenant or _TENANT),
+            "subject": {"type": "string", "minLength": 1},
+            "predicate": {"type": "string", "enum": list(_RELATIONS)},
+            "object": {"type": "string", "minLength": 1},
+            "limit": {"type": "integer", "minimum": 1, "maximum": max_results, "default": 10},
+        },
+        "anyOf": [
+            {"required": ["subject"]},
+            {"required": ["predicate"]},
+            {"required": ["object"]},
+        ],
+        "additionalProperties": False,
+    }
+
+
+def graph_path_schema(
+    *,
+    max_results: int = _DEFAULT_MAX_RESULTS,
+    tenant: dict[str, object] | None = None,
+) -> dict[str, object]:
+    return {
+        "type": "object",
+        "required": ["tenant_id", "start_node", "end_node"],
+        "properties": {
+            "tenant_id": dict(tenant or _TENANT),
+            "start_node": {"type": "string", "minLength": 1},
+            "end_node": {"type": "string", "minLength": 1},
+            "relationship_types": _relationship_types(),
+            "max_depth": {"type": "integer", "minimum": 1, "maximum": 8, "default": 4},
+            "max_paths": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": max_results,
+                "default": 10,
+            },
+            "direction": {
+                "type": "string",
+                "enum": list(_DIRECTIONS),
+                "default": GraphDirection.BOTH.value,
+            },
+        },
+        "additionalProperties": False,
+    }
+
+
+def graph_subgraph_schema(
+    *,
+    max_results: int = _DEFAULT_MAX_RESULTS,
+    tenant: dict[str, object] | None = None,
+) -> dict[str, object]:
+    return {
+        "type": "object",
+        "required": ["tenant_id", "start_node"],
+        "properties": {
+            "tenant_id": dict(tenant or _TENANT),
+            "start_node": {"type": "string", "minLength": 1},
+            "relationship_types": _relationship_types(),
+            "max_depth": {"type": "integer", "minimum": 1, "maximum": 8, "default": 2},
+            "max_nodes": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": max_results,
+                "default": max_results,
+            },
+            "direction": {
+                "type": "string",
+                "enum": list(_DIRECTIONS),
+                "default": GraphDirection.BOTH.value,
+            },
+        },
+        "additionalProperties": False,
+    }
+
+
+VECTOR_SEARCH_DESCRIPTION = (
+    "Search tenant-scoped indexed evidence for a natural-language query. Each result "
+    "carries a chunk_id that doubles as a graph node key for the graph tools."
+)
+GRAPH_TRIPLET_DESCRIPTION = (
+    f"Find active subject-predicate-object records in the tenant knowledge graph. {_SELECTOR_HINT}"
+)
+GRAPH_PATH_DESCRIPTION = (
+    f"Find active graph paths between two tenant-scoped nodes. Defaults to an "
+    f"undirected walk, because the spine is not uniformly directed. {_SELECTOR_HINT}"
+)
+GRAPH_SUBGRAPH_DESCRIPTION = (
+    f"Expand an active tenant-scoped graph neighborhood from one known node. {_SELECTOR_HINT}"
+)
+
+
+RUNTIME_AGENT_TOOL_SPECS = (
+    RuntimeAgentToolSpec(
+        "vector_search",
+        VECTOR_SEARCH_DESCRIPTION,
+        vector_search_schema(),
+    ),
+    RuntimeAgentToolSpec(
+        "graph_triplet_search",
+        GRAPH_TRIPLET_DESCRIPTION,
+        graph_triplet_schema(),
+    ),
+    RuntimeAgentToolSpec(
+        "graph_path_search",
+        GRAPH_PATH_DESCRIPTION,
+        graph_path_schema(),
+    ),
+    RuntimeAgentToolSpec(
+        "graph_subgraph_search",
+        GRAPH_SUBGRAPH_DESCRIPTION,
+        graph_subgraph_schema(),
+    ),
+)
+
+__all__ = [
+    "GRAPH_PATH_DESCRIPTION",
+    "GRAPH_SUBGRAPH_DESCRIPTION",
+    "GRAPH_TRIPLET_DESCRIPTION",
+    "RUNTIME_AGENT_TOOL_SPECS",
+    "RuntimeAgentToolSpec",
+    "VECTOR_SEARCH_DESCRIPTION",
+    "graph_path_schema",
+    "graph_subgraph_schema",
+    "graph_triplet_schema",
+    "vector_search_schema",
+]

harborrag_runtime/agent/tools.py

@@ -0,0 +1,222 @@
+"""Runtime adapter exposing retrieval façades as bounded agent read tools."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING, cast
+
+from harborrag_core.chunking import RelationType
+from harborrag_core.retrieval import (
+    GraphDirection,
+    GraphPathQuery,
+    GraphSubgraphQuery,
+    GraphTripletQuery,
+    compact_node,
+    compact_path,
+    compact_relation,
+    compact_triplet,
+)
+from harborrag_core.schemas.ids import TenantId
+from harborrag_core.security import AccessContext
+from harborrag_engine.agent import AgentToolSpec
+from harborrag_engine.retrieval import RetrievalLane
+from harborrag_runtime.agent.tool_specs import RUNTIME_AGENT_TOOL_SPECS
+from harborrag_runtime.contracts import (
+    GraphPathRequest,
+    GraphSubgraphRequest,
+    GraphTripletRequest,
+    RetrievalRequest,
+)
+
+if TYPE_CHECKING:
+    from harborrag_runtime.sdk import HarborRAG
+
+logger = logging.getLogger("harborrag.runtime.agent.tools")
+
+
+@dataclass(slots=True)
+class RuntimeAgentToolProvider:
+    """Translate engine tool calls into the shared runtime SDK façades."""
+
+    runtime: HarborRAG
+
+    def list_tools(self, tenant_id: str | None = None) -> list[AgentToolSpec]:
+        del tenant_id
+        return [cast("AgentToolSpec", spec) for spec in RUNTIME_AGENT_TOOL_SPECS]
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, object] | None = None,
+        *,
+        principal_id: str = "in-process",
+    ) -> dict[str, object]:
+        values = dict(arguments or {})
+        try:
+            access = _access(values, principal_id)
+            operations = {
+                "vector_search": self._vector,
+                "graph_triplet_search": self._triplets,
+                "graph_path_search": self._paths,
+                "graph_subgraph_search": self._subgraph,
+            }
+            operation = operations.get(name)
+            if operation is None:
+                return {"ok": False, "error": "agent tool is not available"}
+            return await operation(values, access)
+        except (TypeError, ValueError) as exc:
+            return {"ok": False, "error": str(exc)}
+        except Exception:
+            logger.exception("agent retrieval tool %r raised during call_tool", name)
+            return {"ok": False, "error": "agent retrieval tool failed"}
+
+    async def _vector(
+        self,
+        values: dict[str, object],
+        access: AccessContext,
+    ) -> dict[str, object]:
+        lane = RetrievalLane(_optional_text(values, "lane") or RetrievalLane.HYBRID.value)
+        response = await self.runtime.retrieval.search(
+            RetrievalRequest(
+                access=access,
+                query=_text(values, "query"),
+                top_k=_integer(values, "top_k", default=5, maximum=20),
+                filters=_mapping(values, "filters"),
+                lane=lane,
+                observe_graph=False,
+            )
+        )
+        return {
+            "ok": True,
+            "results": [asdict(item) for item in response.results],
+            "diagnostics": response.diagnostics,
+        }
+
+    async def _triplets(
+        self,
+        values: dict[str, object],
+        access: AccessContext,
+    ) -> dict[str, object]:
+        predicate = _optional_text(values, "predicate")
+        response = await self.runtime.graph.search_triplets(
+            GraphTripletRequest(
+                access=access,
+                query=GraphTripletQuery(
+                    subject=_optional_text(values, "subject"),
+                    predicate=RelationType(predicate) if predicate is not None else None,
+                    object=_optional_text(values, "object"),
+                    limit=_integer(values, "limit", default=10, maximum=20),
+                ),
+            )
+        )
+        return {
+            "ok": True,
+            "triplets": [compact_triplet(item) for item in response.triplets],
+            "diagnostics": response.diagnostics,
+        }
+
+    async def _paths(
+        self,
+        values: dict[str, object],
+        access: AccessContext,
+    ) -> dict[str, object]:
+        response = await self.runtime.graph.find_paths(
+            GraphPathRequest(
+                access=access,
+                query=GraphPathQuery(
+                    start_node=_text(values, "start_node"),
+                    end_node=_text(values, "end_node"),
+                    relationship_types=_relations(values),
+                    max_depth=_integer(values, "max_depth", default=4, maximum=8),
+                    max_paths=_integer(values, "max_paths", default=10, maximum=20),
+                    direction=_direction(values, GraphDirection.BOTH),
+                ),
+            )
+        )
+        return {
+            "ok": True,
+            "paths": [compact_path(item) for item in response.paths],
+            "diagnostics": response.diagnostics,
+        }
+
+    async def _subgraph(
+        self,
+        values: dict[str, object],
+        access: AccessContext,
+    ) -> dict[str, object]:
+        response = await self.runtime.graph.expand_subgraph(
+            GraphSubgraphRequest(
+                access=access,
+                query=GraphSubgraphQuery(
+                    start_node=_text(values, "start_node"),
+                    relationship_types=_relations(values),
+                    max_depth=_integer(values, "max_depth", default=2, maximum=8),
+                    max_nodes=_integer(values, "max_nodes", default=20, maximum=20),
+                    direction=_direction(values, GraphDirection.BOTH),
+                ),
+            )
+        )
+        return {
+            "ok": True,
+            "nodes": [compact_node(item) for item in response.nodes],
+            "relations": [compact_relation(item) for item in response.relations],
+            "diagnostics": response.diagnostics,
+        }
+
+
+def _access(values: dict[str, object], principal_id: str) -> AccessContext:
+    return AccessContext(
+        principal_id=principal_id,
+        tenant_id=TenantId(_text(values, "tenant_id")),
+    )
+
+
+def _text(values: dict[str, object], name: str) -> str:
+    value = values.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _optional_text(values: dict[str, object], name: str) -> str | None:
+    return _text(values, name) if values.get(name) is not None else None
+
+
+def _integer(
+    values: dict[str, object],
+    name: str,
+    *,
+    default: int,
+    maximum: int,
+) -> int:
+    value = values.get(name, default)
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= maximum:
+        raise ValueError(f"{name} must be between 1 and {maximum}")
+    return value
+
+
+def _mapping(values: dict[str, object], name: str) -> dict[str, object]:
+    value = values.get(name, {})
+    if not isinstance(value, dict):
+        raise TypeError(f"{name} must be an object")
+    if "tenant_id" in value:
+        raise ValueError("tenant_id is not allowed inside filters")
+    return dict(value)
+
+
+def _relations(values: dict[str, object]) -> tuple[RelationType, ...]:
+    value = values.get("relationship_types", [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise TypeError("relationship_types must be an array of strings")
+    return tuple(RelationType(item) for item in value)
+
+
+def _direction(
+    values: dict[str, object],
+    default: GraphDirection,
+) -> GraphDirection:
+    return GraphDirection(_optional_text(values, "direction") or default.value)
+
+
+__all__ = ["RuntimeAgentToolProvider"]

harborrag_runtime/chat/README.md

@@ -0,0 +1,30 @@
+# Runtime chat
+
+This package owns provider-neutral chat orchestration. Transport packages call
+the `ChatFacade`; they do not construct model adapters or read prompt files.
+
+```text
+chat/
+├── facade.py              # stable HarborRAG SDK surface
+├── service.py             # prompt application and async client lifecycle
+├── composition.py         # model-catalog to AsyncHarborChatClient wiring
+└── prompts/
+    ├── catalog.py         # typed prompt names and safe resource lookup
+    └── templates/
+        ├── default.md
+        └── concise.md
+```
+
+Prompt templates are server-owned system messages. A selected template is
+prepended before request messages; selecting no prompt leaves messages
+unchanged. Templates never contain provider credentials or tenant data.
+
+To add a prompt:
+
+1. add a UTF-8 Markdown file under `prompts/templates/`;
+2. add its stable public name and filename to `ChatPrompt` and
+   `PromptCatalog._FILENAMES`;
+3. add catalog and transport-contract tests.
+
+Model/provider selection remains in `config/models.yaml`; prompt files should
+contain behavior instructions only.

harborrag_runtime/chat/__init__.py

@@ -0,0 +1,7 @@
+"""Chat completion, prompt, and provider composition services."""
+
+from .facade import ChatFacade
+from .prompts import ChatPrompt, PromptCatalog
+from .service import RuntimeChatService
+
+__all__ = ["ChatFacade", "ChatPrompt", "PromptCatalog", "RuntimeChatService"]

harborrag_runtime/chat/composition.py

@@ -0,0 +1,17 @@
+"""Provider-client composition for runtime chat services."""
+
+from __future__ import annotations
+
+from harborrag_adapters.models.chat import (
+    AsyncHarborChatClient,
+    ChatClientFactory,
+    HarborChatClientConfig,
+)
+from harborrag_runtime.config.settings import RuntimeSettings
+
+
+def build_chat_client(settings: RuntimeSettings) -> AsyncHarborChatClient:
+    """Build the async client from the shared model catalog."""
+
+    config = HarborChatClientConfig.from_file(settings.model_config_path)
+    return ChatClientFactory.create_async(config)