agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/contracts/tool.py

@@ -0,0 +1,71 @@
+"""`Tool` — the locked tool ABC.
+
+feat-001 ships the explicit-`input_schema` form. feat-004 layers a
+`@tool` decorator on top that infers the schema from a typed function's
+signature; the resulting object is still a `Tool` subclass under the
+hood.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from pydantic import BaseModel
+
+from agentforge_core.values.messages import ToolSpec
+
+
+class Tool(ABC):
+    """A typed callable the agent can invoke.
+
+    Subclasses declare three class attributes:
+
+        name: str                   — unique identifier the LLM sees
+        description: str            — human-readable usage description
+        input_schema: type[BaseModel]
+                                    — Pydantic v2 model for inputs
+
+    Plus override `run`. The decorator-based path in feat-004 builds
+    these attributes automatically from a typed function.
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str]
+    input_schema: ClassVar[type[BaseModel]]
+    capabilities: ClassVar[frozenset[str]] = frozenset()
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if inspect.isabstract(cls):
+            return
+        # Concrete subclasses must declare the three class attributes.
+        for attr in ("name", "description", "input_schema"):
+            if attr not in cls.__dict__ and not _inherited_attr(cls, attr):
+                raise TypeError(
+                    f"{cls.__name__} must declare class attribute '{attr}' (see Tool docstring)."
+                )
+
+    @abstractmethod
+    async def run(self, **kwargs: Any) -> Any:
+        """Execute the tool with kwargs validated against `input_schema`."""
+
+    def to_spec(self) -> ToolSpec:
+        """Provider-agnostic JSON-schema description for the LLM."""
+        return ToolSpec(
+            name=type(self).name,
+            description=type(self).description,
+            schema=type(self).input_schema.model_json_schema(),
+        )
+
+
+def _inherited_attr(cls: type, attr: str) -> bool:
+    """Walk the MRO (excluding `cls` itself and the abstract `Tool`)
+    looking for a non-`Tool` ancestor that declared `attr`."""
+    for base in cls.__mro__[1:]:
+        if base is Tool or base is object:
+            continue
+        if attr in base.__dict__:
+            return True
+    return False

agentforge_core/contracts/vector_store.py

