agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/contracts/auth.py

@@ -0,0 +1,33 @@
+"""`AuthPolicy` — locked authentication contract (feat-014).
+
+Both `agentforge-chat-http` (feat-020) and `agentforge-a2a`
+(feat-014) need to validate incoming bearer tokens against
+configured credentials. This contract unifies them.
+
+Server-side validation only: `authenticate(bearer_token) ->
+Principal | None`. Client-side credential attachment is
+dict-driven (per-peer config carries `{type, token, cert,
+key, ...}`) — no policy abstraction; outgoing transports build
+the right httpx parameters from the dict.
+
+Per ADR-0007 the methods on this ABC are locked once the
+feature ships. Adding a method is a major-version bump.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from agentforge_core.values.auth import Principal
+
+
+class AuthPolicy(ABC):
+    """Validates incoming bearer credentials against configured
+    identities. Implementations are typically env-backed
+    (`EnvBearerAuth`) or registry-backed."""
+
+    @abstractmethod
+    async def authenticate(self, bearer_token: str | None) -> Principal | None:
+        """Return a `Principal` when the token is valid, else
+        ``None``. ``None`` input (missing header) must yield
+        ``None``."""

agentforge_core/contracts/chat.py

@@ -0,0 +1,118 @@
+"""Chat-agent contracts (feat-020).
+
+`ChatHistoryStore` and `HistoryTruncationStrategy` are the two locked
+ABCs the chat layer ships against. Drivers (in-memory + sqlite +
+postgres + redis) all implement the same `ChatHistoryStore` shape;
+truncation strategies (sliding-window, token-budget, summarise-oldest,
+hybrid) all implement the same `HistoryTruncationStrategy` shape.
+
+Per ADR-0007, methods on these ABCs are locked once the feature
+ships. Adding a method is a major version bump.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+from agentforge_core.values.chat import ChatTurn, SessionInfo
+
+
+class ChatHistoryStore(ABC):
+    """Persistent store for chat turns, isolated by `session_id`.
+
+    All read/write methods take `session_id`; cross-session access
+    is impossible without explicitly passing the id. Drivers
+    typically index on `(session_id, created_at)` so `load()` is
+    sub-linear w.r.t. total store size.
+    """
+
+    @abstractmethod
+    async def append(self, turn: ChatTurn) -> None:
+        """Persist a single chat turn."""
+
+    @abstractmethod
+    async def load(
+        self,
+        session_id: str,
+        *,
+        limit: int | None = None,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        roles: list[str] | None = None,
+    ) -> list[ChatTurn]:
+        """Load turns for ``session_id`` in chronological order
+        (oldest first). Filters apply pre-limit."""
+
+    @abstractmethod
+    async def count(self, session_id: str) -> int:
+        """Total turn count for ``session_id``."""
+
+    @abstractmethod
+    async def delete_session(self, session_id: str) -> int:
+        """Delete every turn for ``session_id``. Returns the number
+        of turns removed."""
+
+    @abstractmethod
+    async def list_sessions(
+        self,
+        *,
+        owner: str | None = None,
+        limit: int = 100,
+        before: datetime | None = None,
+    ) -> list[SessionInfo]:
+        """List sessions, optionally filtered by owner. Ordered by
+        ``last_active_at`` descending."""
+
+    @abstractmethod
+    async def update_session_metadata(self, session_id: str, metadata: Mapping[str, Any]) -> None:
+        """Merge ``metadata`` into the session's metadata dict.
+
+        Implementations may overwrite top-level keys; nested merging
+        is the caller's responsibility.
+        """
+
+    @abstractmethod
+    async def expire_before(self, cutoff: datetime) -> int:
+        """TTL sweep: delete every session whose ``last_active_at <
+        cutoff``. Returns the number of sessions removed. Drivers
+        without TTL support return 0."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release driver resources (DB pool, file handles, etc.)."""
+
+    def capabilities(self) -> set[str]:
+        """Optional capability bag.
+
+        Subset of: ``"ttl"``, ``"encryption_at_rest"``,
+        ``"full_text_search"``, ``"streaming_load"``.
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        return capability in self.capabilities()
+
+
+class HistoryTruncationStrategy(ABC):
+    """Decides which prior turns to include in the next LLM call.
+
+    Truncation runs every turn, between `load()` and the agent call.
+    Returns a possibly-empty subset of ``all_turns`` (ordered).
+    Invariants every strategy honours (covered by the conformance
+    harness):
+
+    - Order-preserving (output is a subsequence of input).
+    - Tool-call / tool-result pairs are never split.
+    """
+
+    @abstractmethod
+    async def select(
+        self,
+        all_turns: list[ChatTurn],
+        next_user_message: str,
+        context: Mapping[str, Any],
+    ) -> list[ChatTurn]:
+        """Return the subset of ``all_turns`` to feed to the LLM."""

agentforge_core/contracts/embedding.py

@@ -0,0 +1,71 @@
+"""`EmbeddingClient` — locked embeddings provider abstraction.
+
+Embedding providers (Bedrock Titan / Cohere, OpenAI, etc.) implement
+this ABC. The vector store / retrieval layer (feat-007) consumes
+`EmbeddingClient`, never the concrete driver type, so swapping
+providers is a string-id swap.
+
+Per ADR-0007 the surface is locked at v0.1: adding a method is a
+major version bump. Optional capabilities (e.g. multimodal embeddings)
+are layered the same way as on `LLMClient` — declared in
+`capabilities()` and gated via `supports()`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from agentforge_core.values.messages import EmbeddingResponse
+
+
+class EmbeddingClient(ABC):
+    """Provider-agnostic text-embedding client.
+
+    Implementations:
+      - normalise the provider's response into `EmbeddingResponse`
+      - declare the model's vector dimensionality up front via
+        `dimensions()` so callers can size storage before the call
+      - compute `cost_usd` from token usage and a per-model price
+        table inside the driver (consistent with `LLMClient`)
+    """
+
+    @abstractmethod
+    async def embed(self, texts: list[str]) -> EmbeddingResponse:
+        """Embed a batch of texts.
+
+        Args:
+            texts: One or more texts to embed. Empty list raises
+                `ValueError` (no provider supports zero-length batches
+                and the cost would be ambiguous).
+
+        Returns:
+            `EmbeddingResponse` carrying one vector per input text in
+            input order. Every vector has length `self.dimensions()`.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release any resources (HTTP clients, connection pools)."""
+
+    @abstractmethod
+    def dimensions(self) -> int:
+        """The vector dimensionality every `embed()` call returns.
+
+        Drivers declare this without a network round-trip — it is a
+        property of the configured model. Callers use this to size
+        storage (e.g. vector-store column widths) before the first
+        embed call.
+        """
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this driver supports.
+
+        Default empty set. Closed vocabulary (additions are minor
+        bumps): `"multimodal"` (image / audio inputs in addition to
+        text), `"matryoshka"` (truncatable variable-length vectors).
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this client declares the given capability."""
+        return capability in self.capabilities()

agentforge_core/contracts/evaluator.py

@@ -0,0 +1,56 @@
+"""`Evaluator` — the locked post-run evaluator ABC, plus `EvalResult`.
+
+feat-001 ships only the contract and the result type. feat-006 ships
+deterministic graders (coverage, consistency, regression-vs-baseline,
+format-compliance) and LLM-judge graders (correctness, faithfulness,
+groundedness, hallucination, relevance, helpfulness) via the
+`agentforge-eval-geval` module.
+
+Evaluators run *after* the reasoning loop completes and score the
+agent's output (per `docs/features/feat-006-evaluators-and-benchmarks.md`).
+This is distinct from real-time validators (feat-018) which block /
+redact at the moment a violation happens.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EvalResult(BaseModel):
+    """The outcome of evaluating one finding (or output)."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    evaluator: str
+    score: float
+    """Conventionally in [0, 1]; NaN allowed for "not applicable"."""
+
+    label: str | None = None
+    """Optional discrete label such as "pass" / "fail" / "warn"."""
+
+    reasoning: str | None = None
+    """LLM-judge rationale or rule-based explanation."""
+
+    raw: dict[str, Any] = Field(default_factory=dict)
+    """Driver-specific extra detail — never required, never relied on."""
+
+
+class Evaluator(ABC):
+    """Post-run quality scorer.
+
+    Subclasses declare:
+
+        name: str                   — identifier surfaced in EvalResult
+        cost_estimate_usd: float    — per-evaluation cost (0 for non-LLM)
+    """
+
+    name: ClassVar[str]
+    cost_estimate_usd: ClassVar[float] = 0.0
+
+    @abstractmethod
+    async def evaluate(self, finding: Any, context: dict[str, Any]) -> EvalResult:
+        """Score `finding` against this evaluator's rubric."""

