agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/contracts/llm.py

@@ -0,0 +1,152 @@
+"""`LLMClient` — the locked LLM provider abstraction.
+
+The mandatory surface is `call`, `close`, and capability introspection
+(`capabilities` / `supports`). The optional surface — `call_with_cache`,
+`call_with_thinking`, `stream` — is layered as default-raise methods so
+the contract stays additive (per ADR-0009): drivers that don't support
+a capability simply leave the default in place; consumers gate on
+`client.supports("capability")` before invoking.
+
+Capability vocabulary (closed enum, additions are minor bumps):
+  - "tools"           — `tools=` argument honoured by `call`
+  - "json_mode"       — provider returns guaranteed-valid JSON
+  - "vision"          — multimodal input
+  - "caching"         — `call_with_cache` works (prompt caching)
+  - "thinking"        — `call_with_thinking` works (extended thinking)
+  - "streaming"       — `stream` works
+  - "parallel_tools"  — provider may emit multiple tool calls per turn
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+from agentforge_core.production.exceptions import CapabilityNotSupported
+from agentforge_core.values.messages import (
+    LLMResponse,
+    Message,
+    StreamChunk,
+    ToolSpec,
+)
+
+
+class LLMClient(ABC):
+    """Provider-agnostic chat-completion client.
+
+    Every provider module implements this ABC. Reasoning strategies
+    consume `LLMClient` (not the concrete provider type) so a string-id
+    swap (`"anthropic:..."` → `"bedrock:..."`) requires no code change.
+    """
+
+    @abstractmethod
+    async def call(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+    ) -> LLMResponse:
+        """Issue a single chat-completion request.
+
+        Args:
+            system: System prompt.
+            messages: Conversation turns to date.
+            tools: Optional tool catalogue exposed to the LLM.
+
+        Returns:
+            The provider's response, normalised to `LLMResponse`.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release any resources (HTTP clients, connection pools)."""
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this provider supports.
+
+        Default empty set. Subclasses override to declare capabilities
+        from the closed vocabulary (per ADR-0009).
+
+        Returns:
+            Set of capability names.
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this client declares the given capability."""
+        return capability in self.capabilities()
+
+    # ------------------------------------------------------------------
+    # Optional capabilities — drivers override; default raise.
+    # ------------------------------------------------------------------
+
+    async def call_with_cache(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+        *,
+        cache_breakpoints: list[int],
+    ) -> LLMResponse:
+        """Call the model with explicit prompt-cache breakpoints.
+
+        `cache_breakpoints` is a list of `messages` indices after which
+        the provider should mark a cache point. Drivers that support
+        prompt caching (Anthropic, Bedrock with Claude) honour this;
+        every other driver leaves the default in place.
+
+        Raises:
+            CapabilityNotSupported: this driver did not declare
+                `"caching"` in `capabilities()`.
+        """
+        raise CapabilityNotSupported(
+            f"{type(self).__name__} does not support 'caching'. "
+            f"Check client.supports('caching') before calling."
+        )
+
+    async def call_with_thinking(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+        *,
+        thinking_budget_tokens: int,
+    ) -> LLMResponse:
+        """Call the model with extended-thinking enabled.
+
+        `thinking_budget_tokens` caps the model's internal reasoning
+        budget. The returned `LLMResponse.usage.thinking_tokens`
+        reports actual usage; the public `content` excludes the
+        thinking trace.
+
+        Raises:
+            CapabilityNotSupported: this driver did not declare
+                `"thinking"` in `capabilities()`.
+        """
+        raise CapabilityNotSupported(
+            f"{type(self).__name__} does not support 'thinking'. "
+            f"Check client.supports('thinking') before calling."
+        )
+
+    def stream(
+        self,
+        system: str,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream the model's response chunk-by-chunk.
+
+        Returns an async iterator that yields `StreamChunk`s and
+        terminates with exactly one `kind="stop"` chunk carrying final
+        usage and cost. Synchronous in shape (returns an iterator) so
+        the caller can pass it through pipes/transforms without an
+        extra `await`.
+
+        Raises:
+            CapabilityNotSupported: this driver did not declare
+                `"streaming"` in `capabilities()`.
+        """
+        raise CapabilityNotSupported(
+            f"{type(self).__name__} does not support 'streaming'. "
+            f"Check client.supports('streaming') before calling."
+        )