@@ -0,0 +1,151 @@
+"""`VectorStore` — locked semantic-search ABC.
+
+A vector store is distinct from `MemoryStore` (the claim audit log):
+the shapes don't unify cleanly. Vectors search by similarity; claims
+filter by structured metadata + monotonic ULID ordering. We keep two
+separate ABCs and a user who wants similarity over claims puts the
+claim text into a vector store with `metadata={"claim_id": <id>}`.
+
+Per ADR-0007 the surface is locked at v0.1: adding a method is a
+major version bump. Optional capabilities (e.g. native ANN indexes,
+hybrid 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_vector_conformance` (lands alongside
+this contract).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from agentforge_core.values.vector import VectorItem, VectorMatch
+
+
+class VectorStore(ABC):
+    """Provider-agnostic vector index.
+
+    Implementations:
+      - declare a fixed `dimensions()` — every upserted vector and
+        every search vector must match
+      - normalise scores to cosine similarity in `[0, 1]` regardless
+        of internal distance metric (drivers convert at the boundary)
+      - implement metadata filtering as conjunctive equality on every
+        key/value pair the caller passes
+
+    Cross-driver invariants enforced by the conformance suite:
+      - upsert(id=X) followed by upsert(id=X) replaces the prior
+        record (write-through semantics)
+      - search returns at most `limit` items, sorted by score desc
+      - dimension mismatch on upsert or search raises `ValueError`
+    """
+
+    @abstractmethod
+    async def upsert(self, items: list[VectorItem]) -> None:
+        """Insert or replace `items`.
+
+        If two items in `items` share an id, the last one wins. Callers
+        wanting transactional all-or-nothing semantics should batch via
+        a single `upsert` call (drivers may still split the request
+        internally).
+
+        Raises:
+            ValueError: a vector's length does not match `dimensions()`.
+        """
+
+    @abstractmethod
+    async def search(
+        self,
+        query_vector: tuple[float, ...],
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        """Return the top-`limit` items by cosine similarity.
+
+        Args:
+            query_vector: Length must equal `dimensions()`.
+            limit: Maximum results to return. Drivers may return fewer.
+            filter_metadata: Conjunctive equality filter on the items'
+                `metadata` dict. `None` means no filtering.
+
+        Raises:
+            ValueError: dimension mismatch or `limit < 1`.
+        """
+
+    async def lexical_search(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        """Return the top-`limit` items by lexical (BM25-style) relevance.
+
+        Drivers that declare the ``"hybrid_search"`` capability MUST
+        override this. The default implementation raises
+        :class:`NotImplementedError` with a remediation message so
+        callers see a clear error rather than silently empty results.
+
+        Scores in the returned matches are normalised to ``[0, 1]`` by
+        max-score division within the result set (so the top match has
+        score 1.0; absolute BM25 magnitudes are not portable across
+        corpora). Cross-path comparability with `search()` scores is
+        NOT guaranteed — hybrid retrieval fuses by **rank**, not raw
+        score (see ``Retriever`` for RRF fusion).
+
+        Args:
+            query: The user's text query. Tokenisation is driver-specific
+                but typically lowercase + non-word split.
+            limit: Maximum results to return. Drivers may return fewer.
+            filter_metadata: Conjunctive equality filter on the items'
+                ``metadata`` dict. ``None`` means no filtering.
+
+        Raises:
+            NotImplementedError: This driver does not support hybrid
+                search (default behaviour).
+            ValueError: ``limit < 1``.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} does not support hybrid search. "
+            "Either swap to a VectorStore that declares the "
+            "'hybrid_search' capability (e.g. the built-in "
+            "InMemoryVectorStore) or open an issue requesting native "
+            "lexical support for this driver."
+        )
+
+    @abstractmethod
+    async def delete(self, ids: list[str]) -> int:
+        """Delete by id. Returns the number of items actually removed.
+
+        Unknown ids are silently ignored (no exception). Empty `ids`
+        list returns 0.
+        """
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release backing resources (connections, file handles)."""
+
+    @abstractmethod
+    def dimensions(self) -> int:
+        """The fixed vector dimensionality this store accepts.
+
+        Synchronous so callers can size storage / validate input
+        without a network round-trip.
+        """
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this driver supports.
+
+        Default empty set. Closed vocabulary (additions are minor
+        bumps): `"native_ann"` (driver uses an ANN index rather than
+        brute force), `"hybrid_search"` (BM25 + vector fusion),
+        `"transactions"` (multi-statement atomic upserts).
+        """
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        """True if this driver declares the given capability."""
+        return capability in self.capabilities()

agentforge_core/migrations/__init__.py

@@ -0,0 +1,14 @@
+"""Migration discovery + checksum helpers (feat-024).
+
+Drivers consume :func:`discover_migrations` to load their bundled
+migration files at startup. The contract type :class:`Migration`
++ :class:`Migrator` Protocol live in
+:mod:`agentforge_core.contracts.migrator`.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.migrations.discover import _checksum, discover_migrations
+from agentforge_core.migrations.template import render_migration_up
+
+__all__ = ["_checksum", "discover_migrations", "render_migration_up"]

agentforge_core/migrations/discover.py

@@ -0,0 +1,77 @@
+"""Filesystem migration discovery (feat-024).
+
+Drivers store migration files at
+``<package>/migrations/NNNN_<snake_name>.<ext>`` where ``<ext>`` is
+the driver's dialect (``sql`` / ``cypher`` / ``surql``). This
+module loads every matching file from a directory, hashes its
+contents, and returns a list of :class:`Migration` values sorted by
+id ascending.
+
+Filename convention is strict: the 4-digit prefix must be followed
+by an underscore and a snake-case name (``[a-z0-9_]+``). Files that
+don't match are silently ignored — operators can drop drafts and
+notes alongside without breaking the discovery.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from agentforge_core.contracts.migrator import Migration
+
+_FILENAME_RE = re.compile(r"^(\d{4})_([a-z0-9_]+)$")
+
+
+def _checksum(text: str) -> str:
+    """SHA-256 hex digest over ``text`` after LF normalisation."""
+    normalised = text.replace("\r\n", "\n").replace("\r", "\n")
+    return hashlib.sha256(normalised.encode("utf-8")).hexdigest()
+
+
+def discover_migrations(path: Path, *, suffix: str) -> list[Migration]:
+    """Load every ``NNNN_<name>.<suffix>`` file in ``path``.
+
+    Args:
+        path: Directory to scan. Non-existent or non-directory paths
+            return an empty list (so a driver without bundled
+            migrations is a no-op rather than an error).
+        suffix: File extension without the dot — e.g. ``"sql"`` for
+            Postgres, ``"cypher"`` for Neo4j.
+
+    Returns:
+        Migrations sorted by id ascending. Duplicate ids raise
+        :class:`ValueError`.
+    """
+    if not path.exists() or not path.is_dir():
+        return []
+
+    pattern = f"*.{suffix}"
+    seen_ids: set[str] = set()
+    migrations: list[Migration] = []
+    for file_path in sorted(path.glob(pattern)):
+        stem = file_path.stem
+        match = _FILENAME_RE.match(stem)
+        if match is None:
+            continue
+        migration_id, name = match.group(1), match.group(2)
+        if migration_id in seen_ids:
+            msg = (
+                f"Duplicate migration id {migration_id!r} in {path}; "
+                f"found at {file_path.name!r} but already seen."
+            )
+            raise ValueError(msg)
+        seen_ids.add(migration_id)
+        body = file_path.read_text(encoding="utf-8")
+        migrations.append(
+            Migration(
+                id=migration_id,
+                name=name,
+                up=body,
+                checksum=_checksum(body),
+            )
+        )
+
+    migrations.sort(key=lambda m: m.id)
+    return migrations

