activegraph 1.0.0__py3-none-any.whl

activegraph/core/ids.py

@@ -0,0 +1,135 @@
+"""ID generation. CONTRACT #1 and CONTRACT v0.5 #6 (run ids are ULIDs).
+
+All IDs flow through one generator so tests can swap in a deterministic one.
+v0 uses short prefixed monotonic strings; v0.5 adds `run()` for ULID-shaped
+run identifiers and `from_events()` to rebuild counters after a replay.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from typing import Iterable
+
+from activegraph.core.event import Event
+
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def _ulid() -> str:
+    """26-char Crockford base32 ULID. Time-prefixed, random suffix.
+
+    Not strictly monotonic within the same millisecond — good enough for
+    run identifiers (low write rate, no sort-criticality).
+    """
+    ms = int(time.time() * 1000) & ((1 << 48) - 1)
+    rand = int.from_bytes(os.urandom(10), "big")
+    n = (ms << 80) | rand
+    out: list[str] = []
+    for _ in range(26):
+        out.append(_CROCKFORD[n & 0x1F])
+        n >>= 5
+    return "".join(reversed(out))
+
+
+_OBJ_RE = re.compile(r"^(?P<type>[^#]+)#(?P<n>\d+)$")
+_NUM_RE = re.compile(r"^[a-zA-Z]+_(?P<n>\d+)$")
+
+
+class IDGen:
+    """Per-graph monotonic ID generator. Not thread-safe (single-threaded loop)."""
+
+    def __init__(self) -> None:
+        # CONTRACT #1: objects use a global counter prefixed by type
+        # (matches the README trace: task#1, task#2, claim#3 — not claim#1).
+        self._object_counter = 0
+        self._event_counter = 0
+        self._relation_counter = 0
+        self._patch_counter = 0
+        self._frame_counter = 0
+
+    # ---- generators ----
+
+    def object(self, type_: str) -> str:
+        self._object_counter += 1
+        return f"{type_}#{self._object_counter}"
+
+    def event(self) -> str:
+        self._event_counter += 1
+        return f"evt_{self._event_counter:03d}"
+
+    def relation(self) -> str:
+        self._relation_counter += 1
+        return f"rel_{self._relation_counter:03d}"
+
+    def patch(self) -> str:
+        self._patch_counter += 1
+        return f"patch_{self._patch_counter:03d}"
+
+    def frame(self) -> str:
+        self._frame_counter += 1
+        return f"frame_{self._frame_counter:03d}"
+
+    def run(self) -> str:
+        # ULID per CONTRACT v0.5 #6. Not counter-based: runs live in storage
+        # and are looked up by id, so collisions across files are the risk.
+        return _ulid()
+
+    # ---- replay reconstruction (CONTRACT v0.5 #14, #15) ----
+
+    def reseed_from_events(self, events: Iterable[Event]) -> None:
+        """Set counters past the highest id seen in `events`.
+
+        Used after replay so subsequent `object()/event()/...` continue
+        monotonically from where the loaded log ended. Forks call this too,
+        which is why two forks at the same point produce IDs that diverge
+        identically (decision #12 — fine because the IDs live in different
+        runs).
+        """
+        max_obj = 0
+        max_evt = 0
+        max_rel = 0
+        max_patch = 0
+        max_frame = 0
+        for e in events:
+            n = _suffix_num(e.id)
+            if n is not None:
+                max_evt = max(max_evt, n)
+            if e.frame_id:
+                fn = _suffix_num(e.frame_id)
+                if fn is not None:
+                    max_frame = max(max_frame, fn)
+            p = e.payload or {}
+            if e.type == "object.created":
+                obj_id = (p.get("object") or {}).get("id", "")
+                m = _OBJ_RE.match(obj_id)
+                if m:
+                    max_obj = max(max_obj, int(m.group("n")))
+            elif e.type == "relation.created":
+                rel_id = (p.get("relation") or {}).get("id", "")
+                rn = _suffix_num(rel_id)
+                if rn is not None:
+                    max_rel = max(max_rel, rn)
+            elif e.type in ("patch.proposed", "patch.applied"):
+                patch_id = (p.get("patch") or {}).get("id", "")
+                pn = _suffix_num(patch_id)
+                if pn is not None:
+                    max_patch = max(max_patch, pn)
+            elif e.type == "patch.rejected":
+                pn = _suffix_num(p.get("patch_id", "") or "")
+                if pn is not None:
+                    max_patch = max(max_patch, pn)
+        self._object_counter = max(self._object_counter, max_obj)
+        self._event_counter = max(self._event_counter, max_evt)
+        self._relation_counter = max(self._relation_counter, max_rel)
+        self._patch_counter = max(self._patch_counter, max_patch)
+        self._frame_counter = max(self._frame_counter, max_frame)
+
+
+def _suffix_num(s: str) -> int | None:
+    m = _NUM_RE.match(s or "")
+    if not m:
+        return None
+    return int(m.group("n"))

activegraph/core/patch.py

@@ -0,0 +1,47 @@
+"""Patch primitives. CONTRACT #4 (versioning) and #12 (single-target atomic).
+
+A Patch is a proposed mutation. Lifecycle:
+    proposed -> applied
+    proposed -> rejected
+`patch_object` is the auto-apply shortcut: builds a patch, version-checks,
+emits patch.applied (or patch.rejected) directly. `propose_patch` emits
+patch.proposed and waits for explicit approval.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+PATCH_OPS = {"create", "update", "replace", "remove"}
+
+
+@dataclass
+class Patch:
+    id: str
+    target: str
+    op: str
+    value: dict[str, Any]
+    expected_version: int
+    proposed_by: str
+    rationale: Optional[str] = None
+    evidence: list[str] = field(default_factory=list)
+    status: str = "proposed"  # proposed | applied | rejected
+    rejection_reason: Optional[str] = None
+    provenance: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "target": self.target,
+            "op": self.op,
+            "value": self.value,
+            "expected_version": self.expected_version,
+            "proposed_by": self.proposed_by,
+            "rationale": self.rationale,
+            "evidence": list(self.evidence),
+            "status": self.status,
+            "rejection_reason": self.rejection_reason,
+            "provenance": dict(self.provenance),
+        }

