activegraph 1.0.0rc2__py3-none-any.whl

activegraph/tools/errors.py

@@ -0,0 +1,320 @@
+"""Tool-side errors. CONTRACT v0.7 #6, + v1.0 PR-D format migration.
+
+Three surface types:
+
+- :class:`ToolError` — structured failure from a tool body. Carries a
+  ``reason`` code that the runtime merges into
+  ``tool.responded.payload.error`` and into the wrapping behavior's
+  ``behavior.failed`` event.
+
+- :class:`MissingToolError` — raised at runtime startup when an
+  ``@llm_behavior`` declares a tool name the runtime cannot find.
+  Stays a plain RuntimeError subclass through PR-D; PR-E re-parents.
+
+- :class:`UnknownToolError` — raised when an LLM response asks for a
+  tool the behavior did not declare. Caught by the runtime and
+  surfaced as ``behavior.failed reason="tool.unknown_tool"``.
+
+PR-D migrates ``ToolError`` and ``UnknownToolError`` to
+:class:`activegraph.errors.ExecutionError`. The
+``(reason, message, payload_extras)`` constructor on ``ToolError`` is
+preserved; per-reason prose lives in ``_TOOL_REASON_PROSE``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.errors import ExecutionError, RegistrationError
+
+
+def _tool_prose_timeout(message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool invocation exceeded its declared `timeout_seconds`:\n  {message}",
+        "Tools declare a per-call timeout at the decorator. The runtime "
+        "enforces it so a slow or hung tool can't stall the whole behavior "
+        "loop. A timed-out call returns a structured failure to the calling "
+        "behavior; the behavior decides whether to retry, fall back, or "
+        "fail.",
+        "If the timeout is too aggressive for the expected work, raise the "
+        "tool's `timeout_seconds`. If the timeout is hitting because the "
+        "endpoint is slow under contention, the right answer is usually a "
+        "narrower retry policy in the calling behavior rather than a higher "
+        "ceiling.",
+    )
+
+
+def _tool_prose_network_error(message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool call failed with a network error:\n  {message}",
+        "Tools that reach the network can fail for many reasons (DNS, TLS, "
+        "connection drop, mid-transfer error). The framework treats these as "
+        "structured tool failures rather than untyped exceptions so the "
+        "calling behavior can read `reason='tool.network_error'` from the "
+        "tool.responded event payload and decide how to proceed.",
+        "Inspect the tool.responded event for the full underlying error. "
+        "Common recoveries: re-run after the network stabilizes, switch to "
+        "RecordedTool for offline replay, or add explicit retry-on-network "
+        "logic in the calling behavior.",
+    )
+
+
+def _tool_prose_invalid_input(message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool was invoked with arguments that didn't match its input schema:\n  {message}",
+        "Tools declare typed input via Pydantic models. The framework "
+        "validates arguments before invoking the body so a malformed call "
+        "fails at the boundary with a clear error instead of producing a "
+        "stack trace inside the tool. This is the same Pydantic invariant "
+        "the LLM output_schema enforces — typed input is the contract.",
+        "Check the tool's declared input schema (in the @tool decorator) "
+        "against the arguments the LLM produced. If the LLM is producing "
+        "consistently malformed args, the prompt may need an explicit "
+        "example of correct invocation; if the tool's schema is too "
+        "strict, relax the relevant field.",
+    )
+
+
+def _tool_prose_invalid_output(message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool returned a value that didn't match its output schema:\n  {message}",
+        "Tools declare typed output via Pydantic models. The framework "
+        "validates the return value before merging it into the "
+        "tool.responded event so downstream behaviors can rely on the "
+        "shape. A schema-violating return is a bug in the tool body — "
+        "the audit trail would lie if the framework silently coerced it.",
+        "Fix the tool body to return data matching the declared schema, "
+        "or relax the schema if the actual return shape is correct. The "
+        "underlying value is in the tool.responded payload for inspection."
+    )
+
+
+def _tool_prose_execution_error(message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool body raised an exception:\n  {message}",
+        "When a tool body raises, the framework catches it and surfaces a "
+        "structured failure so the calling behavior can read "
+        "`reason='tool.execution_error'` from tool.responded and decide "
+        "whether to retry or fail. The raw exception is preserved in "
+        "payload_extras for diagnosis without leaking it past the tool "
+        "boundary.",
+        "Inspect tool.responded.payload_extras for the original exception "
+        "type and traceback. If the failure is intrinsic to the tool's "
+        "inputs (bad data), tighten the input validation. If it's "
+        "intermittent, add retry-on-execution-error logic to the calling "
+        "behavior.",
+    )
+
+
+def _tool_prose_fixture_missing(message: str) -> tuple[str, str, str]:
+    return (
+        f"A RecordedTool has no fixture for this argument combination:\n  {message}",
+        "RecordedTool replays a directory of recorded tool responses keyed "
+        "by tool name + argument hash. A missing fixture means the live "
+        "arguments don't match any recorded invocation — either the tool's "
+        "arguments changed since recording (a behavior edit, an upstream "
+        "data shift), or this is a new invocation that was never recorded.",
+        "Re-record the fixture from a live run with the current arguments:\n"
+        "    1. Switch the tool to its live implementation\n"
+        "    2. Run the goal once to produce live responses\n"
+        "    3. The recorder writes new fixtures alongside the existing ones\n"
+        "    4. Subsequent runs against RecordedTool replay them\n"
+        "\n"
+        "Or diff the args against the recorded hash to find the drift.",
+    )
+
+
+_TOOL_REASON_PROSE: dict[str, Any] = {
+    "tool.timeout": _tool_prose_timeout,
+    "tool.network_error": _tool_prose_network_error,
+    "tool.invalid_input": _tool_prose_invalid_input,
+    "tool.invalid_output": _tool_prose_invalid_output,
+    "tool.execution_error": _tool_prose_execution_error,
+    "tool.fixture_missing": _tool_prose_fixture_missing,
+}
+
+
+def _tool_fallback_prose(reason: str, message: str) -> tuple[str, str, str]:
+    return (
+        f"A tool invocation failed with reason {reason!r}:\n  {message}",
+        f"The runtime catches structured failures from tool bodies and merges "
+        f"them into the emitted tool.responded event, where the calling "
+        f"behavior can read `reason={reason!r}` and decide how to proceed. "
+        f"The exception you're seeing is the underlying carrier.",
+        f"Inspect the tool.responded event in the trace:\n"
+        f"    activegraph inspect <store> --tail 50\n"
+        f"\n"
+        f"The full message is preserved verbatim above; check the tool's "
+        f"documentation for reason {reason!r}.",
+    )
+
+
+class MissingToolError(RegistrationError, RuntimeError):
+    """An ``@llm_behavior`` declares a tool name the runtime cannot find
+    in its tool registry at startup.
+
+    Fires at construction time, not at LLM-call time — the runtime
+    validates the declared tools once when the behavior registers.
+    Multi-inherits :class:`RuntimeError` for back-compat.
+    """
+
+    _doc_slug = "missing-tool-error"
+
+    def __init__(
+        self,
+        tool_name: str,
+        *,
+        behavior_name: Optional[str] = None,
+        registered: Optional[tuple[str, ...]] = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.behavior_name = behavior_name
+        self.registered = registered or ()
+        ctx: dict[str, Any] = {"tool_name": tool_name}
+        if behavior_name:
+            ctx["behavior_name"] = behavior_name
+        if self.registered:
+            ctx["registered"] = list(self.registered)
+        sample = ""
+        if self.registered:
+            preview = ", ".join(repr(n) for n in list(self.registered)[:6])
+            extra = f" (+{len(self.registered) - 6} more)" if len(self.registered) > 6 else ""
+            sample = f"\n  registered tools: {preview}{extra}"
+        on_behavior = (
+            f" on @llm_behavior {behavior_name!r}" if behavior_name else ""
+        )
+        RegistrationError.__init__(
+            self,
+            f"no tool named {tool_name!r} is registered",
+            what_failed=(
+                f"@llm_behavior declares the tool {tool_name!r}{on_behavior}, "
+                f"but the Runtime's tool registry has no tool by that name.{sample}"
+            ),
+            why=(
+                "@llm_behavior validates its declared tools at startup so a "
+                "misconfiguration fails before any LLM call burns budget. "
+                "A missing tool at LLM-call time would either produce "
+                "UnknownToolError on every invocation (cost without "
+                "progress) or silently drop the call (which would corrupt "
+                "the audit trail). Validation at registration prevents both."
+            ),
+            how_to_fix=(
+                "Either register the tool with the runtime:\n"
+                "    rt = Runtime(graph, tools=[my_tool, ...])\n"
+                "or, if the tool comes from a pack, load the pack:\n"
+                "    rt.load_pack(my_pack)\n"
+                "\n"
+                "For pack-scoped tools, use the canonical name "
+                "`'pack_name.tool_name'` in the @llm_behavior's "
+                "`tools=[...]` argument."
+            ),
+            context=ctx,
+        )
+
+
+class UnknownToolError(ExecutionError, RuntimeError):
+    """Raised when an LLM response calls a tool the behavior didn't declare.
+
+    The runtime catches it during the LLM tool-loop and surfaces it as
+    ``behavior.failed reason="tool.unknown_tool"``. Multi-inherits
+    RuntimeError so user code that catches RuntimeError around runtime
+    operations continues to work.
+    """
+
+    _doc_slug = "unknown-tool-error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        tool_name: Optional[str] = None,
+        behavior_name: Optional[str] = None,
+        declared_tools: Optional[tuple[str, ...]] = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.behavior_name = behavior_name
+        self.declared_tools = declared_tools or ()
+        ctx: dict[str, Any] = {"message": message}
+        if tool_name is not None:
+            ctx["tool_name"] = tool_name
+        if behavior_name is not None:
+            ctx["behavior_name"] = behavior_name
+        if self.declared_tools:
+            ctx["declared_tools"] = list(self.declared_tools)
+        declared_list = (
+            ", ".join(repr(t) for t in self.declared_tools)
+            if self.declared_tools
+            else "(none declared)"
+        )
+        ExecutionError.__init__(
+            self,
+            message,
+            what_failed=(
+                f"An LLM response asked to invoke a tool that the calling "
+                f"behavior did not declare.\n"
+                f"  tool requested: {tool_name!r}\n"
+                f"  declared on behavior {behavior_name!r}: {declared_list}"
+            ),
+            why=(
+                "@llm_behavior declares the exact set of tools the wrapped "
+                "behavior is allowed to invoke. The runtime refuses any other "
+                "tool call rather than silently execute it — an undeclared "
+                "tool could perform side effects the behavior's audit trail "
+                "doesn't account for, which would break replay determinism."
+            ),
+            how_to_fix=(
+                f"Either add {tool_name!r} to the @llm_behavior's `tools=[...]` "
+                f"list (and confirm the tool is registered with @tool), or "
+                f"adjust the prompt so the model stops asking for it. If the "
+                f"model is consistently asking for an undeclared tool, the "
+                f"prompt may be implying capabilities the behavior doesn't "
+                f"have — be explicit about which tools are available."
+            ),
+            context=ctx,
+        )
+
+
+class ToolError(ExecutionError, Exception):
+    """Structured failure from inside a tool invocation.
+
+    ``reason`` must be one of the v0.7 codes:
+
+      tool.timeout, tool.network_error, tool.invalid_input,
+      tool.invalid_output, tool.execution_error,
+      tool.unknown_tool, tool.fixture_missing,
+      budget.tool_calls_exhausted, budget.cost_exhausted.
+
+    Constructor signature ``(reason, message, *, payload_extras=)`` is
+    preserved from v0.7 so the internal raise sites in tool bodies do
+    not change. The structured-format fields are auto-derived from
+    ``reason`` via ``_TOOL_REASON_PROSE``.
+    """
+
+    _doc_slug = "tool-error"
+
+    def __init__(
+        self,
+        reason: str,
+        message: str,
+        *,
+        payload_extras: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self.reason = reason
+        self.payload_extras = dict(payload_extras or {})
+        prose_fn = _TOOL_REASON_PROSE.get(reason)
+        if prose_fn is None:
+            what_failed, why, how_to_fix = _tool_fallback_prose(reason, message)
+        else:
+            what_failed, why, how_to_fix = prose_fn(message)
+        ExecutionError.__init__(
+            self,
+            f"{reason}: {message}",
+            what_failed=what_failed,
+            why=why,
+            how_to_fix=how_to_fix,
+            context={
+                "reason": reason,
+                "message": message,
+                "payload_extras": self.payload_extras,
+            },
+        )

activegraph/tools/graph_query.py

@@ -0,0 +1,94 @@
+"""Reference tool: graph_query. CONTRACT v0.7 #16.
+
+`graph_query` is a tool whose body operates on the graph itself —
+the demonstration that the tool primitive is general, not just an
+"external API" escape hatch. It goes through the same event-sourced
+invocation path as any other tool: `tool.requested` / `tool.responded`
+events, the same cache, the same budget.
+
+Per CONTRACT v0.7 #5, the `ToolContext` deliberately does NOT carry
+a graph reference — tools that need the graph close over it via a
+factory at registration time. `make_graph_query_tool(graph)` returns
+a Tool bound to the supplied graph.
+
+Per CONTRACT v0.7 #7 (tool-determinism decision), `graph_query` is
+marked `deterministic=True`: given the same graph state, it returns
+the same answer. But replay still serves from cache by default; the
+`Runtime(replay_reinvoke_deterministic=True)` opt-in is what lets
+deterministic tools actually re-invoke during replay. Reasoning:
+even a deterministic tool's correctness depends on the reconstructed
+graph state matching the recorded state at the moment of the call,
+and that's a strong invariant — cheaper and more honest to serve
+from cache.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from activegraph.tools.base import Tool
+from activegraph.tools.context import ToolContext
+
+
+class ObjectRef(BaseModel):
+    id: str
+    type: str
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphQueryInput(BaseModel):
+    object_type: str = Field(description="The object type to query.")
+    where: Optional[dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Optional filter: dotted-path keys, literal or {op: value} values. "
+            "Same semantics as Graph.query(where=...)."
+        ),
+    )
+    limit: int = Field(default=50, ge=1, le=500)
+
+
+class GraphQueryOutput(BaseModel):
+    refs: list[ObjectRef]
+    truncated: bool = False
+
+
+def make_graph_query_tool(graph) -> Tool:
+    """Factory: produces a `graph_query` tool bound to the given Graph.
+
+    Returns a Tool, NOT a registered callable — the caller is expected
+    to either pass it directly into `@llm_behavior(tools=[...])` or
+    into `Runtime(tools=[...])`. We do NOT push it into the global
+    `@tool` registry: graph-bound tools are runtime-specific, and a
+    global registry would silently couple tools to the first graph
+    that constructed one.
+    """
+
+    def fn(args: GraphQueryInput, ctx: ToolContext) -> GraphQueryOutput:
+        results = graph.query(object_type=args.object_type, where=args.where)
+        truncated = len(results) > args.limit
+        results = results[: args.limit]
+        return GraphQueryOutput(
+            refs=[
+                ObjectRef(id=o.id, type=o.type, data=dict(o.data))
+                for o in results
+            ],
+            truncated=truncated,
+        )
+
+    return Tool(
+        name="graph_query",
+        fn=fn,
+        description=(
+            "Query objects in the active graph by type and optional WHERE "
+            "filter. Returns object id, type, and data for matching objects."
+        ),
+        input_schema=GraphQueryInput,
+        output_schema=GraphQueryOutput,
+        cost_per_call=Decimal("0"),
+        timeout_seconds=1.0,
+        deterministic=True,
+    )