agentforge_core/migrations/template.py

@@ -0,0 +1,34 @@
+"""Migration body templating (feat-024 v0.3 follow-up).
+
+Per-driver migrators may need per-deployment variables in their
+migration bodies — Postgres `vector(${dimensions})` and SurrealDB
+`HNSW DIMENSION ${dimensions}` are the canonical cases. The
+templating syntax is Python's :class:`string.Template` with
+``${var}`` placeholders and ``$$`` for a literal ``$``.
+
+Important invariant: the migration's checksum is computed over the
+*un-substituted* template body. Re-deploying with a different
+variable value (e.g. swapping a 768-dim embedder for a 1536-dim
+one) produces the same checksum, so the framework's drift
+detection stays correct.
+
+Unknown placeholders left untouched (`safe_substitute` semantics)
+— template-key typos surface as SQL syntax errors at apply time
+rather than silently empty replacements.
+"""
+
+from __future__ import annotations
+
+from string import Template
+
+
+def render_migration_up(body: str, variables: dict[str, str] | None) -> str:
+    """Substitute ``${var}`` placeholders in ``body`` with ``variables``.
+
+    Returns ``body`` unchanged when ``variables`` is ``None`` or
+    empty. Unknown placeholders pass through unchanged so callers
+    can spot template-key typos as apply-time SQL errors.
+    """
+    if not variables:
+        return body
+    return Template(body).safe_substitute(**variables)

agentforge_core/observability/__init__.py

@@ -0,0 +1,18 @@
+"""Observability primitives — tracer helper, span attribute helpers.
+
+The OpenTelemetry **API** ships in core; the **SDK** + exporter ship
+in the optional `agentforge-otel` package. Without the SDK, all
+`tracer.start_*` calls degrade to the no-op `NonRecordingTracer` —
+near-zero cost. Consumers that want real spans install
+`agentforge-otel` and construct an `OpenTelemetryHook` (which
+configures the SDK provider once).
+"""
+
+from __future__ import annotations
+
+from agentforge_core.observability.tracing import (
+    SCOPE_NAME,
+    get_tracer,
+)
+
+__all__ = ["SCOPE_NAME", "get_tracer"]

agentforge_core/observability/tracing.py

