activegraph 1.0.0rc2__py3-none-any.whl

activegraph/store/url.py

@@ -0,0 +1,230 @@
+"""Connection URL parsing for stores. CONTRACT v0.8 #2.
+
+The framework addresses stores by URL everywhere (runtime, CLI, library).
+URLs follow SQLAlchemy conventions:
+
+- sqlite:///absolute/path/to/run.db         (three slashes!)
+- sqlite:///./relative/path.db
+- postgres://user:pass@host:port/dbname
+- postgresql://user:pass@host:port/dbname    (same scheme)
+
+A path with no scheme is rejected with a message pointing operators at
+the right form. We do not silently guess. The operator who types
+`activegraph inspect run.db` should see "use sqlite:///run.db", not a
+confusing parse error from psycopg.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from activegraph.errors import StorageError
+
+
+SQLITE_SCHEMES = ("sqlite",)
+POSTGRES_SCHEMES = ("postgres", "postgresql")
+
+
+@dataclass(frozen=True)
+class StoreURL:
+    scheme: str
+    """Normalised: "sqlite" or "postgres"."""
+
+    raw: str
+    """The original URL as the user typed it."""
+
+    sqlite_path: Optional[str] = None
+    """Filesystem path; populated for SQLite URLs only."""
+
+
+class InvalidStoreURL(StorageError, ValueError):
+    """Raised when a URL is missing a scheme, has an unsupported scheme,
+    or is otherwise malformed.
+
+    Multi-inherits :class:`ValueError` so user code that catches
+    ``ValueError`` around URL parsing keeps working. The message always
+    points the user at a concrete fix — bare paths get
+    ``sqlite:///<that path>``, unsupported schemes get the list of
+    supported ones.
+    """
+
+    _doc_slug = "invalid-store-url-error"
+
+
+# Voice notes for the InvalidStoreURL leaves: every "Why:" frames the
+# invariant as 'the framework refuses to guess what you meant.' The
+# operator who types `activegraph inspect run.db` should not silently
+# get treated as `sqlite:///run.db`; the same string could equally be
+# a Postgres URL fragment or a typo, and guessing wrong corrupts the
+# audit trail (or worse, opens the wrong store).
+_WHY_NO_GUESS = (
+    "The framework addresses stores by URL everywhere — runtime, CLI, "
+    "library — so the same string can be passed around without ambiguity "
+    "about which driver opens it. A malformed URL is refused at parse "
+    "time rather than silently coerced to a default scheme; guessing "
+    "wrong would either corrupt the audit trail or open an unintended "
+    "store."
+)
+
+
+def _invalid_url(
+    summary: str, *, what_failed: str, how_to_fix: str, url: str | None = None
+) -> "InvalidStoreURL":
+    ctx: dict[str, Any] = {}
+    if url is not None:
+        ctx["url"] = url
+    return InvalidStoreURL(
+        summary,
+        what_failed=what_failed,
+        why=_WHY_NO_GUESS,
+        how_to_fix=how_to_fix,
+        context=ctx,
+    )
+
+
+def parse_store_url(url: str) -> StoreURL:
+    """Parse a store URL, or raise InvalidStoreURL with a helpful message."""
+    if not url or not isinstance(url, str):
+        raise _invalid_url(
+            "store URL is empty",
+            what_failed="The store URL is empty or not a string.",
+            how_to_fix=(
+                "Provide a URL like:\n"
+                "  sqlite:///path/to/run.db\n"
+                "  postgres://host/dbname"
+            ),
+            url=url if isinstance(url, str) else None,
+        )
+    parsed = urlparse(url)
+    scheme = parsed.scheme.lower()
+    if not scheme:
+        # Bare path — the most common operator mistake.
+        raise _invalid_url(
+            f"store URL {url!r} has no scheme",
+            what_failed=(
+                f"The string {url!r} looks like a filesystem path with no "
+                f"URL scheme prefix."
+            ),
+            how_to_fix=(
+                f"If it's a SQLite file, use:\n"
+                f"    sqlite:///{url}\n"
+                f"\n"
+                f"If it's a Postgres database, use:\n"
+                f"    postgres://host/dbname"
+            ),
+            url=url,
+        )
+    if scheme in SQLITE_SCHEMES:
+        # SQLAlchemy convention (the de-facto standard the framework
+        # follows):
+        #   sqlite:///path           — relative path
+        #   sqlite:////abs/path      — absolute path (the leading / of
+        #                              the absolute path adds a 4th slash)
+        # urlparse splits these as path="/path" and path="//abs/path"
+        # respectively. Strip one leading slash to recover the actual
+        # filesystem path.
+        path = parsed.path
+        if parsed.netloc:
+            # "sqlite://host/path" — non-standard; treat host as part of
+            # the path component for forgiveness in tests.
+            path = f"//{parsed.netloc}{path}"
+        if not path:
+            raise _invalid_url(
+                f"sqlite URL {url!r} has no path",
+                what_failed=(
+                    f"The URL {url!r} has the `sqlite` scheme but no filesystem "
+                    f"path after it."
+                ),
+                how_to_fix=(
+                    "Use one of:\n"
+                    "    sqlite:///relative/path/to/run.db\n"
+                    "    sqlite:////absolute/path/to/run.db\n"
+                    "Note the slash counts — three for relative, four for absolute."
+                ),
+                url=url,
+            )
+        if path.startswith("/"):
+            path = path[1:]
+        if not path:
+            raise _invalid_url(
+                f"sqlite URL {url!r} has no path",
+                what_failed=(
+                    f"The URL {url!r} has the `sqlite` scheme but the path "
+                    f"resolved to empty."
+                ),
+                how_to_fix=(
+                    "Use one of:\n"
+                    "    sqlite:///relative/path/to/run.db\n"
+                    "    sqlite:////absolute/path/to/run.db"
+                ),
+                url=url,
+            )
+        return StoreURL(scheme="sqlite", raw=url, sqlite_path=path)
+    if scheme in POSTGRES_SCHEMES:
+        if not (parsed.hostname or parsed.path.lstrip("/")):
+            raise _invalid_url(
+                f"postgres URL {url!r} has no host or database",
+                what_failed=(
+                    f"The URL {url!r} has a `postgres` scheme but no host and "
+                    f"no database name."
+                ),
+                how_to_fix=(
+                    "Use:\n"
+                    "    postgres://host/dbname\n"
+                    "or with credentials and port:\n"
+                    "    postgres://user:pass@host:port/dbname"
+                ),
+                url=url,
+            )
+        return StoreURL(scheme="postgres", raw=url)
+    raise _invalid_url(
+        f"unsupported store URL scheme {scheme!r} in {url!r}",
+        what_failed=(
+            f"The URL {url!r} has scheme {scheme!r}, which the framework "
+            f"does not recognize."
+        ),
+        how_to_fix=(
+            "Supported schemes are:\n"
+            "    sqlite:///...        local SQLite file\n"
+            "    postgres://...       PostgreSQL (also accepted: postgresql://)\n"
+            "\n"
+            "Other databases are not supported in v1.0; the EventStore protocol "
+            "in activegraph/store/base.py is the path for adding new backends."
+        ),
+        url=url,
+    )
+
+
+def open_store(url: str, run_id: str) -> Any:
+    """Open a store for `run_id` at `url`. Returns an EventStore.
+
+    This is the single entry point the runtime and CLI use to open a
+    store from a URL. Drivers are imported lazily so the Postgres
+    dependency stays optional.
+    """
+    parsed = parse_store_url(url)
+    if parsed.scheme == "sqlite":
+        from activegraph.store.sqlite import SQLiteEventStore
+
+        assert parsed.sqlite_path is not None
+        return SQLiteEventStore(parsed.sqlite_path, run_id=run_id)
+    if parsed.scheme == "postgres":
+        from activegraph.store.postgres import PostgresEventStore
+
+        return PostgresEventStore(parsed.raw, run_id=run_id)
+    # Defensive: parse_store_url should have rejected this already.
+    raise _invalid_url(
+        f"unhandled scheme {parsed.scheme!r}",
+        what_failed=(
+            f"open_store reached its dispatcher with parsed scheme "
+            f"{parsed.scheme!r}, which parse_store_url should have refused."
+        ),
+        how_to_fix=(
+            "This is an internal inconsistency between parse_store_url "
+            "and open_store. File an issue with the URL that triggered "
+            "it at https://github.com/yoheinakajima/activegraph/issues."
+        ),
+        url=url,
+    )

activegraph/tools/__init__.py

@@ -0,0 +1,64 @@
+"""Tools subpackage. CONTRACT v0.7.
+
+A tool is a primitive — not buried inside an LLM behavior. The
+`@tool` decorator registers a callable with a name, schemas, cost,
+and a determinism flag. The runtime invokes tools via the same
+event-sourced pattern as LLM calls: every invocation is a
+`tool.requested` / `tool.responded` event pair, and replay reads
+those back instead of re-invoking (unless `replay_reinvoke_deterministic`
+is set and the tool is marked deterministic).
+
+Public surface:
+
+  Tool                       — registered tool metadata + body
+  ToolContext                — passed to tool function bodies
+  ToolCache                  — content-keyed replay cache
+  RecordedToolProvider       — fixture-backed tool invoker for tests
+  RecordingToolProvider      — wraps another invoker, persists fixtures
+  ToolError                  — structured failure from a tool body
+  MissingToolError           — raised at registration when an LLM
+                               behavior references an unregistered tool
+  UnknownToolError           — raised when the LLM requests a tool
+                               the behavior didn't declare
+  tool                       — decorator
+  get_tool_registry          — global tool registry inspector
+  clear_tool_registry        — registry reset (test hygiene)
+  make_graph_query_tool      — factory binding a graph_query tool to a Graph
+  web_fetch                  — reference tool: stdlib urllib-based URL fetcher
+"""
+
+from activegraph.tools.base import Tool
+from activegraph.tools.cache import ToolCache
+from activegraph.tools.context import ToolContext
+from activegraph.tools.decorators import (
+    clear_tool_registry,
+    get_tool_registry,
+    tool,
+)
+from activegraph.tools.errors import (
+    MissingToolError,
+    ToolError,
+    UnknownToolError,
+)
+from activegraph.tools.graph_query import make_graph_query_tool
+from activegraph.tools.recorded import (
+    RecordedToolProvider,
+    RecordingToolProvider,
+)
+from activegraph.tools.web_fetch import web_fetch
+
+__all__ = [
+    "MissingToolError",
+    "RecordedToolProvider",
+    "RecordingToolProvider",
+    "Tool",
+    "ToolCache",
+    "ToolContext",
+    "ToolError",
+    "UnknownToolError",
+    "clear_tool_registry",
+    "get_tool_registry",
+    "make_graph_query_tool",
+    "tool",
+    "web_fetch",
+]

activegraph/tools/base.py

@@ -0,0 +1,57 @@
+"""Tool dataclass. CONTRACT v0.7 #2 / #5.
+
+A Tool is metadata + callable, mirror image of Behavior. The runtime
+introspects metadata to dispatch invocations and budget enforcement;
+the callable is the actual body. The tool function signature is
+fixed:
+
+    def tool_fn(args: InputSchema, ctx: ToolContext) -> OutputSchema
+
+`input_schema` and `output_schema` are Pydantic v2 BaseModel classes;
+the runtime validates inputs before invocation and outputs after.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Callable, Optional
+
+
+@dataclass
+class Tool:
+    name: str
+    fn: Callable[..., Any]
+    description: str = ""
+    input_schema: Optional[type] = None
+    output_schema: Optional[type] = None
+    cost_per_call: Decimal = field(default_factory=lambda: Decimal("0"))
+    timeout_seconds: float = 30.0
+    # CONTRACT v0.7 #7. False (the default) means "replay must serve
+    # this tool from the recorded fixture or fail loud"; True means
+    # "replay may re-invoke this tool". The runtime's replay-cache
+    # policy serves from cache by default for ALL tools, deterministic
+    # or not, because deterministic-tool correctness depends on the
+    # graph state at the moment of the call matching exactly — and the
+    # runtime cannot cheaply verify that. `replay_reinvoke_deterministic`
+    # on the Runtime is the opt-in that exercises re-invocation.
+    deterministic: bool = False
+
+    def to_definition(self) -> dict[str, Any]:
+        """Provider-facing tool definition.
+
+        Sent in the `tools=` parameter to `LLMProvider.complete()`.
+        Anthropic and OpenAI both accept a similar shape; the provider
+        translates if needed.
+        """
+        from activegraph.llm.prompt import schema_to_json
+
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": (
+                schema_to_json(self.input_schema)
+                if self.input_schema is not None
+                else {"type": "object", "properties": {}}
+            ),
+        }

