activegraph 1.0.0__py3-none-any.whl

activegraph/__init__.py

@@ -0,0 +1,222 @@
+"""Active Graph Runtime. Public API surface.
+
+The graph is the world. Behaviors are physics. The trace is the proof.
+"""
+
+from activegraph.behaviors.base import Behavior, LLMBehavior, RelationBehavior
+from activegraph.behaviors.decorators import (
+    behavior,
+    clear_registry,
+    get_registry,
+    llm_behavior,
+    relation_behavior,
+)
+from activegraph.core.clock import Clock, FrozenClock, TickingClock
+from activegraph.core.event import Event
+from activegraph.core.graph import Graph, Object, Relation
+from activegraph.core.ids import IDGen
+from activegraph.core.patch import Patch
+from activegraph.core.view import View
+from activegraph.errors import (
+    ActiveGraphError,
+    ConfigurationError,
+    ExecutionError,
+    MissingOptionalDependency,
+    PackError,
+    PatternError,
+    RegistrationError,
+    ReplayError,
+    StorageError,
+)
+from activegraph.runtime.registration_errors import (
+    AmbiguousBehaviorError,
+    AmbiguousToolError,
+    BehaviorNotFoundError,
+    InvalidToolRegistration,
+    ToolNotFoundError,
+)
+from activegraph.runtime.scheduler import InvalidActivateAfter
+from activegraph.frame import Frame
+from activegraph.llm.errors import LLMBehaviorError, MissingProviderError
+from activegraph.policy import Policy
+from activegraph.runtime.budget import Budget
+from activegraph.runtime.diff import Diff, DivergentObject, DivergentRelation
+from activegraph.runtime.config_errors import (
+    IncompatibleRuntimeState,
+    InvalidArgumentType,
+    InvalidRuntimeConfiguration,
+)
+from activegraph.runtime.errors import ReplayDivergenceError
+from activegraph.runtime.exec_errors import (
+    ApprovalNotFoundError,
+    InternalEvaluatorError,
+    InvalidPatchLifecycleState,
+    RuntimeContextRequiredError,
+)
+from activegraph.runtime.patterns import UnsupportedPatternError
+from activegraph.runtime.runtime import Runtime
+from activegraph.store import (
+    CorruptedEventPayloadError,
+    DuplicateEventError,
+    EventNotFoundError,
+    EventStore,
+    InMemoryEventStore,
+    InvalidStoreURL,
+    NonSerializableEventError,
+    RunRecord,
+    SQLiteEventStore,
+    SchemaVersionMismatch,
+    open_store,
+    parse_store_url,
+)
+# v0.7 public surface for tools
+from activegraph.tools import (
+    MissingToolError,
+    Tool,
+    ToolContext,
+    ToolError,
+    UnknownToolError,
+    clear_tool_registry,
+    get_tool_registry,
+    tool,
+)
+# v0.8 observability surface
+from activegraph.observability import (
+    Metrics,
+    MigrationReport,
+    MigrationRunReport,
+    NoOpMetrics,
+    PrometheusMetrics,
+    RuntimeStatus,
+    configure_logging,
+    migrate,
+)
+# v0.9 packs surface (top-level: the API for *using* packs from user code).
+# Pack-aware decorators live under `activegraph.packs` and are intentionally
+# NOT re-exported here — pack authors must import them from `activegraph.packs`
+# so the import path makes the boundary explicit. CONTRACT v0.9 #3.
+from activegraph.packs import (
+    DiscoveredPack,
+    EmptySettings,
+    ObjectType,
+    Pack,
+    PackConflictError,
+    PackError,
+    PackNotFoundError,
+    PackPolicy,
+    PackPrompt,
+    PackPromptLoadError,
+    PackSchemaViolation,
+    PackSettingsMissingError,
+    PackValidationError,
+    PackVersionConflictError,
+    PendingApproval,
+    RelationType,
+    clear_discovery_cache,
+    discover,
+    load_by_name,
+    load_prompts_from_dir,
+)
+
+__all__ = [
+    "ActiveGraphError",
+    "AmbiguousBehaviorError",
+    "AmbiguousToolError",
+    "ApprovalNotFoundError",
+    "Behavior",
+    "BehaviorNotFoundError",
+    "Budget",
+    "Clock",
+    "ConfigurationError",
+    "CorruptedEventPayloadError",
+    "Diff",
+    "DiscoveredPack",
+    "DivergentObject",
+    "DivergentRelation",
+    "DuplicateEventError",
+    "EmptySettings",
+    "Event",
+    "EventNotFoundError",
+    "EventStore",
+    "ExecutionError",
+    "Frame",
+    "FrozenClock",
+    "Graph",
+    "IDGen",
+    "InMemoryEventStore",
+    "IncompatibleRuntimeState",
+    "InternalEvaluatorError",
+    "InvalidActivateAfter",
+    "InvalidArgumentType",
+    "InvalidPatchLifecycleState",
+    "InvalidRuntimeConfiguration",
+    "InvalidStoreURL",
+    "InvalidToolRegistration",
+    "LLMBehavior",
+    "LLMBehaviorError",
+    "Metrics",
+    "MigrationReport",
+    "MigrationRunReport",
+    "MissingOptionalDependency",
+    "MissingProviderError",
+    "MissingToolError",
+    "NoOpMetrics",
+    "NonSerializableEventError",
+    "Object",
+    "ObjectType",
+    "Pack",
+    "PackConflictError",
+    "PackError",
+    "PackNotFoundError",
+    "PackPolicy",
+    "PackPromptLoadError",
+    "PackPrompt",
+    "PackSchemaViolation",
+    "PackSettingsMissingError",
+    "PackValidationError",
+    "PackVersionConflictError",
+    "PatternError",
+    "Patch",
+    "PendingApproval",
+    "Policy",
+    "PrometheusMetrics",
+    "Relation",
+    "RelationBehavior",
+    "RegistrationError",
+    "RelationType",
+    "ReplayDivergenceError",
+    "ReplayError",
+    "RunRecord",
+    "Runtime",
+    "RuntimeContextRequiredError",
+    "RuntimeStatus",
+    "SQLiteEventStore",
+    "SchemaVersionMismatch",
+    "StorageError",
+    "TickingClock",
+    "Tool",
+    "ToolContext",
+    "ToolError",
+    "ToolNotFoundError",
+    "UnknownToolError",
+    "UnsupportedPatternError",
+    "View",
+    "behavior",
+    "clear_discovery_cache",
+    "clear_registry",
+    "clear_tool_registry",
+    "configure_logging",
+    "discover",
+    "get_registry",
+    "get_tool_registry",
+    "llm_behavior",
+    "load_by_name",
+    "load_prompts_from_dir",
+    "migrate",
+    "open_store",
+    "parse_store_url",
+    "relation_behavior",
+    "tool",
+]
+
+__version__ = "1.0.0"