@@ -0,0 +1,37 @@
+"""`get_tracer` — OpenTelemetry tracer accessor for framework spans.
+
+feat-009 §4.3 defines a span tree per run:
+
+    span: agent.run
+    └── span: strategy.iteration
+        ├── span: llm.call
+        ├── span: tool.<name>
+        └── span: evaluator.<name>
+
+The framework emits these spans unconditionally via the OTel API. When
+no SDK provider is configured (the default), `start_as_current_span`
+returns the no-op `NonRecordingSpan` and the cost is negligible. When
+`agentforge-otel` configures a real provider, the same call sites
+produce real spans + attributes that flow to the OTLP collector.
+
+`SCOPE_NAME` is the OTel instrumentation scope used for every framework
+span; `agentforge-otel` filters or routes on it.
+"""
+
+from __future__ import annotations
+
+from opentelemetry import trace
+from opentelemetry.trace import Tracer
+
+SCOPE_NAME = "agentforge"
+"""Instrumentation scope name for every framework-emitted span."""
+
+
+def get_tracer() -> Tracer:
+    """Return the framework's tracer.
+
+    Always safe to call — works whether or not an SDK provider is
+    installed. The same `Tracer` instance is fine across the
+    process; OTel handles thread/async safety internally.
+    """
+    return trace.get_tracer(SCOPE_NAME)

agentforge_core/production/__init__.py

@@ -0,0 +1,77 @@
+"""Production-rails primitives.
+
+Owned by the framework (per ADR-0010): every agent has these wired by
+default. Includes per-run cost guarding (`BudgetPolicy`), correlation
+context (`RunContext`, `current_run`), structured logging filter
+(`RunIdFilter`), cross-provider failover (`FallbackChain`), and the
+framework's exception hierarchy.
+"""
+
+from __future__ import annotations
+
+# `FallbackChain` is intentionally NOT re-exported here because it
+# imports `LLMClient`, which would create a circular import:
+# `agentforge_core/__init__.py` → contracts.llm (imports
+# `CapabilityNotSupported` from `production.exceptions`) →
+# triggers `production/__init__.py` → fallback (imports
+# LLMClient still being loaded). Users reach FallbackChain via the
+# top-level `from agentforge_core import FallbackChain` (loaded
+# after `production` finishes), or directly via
+# `agentforge_core.production.fallback`.
+from agentforge_core.production.budget import BudgetPolicy
+from agentforge_core.production.exceptions import (
+    AgentForgeError,
+    AuthenticationError,
+    BudgetExceeded,
+    CapabilityNotSupported,
+    GuardrailViolation,
+    ModelNotFoundError,
+    ModuleError,
+    ProviderError,
+    RateLimitError,
+    ServiceError,
+    TimeoutError,
+)
+from agentforge_core.production.log_filter import (
+    RunIdFilter,
+    install_run_id_filter,
+    uninstall_run_id_filter,
+)
+from agentforge_core.production.log_format import (
+    JsonFormatter,
+    install_json_formatter,
+    uninstall_json_formatter,
+)
+from agentforge_core.production.run_context import (
+    RunContext,
+    bind_run,
+    current_run,
+    new_run,
+    reset_run,
+)
+
+__all__ = [
+    "AgentForgeError",
+    "AuthenticationError",
+    "BudgetExceeded",
+    "BudgetPolicy",
+    "CapabilityNotSupported",
+    "GuardrailViolation",
+    "JsonFormatter",
+    "ModelNotFoundError",
+    "ModuleError",
+    "ProviderError",
+    "RateLimitError",
+    "RunContext",
+    "RunIdFilter",
+    "ServiceError",
+    "TimeoutError",
+    "bind_run",
+    "current_run",
+    "install_json_formatter",
+    "install_run_id_filter",
+    "new_run",
+    "reset_run",
+    "uninstall_json_formatter",
+    "uninstall_run_id_filter",
+]

agentforge_core/production/budget.py