agentforge_core/contracts/memory.py

@@ -0,0 +1,113 @@
+"""`MemoryStore` — the locked persistence ABC.
+
+feat-001 ships the contract plus an `InMemoryStore` reference impl in
+the runtime package. feat-005 adds drivers for SQLite, PostgreSQL,
+SurrealDB, and Neo4j (all passing the same conformance suite per
+ADR-0007 and feat-016's `run_memory_conformance`).
+
+Per feat-005's design (`docs/design/persistence-and-orm.md`), every
+driver implements `MemoryStore`; graph-capable drivers additionally
+implement `GraphStore` (deferred to feat-005).
+
+Cross-agent isolation: every query is scoped by `(project, agent)` by
+default. Cross-scope access requires explicit `None` filters — a
+deliberate verb, not an accident.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from datetime import datetime
+
+from agentforge_core.values.claim import Claim
+
+
+class MemoryStore(ABC):
+    """Persistent store of `Claim`s with `(project, agent)` namespacing."""
+
+    @abstractmethod
+    async def put(self, claim: Claim) -> str:
+        """Persist `claim`. Returns its id (the claim's own ULID by default)."""
+
+    @abstractmethod
+    async def get(self, claim_id: str) -> Claim | None:
+        """Fetch a claim by id, or None if not present."""
+
+    @abstractmethod
+    async def query(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+        limit: int = 100,
+    ) -> list[Claim]:
+        """Query claims with the given filters.
+
+        Filters are conjunctive. Passing `None` for `project` or `agent`
+        explicitly broadens the scope (cross-scope access is a verb).
+        """
+
+    @abstractmethod
+    async def supersede(self, old_id: str, new_claim: Claim) -> str:
+        """Replace `old_id` with `new_claim`; preserves history.
+
+        Sets `new_claim.supersedes = old_id` if not already set; returns
+        the new claim's id.
+        """
+
+    @abstractmethod
+    def stream(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+    ) -> AsyncIterator[Claim]:
+        """Stream all matching claims as an async iterator.
+
+        Required even on backends with paged queries — drivers paginate
+        internally and yield `Claim`s as they arrive.
+        """
+
+    @abstractmethod
+    async def delete(
+        self,
+        *,
+        run_id: str | None = None,
+        older_than: datetime | None = None,
+        category: str | None = None,
+    ) -> int:
+        """Delete claims matching the given conjunctive filters.
+
+        At least one filter must be set; calling `delete()` with every
+        filter `None` raises `ModuleError` — a deliberate guard against
+        the silent total-wipe footgun. Returns the number of claims
+        deleted.
+
+        Added in feat-017 to back `agentforge db purge`. The opt-in
+        filter set is small on purpose; broader DSL queries route
+        through `agentforge db query` followed by per-id deletions.
+        """
+
+    @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. Subclasses declare capabilities from the
+        closed vocabulary: "graph", "vector", "fts", "transactions",
+        "ttl", "encryption_at_rest". Per ADR-0009, declarations must be
+        honest — a nightly conformance test exercises every declared
+        capability against the real backend.
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this driver declares the given capability."""
+        return capability in self.capabilities()

agentforge_core/contracts/migrator.py

@@ -0,0 +1,120 @@
+"""`Migrator` Protocol + `Migration` value type — feat-024.
+
+A migration is a single versioned schema delta: a numbered
+filename, a name, an SQL/Cypher/SurrealQL body, and a checksum
+of the body. Drivers ship migrations in-package; the migrator
+applies pending ones in order and records each in a per-driver
+tracking table or graph node so re-runs are idempotent.
+
+Per ADR-0007 the surface is locked at v0.1: adding a method to
+:class:`Migrator` is a major version bump. The bodies of migrations
+are driver-dialect-specific (SQL / Cypher / SurrealQL); the
+framework only enforces filename convention, checksum stability,
+ordering, and apply-once semantics.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from agentforge_core.production.exceptions import ModuleError
+
+_MIGRATION_ID_RE = re.compile(r"^\d{4}$")
+
+
+class Migration(BaseModel):
+    """One versioned schema migration.
+
+    The ``id`` is the 4-digit prefix of the migration filename
+    (e.g. ``"0001"``); ``name`` is the snake-case description
+    (e.g. ``"initial"``); ``up`` is the migration body the
+    driver executes; ``checksum`` is the SHA-256 hex digest over
+    the LF-normalised UTF-8 body — recorded at apply time and
+    re-verified on every subsequent migrate / status invocation.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    up: str
+    checksum: str = Field(min_length=64, max_length=64)
+
+    @field_validator("id")
+    @classmethod
+    def _validate_id_format(cls, value: str) -> str:
+        if not _MIGRATION_ID_RE.match(value):
+            msg = f"Migration id must be exactly 4 digits, got {value!r}"
+            raise ValueError(msg)
+        return value
+
+
+class MigrationStatus(BaseModel):
+    """Per-migration applied-state record for :meth:`Migrator.status`.
+
+    ``applied`` and ``applied_at`` track whether the migration has
+    been recorded against this driver. ``checksum_match`` is True
+    when the migration is both applied and its recorded checksum
+    equals the file's current checksum — drift triggers
+    :class:`MigrationChecksumError` on the next ``apply_pending``.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    migration: Migration
+    applied: bool
+    applied_at: datetime | None = None
+    checksum_match: bool
+
+
+class MigrationChecksumError(ModuleError):
+    """An applied migration's recorded checksum no longer matches
+    the file's checksum.
+
+    Indicates the migration body was edited after deployment. The
+    framework refuses to silently re-apply — operators must either
+    restore the original file or add a forward-migration that
+    expresses the intended delta.
+    """
+
+
+@runtime_checkable
+class Migrator(Protocol):
+    """Driver-specific migration runner.
+
+    Implementations live alongside each persistent-store driver
+    (`PostgresMigrator`, `SqliteMigrator`, `Neo4jMigrator`,
+    `SurrealMigrator`). They share a single Protocol so the
+    `agentforge db migrate` CLI can drive any of them through the
+    same surface.
+    """
+
+    async def apply_pending(self) -> list[Migration]:
+        """Apply every discovered migration whose id is strictly
+        greater than ``await current_version()``. Returns the
+        applied migrations in order.
+
+        Raises:
+            MigrationChecksumError: An already-applied migration's
+                recorded checksum doesn't match the file's
+                checksum. Aborts before applying any pending
+                migration.
+        """
+        ...
+
+    async def status(self) -> list[MigrationStatus]:
+        """Return per-migration applied + checksum-match status
+        for every discovered migration, sorted by id ascending.
+        """
+        ...
+
+    async def current_version(self) -> str | None:
+        """Return the id of the highest applied migration, or
+        ``None`` if nothing has been applied yet (e.g. the
+        tracking table doesn't exist).
+        """
+        ...

agentforge_core/contracts/renderer.py

@@ -0,0 +1,57 @@
+"""`FindingRenderer` — locked contract for rendering Findings to text.
+
+Per feat-008 / ADR-0007, this ABC is part of the framework's stable
+surface. Concrete renderers ship in `agentforge.renderers` and resolve
+through `RendererRegistry`; agent / module authors implement this ABC
+to ship custom renderers for their own `Finding` variants.
+
+Rendering is intentionally text-out. Format strings are advisory —
+implementations should accept at least `"text"` (plain) and
+`"markdown"` (markdown-formatted), and may support additional formats
+they declare.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from agentforge_core.contracts.finding import Finding
+
+
+class FindingRenderer(ABC):
+    """Render a `Finding` to a string in one of several formats.
+
+    Implementations are typically pinned to a single variant via the
+    registry's type-based dispatch (most-specific-wins). The base
+    `supports()` returns `True` only for the concrete variant the
+    renderer was registered against, so the registry handles dispatch.
+
+    Subclass and override `render`. If a subclass supports multiple
+    `Finding` variants, override `supports()` to declare which.
+    """
+
+    @abstractmethod
+    def render(self, finding: Finding, format: str = "text") -> str:
+        """Render `finding` to a string in the given format.
+
+        Args:
+            finding: Any object satisfying the `Finding` Protocol.
+            format: Output format. At minimum, implementations support
+                `"text"` (plain) and `"markdown"`. Unknown formats
+                should raise `ValueError`.
+
+        Returns:
+            A string suitable for direct emission to a terminal,
+            markdown file, log line, etc. — depending on `format`.
+        """
+
+    def supports(self, finding_type: type) -> bool:
+        """Whether this renderer accepts findings of `finding_type`.
+
+        Default: returns `False`; subclasses or the registry pin
+        renderers to a specific variant. The registry uses this only
+        as a fallback — primary dispatch is by isinstance-against-the-
+        registered-type, not by calling `supports()`.
+        """
+        del finding_type
+        return False

agentforge_core/contracts/reranker.py

@@ -0,0 +1,91 @@
+"""`Reranker` — locked cross-encoder reranking ABC (feat-021).
+
+A reranker scores `(query, candidate)` pairs directly, rather
+than indexing then matching like a `VectorStore`. The standard
+production RAG pattern is: pull the top-`K * factor` candidates
+from a `VectorStore` for recall, then rerank to `top_k` for
+precision. The framework owns the contract so swapping
+SentenceTransformers ↔ Cohere ↔ Voyage is a config change, not
+a rewrite.
+
+Per ADR-0007 the surface is locked at v0.2: adding a method is
+a major version bump. Optional capabilities layer the same way
+as `VectorStore` / `LLMClient` capabilities — declared via
+`capabilities()` and gated by callers.
+
+Conformance: every shipped or third-party reranker must pass
+`run_reranker_conformance(reranker)` (ships alongside this
+contract).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from agentforge_core.values.vector import VectorMatch
+
+
+class Reranker(ABC):
+    """Re-orders a candidate list by relevance to a query.
+
+    Implementations:
+      - return a *new* list (callers may inspect the input list
+        after the call; mutation is forbidden)
+      - sort descending by the reranker's own relevance score
+      - replace each returned `VectorMatch.score` with the
+        reranker's normalised score (still in `[0, 1]`); other
+        fields (`id`, `text`, `metadata`) pass through unchanged
+      - when ``top_k`` is None, return all candidates re-sorted
+      - when set, truncate to the top ``top_k`` after sorting
+
+    Cross-driver invariants enforced by the conformance suite:
+      - len(rerank(...)) == min(len(candidates), top_k or ∞)
+      - 0 ≤ result[i].score ≤ 1 for every returned match
+      - result is sorted descending by score
+      - empty `candidates` returns `[]`
+    """
+
+    @abstractmethod
+    async def rerank(
+        self,
+        query: str,
+        candidates: list[VectorMatch],
+        *,
+        top_k: int | None = None,
+    ) -> list[VectorMatch]:
+        """Re-sort `candidates` by relevance to `query`.
+
+        Args:
+            query: Free-text query to score candidates against.
+            candidates: Output of an earlier `VectorStore.search`
+                (or any list of `VectorMatch`). Read-only — the
+                reranker must not mutate the input.
+            top_k: When set, truncate the result to this many
+                items. None returns all candidates re-sorted.
+
+        Returns:
+            A new list of `VectorMatch`, sorted descending by the
+            reranker's relevance score (replacing the original
+            `score`). Other fields pass through unchanged.
+
+        Raises:
+            ValueError: ``top_k < 1`` when not None.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release backing resources (model handles, HTTP clients)."""
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this reranker declares.
+
+        Default empty set. Closed vocabulary (additions are minor
+        bumps): ``"local"`` (runs offline, no network calls),
+        ``"managed"`` (calls an external API), ``"batched"``
+        (`rerank` internally batches the candidate pairs).
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this reranker declares the given capability."""
+        return capability in self.capabilities()

agentforge_core/contracts/strategy.py

@@ -0,0 +1,70 @@
+"""`ReasoningStrategy` — the locked reasoning-loop ABC.
+
+feat-001 ships only the contract. feat-002 ships `ReActLoop` (the stable
+default) and three experimental loops (`PlanExecuteLoop`,
+`TreeOfThoughts`, `MultiAgentSupervisor`).
+
+Every concrete strategy honours these invariants (enforced by the
+conformance suite in feat-002):
+
+  - Guardrails (`BudgetPolicy.check`) are called before every LLM call.
+  - All state flows through one shared `AgentState` — no module globals.
+  - Every reasoning step is appended to `state.steps`.
+  - Termination is one of: finish signal, max_iterations, guardrail trip.
+
+feat-020 v0.2 adds a non-abstract `stream()` default that wraps
+`run()` and emits a single terminal `done` `StreamingEvent` so
+existing concrete strategies keep working unchanged. Strategies
+that want real per-token (or per-step) streaming override it to
+yield events as the LLM emits tokens. `ChatSession.stream()`
+detects the override and forwards events to the wire.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+from agentforge_core.values.chat import StreamingEvent
+from agentforge_core.values.state import AgentState
+
+
+class ReasoningStrategy(ABC):
+    """Drives the agent from initial task to terminal state."""
+
+    @abstractmethod
+    async def run(self, state: AgentState) -> AgentState:
+        """Execute the reasoning loop until termination.
+
+        Args:
+            state: The mutable per-run state.
+
+        Returns:
+            The same `AgentState` instance with `steps` populated.
+        """
+
+    async def stream(self, state: AgentState) -> AsyncIterator[StreamingEvent]:
+        """Drive the agent and yield `StreamingEvent` frames as they arrive.
+
+        Default implementation: call `run(state)` to completion, then
+        yield exactly one `done` event carrying the run-level summary.
+        Backward-compatible — every existing strategy gets a working
+        `stream()` for free, and `ChatSession.stream()` falls back to
+        the v0.1 buffer-then-stream path when this default is in
+        effect.
+
+        Concrete strategies that want per-token streaming override
+        this and yield `text` / `tool_call` / `tool_result` /
+        `thinking` events as the LLM produces them, then a terminal
+        `done` event. `ChatSession.stream()` detects the override
+        via `type(strategy).stream is not ReasoningStrategy.stream`
+        and switches to forwarding events directly to the wire.
+        """
+        result = await self.run(state)
+        yield StreamingEvent(
+            kind="done",
+            content={
+                "run_id": getattr(result, "run_id", ""),
+                "cost_usd": float(getattr(result, "cost_usd", 0.0) or 0.0),
+            },
+        )

agentforge_core/contracts/task.py

@@ -0,0 +1,73 @@
+"""`Task` — the locked pipeline-task ABC.
+
+feat-015 introduces deterministic, pre-LLM analysis steps. A `Task`
+emits a list of `Finding`s; `Pipeline` (in `agentforge.pipeline`)
+runs a DAG of tasks in parallel and hands the consolidated findings
+to the agent before the reasoning loop starts.
+
+Subclasses declare four class attributes:
+
+    name: ClassVar[str]
+        Unique identifier within a pipeline. Must be non-empty.
+    cost_estimate_usd: ClassVar[float]
+        Declared cost. ``0.0`` for deterministic tasks; positive for
+        tasks that call the LLM (charged against the agent's budget).
+    timeout_s: ClassVar[float]
+        Per-task timeout in seconds. The engine wraps each
+        ``run()`` call in ``asyncio.wait_for(timeout_s)``.
+    depends_on: ClassVar[tuple[str, ...]]
+        Names of tasks that must finish before this one starts.
+        The engine validates the DAG at construction (no cycles, no
+        dangling references).
+
+Subclasses implement ``run(context)`` and return ``list[Finding]``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Any, ClassVar
+
+from agentforge_core.contracts.finding import Finding
+
+
+class Task(ABC):
+    """A deterministic (or LLM-using) step in a `Pipeline`."""
+
+    name: ClassVar[str]
+    cost_estimate_usd: ClassVar[float] = 0.0
+    timeout_s: ClassVar[float] = 60.0
+    depends_on: ClassVar[tuple[str, ...]] = ()
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if inspect.isabstract(cls):
+            return
+        if "name" not in cls.__dict__ and not _inherited_attr(cls, "name"):
+            raise TypeError(
+                f"{cls.__name__} must declare class attribute 'name' (see Task docstring)."
+            )
+
+    @abstractmethod
+    async def run(self, context: Mapping[str, Any]) -> list[Finding]:
+        """Execute the task and emit findings.
+
+        Args:
+            context: Caller-provided dict, merged with prior tasks'
+                findings under the key ``"pipeline_findings_so_far"``.
+                Treat as read-only; do not mutate.
+
+        Returns:
+            A list of `Finding`s. An empty list is valid.
+        """
+
+
+def _inherited_attr(cls: type, attr: str) -> bool:
+    for base in cls.__mro__[1:]:
+        if base is Task or base is object:
+            continue
+        if attr in base.__dict__:
+            return True
+    return False