activegraph/tools/recorded.py

@@ -0,0 +1,205 @@
+"""Fixture-based tool invokers for tests. CONTRACT v0.7 #15.
+
+Mirrors `activegraph.llm.recorded`. Fixtures live at
+`tests/fixtures/tools/<tool_name>/<args_hash>.json`. Same
+`recorded_at`-outside-the-hash pattern as v0.6's LLM fixtures.
+
+  RecordedToolProvider   — wraps an inner invocation pipeline. On
+                           `invoke(tool, args, ctx)`, computes the
+                           args hash, reads the fixture, returns the
+                           cached response. Missing fixtures raise
+                           ToolError(reason="tool.fixture_missing").
+
+  RecordingToolProvider  — wraps a real invoker. Calls the real
+                           thing, persists the response as a
+                           fixture, returns it. Use once under a
+                           `@pytest.mark.records_tools` opt-in to
+                           seed fixtures; commit; run thereafter
+                           against `RecordedToolProvider`.
+
+Fixture file shape:
+
+    {
+      "tool":        "web_fetch",
+      "args_hash":   "<sha256_hex>",
+      "recorded_at": "2026-05-15T10:32:01Z",
+      "args":        { ... only this contributes to the hash ... },
+      "output":      { ... },
+      "error":       null | { "reason": "tool.network_error", "message": "..." },
+      "latency_seconds": 0.8,
+      "cost_usd":    "0.001"
+    }
+
+The "invoker" abstraction matters: tools register as Python
+callables, but the runtime's tool-dispatch path can be wrapped by
+either Recorded or Recording — the registered tool function is the
+inner-most callable, and the Recording wrapper intercepts and
+fingerprints. This is exactly the same pattern as
+RecordingLLMProvider wrapping AnthropicProvider.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any, Optional
+
+from activegraph.tools.base import Tool
+from activegraph.tools.cache import CachedToolResponse, hash_tool_call
+from activegraph.tools.context import ToolContext
+from activegraph.tools.errors import ToolError
+
+
+def _now_iso() -> str:
+    return (
+        datetime.now(tz=timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def _normalize_args(tool: Tool, args: Any) -> Any:
+    """If args is a dict and the tool has an input_schema, return the dict.
+    If args is a BaseModel instance, dump to dict via canonicalize_args.
+    """
+    from activegraph.tools.cache import canonicalize_args
+
+    return canonicalize_args(args)
+
+
+class RecordedToolProvider:
+    """Read-only invoker. Tests use this so they never call out."""
+
+    def __init__(self, fixtures_dir: str) -> None:
+        self._dir = fixtures_dir
+
+    def invoke(
+        self,
+        tool: Tool,
+        args: Any,
+        ctx: ToolContext,
+    ) -> CachedToolResponse:
+        args_hash = hash_tool_call(tool_name=tool.name, args=args)
+        path = os.path.join(self._dir, tool.name, f"{args_hash}.json")
+        if not os.path.exists(path):
+            raise ToolError(
+                "tool.fixture_missing",
+                f"no recorded fixture for tool={tool.name!r} "
+                f"args_hash={args_hash} in {self._dir}",
+                payload_extras={
+                    "tool": tool.name,
+                    "args_hash": args_hash,
+                    "fixtures_dir": self._dir,
+                },
+            )
+        with open(path, "r") as f:
+            data = json.load(f)
+        return CachedToolResponse(
+            output=data.get("output"),
+            error=data.get("error"),
+            latency_seconds=float(data.get("latency_seconds", 0.0) or 0.0),
+            cost_usd=_decimal(data.get("cost_usd", "0")),
+        )
+
+
+class RecordingToolProvider:
+    """Wraps an inner invoker and persists each response as a fixture.
+
+    The inner invoker is normally the runtime's direct-call dispatcher
+    (i.e. it just runs `tool.fn(args, ctx)` with the right validation).
+    For seeding fixtures from a live tool body, use this:
+
+        invoker = RecordingToolProvider(
+            inner=DirectToolInvoker(),   # runs tool.fn(args, ctx)
+            fixtures_dir="tests/fixtures/tools",
+        )
+    """
+
+    def __init__(self, inner, fixtures_dir: str) -> None:
+        self._inner = inner
+        self._dir = fixtures_dir
+        os.makedirs(self._dir, exist_ok=True)
+
+    def invoke(
+        self,
+        tool: Tool,
+        args: Any,
+        ctx: ToolContext,
+    ) -> CachedToolResponse:
+        response = self._inner.invoke(tool, args, ctx)
+        args_hash = hash_tool_call(tool_name=tool.name, args=args)
+        fixture_dir = os.path.join(self._dir, tool.name)
+        os.makedirs(fixture_dir, exist_ok=True)
+        path = os.path.join(fixture_dir, f"{args_hash}.json")
+        fixture = {
+            "tool": tool.name,
+            "args_hash": args_hash,
+            "recorded_at": _now_iso(),
+            "args": _normalize_args(tool, args),
+            "output": response.output,
+            "error": response.error,
+            "latency_seconds": response.latency_seconds,
+            "cost_usd": str(response.cost_usd),
+        }
+        with open(path, "w") as f:
+            json.dump(fixture, f, indent=2, sort_keys=True)
+        return response
+
+
+class DirectToolInvoker:
+    """The default invoker: just calls `tool.fn(args, ctx)` with timing
+    and exception trapping. The runtime uses this when no provider
+    wrapper is in play (i.e. production).
+    """
+
+    def invoke(
+        self,
+        tool: Tool,
+        args: Any,
+        ctx: ToolContext,
+    ) -> CachedToolResponse:
+        import time
+
+        # CONTRACT v0.7 #6: timeout and execution_error are mapped.
+        # Other failure modes (invalid_input/output) are checked by the
+        # runtime, NOT here — schema validation happens before/after.
+        t0 = time.monotonic()
+        try:
+            result = tool.fn(args, ctx)
+        except ToolError:
+            raise
+        except Exception as e:
+            raise ToolError(
+                "tool.execution_error",
+                f"{type(e).__name__}: {e}",
+                payload_extras={
+                    "tool": tool.name,
+                    "exception_type": type(e).__name__,
+                },
+            ) from e
+        latency = time.monotonic() - t0
+        # Output can be a Pydantic instance or a dict. The runtime
+        # validates after; here we just store what the tool returned.
+        dump = getattr(result, "model_dump", None)
+        output: Any
+        if callable(dump):
+            try:
+                output = dump(mode="json")
+            except TypeError:
+                output = dump()
+        else:
+            output = result
+        return CachedToolResponse(
+            output=output,
+            error=None,
+            latency_seconds=latency,
+            cost_usd=tool.cost_per_call,
+        )
+
+
+def _decimal(v: Any) -> Decimal:
+    if isinstance(v, Decimal):
+        return v
+    return Decimal(str(v))