activegraph/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m activegraph`` → CLI entry point."""
+
+from activegraph.cli.main import main
+
+raise SystemExit(main())

activegraph/behaviors/__init__.py

@@ -0,0 +1 @@
+"""Behavior decorators and base classes. Imports core only (CONTRACT #14)."""

activegraph/behaviors/base.py

@@ -0,0 +1,153 @@
+"""Behavior + RelationBehavior + LLMBehavior. Plain holders for metadata
+plus the callable.
+
+A Behavior is data, not magic. The decorator wraps a function in one of
+these; class-based behaviors subclass directly. The runtime introspects
+the metadata to match events and build views.
+
+CONTRACT v0.6 #2: an LLMBehavior is structurally a Behavior whose
+invocation lifecycle is owned by the runtime — the developer-supplied
+function is the 4-arg `handler` (event, graph, ctx, llm_output), NOT
+the 3-arg `fn`. Per CONTRACT v0.6 #20, `LLMBehavior.build_prompt` is
+public so a developer can inspect the exact bytes that would be sent
+to the model without making a call.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from activegraph.core.event import Event
+    from activegraph.core.graph import Graph
+    from activegraph.frame import Frame
+    from activegraph.llm.prompt import AssembledPrompt
+
+
+def _llm_behavior_fn_placeholder(event, graph, ctx) -> None:  # pragma: no cover
+    raise RuntimeError(
+        "LLMBehavior.fn invoked directly. The runtime owns LLM behavior "
+        "invocation via _invoke_llm; calling .run() bypasses prompt "
+        "assembly, the provider, and the LLM event log. This is a bug."
+    )
+
+
+@dataclass
+class Behavior:
+    name: str
+    fn: Callable[..., None]
+    on: list[str] = field(default_factory=list)
+    where: Optional[dict[str, Any]] = None
+    view_spec: Optional[dict[str, Any]] = None
+    creates: list[str] = field(default_factory=list)
+    budget: Optional[dict[str, Any]] = None
+    priority: int = 0  # reserved; v0 ties resolved by registration order
+    # CONTRACT v0.7 #8 / #9 / #11. A Cypher subset pattern string.
+    # Compiled at registration time. None = event-type-only matching
+    # (CONTRACT #10).
+    pattern: Optional[str] = None
+    pattern_matcher: Any = None  # PatternMatcher; set by Registry at startup
+    # CONTRACT v0.7 #13. Event-count delay. None = fire immediately.
+    activate_after: Optional[int] = None
+
+    def run(self, event, graph, ctx) -> None:
+        self.fn(event, graph, ctx)
+
+
+@dataclass
+class RelationBehavior:
+    name: str
+    fn: Callable[..., None]
+    relation_type: str
+    on: list[str] = field(default_factory=list)
+    where: Optional[dict[str, Any]] = None
+    view_spec: Optional[dict[str, Any]] = None
+    creates: list[str] = field(default_factory=list)
+    budget: Optional[dict[str, Any]] = None
+    priority: int = 0
+    # Pattern subscriptions also work on relation behaviors. The match
+    # fires once per (event, relation) pair when the pattern matches.
+    pattern: Optional[str] = None
+    pattern_matcher: Any = None
+    activate_after: Optional[int] = None
+
+    def run(self, relation, event, graph, ctx) -> None:
+        self.fn(relation, event, graph, ctx)
+
+
+@dataclass
+class LLMBehavior(Behavior):
+    """A behavior whose body is an LLM call.
+
+    The runtime owns prompt assembly, cache lookup, the provider call,
+    event emission, and structured-output parsing. The developer's
+    `handler` is invoked only after the LLM has responded (or a cached
+    response was found) and the output was successfully parsed.
+
+    CONTRACT v0.7: `tools=` declares a list of `Tool` objects (or
+    strings naming globally-registered tools) the LLM can call during
+    the turn loop. The runtime orchestrates the loop; the handler
+    receives only the final structured output, never raw tool calls.
+    """
+
+    handler: Optional[Callable[..., None]] = None
+    description: str = ""
+    model: str = "claude-sonnet-4-5"
+    output_schema: Optional[type] = None
+    deterministic: bool = False
+    max_tokens: int = 4096
+    temperature: float = 0.7
+    top_p: float = 1.0
+    timeout_seconds: float = 60.0
+    prompt_template: Optional[str] = None
+    # v0.7
+    tools: list = field(default_factory=list)
+    max_tool_turns: int = 6
+
+    def build_prompt(
+        self,
+        event: "Event",
+        graph: "Graph",
+        *,
+        frame: Optional["Frame"] = None,
+    ) -> "AssembledPrompt":
+        """Assemble the prompt that would be sent for this event.
+
+        CONTRACT v0.6 #20 — public so a developer can inspect prompts
+        without making an API call. Reproducible (pure over inputs);
+        cheap (no I/O).
+        """
+
+        from activegraph.llm.prompt import assemble_prompt
+        from activegraph.runtime.view_builder import (
+            DEFAULT_RECENT_EVENTS,
+            _resolve_event_path,
+            build_view,
+        )
+
+        view = build_view(self, event, graph)
+        around_id: Optional[str] = None
+        depth: Optional[int] = None
+        if self.view_spec:
+            ar_expr = self.view_spec.get("around")
+            if ar_expr:
+                around_id = _resolve_event_path(ar_expr, event)
+            depth = self.view_spec.get("depth")
+        return assemble_prompt(
+            behavior_name=self.name,
+            description=self.description,
+            model=self.model,
+            output_schema=self.output_schema,
+            creates=self.creates,
+            view=view,
+            event=event,
+            frame=frame,
+            around=around_id,
+            depth=depth,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+            top_p=self.top_p,
+            deterministic=self.deterministic,
+            prompt_template=self.prompt_template,
+        )

activegraph/behaviors/decorators.py

@@ -0,0 +1,218 @@
+"""@behavior, @relation_behavior, and @llm_behavior decorators
+plus the global registry.
+
+CONTRACT #6: regular behavior signature is (event, graph, ctx) -> None.
+CONTRACT v0.6 #2: @llm_behavior handler signature is
+(event, graph, ctx, llm_output) -> None — the 4th arg is bound by the
+decorator's wrapper, not by the runtime.
+
+The global registry exists so the README quickstart works without an
+explicit `behaviors=[...]` list. `Runtime(graph)` reads the global
+registry by default; passing `behaviors=[...]` overrides it. Tests
+that need isolation can call `clear_registry()`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Union
+
+from activegraph.behaviors.base import (
+    Behavior,
+    LLMBehavior,
+    RelationBehavior,
+    _llm_behavior_fn_placeholder,
+)
+
+
+_REGISTRY: list[Union[Behavior, RelationBehavior]] = []
+
+
+def clear_registry() -> None:
+    _REGISTRY.clear()
+
+
+def get_registry() -> list[Union[Behavior, RelationBehavior]]:
+    return list(_REGISTRY)
+
+
+def behavior(
+    name: Optional[str] = None,
+    on: Optional[list[str]] = None,
+    where: Optional[dict[str, Any]] = None,
+    view: Optional[dict[str, Any]] = None,
+    creates: Optional[list[str]] = None,
+    budget: Optional[dict[str, Any]] = None,
+    priority: int = 0,
+    *,
+    pattern: Optional[str] = None,
+    activate_after: Any = None,
+) -> Callable[[Callable], Behavior]:
+    """Decorate a function as an event-driven behavior.
+
+    v0.7 additions (both keyword-only):
+      - `pattern=`: a Cypher subset pattern string. When set, the
+        behavior fires only when the pattern matches the post-event
+        graph state. Combined with `on=` both conditions must hold
+        (CONTRACT v0.7 #11). Matches are exposed as `ctx.matches`.
+      - `activate_after=`: int event count or "N events". Delays
+        invocation by N events; re-checks `where=` at fire time
+        (CONTRACT v0.7 #13).
+    """
+
+    from activegraph.runtime.patterns import parse as _parse_pattern
+    from activegraph.runtime.scheduler import parse_activate_after as _parse_aa
+
+    compiled_matcher = None
+    if pattern is not None:
+        compiled_matcher = _parse_pattern(pattern).compile()
+    delay_n: Optional[int] = None
+    if activate_after is not None:
+        delay_n = _parse_aa(activate_after)
+
+    def wrap(fn: Callable) -> Behavior:
+        b = Behavior(
+            name=name or fn.__name__,
+            fn=fn,
+            on=list(on or []),
+            where=dict(where) if where else None,
+            view_spec=dict(view) if view else None,
+            creates=list(creates or []),
+            budget=dict(budget) if budget else None,
+            priority=priority,
+            pattern=pattern,
+            pattern_matcher=compiled_matcher,
+            activate_after=delay_n,
+        )
+        _REGISTRY.append(b)
+        return b
+
+    return wrap
+
+
+def llm_behavior(
+    *,
+    name: Optional[str] = None,
+    on: Optional[list[str]] = None,
+    where: Optional[dict[str, Any]] = None,
+    description: str = "",
+    model: str = "claude-sonnet-4-5",
+    output_schema: Optional[type] = None,
+    view: Optional[dict[str, Any]] = None,
+    creates: Optional[list[str]] = None,
+    budget: Optional[dict[str, Any]] = None,
+    deterministic: bool = False,
+    max_tokens: int = 4096,
+    temperature: float = 0.7,
+    top_p: float = 1.0,
+    timeout_seconds: float = 60.0,
+    prompt_template: Optional[str] = None,
+    priority: int = 0,
+    pattern: Optional[str] = None,
+    activate_after: Any = None,
+    tools: Optional[list] = None,
+    max_tool_turns: int = 6,
+) -> Callable[[Callable], LLMBehavior]:
+    """Decorate a function as an LLM-driven behavior.
+
+    The decorated function's signature is
+    `(event, graph, ctx, llm_output) -> None`. The runtime assembles
+    the prompt, calls the provider, parses the structured output, and
+    only then invokes the handler with the parsed result. Failures
+    flow as `behavior.failed` events with a `reason` from
+    CONTRACT v0.6 #11 (`llm.parse_error`, `llm.schema_violation`,
+    `llm.network_error`, `llm.rate_limited`, `budget.cost_exhausted`).
+
+    Keyword-only on purpose — `@llm_behavior` carries enough
+    parameters that positional binding would be a footgun.
+    """
+
+    from activegraph.runtime.patterns import parse as _parse_pattern
+    from activegraph.runtime.scheduler import parse_activate_after as _parse_aa
+
+    compiled_matcher = None
+    if pattern is not None:
+        compiled_matcher = _parse_pattern(pattern).compile()
+    delay_n: Optional[int] = None
+    if activate_after is not None:
+        delay_n = _parse_aa(activate_after)
+
+    def wrap(fn: Callable) -> LLMBehavior:
+        b = LLMBehavior(
+            name=name or fn.__name__,
+            fn=_llm_behavior_fn_placeholder,
+            on=list(on or []),
+            where=dict(where) if where else None,
+            view_spec=dict(view) if view else None,
+            creates=list(creates or []),
+            budget=dict(budget) if budget else None,
+            priority=priority,
+            handler=fn,
+            description=description,
+            model=model,
+            output_schema=output_schema,
+            deterministic=deterministic,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            timeout_seconds=timeout_seconds,
+            prompt_template=prompt_template,
+            pattern=pattern,
+            pattern_matcher=compiled_matcher,
+            activate_after=delay_n,
+            tools=list(tools) if tools else [],
+            max_tool_turns=max_tool_turns,
+        )
+        _REGISTRY.append(b)
+        return b
+
+    return wrap
+
+
+def relation_behavior(
+    relation_type: str,
+    on: Optional[list[str]] = None,
+    name: Optional[str] = None,
+    where: Optional[dict[str, Any]] = None,
+    view: Optional[dict[str, Any]] = None,
+    creates: Optional[list[str]] = None,
+    budget: Optional[dict[str, Any]] = None,
+    priority: int = 0,
+    *,
+    pattern: Optional[str] = None,
+    activate_after: Any = None,
+) -> Callable[[Callable], RelationBehavior]:
+    """Decorate a function as a relation behavior — fires once per matching edge.
+
+    v0.7: also accepts `pattern=` and `activate_after=` per CONTRACT
+    v0.7 #8 / #11 / #13.
+    """
+
+    from activegraph.runtime.patterns import parse as _parse_pattern
+    from activegraph.runtime.scheduler import parse_activate_after as _parse_aa
+
+    compiled_matcher = None
+    if pattern is not None:
+        compiled_matcher = _parse_pattern(pattern).compile()
+    delay_n: Optional[int] = None
+    if activate_after is not None:
+        delay_n = _parse_aa(activate_after)
+
+    def wrap(fn: Callable) -> RelationBehavior:
+        rb = RelationBehavior(
+            name=name or fn.__name__,
+            fn=fn,
+            relation_type=relation_type,
+            on=list(on or []),
+            where=dict(where) if where else None,
+            view_spec=dict(view) if view else None,
+            creates=list(creates or []),
+            budget=dict(budget) if budget else None,
+            priority=priority,
+            pattern=pattern,
+            pattern_matcher=compiled_matcher,
+            activate_after=delay_n,
+        )
+        _REGISTRY.append(rb)
+        return rb
+
+    return wrap

activegraph/cli/__init__.py

@@ -0,0 +1,17 @@
+"""activegraph CLI. CONTRACT v0.8 #12.
+
+A thin wrapper around library APIs. No business logic in the CLI — every
+subcommand calls into the library and formats the result. Programmatic
+users do exactly the same things the CLI does.
+
+Entry point is wired via ``[project.scripts]`` in pyproject:
+
+    activegraph = "activegraph.cli.main:main"
+
+So ``activegraph inspect ...`` runs ``activegraph.cli.main:main`` with
+the rest of argv.
+"""
+
+from activegraph.cli.main import main, EXIT_CODES
+
+__all__ = ["main", "EXIT_CODES"]