activegraph/tools/cache.py

@@ -0,0 +1,157 @@
+"""Tool replay cache. CONTRACT v0.7 #3.
+
+Mirror of `activegraph.llm.cache.LLMCache`. Keyed by
+`sha256(canonical_json({tool_name, args_normalized}))`. Population
+paths:
+
+  * `ToolCache.from_events(events)` — used at `Runtime.load(...,
+    replay_tool_cache=True)` and `runtime.fork(...,
+    replay_tool_cache=True)`. Walks the recorded log and harvests
+    every `tool.responded` whose preceding `tool.requested` carries
+    `args_hash`.
+
+  * `cache.record(args_hash, output, ...)` — same-run repeat-call
+    insurance, called inline from the runtime's tool invocation path.
+
+CONTRACT v0.7 (tool-determinism decision): serve-from-cache is the
+default on replay for ALL tools, deterministic or not. The
+`replay_reinvoke_deterministic=True` Runtime flag is the opt-in that
+lets deterministic tools actually re-invoke during replay. The
+reasoning is documented in CONTRACT.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Iterable, Optional
+
+from activegraph.core.event import Event
+
+
+def canonicalize_args(args: Any) -> Any:
+    """Normalize tool args into a JSON-stable shape for hashing.
+
+    - Pydantic v2 BaseModel instance → `model.model_dump(mode="json")`
+    - dict / list / scalar → recursed, Decimals → canonical string
+    - sort_keys at JSON-dump time guarantees ordering stability.
+    """
+    dump = getattr(args, "model_dump", None)
+    if callable(dump):
+        try:
+            return dump(mode="json")
+        except TypeError:
+            return dump()
+    if isinstance(args, dict):
+        return {k: canonicalize_args(v) for k, v in args.items()}
+    if isinstance(args, list):
+        return [canonicalize_args(v) for v in args]
+    if isinstance(args, Decimal):
+        return str(args)
+    return args
+
+
+def hash_tool_call(*, tool_name: str, args: Any) -> str:
+    payload = {"tool": tool_name, "args": canonicalize_args(args)}
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class CachedToolResponse:
+    """A cached tool response. Mirrors `LLMResponse` in shape so the
+    replay path can hydrate without re-invoking the tool.
+    """
+
+    output: Any  # JSON-serializable; runtime will re-validate via output_schema
+    error: Optional[dict[str, Any]] = None  # None for success
+    latency_seconds: float = 0.0
+    cost_usd: Decimal = Decimal("0")
+    cache_hit: bool = False
+    requesting_event_id: Optional[str] = None
+
+
+class ToolCache:
+    def __init__(self) -> None:
+        self._by_hash: dict[str, CachedToolResponse] = {}
+
+    # ---- read ----
+
+    def get(self, args_hash: str) -> Optional[CachedToolResponse]:
+        entry = self._by_hash.get(args_hash)
+        if entry is None:
+            return None
+        return CachedToolResponse(
+            output=entry.output,
+            error=dict(entry.error) if entry.error else None,
+            latency_seconds=entry.latency_seconds,
+            cost_usd=entry.cost_usd,
+            cache_hit=True,
+            requesting_event_id=entry.requesting_event_id,
+        )
+
+    def has(self, args_hash: str) -> bool:
+        return args_hash in self._by_hash
+
+    def __len__(self) -> int:
+        return len(self._by_hash)
+
+    # ---- write ----
+
+    def record(
+        self,
+        args_hash: str,
+        response: CachedToolResponse,
+        *,
+        requesting_event_id: Optional[str] = None,
+    ) -> None:
+        clean = CachedToolResponse(
+            output=response.output,
+            error=dict(response.error) if response.error else None,
+            latency_seconds=response.latency_seconds,
+            cost_usd=response.cost_usd,
+            cache_hit=False,
+            requesting_event_id=requesting_event_id or response.requesting_event_id,
+        )
+        self._by_hash[args_hash] = clean
+
+    # ---- bulk-load from a recorded event log ----
+
+    @classmethod
+    def from_events(cls, events: Iterable[Event]) -> "ToolCache":
+        cache = cls()
+        events_list = list(events)
+        by_id: dict[str, Event] = {e.id: e for e in events_list}
+        for e in events_list:
+            if e.type != "tool.responded":
+                continue
+            req_id = e.caused_by
+            if req_id is None:
+                continue
+            req = by_id.get(req_id)
+            if req is None or req.type != "tool.requested":
+                continue
+            args_hash = req.payload.get("args_hash")
+            if not args_hash:
+                continue
+            cache.record(
+                args_hash,
+                CachedToolResponse(
+                    output=e.payload.get("output"),
+                    error=e.payload.get("error"),
+                    latency_seconds=float(
+                        e.payload.get("latency_seconds", 0.0) or 0.0
+                    ),
+                    cost_usd=_decimal(e.payload.get("cost_usd", "0")),
+                ),
+                requesting_event_id=req_id,
+            )
+        return cache
+
+
+def _decimal(v: Any) -> Decimal:
+    if isinstance(v, Decimal):
+        return v
+    return Decimal(str(v))

activegraph/tools/context.py

@@ -0,0 +1,48 @@
+"""ToolContext — what a tool function body sees. CONTRACT v0.7 #5.
+
+A `ToolContext` is to a tool what `BehaviorGraph` is to a behavior:
+the surface deliberately omits anything a tool shouldn't touch.
+
+Provides:
+  - behavior_name:   the @llm_behavior that triggered this tool call
+  - event_id:        the triggering event id (NOT the tool.requested
+                     event id — that one is on the wrapping turn loop)
+  - frame:           the active Frame, if any
+  - idempotency_key: opaque pass-through for tools to forward to
+                     external APIs that support idempotency tokens.
+                     The runtime never uses this for dedupe — that's
+                     the cache's job (CONTRACT v0.7 #5 / idempotency
+                     decision).
+  - timeout_seconds: copied from the @tool decorator; tools may
+                     enforce via signal/select; the runtime does NOT
+                     forcibly preempt (no thread/signal magic).
+  - logger:          a `logging.Logger` named "activegraph.tools.<tool>"
+
+Does NOT provide a graph reference. Tools that need to read graph
+state (e.g. `graph_query`) close over the Graph at registration time
+via the `make_graph_query_tool(graph)` factory. The constraint is
+intentional: tools that need graph state should be obvious (named,
+constructed deliberately) rather than every tool having ambient
+graph access.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from activegraph.frame import Frame
+
+
+@dataclass
+class ToolContext:
+    behavior_name: str
+    event_id: str
+    frame: Optional["Frame"]
+    idempotency_key: str
+    timeout_seconds: float
+    logger: logging.Logger = field(
+        default_factory=lambda: logging.getLogger("activegraph.tools")
+    )

