agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/production/run_context.py

@@ -0,0 +1,108 @@
+"""`RunContext` and the `current_run()` ContextVar.
+
+Per ADR-0010, every agent run carries a `run_id` propagated through
+async tasks via `contextvars.ContextVar`. Every log line, every span,
+every tool call, every claim record carries this id — there is no path
+to a log line without one.
+
+Generation: ULID (sortable, monotonic, 26 chars). Imported from
+`python-ulid`.
+
+Idempotency keys are derived from the run's `idempotency_seed` plus
+caller-supplied parts. Same parts within the same run produce the same
+key; different parts produce different keys; different runs produce
+different keys for the same parts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from contextvars import ContextVar, Token
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from ulid import ULID
+
+
+class RunContext(BaseModel):
+    """Per-run correlation primitive bound to the current async task."""
+
+    model_config = ConfigDict(strict=True, validate_assignment=True)
+
+    run_id: str
+    parent_run_id: str | None = None
+    started_at: datetime
+    idempotency_seed: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def idempotency_key_for(self, *parts: object) -> str:
+        """Stable key derived from `(idempotency_seed, *parts)`.
+
+        Tools that mutate external state read this to safely retry within
+        a single run. Same `parts` → same key; different `parts` →
+        different key; different run → different key.
+
+        Returns:
+            64-hex-character SHA-256 digest.
+        """
+        joined = self.idempotency_seed
+        for part in parts:
+            joined += "|" + str(part)
+        return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+_current_run: ContextVar[RunContext | None] = ContextVar("agentforge_current_run", default=None)
+
+
+def current_run() -> RunContext:
+    """Return the live `RunContext` bound to this async task.
+
+    Raises:
+        RuntimeError: no run is active. `current_run()` is only callable
+            from within an `Agent.run()` invocation.
+    """
+    ctx = _current_run.get()
+    if ctx is None:
+        raise RuntimeError(
+            "No active RunContext. current_run() can only be called inside "
+            "Agent.run() (or a tool / hook invoked from one)."
+        )
+    return ctx
+
+
+def new_run(
+    *,
+    parent_run_id: str | None = None,
+    task: str | None = None,
+) -> RunContext:
+    """Create a new `RunContext` with a fresh ULID `run_id`.
+
+    Does NOT bind it to the ContextVar — call `bind_run` for that.
+    """
+    run_id = str(ULID())
+    seed_input = f"{run_id}|{task or ''}"
+    seed = hashlib.sha256(seed_input.encode("utf-8")).hexdigest()[:32]
+    return RunContext(
+        run_id=run_id,
+        parent_run_id=parent_run_id,
+        started_at=datetime.now(UTC),
+        idempotency_seed=seed,
+    )
+
+
+def bind_run(ctx: RunContext) -> Token[RunContext | None]:
+    """Bind a `RunContext` to the current async scope.
+
+    Returns the `Token` that `reset_run` consumes. Always pair with
+    `reset_run` in a try/finally to avoid leaking context across runs.
+    """
+    return _current_run.set(ctx)
+
+
+def reset_run(token: Token[RunContext | None]) -> None:
+    """Reset the ContextVar to its prior value.
+
+    Pair with `bind_run`; safe to call exactly once per token.
+    """
+    _current_run.reset(token)

agentforge_core/resolver/__init__.py

@@ -0,0 +1,38 @@
+"""Module resolver — maps name → registered class.
+
+Per ADR-0004, modules normally register via Python entry points
+(loaded by feat-010). For feat-001 we ship the in-process registry
+that the entry-point loader will populate. Anyone can register a
+class manually with `@register("strategies", "my-loop")` for an
+in-repo or test-only module.
+
+A model identifier string `"<provider>:<model_id>"` is parsed by
+`parse_model_string`; the leading provider is looked up as an entry
+in `agentforge.providers`, the trailing piece is treated as the
+model id and passed through to the provider constructor (per
+feat-003).
+"""
+
+from __future__ import annotations
+
+from agentforge_core.resolver.discover import (
+    discover_entry_points,
+    reset_discovery,
+)
+from agentforge_core.resolver.resolve import (
+    Resolver,
+    parse_model_string,
+    register,
+    register_embedding_provider,
+    register_provider,
+)
+
+__all__ = [
+    "Resolver",
+    "discover_entry_points",
+    "parse_model_string",
+    "register",
+    "register_embedding_provider",
+    "register_provider",
+    "reset_discovery",
+]

agentforge_core/resolver/discover.py

@@ -0,0 +1,145 @@
+"""Entry-point discovery for feat-010.
+
+Scans `importlib.metadata.entry_points()` for groups starting with
+`agentforge.` and registers each entry against the global resolver.
+A group named `agentforge.<category>` (e.g. `agentforge.providers`,
+`agentforge.memory`) maps to the resolver's `<category>` slot.
+
+The scan runs lazily — `Resolver.resolve` calls `ensure_discovered()`
+on first use. Tests that want to start with a clean slate can call
+`Resolver.global_().clear()` (also resets the discovery cache).
+
+Conflict handling: if two distributions register under the same
+`(category, name)` pair, the first one to register wins (entry-point
+iteration order is the source). The resolver's own `register`
+method raises `ModuleError` when the second registration arrives at
+a different class — we catch that, log, and let the first win. This
+matches the spec's §8 "Conflict resolution" entry while keeping the
+runtime predictable.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.values.module import ModuleInfo
+
+if TYPE_CHECKING:
+    from agentforge_core.resolver.resolve import Resolver
+
+_log = logging.getLogger("agentforge.resolver")
+
+_GROUP_PREFIX = "agentforge."
+
+# Module-level state held on a mutable list to avoid `global` (PLW0603).
+_discovered: list[bool] = [False]
+# Cache of resolved ModuleInfo per registered entry — keyed by
+# `(category, name)`. Populated alongside the registry by
+# `discover_entry_points`.
+_module_info_cache: dict[tuple[str, str], ModuleInfo] = {}
+
+
+def ensure_discovered(resolver: Resolver) -> None:
+    """Lazy hook — runs `discover_entry_points` once per resolver lifetime.
+
+    Resolver methods that need entry-point-registered modules call
+    this on entry. Safe to call repeatedly; only the first call does
+    work.
+    """
+    if _discovered[0]:
+        return
+    discover_entry_points(resolver)
+
+
+def discover_entry_points(resolver: Resolver, *, force: bool = False) -> int:
+    """Scan `agentforge.*` entry points and register them on `resolver`.
+
+    Args:
+        resolver: Target resolver — typically `Resolver.global_()`.
+        force: When `True`, re-scan even if discovery has already run
+            (used by tests and by `Resolver.clear()`).
+
+    Returns:
+        Number of entries registered (excluding conflicts skipped).
+    """
+    if _discovered[0] and not force:
+        return 0
+    registered = 0
+    eps = entry_points()
+    # `entry_points()` returns an `EntryPoints` selectable view on
+    # 3.10+; iterate by group prefix.
+    for ep in eps:
+        if not ep.group.startswith(_GROUP_PREFIX):
+            continue
+        category = ep.group[len(_GROUP_PREFIX) :]
+        try:
+            cls = ep.load()
+        except Exception as exc:
+            _log.warning(
+                "skipping entry point %s.%s: load failed (%s: %s)",
+                ep.group,
+                ep.name,
+                type(exc).__name__,
+                exc,
+            )
+            continue
+        if not isinstance(cls, type):
+            _log.warning(
+                "skipping entry point %s.%s: target %r is not a class",
+                ep.group,
+                ep.name,
+                cls,
+            )
+            continue
+        try:
+            resolver.register(category, ep.name, cls)
+        except ModuleError as exc:
+            # Another distribution already registered the same key —
+            # first wins per spec §8. Log and move on.
+            _log.warning(
+                "entry-point conflict %s.%s ignored: %s",
+                ep.group,
+                ep.name,
+                exc,
+            )
+            continue
+        # Carry the source distribution metadata for `list_installed`.
+        dist = ep.dist
+        info = ModuleInfo(
+            category=category,
+            name=ep.name,
+            package=dist.name if dist is not None else None,
+            version=dist.version if dist is not None else None,
+            cls_qualname=f"{cls.__module__}.{cls.__qualname__}",
+        )
+        _module_info_cache[(category, ep.name)] = info
+        registered += 1
+    _discovered[0] = True
+    return registered
+
+
+def reset_discovery() -> None:
+    """Clear the discovery cache. Called from `Resolver.clear()` and
+    by tests that want a clean slate."""
+    _discovered[0] = False
+    _module_info_cache.clear()
+
+
+def module_info_for(category: str, name: str, cls: type) -> ModuleInfo:
+    """Return cached `ModuleInfo` if the entry was discovered via
+    entry points; otherwise synthesise one from `cls.__module__` /
+    `__qualname__` (for `@register`-registered classes).
+    """
+    cached = _module_info_cache.get((category, name))
+    if cached is not None:
+        return cached
+    return ModuleInfo(
+        category=category,
+        name=name,
+        package=None,
+        version=None,
+        cls_qualname=f"{cls.__module__}.{cls.__qualname__}",
+    )