agentforge_core/contracts/finding.py

@@ -0,0 +1,39 @@
+"""`Finding` — structural Protocol the agent's output items satisfy.
+
+Per feat-008 / ADR-0012, `Finding` is a `runtime_checkable` Protocol
+rather than a single dataclass. Shipped variants (`SimpleFinding`,
+`PatchFinding`, `NarrativeFinding`, `MultiSpanFinding`) live in the
+runtime package; they satisfy this Protocol structurally without
+needing to inherit from anything.
+
+Custom variants from agent code or third-party packages also satisfy
+the Protocol simply by declaring the required attributes — no
+registration ceremony.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Finding(Protocol):
+    """Minimum shape any pipeline / agent output item satisfies.
+
+    The runtime checks `isinstance(x, Finding)` opportunistically (e.g.
+    when storing as a `Claim.payload`); the check is structural and
+    tolerant.
+    """
+
+    severity: str
+    """One of "critical" | "warning" | "suggestion" | "info"."""
+
+    category: str
+    """Free-form categorisation: "style", "security", "answer", etc."""
+
+    message: str
+    """Short human-readable summary (one or two sentences)."""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-compatible dict for persistence / transport."""
+        ...

agentforge_core/contracts/graph_store.py

@@ -0,0 +1,180 @@
+"""`GraphStore` — locked graph-traversal ABC.
+
+A graph store is distinct from `MemoryStore` (claim audit log) and
+`VectorStore` (similarity search): the shapes don't unify cleanly.
+`MemoryStore` filters by structured metadata; `VectorStore` ranks by
+cosine similarity; `GraphStore` walks relationships — multi-hop
+queries, pattern matching, ontology traversal. Forcing graph traversal
+into either of the existing ABCs would degrade them; keeping
+`GraphStore` separate respects the contract layer's purpose (one ABC
+per concern, not one per backend).
+
+Per ADR-0007 the surface is locked at v0.1: adding a method is a
+major version bump. Optional capabilities (e.g. native Cypher
+support, transactions, embedded vector search) layer the same way as
+`LLMClient` capabilities — declared via `capabilities()` and gated via
+`supports()`.
+
+Conformance: every shipped or third-party driver must pass
+`agentforge_core.testing.run_graph_conformance` (lands alongside this
+contract).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Literal
+
+from agentforge_core.values.graph import (
+    GraphEdge,
+    GraphNode,
+    GraphPattern,
+    Path,
+)
+
+
+class GraphStore(ABC):
+    """Provider-agnostic property graph.
+
+    Implementations:
+      - treat `add_node` and `add_edge` as idempotent upserts
+        (re-adding the same `id` / `(src, dst, edge_type)` replaces
+        the prior record's `properties`)
+      - reject edges whose `src` or `dst` references an unknown node —
+        callers must `add_node` first; this keeps the graph
+        well-formed and matches Cypher / SurrealQL behaviour
+      - return `Path` results with `len(edges) == len(nodes) - 1` and
+        edges in chain order
+
+    Cross-driver invariants enforced by the conformance suite:
+      - round-trip: `add_node(N); get_node(N.id)` returns an equal node
+      - edge readback: `add_edge(E); get_edges(E.src)` includes E
+      - pattern match: a one-segment pattern returns paths of length 2
+      - traversal: depth-bounded BFS does not exceed `max_depth`
+      - cascade delete: `delete_node(id, cascade=True)` removes
+        adjacent edges; `cascade=False` raises if edges remain
+    """
+
+    @abstractmethod
+    async def add_node(self, node: GraphNode) -> None:
+        """Insert or replace `node` (idempotent upsert by `node.id`)."""
+
+    @abstractmethod
+    async def add_edge(self, edge: GraphEdge) -> None:
+        """Insert or replace `edge` (idempotent upsert by
+        `(src, dst, edge_type)`).
+
+        Raises:
+            ValueError: `edge.src` or `edge.dst` references an unknown
+                node. Callers must add nodes before edges.
+        """
+
+    @abstractmethod
+    async def get_node(self, node_id: str) -> GraphNode | None:
+        """Return the node with this id, or `None` if absent."""
+
+    @abstractmethod
+    async def get_edges(
+        self,
+        node_id: str,
+        *,
+        edge_type: str | None = None,
+        direction: Literal["out", "in", "any"] = "out",
+    ) -> list[GraphEdge]:
+        """Return edges incident on `node_id`.
+
+        Args:
+            node_id: The node whose edges to fetch.
+            edge_type: If set, only edges of this type. `None` returns
+                all types.
+            direction: `"out"` returns edges where `src == node_id`;
+                `"in"` returns edges where `dst == node_id`; `"any"`
+                returns the union.
+        """
+
+    @abstractmethod
+    async def match(
+        self,
+        pattern: GraphPattern,
+        *,
+        limit: int = 50,
+    ) -> list[Path]:
+        """Return paths matching `pattern`, capped at `limit`.
+
+        Drivers may evaluate the pattern via Cypher (Neo4j),
+        SurrealQL (SurrealDB), or in-memory walking (the reference
+        implementation). The return shape is the same.
+
+        Raises:
+            ValueError: `limit < 1`.
+        """
+
+    @abstractmethod
+    async def traverse(
+        self,
+        start_id: str,
+        *,
+        edge_types: tuple[str, ...] | None = None,
+        max_depth: int = 3,
+        limit: int = 50,
+    ) -> list[Path]:
+        """Breadth-first traversal from `start_id`.
+
+        Returns every path of length 1..`max_depth` starting from
+        `start_id`, restricted to `edge_types` if given. Useful for
+        knowledge-graph expansion (pull a neighbourhood for retrieval
+        augmentation).
+
+        Args:
+            start_id: The seed node. If absent, returns an empty list.
+            edge_types: If set, only traverse edges of these types.
+            max_depth: Hop limit (>= 1).
+            limit: Maximum number of paths to return (>= 1).
+
+        Raises:
+            ValueError: `max_depth < 1` or `limit < 1`.
+        """
+
+    @abstractmethod
+    async def delete_node(self, node_id: str, *, cascade: bool = False) -> bool:
+        """Delete a node by id. Returns True if a node was removed.
+
+        Args:
+            node_id: The node to delete.
+            cascade: If True, also delete every edge incident on the
+                node. If False (default) and the node still has edges,
+                raises `ValueError` — drivers must not orphan edges.
+
+        Raises:
+            ValueError: `cascade=False` and the node has incident edges.
+        """
+
+    @abstractmethod
+    async def delete_edge(self, src: str, dst: str, *, edge_type: str) -> bool:
+        """Delete an edge by `(src, dst, edge_type)`. Returns True if
+        an edge was removed.
+
+        Unknown triples return False (no exception).
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release backing resources (connections, file handles)."""
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this driver supports.
+
+        Default empty set. Closed vocabulary (additions are minor
+        bumps): `"transactions"` (multi-statement atomic writes),
+        `"cypher"` (driver speaks Cypher natively),
+        `"surrealql"` (driver speaks SurrealQL natively),
+        `"vector"` (driver also indexes embeddings — typically also
+        implements `VectorStore`), `"live_query"` (driver pushes
+        change notifications), `"fulltext"` (driver indexes node /
+        edge property text).
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this driver declares the given capability."""
+        return capability in self.capabilities()

agentforge_core/contracts/guardrails.py

@@ -0,0 +1,129 @@
+"""Guardrail ABCs (feat-018).
+
+Three locked ABCs:
+
+- `InputValidator.validate(content, context)` — runs before each
+  LLM call on the user-visible input.
+- `OutputValidator.validate(content, context)` — runs after each
+  LLM call on the model's output.
+- `ToolCallGate.authorize(tool_name, tool, args, context)` — runs
+  before tool dispatch.
+
+All three return `ValidationResult`. Implementations are async so
+they can integrate with HTTP-based validators (LLM Guard,
+Presidio, Llama Guard) without blocking the event loop.
+
+The `name: str` ClassVar identifies the validator in audit events
+and config-resolution paths.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from agentforge_core.values.guardrails import ValidationResult
+
+if TYPE_CHECKING:
+    from agentforge_core.contracts.tool import Tool
+
+
+class InputValidator(ABC):
+    """Validates user input before the agent's first LLM call.
+
+    Subclasses set ClassVars `name`, `description`, and
+    `cost_estimate_ms` (rough per-call latency in milliseconds).
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str]
+    cost_estimate_ms: ClassVar[int] = 0
+
+    @abstractmethod
+    async def validate(self, content: str, context: dict[str, Any]) -> ValidationResult:
+        """Validate `content`. `context` carries `run_id`, `project`,
+        `agent`, and any per-call metadata."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        _require_attrs(cls, ("name", "description"))
+
+
+class OutputValidator(ABC):
+    """Validates the model's output after each LLM call.
+
+    Output validators MAY redact: set `redacted_content` on the
+    returned `ValidationResult` to the post-redaction text. The
+    framework forwards that content downstream when
+    `policy.on_output_violation == "redact"`.
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str]
+    cost_estimate_ms: ClassVar[int] = 0
+
+    @abstractmethod
+    async def validate(self, content: str, context: dict[str, Any]) -> ValidationResult:
+        """Validate `content` (the LLM's text output)."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        _require_attrs(cls, ("name", "description"))
+
+
+class ToolCallGate(ABC):
+    """Authorises a tool invocation before dispatch.
+
+    Receives the tool instance so gates can inspect `tool.capabilities`
+    or other static metadata.
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str]
+    cost_estimate_ms: ClassVar[int] = 0
+
+    @abstractmethod
+    async def authorize(
+        self,
+        tool_name: str,
+        tool: Tool,
+        args: dict[str, Any],
+        context: dict[str, Any],
+    ) -> ValidationResult:
+        """Authorise the upcoming tool call."""
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        _require_attrs(cls, ("name", "description"))
+
+
+def _require_attrs(cls: type, attrs: tuple[str, ...]) -> None:
+    """Enforce the ClassVar contract on concrete subclasses."""
+    import inspect  # noqa: PLC0415
+
+    if inspect.isabstract(cls):
+        return
+    for attr in attrs:
+        if attr not in cls.__dict__ and not _inherited(cls, attr):
+            msg = (
+                f"{cls.__name__} must declare class attribute {attr!r} "
+                "(every guardrail validator carries a stable name and "
+                "human-readable description for audit events)."
+            )
+            raise TypeError(msg)
+
+
+def _inherited(cls: type, attr: str) -> bool:
+    for base in cls.__mro__[1:]:
+        if base is object:
+            continue
+        if attr in base.__dict__ and base.__module__ != cls.__module__:
+            return True
+    return False
+
+
+__all__ = [
+    "InputValidator",
+    "OutputValidator",
+    "ToolCallGate",
+]