@@ -0,0 +1,134 @@
+"""`BudgetPolicy` — per-run cost cap (per ADR-0010).
+
+Every reasoning strategy must call `BudgetPolicy.check` before every
+LLM call. Branching strategies (Tree-of-Thoughts, Multi-Agent
+Supervisor in feat-002) call `reserve` before fanning out so collective
+spend across parallel branches cannot exceed the cap.
+
+The policy aggregates spend across every provider used in a run. A
+multi-provider agent (e.g. reasoning model + cheap judge + embedding
+model per ADR-0018) shares one policy.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentforge_core.production.exceptions import (
+    BudgetExceeded,
+    GuardrailViolation,
+)
+
+
+class BudgetPolicy(BaseModel):
+    """Per-run cost and resource cap.
+
+    Attributes:
+        usd: Maximum spend in USD across all LLM/embedding providers
+            used during the run. Default $1.00 — small enough that the
+            naive 3-line agent never racks up surprise bills, large
+            enough for a meaningful exploration.
+        max_tokens: Maximum total tokens (input + output) consumed in
+            the run.
+        max_iterations: Maximum reasoning loop iterations.
+        error_streak_limit: Maximum consecutive tool/observation errors
+            before the loop aborts.
+    """
+
+    model_config = ConfigDict(strict=True, validate_assignment=True)
+
+    usd: float = Field(default=1.0, ge=0.0)
+    max_tokens: int = Field(default=200_000, ge=0)
+    max_iterations: int = Field(default=25, ge=1)
+    error_streak_limit: int = Field(default=3, ge=1)
+
+    spent_usd: float = Field(default=0.0, ge=0.0)
+    reserved_usd: float = Field(default=0.0, ge=0.0)
+    consumed_tokens: int = Field(default=0, ge=0)
+    iteration: int = Field(default=0, ge=0)
+    error_streak: int = Field(default=0, ge=0)
+
+    def remaining_usd(self) -> float:
+        """USD budget left after committed spend and reservations."""
+        return max(0.0, self.usd - self.spent_usd - self.reserved_usd)
+
+    def check(self) -> None:
+        """Raise if any cap is breached. Called before every LLM call.
+
+        Raises:
+            BudgetExceeded: USD or token cap exhausted.
+            GuardrailViolation: iteration or error-streak limit reached.
+        """
+        if self.spent_usd >= self.usd:
+            raise BudgetExceeded(
+                f"USD budget exhausted: spent ${self.spent_usd:.4f} of ${self.usd:.4f}"
+            )
+        if self.consumed_tokens >= self.max_tokens:
+            raise BudgetExceeded(
+                f"Token budget exhausted: {self.consumed_tokens} of {self.max_tokens}"
+            )
+        if self.iteration >= self.max_iterations:
+            raise GuardrailViolation(
+                f"Iteration cap reached: {self.iteration} of {self.max_iterations}"
+            )
+        if self.error_streak >= self.error_streak_limit:
+            raise GuardrailViolation(
+                f"Error streak limit hit: {self.error_streak} consecutive errors"
+            )
+
+    def reserve(self, usd: float) -> None:
+        """Pre-reserve USD budget for a planned spend.
+
+        Used by branching strategies that fan out: each branch reserves
+        before issuing the LLM call so the sum of reservations cannot
+        exceed the cap.
+
+        Raises:
+            ValueError: `usd` is negative.
+            BudgetExceeded: reservation would exceed remaining budget.
+        """
+        if usd < 0:
+            raise ValueError(f"Cannot reserve negative budget: {usd}")
+        if self.spent_usd + self.reserved_usd + usd > self.usd:
+            raise BudgetExceeded(
+                f"Cannot reserve ${usd:.4f}; only ${self.remaining_usd():.4f} "
+                f"of ${self.usd:.4f} remains"
+            )
+        self.reserved_usd += usd
+
+    def commit(self, actual_usd: float, tokens: int = 0) -> None:
+        """Record actual cost after a call completes.
+
+        Reservations are released by `release_reservation` separately;
+        commit only records spend.
+
+        Raises:
+            ValueError: negative cost or token count.
+        """
+        if actual_usd < 0:
+            raise ValueError(f"Cannot commit negative cost: {actual_usd}")
+        if tokens < 0:
+            raise ValueError(f"Cannot commit negative tokens: {tokens}")
+        self.spent_usd += actual_usd
+        self.consumed_tokens += tokens
+
+    def release_reservation(self, usd: float) -> None:
+        """Release a previously-reserved budget (e.g. on cancellation).
+
+        Idempotent at zero — releasing more than reserved clamps to 0.
+        """
+        if usd < 0:
+            raise ValueError(f"Cannot release negative reservation: {usd}")
+        self.reserved_usd = max(0.0, self.reserved_usd - usd)
+
+    def increment_iteration(self) -> None:
+        """Record one strategy iteration. Called by the strategy loop."""
+        self.iteration += 1
+
+    def record_error(self) -> None:
+        """Increment the error streak counter."""
+        self.error_streak += 1
+
+    def record_success(self) -> None:
+        """Reset the error streak counter."""
+        self.error_streak = 0