activegraph/tools/decorators.py

@@ -0,0 +1,70 @@
+"""@tool decorator + global tool registry. CONTRACT v0.7 #2.
+
+The registry mirrors the @behavior registry: decoration pushes into
+a module-level list; tests call `clear_tool_registry()` for
+isolation. Runtime construction snapshots the registry — late
+registrations after `_ensure_registry()` are ignored.
+
+`Runtime(graph, tools=[...])` is the explicit override that bypasses
+the global registry, mirroring how `behaviors=[...]` works.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any, Callable, Optional
+
+from activegraph.tools.base import Tool
+
+
+_TOOL_REGISTRY: list[Tool] = []
+
+
+def clear_tool_registry() -> None:
+    _TOOL_REGISTRY.clear()
+
+
+def get_tool_registry() -> list[Tool]:
+    return list(_TOOL_REGISTRY)
+
+
+def tool(
+    *,
+    name: Optional[str] = None,
+    description: str = "",
+    input_schema: Optional[type] = None,
+    output_schema: Optional[type] = None,
+    cost_per_call: Any = Decimal("0"),
+    timeout_seconds: float = 30.0,
+    deterministic: bool = False,
+) -> Callable[[Callable], Tool]:
+    """Register a function as a Tool.
+
+    The decorated function's signature is
+    `(args: input_schema, ctx: ToolContext) -> output_schema`. The
+    runtime validates `args` against `input_schema` before invocation
+    and validates the return value against `output_schema` after.
+
+    Keyword-only on purpose — too many fields for safe positional
+    binding.
+    """
+
+    cost = cost_per_call if isinstance(cost_per_call, Decimal) else Decimal(
+        str(cost_per_call)
+    )
+
+    def wrap(fn: Callable) -> Tool:
+        t = Tool(
+            name=name or fn.__name__,
+            fn=fn,
+            description=description,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            cost_per_call=cost,
+            timeout_seconds=float(timeout_seconds),
+            deterministic=bool(deterministic),
+        )
+        _TOOL_REGISTRY.append(t)
+        return t
+
+    return wrap