agentforge_core/resolver/resolve.py

@@ -0,0 +1,168 @@
+"""In-process module registry + model-string parsing.
+
+feat-010 will extend `Resolver` to scan `importlib.metadata` entry
+points; until then, anything in this registry was put there by an
+explicit `register(...)` call. The two-phase design lets us write
+integration tests in feat-001 without entry-point machinery.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.resolver.discover import (
+    ensure_discovered,
+    module_info_for,
+)
+
+if TYPE_CHECKING:
+    from agentforge_core.values.module import ModuleInfo
+
+T = TypeVar("T", bound=type)
+
+
+class Resolver:
+    """Maps `(category, name) -> registered class`.
+
+    A single global instance is shared by `register()` and `Agent`.
+    Tests reset it via `Resolver.global_().clear()`.
+    """
+
+    def __init__(self) -> None:
+        self._registry: dict[tuple[str, str], type] = {}
+
+    @classmethod
+    def global_(cls) -> Resolver:
+        global _GLOBAL_RESOLVER  # noqa: PLW0603 — singleton intentional
+        if _GLOBAL_RESOLVER is None:
+            _GLOBAL_RESOLVER = cls()
+        return _GLOBAL_RESOLVER
+
+    def register(self, category: str, name: str, cls: type) -> None:
+        key = (category, name)
+        if key in self._registry and self._registry[key] is not cls:
+            raise ModuleError(
+                f"Cannot register {cls.__name__} as {category}:{name}; "
+                f"already registered to {self._registry[key].__name__}."
+            )
+        self._registry[key] = cls
+
+    def resolve(self, category: str, name: str) -> type:
+        # Lazy entry-point discovery (feat-010): the first call to
+        # `resolve()` triggers a one-shot scan of installed
+        # `agentforge.*` entry points so packages-by-pip-install are
+        # available without explicit imports.
+        ensure_discovered(self)
+        key = (category, name)
+        if key not in self._registry:
+            available = sorted(n for c, n in self._registry if c == category)
+            raise ModuleError(
+                f"No module registered for {category}:{name!r}. "
+                f"Registered {category}: {available or '(none)'}. "
+                f"Install the relevant agentforge-* package or register "
+                f"a custom class with @register('{category}', '{name}')."
+            )
+        return self._registry[key]
+
+    def list_(self, category: str | None = None) -> list[tuple[str, str, type]]:
+        ensure_discovered(self)
+        items = [(c, n, cls) for (c, n), cls in self._registry.items()]
+        if category is not None:
+            items = [item for item in items if item[0] == category]
+        return sorted(items, key=lambda item: (item[0], item[1]))
+
+    def list_installed(self, category: str | None = None) -> list[ModuleInfo]:
+        """Return `ModuleInfo` for every registered module (feat-010).
+
+        Triggers entry-point discovery first so the returned list
+        reflects every `agentforge-*` package pip-installed in the
+        active environment plus anything registered manually via
+        `@register`.
+        """
+        ensure_discovered(self)
+        items: list[ModuleInfo] = []
+        for (cat, name), cls in self._registry.items():
+            if category is not None and cat != category:
+                continue
+            items.append(module_info_for(cat, name, cls))
+        return sorted(items, key=lambda m: (m.category, m.name))
+
+    def clear(self) -> None:
+        """Empty the in-process registry.
+
+        Does NOT reset the entry-point discovery cache — call
+        `reset_discovery()` separately if you need a fresh scan on
+        the next `resolve()`. Typical tests want a clean slate
+        without re-triggering discovery; tests that install fake
+        entry points opt in to the rediscovery explicitly.
+        """
+        self._registry.clear()
+
+
+_GLOBAL_RESOLVER: Resolver | None = None
+
+
+def register(category: str, name: str) -> Callable[[T], T]:
+    """Decorator: register a class under `(category, name)` in the global resolver.
+
+    Example:
+        @register("strategies", "my-loop")
+        class MyLoop(ReasoningStrategy):
+            ...
+    """
+
+    def decorator(cls: T) -> T:
+        Resolver.global_().register(category, name, cls)
+        return cls
+
+    return decorator
+
+
+def register_provider(name: str) -> Callable[[T], T]:
+    """Decorator: register an `LLMClient` subclass as a model provider.
+
+    Convenience wrapper around `register("providers", name)` — used by
+    every concrete provider package (`agentforge-bedrock`,
+    `agentforge-anthropic`, ...). The provider name corresponds to the
+    leading token in a model string: `register_provider("bedrock")`
+    enables `Agent(model="bedrock:...")`.
+
+    Example:
+        @register_provider("bedrock")
+        class BedrockClient(LLMClient):
+            def __init__(self, *, model_id: str, region: str = "us-east-1") -> None:
+                ...
+    """
+    return register("providers", name)
+
+
+def register_embedding_provider(name: str) -> Callable[[T], T]:
+    """Decorator: register an `EmbeddingClient` subclass as an embedding provider.
+
+    Mirrors `register_provider` but under the `"embeddings"` category
+    so chat models and embedding models can share a provider name
+    without colliding (e.g. `bedrock:anthropic.claude-...` for chat,
+    `embeddings:bedrock:amazon.titan-embed-text-v2:0` for embeddings).
+    """
+    return register("embeddings", name)
+
+
+def parse_model_string(model_str: str) -> tuple[str, str]:
+    """Parse `"<provider>:<model_id>"` into `(provider, model_id)`.
+
+    Raises:
+        ModuleError: if the string does not contain a `:`.
+    """
+    if ":" not in model_str:
+        raise ModuleError(
+            f"Invalid model string {model_str!r}: expected '<provider>:<model_id>' "
+            f"(for example, 'anthropic:claude-sonnet-4.7')."
+        )
+    provider, _, model_id = model_str.partition(":")
+    if not provider or not model_id:
+        raise ModuleError(
+            f"Invalid model string {model_str!r}: provider and model_id must both be non-empty."
+        )
+    return provider, model_id

agentforge_core/testing/__init__.py

@@ -0,0 +1,45 @@
+"""Testing utilities — conformance suites that every driver must pass.
+
+Per ADR-0007 and feat-016, every ABC in `agentforge-core` ships a
+shared conformance suite. External module packages (e.g.
+`agentforge-memory-postgres`) import these helpers to verify their
+drivers against the locked contract.
+
+The suites live in core (rather than the runtime package) so module
+authors only need `agentforge-core` to test conformance — they don't
+have to depend on the full runtime.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.testing.conformance import (
+    run_chat_history_conformance,
+    run_embedding_conformance,
+    run_graph_conformance,
+    run_hybrid_search_conformance,
+    run_input_validator_conformance,
+    run_memory_conformance,
+    run_output_validator_conformance,
+    run_reranker_conformance,
+    run_strategy_conformance,
+    run_task_conformance,
+    run_tool_gate_conformance,
+    run_truncation_conformance,
+    run_vector_conformance,
+)
+
+__all__ = [
+    "run_chat_history_conformance",
+    "run_embedding_conformance",
+    "run_graph_conformance",
+    "run_hybrid_search_conformance",
+    "run_input_validator_conformance",
+    "run_memory_conformance",
+    "run_output_validator_conformance",
+    "run_reranker_conformance",
+    "run_strategy_conformance",
+    "run_task_conformance",
+    "run_tool_gate_conformance",
+    "run_truncation_conformance",
+    "run_vector_conformance",
+]