activegraph 1.0.0rc2__py3-none-any.whl

activegraph/llm/provider.py

@@ -0,0 +1,66 @@
+"""The `LLMProvider` Protocol every provider implements.
+
+CONTRACT v0.6 #3, extended in v0.7. Narrow, explicit, keyword-only.
+Shipped reference implementation is `AnthropicProvider`. Tests use
+`RecordedLLMProvider` + `RecordingLLMProvider`. The demo ships its
+own scripted provider.
+
+A provider does three things:
+  * `complete()`: run a single non-streaming completion. v0.7 adds
+    an optional `tools=` parameter; when non-empty, the model is
+    allowed to return tool_use blocks in the response.
+  * `estimate_cost()`: turn token counts into USD (Decimal).
+  * `count_tokens()`: provider-official input token count for the
+    prompt that's about to be sent. Used for pre-call budget gating
+    when `budget.max_cost_usd` is set; otherwise skipped (see
+    CONTRACT v0.6 #4 / decision 10).
+
+No streaming, no multi-model orchestration — those are deferred to
+v0.8+. Tool use IS in v0.7, but the loop is orchestrated by the
+runtime, not the provider: provider returns `tool_calls`, runtime
+invokes the tool, runtime re-calls `complete()` with the result
+echoed back as a `role="tool"` message.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Optional, Protocol, runtime_checkable
+
+from activegraph.llm.types import LLMMessage, LLMResponse
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: list[LLMMessage],
+        model: str,
+        max_tokens: int,
+        temperature: float,
+        top_p: float,
+        output_schema: Optional[type],
+        timeout_seconds: float,
+        tools: Optional[list[dict[str, Any]]] = None,
+    ) -> LLMResponse:
+        ...
+
+    def estimate_cost(
+        self,
+        *,
+        input_tokens: int,
+        output_tokens: int,
+        model: str,
+    ) -> Decimal:
+        ...
+
+    def count_tokens(
+        self,
+        *,
+        system: str,
+        messages: list[LLMMessage],
+        model: str,
+    ) -> int:
+        ...

activegraph/llm/recorded.py

@@ -0,0 +1,270 @@
+"""Fixture-based LLM providers for tests.
+
+CONTRACT v0.6 #12, plus decision-3 adjustment for `recorded_at`:
+
+  RecordedLLMProvider   — looks up fixtures by prompt hash. Tests run
+                          against this. Raises if a fixture is
+                          missing (so tests fail loud rather than
+                          regressing into live calls).
+
+  RecordingLLMProvider  — wraps another provider, mirrors every call
+                          to disk as a fixture file. Use once with
+                          `--record` to seed fixtures, then commit
+                          them. Marked with `@pytest.mark.records_llm`
+                          so they don't run in CI without explicit
+                          opt-in.
+
+Fixture file layout (`tests/fixtures/llm/<sha256_hex>.json`):
+
+    {
+      "prompt_hash": "<sha256_hex>",
+      "recorded_at": "2026-05-15T10:32:01Z",   # outside the hash
+      "model":       "claude-sonnet-4-5",
+      "prompt": {                              # only this hashes
+        "model": ..., "system": ..., "messages": [...],
+        "output_schema_name": ..., "output_schema_json": {...},
+        "max_tokens": ..., "temperature": ..., "top_p": ...,
+        "deterministic": ...
+      },
+      "response": {
+        "raw_text": "...", "parsed": {...},
+        "input_tokens": 0, "output_tokens": 0,
+        "cost_usd": "0.001", "latency_seconds": 0.0,
+        "model": "...", "finish_reason": "end_turn",
+        "seed": null, "provider_meta": {}
+      }
+    }
+
+`recorded_at` is intentionally OUTSIDE the hashed `prompt` payload so
+it doesn't perturb lookups but stays available for future debugging
+when fixtures drift.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any, Optional
+
+from activegraph.llm.errors import LLMBehaviorError
+from activegraph.llm.provider import LLMProvider
+from activegraph.llm.types import LLMMessage, LLMResponse
+
+
+def _now_iso() -> str:
+    return (
+        datetime.now(tz=timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def _canonical_prompt_payload(
+    *,
+    model: str,
+    system: str,
+    messages: list[LLMMessage],
+    output_schema: Optional[type],
+    max_tokens: int,
+    temperature: float,
+    top_p: float,
+    deterministic: bool,
+    tools: Optional[list[dict[str, Any]]] = None,
+) -> dict[str, Any]:
+    from activegraph.llm.prompt import schema_to_json
+
+    return {
+        "model": model,
+        "system": system,
+        "messages": [m.to_dict() for m in messages],
+        "output_schema_name": (
+            getattr(output_schema, "__name__", None) if output_schema else None
+        ),
+        "output_schema_json": schema_to_json(output_schema),
+        "max_tokens": int(max_tokens),
+        "temperature": float(temperature),
+        "top_p": float(top_p),
+        "deterministic": bool(deterministic),
+        # v0.7: tool definitions contribute to the prompt hash so a
+        # behavior gaining or losing a tool produces a different key.
+        "tools": list(tools) if tools else None,
+    }
+
+
+def _hash_payload(payload: dict[str, Any]) -> str:
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+# ---------- RecordedLLMProvider ---------------------------------------------
+
+
+class RecordedLLMProvider(LLMProvider):
+    """Reads fixtures from a directory keyed by prompt hash.
+
+    Tests construct one of these instead of an `AnthropicProvider`.
+    Missing fixtures raise so the test fails loud — there is no
+    silent fallthrough to a real call.
+    """
+
+    def __init__(self, fixtures_dir: str) -> None:
+        self._dir = fixtures_dir
+
+    # ---- LLMProvider methods ----
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: list[LLMMessage],
+        model: str,
+        max_tokens: int,
+        temperature: float,
+        top_p: float,
+        output_schema: Optional[type],
+        timeout_seconds: float,
+        tools: Optional[list[dict[str, Any]]] = None,
+    ) -> LLMResponse:
+        payload = _canonical_prompt_payload(
+            model=model,
+            system=system,
+            messages=messages,
+            output_schema=output_schema,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            deterministic=(temperature == 0.0 and top_p == 1.0),
+            tools=tools,
+        )
+        prompt_hash = _hash_payload(payload)
+        path = os.path.join(self._dir, f"{prompt_hash}.json")
+        if not os.path.exists(path):
+            raise LLMBehaviorError(
+                "llm.fixture_missing",
+                f"no recorded fixture for prompt_hash={prompt_hash} in {self._dir}",
+                payload_extras={"prompt_hash": prompt_hash, "fixtures_dir": self._dir},
+            )
+        with open(path, "r") as f:
+            data = json.load(f)
+        return _response_from_fixture(data["response"], output_schema)
+
+    def estimate_cost(
+        self, *, input_tokens: int, output_tokens: int, model: str
+    ) -> Decimal:
+        # Tests don't care about real pricing; just return zero.
+        return Decimal("0")
+
+    def count_tokens(
+        self, *, system: str, messages: list[LLMMessage], model: str
+    ) -> int:
+        total = len(system) + sum(len(m.content) for m in messages)
+        return max(1, total // 4)
+
+
+def _response_from_fixture(
+    rdata: dict[str, Any], output_schema: Optional[type]
+) -> LLMResponse:
+    parsed_raw = rdata.get("parsed")
+    parsed: Any = None
+    if parsed_raw is not None and output_schema is not None:
+        parsed = output_schema.model_validate(parsed_raw)
+    elif parsed_raw is not None:
+        parsed = parsed_raw
+    cost = rdata.get("cost_usd", "0")
+    if not isinstance(cost, Decimal):
+        cost = Decimal(str(cost))
+    return LLMResponse(
+        raw_text=rdata.get("raw_text", ""),
+        parsed=parsed,
+        input_tokens=int(rdata.get("input_tokens", 0) or 0),
+        output_tokens=int(rdata.get("output_tokens", 0) or 0),
+        cost_usd=cost,
+        latency_seconds=float(rdata.get("latency_seconds", 0.0) or 0.0),
+        model=rdata.get("model", "?"),
+        finish_reason=rdata.get("finish_reason", "end_turn"),
+        seed=rdata.get("seed"),
+        cache_hit=False,
+        provider_meta=dict(rdata.get("provider_meta", {}) or {}),
+    )
+
+
+# ---------- RecordingLLMProvider --------------------------------------------
+
+
+class RecordingLLMProvider(LLMProvider):
+    """Wraps a real provider and persists responses to fixtures.
+
+    Use this once (with `--record` opt-in) to seed `tests/fixtures/llm`
+    against the live Anthropic API, then commit the fixtures and run
+    tests against `RecordedLLMProvider` thereafter.
+    """
+
+    def __init__(self, inner: LLMProvider, fixtures_dir: str) -> None:
+        self._inner = inner
+        self._dir = fixtures_dir
+        os.makedirs(self._dir, exist_ok=True)
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: list[LLMMessage],
+        model: str,
+        max_tokens: int,
+        temperature: float,
+        top_p: float,
+        output_schema: Optional[type],
+        timeout_seconds: float,
+        tools: Optional[list[dict[str, Any]]] = None,
+    ) -> LLMResponse:
+        response = self._inner.complete(
+            system=system,
+            messages=messages,
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            output_schema=output_schema,
+            timeout_seconds=timeout_seconds,
+            tools=tools,
+        )
+        payload = _canonical_prompt_payload(
+            model=model,
+            system=system,
+            messages=messages,
+            output_schema=output_schema,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            deterministic=(temperature == 0.0 and top_p == 1.0),
+            tools=tools,
+        )
+        prompt_hash = _hash_payload(payload)
+        fixture = {
+            "prompt_hash": prompt_hash,
+            "recorded_at": _now_iso(),
+            "model": model,
+            "prompt": payload,
+            "response": response.to_dict(),
+        }
+        path = os.path.join(self._dir, f"{prompt_hash}.json")
+        with open(path, "w") as f:
+            json.dump(fixture, f, indent=2, sort_keys=True)
+        return response
+
+    def estimate_cost(
+        self, *, input_tokens: int, output_tokens: int, model: str
+    ) -> Decimal:
+        return self._inner.estimate_cost(
+            input_tokens=input_tokens, output_tokens=output_tokens, model=model
+        )
+
+    def count_tokens(
+        self, *, system: str, messages: list[LLMMessage], model: str
+    ) -> int:
+        return self._inner.count_tokens(
+            system=system, messages=messages, model=model
+        )

activegraph/llm/types.py

@@ -0,0 +1,130 @@
+"""LLM data types. Locked in v0.6, extended in v0.7.
+
+These shapes are part of the public contract:
+
+  LLMMessage     — single role-tagged message in the conversation history.
+                   v0.7 adds the "tool" role and `tool_use_id` so the
+                   LLM ↔ tool turn loop can echo results back.
+  ToolCall       — a single tool-call request returned by the model
+                   inside an `LLMResponse.tool_calls`. v0.7 addition.
+  LLMResponse    — what every provider's `complete()` returns. Carries
+                   raw text, parsed structured output (if a schema was
+                   requested), token counts, cost, latency, model id,
+                   finish reason, a `cache_hit` flag, and (v0.7) an
+                   optional list of `tool_calls`.
+
+Anything provider-specific (Anthropic stop reasons, retry-after
+seconds, etc.) goes into the `provider_meta` dict so the contract
+stays narrow.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Literal, Optional
+
+
+# v0.7: the assistant can return tool_use blocks; the user echoes results
+# back as a "tool" message. Anthropic uses content blocks with a
+# `tool_use_id`; we flatten to a string content + carry the id alongside.
+Role = Literal["user", "assistant", "tool"]
+
+
+@dataclass(frozen=True)
+class LLMMessage:
+    """One message in a chat-style prompt.
+
+    Anthropic's `system` prompt is conventionally separate from the
+    `messages` list, so we keep `system` out of this dataclass and pass
+    it as its own argument to `LLMProvider.complete()`. That keeps the
+    interface aligned with what the SDK actually wants.
+
+    CONTRACT v0.7: a `role="tool"` message echoes a tool result back to
+    the model. `tool_use_id` ties it to the originating tool_use block
+    from the previous assistant turn.
+    """
+
+    role: Role
+    content: str
+    tool_use_id: Optional[str] = None
+    tool_name: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"role": self.role, "content": self.content}
+        if self.tool_use_id is not None:
+            out["tool_use_id"] = self.tool_use_id
+        if self.tool_name is not None:
+            out["tool_name"] = self.tool_name
+        return out
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """A single tool-call request returned inside `LLMResponse.tool_calls`.
+
+    `id` is the provider-assigned identifier the assistant uses to
+    match up its tool_use block with the following tool result; the
+    runtime forwards it back as `LLMMessage.tool_use_id`. `name`
+    matches the tool's `@tool(name=...)`. `args` is the JSON-shaped
+    argument payload.
+    """
+
+    id: str
+    name: str
+    args: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "name": self.name, "args": dict(self.args)}
+
+
+@dataclass
+class LLMResponse:
+    raw_text: str
+    parsed: Optional[Any]
+    input_tokens: int
+    output_tokens: int
+    cost_usd: Decimal
+    latency_seconds: float
+    model: str
+    finish_reason: str
+    seed: Optional[int] = None
+    cache_hit: bool = False
+    provider_meta: dict[str, Any] = field(default_factory=dict)
+    # v0.7: when finish_reason indicates the model wants to call tools,
+    # `tool_calls` is non-empty and the runtime enters the turn loop
+    # instead of handing `parsed` to the handler.
+    tool_calls: Optional[list[ToolCall]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "raw_text": self.raw_text,
+            "parsed": _parsed_to_jsonable(self.parsed),
+            "input_tokens": int(self.input_tokens),
+            "output_tokens": int(self.output_tokens),
+            "cost_usd": str(self.cost_usd),
+            "latency_seconds": float(self.latency_seconds),
+            "model": self.model,
+            "finish_reason": self.finish_reason,
+            "seed": self.seed,
+            "cache_hit": bool(self.cache_hit),
+            "provider_meta": dict(self.provider_meta),
+            "tool_calls": (
+                [tc.to_dict() for tc in self.tool_calls]
+                if self.tool_calls
+                else None
+            ),
+        }
+
+
+def _parsed_to_jsonable(parsed: Any) -> Any:
+    """Make a Pydantic model JSON-safe for event payloads."""
+    if parsed is None:
+        return None
+    dump = getattr(parsed, "model_dump", None)
+    if callable(dump):
+        try:
+            return dump(mode="json")
+        except TypeError:
+            return dump()
+    return parsed

activegraph/observability/__init__.py

@@ -0,0 +1,61 @@
+"""Operator-facing observability surface. v0.8.
+
+Three pillars, all opt-in:
+
+- Structured logging (``configure_logging``) — JSON-line logger setup
+  matching the documented schema. Off by default; users with existing
+  ``logging`` config keep theirs.
+- Metrics (``Metrics`` protocol + ``NoOpMetrics`` + ``PrometheusMetrics``)
+  — three methods, fixed metric names. NoOp is the default.
+- Runtime introspection (``RuntimeStatus``) — frozen snapshot returned
+  by ``runtime.status()``.
+
+The framework never auto-configures any of these. A library that does
+is hostile to operators who already have their own config.
+"""
+
+from activegraph.observability.logging import (
+    LOG_FIELDS,
+    configure_logging,
+    get_logger,
+    runtime_log_extra,
+)
+from activegraph.observability.metrics import (
+    METRIC_NAMES,
+    Metrics,
+    NoOpMetrics,
+)
+from activegraph.observability.migration import (
+    MigrationReport,
+    MigrationRunReport,
+    migrate,
+)
+from activegraph.observability.prometheus import PrometheusMetrics
+from activegraph.observability.status import (
+    BehaviorInfo,
+    BudgetSnapshot,
+    EventSummary,
+    FrameSnapshot,
+    RuntimeStatus,
+    status_to_dict,
+)
+
+__all__ = [
+    "BehaviorInfo",
+    "BudgetSnapshot",
+    "EventSummary",
+    "FrameSnapshot",
+    "LOG_FIELDS",
+    "METRIC_NAMES",
+    "Metrics",
+    "MigrationReport",
+    "MigrationRunReport",
+    "NoOpMetrics",
+    "PrometheusMetrics",
+    "RuntimeStatus",
+    "configure_logging",
+    "get_logger",
+    "migrate",
+    "runtime_log_extra",
+    "status_to_dict",
+]