activegraph/core/view.py

@@ -0,0 +1,59 @@
+"""Read-only scoped slice of the graph passed to behaviors as ctx.view.
+
+CONTRACT #11: behaviors do not build their own views via graph.query —
+they declare what they want via decorator metadata and the runtime
+constructs a View before invocation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.core.event import Event
+from activegraph.core.graph import Object, Relation, evaluate_where
+
+
+class View:
+    def __init__(
+        self,
+        objects: list[Object],
+        relations: list[Relation],
+        events: list[Event],
+    ) -> None:
+        self._objects = objects
+        self._relations = relations
+        self._events = events
+
+    def objects(
+        self,
+        type: Optional[str] = None,
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Object]:
+        out = self._objects
+        if type is not None:
+            out = [o for o in out if o.type == type]
+        if where:
+            out = [o for o in out if evaluate_where(where, _object_root(o))]
+        return list(out)
+
+    def relations(self, type: Optional[str] = None) -> list[Relation]:
+        out = self._relations
+        if type is not None:
+            out = [r for r in out if r.type == type]
+        return list(out)
+
+    def events(self, type: Optional[str] = None) -> list[Event]:
+        out = self._events
+        if type is not None:
+            out = [e for e in out if e.type == type]
+        return list(out)
+
+
+def _object_root(o: Object) -> dict[str, Any]:
+    return {
+        "id": o.id,
+        "type": o.type,
+        "data": o.data,
+        "version": o.version,
+        "provenance": o.provenance,
+    }

activegraph/errors.py

@@ -0,0 +1,345 @@
+"""ActiveGraphError hierarchy. CONTRACT v1.0 #3, #4 — the error format and
+the class tree are public contract.
+
+Every framework error inherits from `ActiveGraphError` and renders in the
+locked format:
+
+    <ErrorClass>: <one-line summary>
+
+    What failed:
+      <specific thing that went wrong, with names>
+
+    Why:
+      <root cause, not the symptom>
+
+    How to fix:
+      <concrete action>
+
+    More:
+      https://docs.activegraph.ai/errors/<slug>
+
+The seven category bases are stable. Concrete leaves are migrated under
+their categories one PR at a time (CONTRACT v1.0 #C1 — the rewrite ships
+as a PR series, not one PR). PR-A lands the foundation plus ReplayError
+as the reference category; subsequent PRs migrate the other categories
+without changing the bases.
+
+`_doc_slug` on each class is the URL slug for the error's doc page. The
+base URL is the primary `docs.activegraph.ai` domain (CONTRACT v1.0 #C6,
+v1.0-rc3 amendment); the constant is the single swap point.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+
+# CONTRACT v1.0 #C6 (v1.0-rc3 amendment): primary doc-site domain is
+# docs.activegraph.ai. Until the user-owned Pages enablement and DNS
+# land, the URL renders the same 404 the rc2 user-test surfaced; the
+# v1.1 #9 deploy-verification gate fails until that lands, which is
+# the correct signal. One-line swap point: update this constant and
+# every error message URL and `DOCS_BASE_URL`-derived f-string follows.
+DOCS_BASE_URL = "https://docs.activegraph.ai"
+
+
+def _indent_continuation(text: str, indent: str = "  ") -> str:
+    """Re-indent a multi-line block so every line after the first sits
+    under the same column as the first line. The format spec puts every
+    field's body on a continuation line indented by two spaces; multi-line
+    bodies (a how-to-fix with three steps, for instance) maintain that
+    indent on every line so the message reads as a single block."""
+    lines = text.split("\n")
+    if len(lines) == 1:
+        return lines[0]
+    return lines[0] + "\n" + "\n".join(indent + line if line else line for line in lines[1:])
+
+
+class ActiveGraphError(Exception):
+    """Root of every framework error. CONTRACT v1.0 #4.
+
+    Subclasses construct by passing a one-line ``summary`` plus the three
+    structured fields (``what_failed``, ``why``, ``how_to_fix``) and any
+    error-specific context. ``__str__`` produces the locked format; the
+    structured fields stay accessible programmatically for tools that
+    want to render errors differently (a doc-site error catalog, a
+    machine-readable failure log, etc.).
+    """
+
+    # Each subclass sets its own slug. The base class slug exists so a
+    # bare `ActiveGraphError` (which should not be raised in practice;
+    # always reach for a concrete subclass) still produces a valid URL.
+    _doc_slug: ClassVar[str] = "active-graph-error"
+
+    def __init__(
+        self,
+        summary_or_message: str,
+        *,
+        what_failed: str | None = None,
+        why: str | None = None,
+        how_to_fix: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """Two construction modes during the v1.0 transition:
+
+        - **Structured** (the v1.0 target): pass ``summary`` plus the three
+          named fields. ``__str__`` produces the locked format.
+        - **Legacy**: pass a single positional message. Used by error
+          leaves that have not yet migrated under the v1.0 PR series.
+          ``__str__`` returns the message verbatim — format-noncompliant
+          but valid Python, so existing raises keep working.
+
+        PR-A converts the ReplayError leaves (the reference category).
+        PR-B through PR-F convert the rest one PR at a time. The legacy
+        branch goes away once every leaf is migrated; until then this
+        gateway is the bridge.
+        """
+        self._summary = summary_or_message
+        self.what_failed = what_failed or ""
+        self.why = why or ""
+        self.how_to_fix = how_to_fix or ""
+        self.context: dict[str, Any] = dict(context) if context else {}
+        if self.is_structured():
+            super().__init__(self._format())
+        else:
+            super().__init__(summary_or_message)
+
+    def is_structured(self) -> bool:
+        """True when the three structured fields are populated. Used by
+        the format snapshot tests and the docs catalog to filter out
+        leaves that have not yet migrated to the v1.0 format."""
+        return bool(self.what_failed and self.why and self.how_to_fix)
+
+    @property
+    def doc_url(self) -> str:
+        return f"{DOCS_BASE_URL}/errors/{self._doc_slug}"
+
+    def _format(self) -> str:
+        return (
+            f"{type(self).__name__}: {self._summary}\n\n"
+            f"What failed:\n  {_indent_continuation(self.what_failed)}\n\n"
+            f"Why:\n  {_indent_continuation(self.why)}\n\n"
+            f"How to fix:\n  {_indent_continuation(self.how_to_fix)}\n\n"
+            f"More:\n  {self.doc_url}"
+        )
+
+    def __str__(self) -> str:
+        if self.is_structured():
+            return self._format()
+        return self._summary
+
+
+# ---------- Category bases ----------------------------------------------
+#
+# The seven categories from CONTRACT v1.0 #4. Each is an abstract base —
+# raise a concrete subclass, not a bare category. Until PR-B through PR-F
+# land, some categories have no concrete leaves yet; the bases still
+# exist so external code can `except RegistrationError:` today and have
+# it cover those leaves once they migrate.
+
+
+class ConfigurationError(ActiveGraphError):
+    """Runtime construction problems: invalid budget, malformed store URL,
+    missing required configuration. Fires before any work runs."""
+
+    _doc_slug = "configuration-error"
+
+
+class RegistrationError(ActiveGraphError):
+    """Behavior, tool, or pack registration problems: conflicts at
+    registration time, version mismatches, missing providers, unknown
+    tools. Fires at registration / pack-load time."""
+
+    _doc_slug = "registration-error"
+
+
+class ExecutionError(ActiveGraphError):
+    """Runtime execution problems: behavior failures, budget exhausted,
+    tool failures during a goal run. Named ExecutionError (not
+    RuntimeError) because Python already has builtin ``RuntimeError`` and
+    shadowing the builtin produces confusing stack traces."""
+
+    _doc_slug = "execution-error"
+
+
+class ReplayError(ActiveGraphError):
+    """Replay and fork problems: cache hash mismatches, type-stream
+    divergence between recorded and re-run event logs. Fires only during
+    replay / fork; never during a fresh run."""
+
+    _doc_slug = "replay-error"
+
+
+class StorageError(ActiveGraphError):
+    """Persistence problems: failed writes, malformed event payloads on
+    deserialize, schema version mismatches."""
+
+    _doc_slug = "storage-error"
+
+
+class PatternError(ActiveGraphError):
+    """Pattern subscription problems: invalid Cypher syntax, unsupported
+    features, malformed WHERE clauses at registration time."""
+
+    _doc_slug = "pattern-error"
+
+
+class PackError(ActiveGraphError):
+    """Pack-specific problems at runtime (not registration): schema
+    violations on add_object after pack load, pack-state inconsistencies.
+    Registration-time pack errors live under :class:`RegistrationError`
+    instead."""
+
+    _doc_slug = "pack-error"
+
+
+class MissingOptionalDependency(RegistrationError, ImportError):
+    """A subsystem requires an optional Python package that isn't installed.
+
+    Used by the Postgres store, the Prometheus metrics backend, and the
+    Pack format (which requires Pydantic). Multi-inherits :class:`ImportError`
+    so user code that catches the builtin around optional-dep imports
+    continues to work. v1.0 PR-E.
+
+    Construct with the missing package name and the activegraph extras
+    name that bundles it; the structured message walks the user through
+    the install line.
+    """
+
+    _doc_slug = "missing-optional-dependency"
+
+    def __init__(
+        self,
+        *,
+        package: str,
+        feature: str,
+        extras: str | None = None,
+    ) -> None:
+        self.package = package
+        self.feature = feature
+        self.extras = extras
+        install_line = (
+            f"pip install 'activegraph[{extras}]'"
+            if extras
+            else f"pip install {package}"
+        )
+        ctx = {"package": package, "feature": feature}
+        if extras is not None:
+            ctx["extras"] = extras
+        RegistrationError.__init__(
+            self,
+            f"{feature} requires the {package!r} Python package",
+            what_failed=(
+                f"While initializing {feature}, the import of {package!r} "
+                f"failed because the package is not installed in this "
+                f"environment."
+            ),
+            why=(
+                "The framework keeps optional subsystems off the default "
+                "install path so a minimal install stays small. Each "
+                "optional subsystem declares its dependency explicitly; "
+                "missing it produces this error rather than failing later "
+                "with a confusing AttributeError or ImportError deep inside "
+                "the subsystem."
+            ),
+            how_to_fix=(
+                f"Install the optional dependency:\n"
+                f"    {install_line}\n"
+                f"\n"
+                f"If you don't need {feature}, the bare `activegraph` "
+                f"install does not depend on {package!r} — the error only "
+                f"fires when the subsystem is actually used."
+            ),
+            context=ctx,
+        )
+
+
+__all__ = [
+    "ActiveGraphError",
+    "ConfigurationError",
+    "RegistrationError",
+    "ExecutionError",
+    "ReplayError",
+    "StorageError",
+    "PatternError",
+    "PackError",
+    "MissingOptionalDependency",
+    "internal_bug_fields",
+    "GITHUB_NEW_ISSUE_URL",
+    "DOCS_BASE_URL",
+]
+
+
+# ---------- v1.0 PR-G: shared internal-bug helper -----------------------
+#
+# Three sites in the framework raise exceptions for framework-bug
+# conditions (the parser/evaluator sees something the framework itself
+# produced incorrectly, not user input). Per PR-G consistency pass, all
+# three use the same context-dict shape and the same recovery prose so
+# GitHub Issues filed from these errors arrive with uniform metadata.
+
+
+GITHUB_NEW_ISSUE_URL = "https://github.com/yoheinakajima/activegraph/issues/new"
+
+
+def internal_bug_fields(
+    *,
+    summary: str,
+    what_happened: str,
+    why_invariant: str,
+    location: str,
+    extra_context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Produce uniform structured fields for an internal-bug exception.
+
+    Used by the three framework-bug raise sites (two in
+    ``activegraph/runtime/patterns.py`` for the WHERE evaluator's
+    unknown-operator and unrecognized-AST-node cases; one in
+    ``activegraph/core/graph.py`` for the view-filter evaluator's
+    unknown-operator case). Returns the kwargs dict that an
+    :class:`ActiveGraphError` subclass's structured ``__init__``
+    consumes.
+
+    Uniform context dict shape:
+
+    - ``internal``: ``True``
+    - ``framework_version``: ``activegraph.__version__``
+    - ``internal_error_location``: module:function pointer for triage
+    - ``report_url``: the GitHub new-issue URL
+    - any per-site keys from ``extra_context``
+
+    Uniform recovery prose:
+
+      "This is a framework bug, not a problem with your code. Please
+      file an issue at <URL> with the framework version and the message
+      above."
+
+    PR-G normalization pass: the three pre-existing internal-bug
+    messages had drifted into three slightly different shapes; they
+    are unified here. Future internal-bug raises should call this
+    helper so the pattern stays uniform.
+    """
+    from activegraph import __version__ as _aw_version
+    ctx: dict[str, Any] = {
+        "internal": True,
+        "framework_version": _aw_version,
+        "internal_error_location": location,
+        "report_url": GITHUB_NEW_ISSUE_URL,
+    }
+    if extra_context:
+        ctx.update(extra_context)
+    return {
+        "summary": summary,
+        "what_failed": what_happened,
+        "why": why_invariant,
+        "how_to_fix": (
+            "This is a framework bug, not a problem with your code.\n"
+            "Please file an issue and include the framework version, the\n"
+            "internal error location, and the full message above:\n"
+            f"    {GITHUB_NEW_ISSUE_URL}\n"
+            "\n"
+            f"  framework version:   activegraph {_aw_version}\n"
+            f"  internal location:   {location}"
+        ),
+        "context": ctx,
+    }

activegraph/frame.py

@@ -0,0 +1,15 @@
+"""Mission context for a run."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Frame:
+    goal: str
+    id: Optional[str] = None
+    constraints: list[str] = field(default_factory=list)
+    success_criteria: list[str] = field(default_factory=list)
+    permissions: list[str] = field(default_factory=list)

activegraph/llm/__init__.py

@@ -0,0 +1,51 @@
+"""LLM behaviors subpackage. CONTRACT v0.6.
+
+Public surface:
+
+  LLMProvider            — Protocol every provider implements
+  LLMMessage             — single role-tagged message
+  LLMResponse            — what `complete()` returns
+  AnthropicProvider      — reference implementation
+  RecordedLLMProvider    — fixture-backed provider for tests
+  RecordingLLMProvider   — wraps another provider, persists responses
+                           as fixtures (for first-time test seed)
+  LLMCache               — content-keyed replay cache
+  AssembledPrompt        — the deterministic prompt + params blob
+                           returned by `LLMBehavior.build_prompt`
+  MissingProviderError   — raised when an @llm_behavior is registered
+                           without a runtime provider
+  LLMBehaviorError       — structured failure carrier from @llm_behavior
+                           wrappers; runtime turns it into
+                           `behavior.failed` with a `reason`
+"""
+
+from activegraph.llm.anthropic import AnthropicProvider
+from activegraph.llm.cache import LLMCache
+from activegraph.llm.errors import LLMBehaviorError, MissingProviderError
+from activegraph.llm.prompt import (
+    AssembledPrompt,
+    assemble_prompt,
+    schema_to_json,
+    serialize_view,
+)
+from activegraph.llm.provider import LLMProvider
+from activegraph.llm.recorded import RecordedLLMProvider, RecordingLLMProvider
+from activegraph.llm.types import LLMMessage, LLMResponse, ToolCall
+
+
+__all__ = [
+    "AnthropicProvider",
+    "AssembledPrompt",
+    "LLMBehaviorError",
+    "LLMCache",
+    "LLMMessage",
+    "LLMProvider",
+    "LLMResponse",
+    "MissingProviderError",
+    "RecordedLLMProvider",
+    "RecordingLLMProvider",
+    "ToolCall",
+    "assemble_prompt",
+    "schema_to_json",
+    "serialize_view",
+]