activegraph 1.0.0rc2__tar.gz

activegraph-1.0.0rc2/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: activegraph
+Version: 1.0.0rc2
+Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
+Author: Active Graph contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yoheinakajima/activegraph
+Keywords: graph,agents,event-sourcing,runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click<9,>=8
+Requires-Dist: pydantic>=2
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
+Requires-Dist: pydantic>=2; extra == "llm"
+Provides-Extra: sqlite
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
+Provides-Extra: prometheus
+Requires-Dist: prometheus_client>=0.20; extra == "prometheus"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == "all"
+Requires-Dist: pydantic>=2; extra == "all"
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == "all"
+Requires-Dist: prometheus_client>=0.20; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pydantic>=2; extra == "dev"
+Requires-Dist: prometheus_client>=0.20; extra == "dev"
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == "dev"
+
+# Active Graph
+
+> The graph is the world. Behaviors are physics. The trace is the proof.
+
+An event-sourced reactive graph runtime for long-running, auditable,
+agentic systems. Behaviors react to a shared graph instead of talking
+to each other. Every change is traceable. Every run is resumable,
+forkable, and diff-able from its event log.
+
+If chat-based agents are a group conversation, Active Graph is a
+shared workspace where everyone can see what changed, who changed
+it, and why.
+
+## Try it in 30 seconds
+
+```bash
+pip install activegraph
+activegraph quickstart
+```
+
+The bundled Diligence pack runs against recorded fixtures: no API
+key, no configuration, byte-deterministic output. You see what the
+framework does before you read about how it does it.
+
+Then walk the 10-minute tutorial:
+
+```bash
+activegraph quickstart --interactive
+```
+
+It scaffolds a behavior, runs it against the same fixtures, and ends
+with the fork-and-diff workflow — the framework's most differentiated
+capability.
+
+## Install
+
+```bash
+pip install activegraph                    # core runtime + SQLite store + Diligence pack
+pip install "activegraph[llm]"             # Anthropic provider
+pip install "activegraph[postgres]"        # Postgres-backed event store
+pip install "activegraph[prometheus]"      # Prometheus metrics
+pip install "activegraph[all]"             # everything
+```
+
+Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
+for the pack format); persistence backends and provider integrations
+are opt-in extras.
+
+## What you get
+
+- **Event-sourced graph runtime.** Objects + typed relations + an
+  append-only event log. Every mutation is an event; the trace is the
+  audit trail.
+- **Reactive behaviors as first-class.** Function, class, LLM-backed,
+  or attached to typed edges (the relation-behavior primitive — edges
+  with logic). Subscriptions are event type + predicate + a Cypher
+  subset for graph-shape patterns.
+- **Fork-and-diff.** Branch any run at any event into an independent
+  fork, configure it differently, and structurally diff the result
+  against the parent. Cache replay means the shared prefix doesn't
+  re-execute (no new LLM calls). Most agent frameworks can't do this.
+- **Packs.** A pack bundles object types, behaviors, tools, prompts,
+  and policies for a specific domain. The bundled
+  [Diligence pack](activegraph/packs/diligence) is the reference:
+  8 object types, 7 behaviors, 3 tools, recorded fixtures.
+- **Per-error reference pages.** Every error message ends with a
+  `More:` link to a page that explains when it fires, why, and how to
+  fix it. Catalog at [docs.activegraph.dev/reference/errors](https://docs.activegraph.dev/reference/errors/).
+
+## A small example
+
+The relation-behavior primitive — coordination logic on the edge,
+not on either endpoint:
+
+```python
+from activegraph import Graph, Runtime, behavior, relation_behavior
+
+graph = Graph()
+runtime = Runtime(graph, budget={"max_events": 200, "max_seconds": 60})
+
+@behavior(name="planner", on=["goal.created"])
+def planner(event, graph, ctx):
+    research = graph.add_object("task", {"title": "Research", "status": "open"})
+    memo = graph.add_object("task", {"title": "Draft memo", "status": "blocked"})
+    graph.add_relation(research.id, memo.id, "depends_on")
+
+@behavior(name="researcher", on=["object.created"], where={"object.type": "task"})
+def researcher(event, graph, ctx):
+    task = event.payload["object"]
+    if task["data"]["status"] != "open" or "Research" not in task["data"]["title"]:
+        return
+    graph.add_object("claim", {"text": "Market early but growing.", "confidence": 0.7})
+    graph.emit("task.completed", {"task_id": task["id"]})
+
+@relation_behavior(name="unblock", relation_type="depends_on", on=["task.completed"])
+def unblock(relation, event, graph, ctx):
+    if event.payload["task_id"] == relation.source:
+        graph.patch_object(relation.target, {"status": "open"})
+
+runtime.run_goal("Evaluate this startup idea")
+runtime.print_trace()
+```
+
+The `unblock` relation behavior fires only for events touching one of
+its edge endpoints. The conceptual deep-dive on edges-with-logic is
+in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relations/).
+
+## Documentation
+
+- **[docs.activegraph.dev](https://docs.activegraph.dev/)** — full doc site:
+  concepts, guides, cookbook, CLI reference, API reference, the
+  per-error catalog.
+- **[10-minute tutorial](https://docs.activegraph.dev/quickstart/)** — install
+  to a working custom behavior, including fork-and-diff.
+- **[CHANGELOG.md](CHANGELOG.md)** — every release, with per-version
+  migration notes.
+- **[CONTRACT.md](CONTRACT.md)** — locked design decisions, version
+  by version. Useful when you want to know *why* something is the way
+  it is.
+- **[examples/](examples)** — runnable end-to-end demos:
+  [`diligence_real_run.py`](examples/diligence_real_run.py),
+  [`resume_and_fork.py`](examples/resume_and_fork.py),
+  [`llm_claim_extraction.py`](examples/llm_claim_extraction.py),
+  [`diligence_with_tools.py`](examples/diligence_with_tools.py),
+  [`operate_a_run.py`](examples/operate_a_run.py).
+
+## What this is not
+
+- Not a chat framework. If your problem fits in one conversation, use
+  a chat framework.
+- Not a workflow engine. Workflows model control flow. This models
+  world state.
+- Not a rules engine, exactly. Rules engines forward-chain over
+  facts. This event-sources over a graph and supports LLM behaviors
+  as first-class.
+- Not a production graph database. The default store is SQLite,
+  optionally Postgres. For a high-throughput graph backend, plug one
+  in behind the `EventStore` protocol.
+- Not magic. Bad behaviors produce bad graphs. The runtime makes the
+  badness inspectable, not absent.
+
+## Status
+
+**v1.0-rc1** (2026-05). v1.0 final ships after the first-time-user
+gate per [CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally).
+See [CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
+per-version migration notes.
+
+Major shipped milestones:
+
+- **v1.0 (rc1)** — error hierarchy rewrite with per-error reference
+  pages, doc site at [docs.activegraph.dev](https://docs.activegraph.dev/),
+  `activegraph quickstart` command, mypy `--strict` and docstring
+  coverage CI gates.
+- **v0.9** — pack format and the Diligence reference pack (8 object
+  types, 7 behaviors, 3 tools, recorded fixtures).
+- **v0.8** — operator surface: structured logging, Prometheus
+  metrics, `runtime.status()`, full `activegraph` CLI,
+  `PostgresEventStore`.
+- **v0.7** — `@tool` decorator, Cypher-subset pattern subscriptions,
+  temporal predicates.
+- **v0.6** — `@llm_behavior` with structured output, frame-aware
+  prompt construction, cost accounting.
+- **v0.5** — full event-log persistence, save/load across processes,
+  fork from any historical event, structural diff between runs.
+- **v0** — core runtime: graph, behaviors, relation behaviors,
+  patches with optimistic concurrency, views, frames, policies,
+  budgets, the trace.
+
+Roadmap items planned for v1.1 are tracked in
+[CONTRACT.md § v1.1](CONTRACT.md).
+
+## License
+
+MIT.
+
+## Contributing
+
+The core runtime stays small and sharp. Contributions to packs,
+backends, and LLM integrations are especially welcome. Open an issue
+before large changes — the abstractions are still settling.
+
+**Test discipline:** tests must remain deterministic. No live network
+calls in CI. LLM and tool tests use recorded fixtures
+(`RecordedLLMProvider`, `RecordedToolProvider`). If a contribution
+adds a test that would only pass with a live API key or live HTTP,
+it cannot land.
+
+---
+
+The graph is the world. Behaviors are physics. The trace is the proof.

activegraph-1.0.0rc2/README.md

@@ -0,0 +1,191 @@
+# Active Graph
+
+> The graph is the world. Behaviors are physics. The trace is the proof.
+
+An event-sourced reactive graph runtime for long-running, auditable,
+agentic systems. Behaviors react to a shared graph instead of talking
+to each other. Every change is traceable. Every run is resumable,
+forkable, and diff-able from its event log.
+
+If chat-based agents are a group conversation, Active Graph is a
+shared workspace where everyone can see what changed, who changed
+it, and why.
+
+## Try it in 30 seconds
+
+```bash
+pip install activegraph
+activegraph quickstart
+```
+
+The bundled Diligence pack runs against recorded fixtures: no API
+key, no configuration, byte-deterministic output. You see what the
+framework does before you read about how it does it.
+
+Then walk the 10-minute tutorial:
+
+```bash
+activegraph quickstart --interactive
+```
+
+It scaffolds a behavior, runs it against the same fixtures, and ends
+with the fork-and-diff workflow — the framework's most differentiated
+capability.
+
+## Install
+
+```bash
+pip install activegraph                    # core runtime + SQLite store + Diligence pack
+pip install "activegraph[llm]"             # Anthropic provider
+pip install "activegraph[postgres]"        # Postgres-backed event store
+pip install "activegraph[prometheus]"      # Prometheus metrics
+pip install "activegraph[all]"             # everything
+```
+
+Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
+for the pack format); persistence backends and provider integrations
+are opt-in extras.
+
+## What you get
+
+- **Event-sourced graph runtime.** Objects + typed relations + an
+  append-only event log. Every mutation is an event; the trace is the
+  audit trail.
+- **Reactive behaviors as first-class.** Function, class, LLM-backed,
+  or attached to typed edges (the relation-behavior primitive — edges
+  with logic). Subscriptions are event type + predicate + a Cypher
+  subset for graph-shape patterns.
+- **Fork-and-diff.** Branch any run at any event into an independent
+  fork, configure it differently, and structurally diff the result
+  against the parent. Cache replay means the shared prefix doesn't
+  re-execute (no new LLM calls). Most agent frameworks can't do this.
+- **Packs.** A pack bundles object types, behaviors, tools, prompts,
+  and policies for a specific domain. The bundled
+  [Diligence pack](activegraph/packs/diligence) is the reference:
+  8 object types, 7 behaviors, 3 tools, recorded fixtures.
+- **Per-error reference pages.** Every error message ends with a
+  `More:` link to a page that explains when it fires, why, and how to
+  fix it. Catalog at [docs.activegraph.dev/reference/errors](https://docs.activegraph.dev/reference/errors/).
+
+## A small example
+
+The relation-behavior primitive — coordination logic on the edge,
+not on either endpoint:
+
+```python
+from activegraph import Graph, Runtime, behavior, relation_behavior
+
+graph = Graph()
+runtime = Runtime(graph, budget={"max_events": 200, "max_seconds": 60})
+
+@behavior(name="planner", on=["goal.created"])
+def planner(event, graph, ctx):
+    research = graph.add_object("task", {"title": "Research", "status": "open"})
+    memo = graph.add_object("task", {"title": "Draft memo", "status": "blocked"})
+    graph.add_relation(research.id, memo.id, "depends_on")
+
+@behavior(name="researcher", on=["object.created"], where={"object.type": "task"})
+def researcher(event, graph, ctx):
+    task = event.payload["object"]
+    if task["data"]["status"] != "open" or "Research" not in task["data"]["title"]:
+        return
+    graph.add_object("claim", {"text": "Market early but growing.", "confidence": 0.7})
+    graph.emit("task.completed", {"task_id": task["id"]})
+
+@relation_behavior(name="unblock", relation_type="depends_on", on=["task.completed"])
+def unblock(relation, event, graph, ctx):
+    if event.payload["task_id"] == relation.source:
+        graph.patch_object(relation.target, {"status": "open"})
+
+runtime.run_goal("Evaluate this startup idea")
+runtime.print_trace()
+```
+
+The `unblock` relation behavior fires only for events touching one of
+its edge endpoints. The conceptual deep-dive on edges-with-logic is
+in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relations/).
+
+## Documentation
+
+- **[docs.activegraph.dev](https://docs.activegraph.dev/)** — full doc site:
+  concepts, guides, cookbook, CLI reference, API reference, the
+  per-error catalog.
+- **[10-minute tutorial](https://docs.activegraph.dev/quickstart/)** — install
+  to a working custom behavior, including fork-and-diff.
+- **[CHANGELOG.md](CHANGELOG.md)** — every release, with per-version
+  migration notes.
+- **[CONTRACT.md](CONTRACT.md)** — locked design decisions, version
+  by version. Useful when you want to know *why* something is the way
+  it is.
+- **[examples/](examples)** — runnable end-to-end demos:
+  [`diligence_real_run.py`](examples/diligence_real_run.py),
+  [`resume_and_fork.py`](examples/resume_and_fork.py),
+  [`llm_claim_extraction.py`](examples/llm_claim_extraction.py),
+  [`diligence_with_tools.py`](examples/diligence_with_tools.py),
+  [`operate_a_run.py`](examples/operate_a_run.py).
+
+## What this is not
+
+- Not a chat framework. If your problem fits in one conversation, use
+  a chat framework.
+- Not a workflow engine. Workflows model control flow. This models
+  world state.
+- Not a rules engine, exactly. Rules engines forward-chain over
+  facts. This event-sources over a graph and supports LLM behaviors
+  as first-class.
+- Not a production graph database. The default store is SQLite,
+  optionally Postgres. For a high-throughput graph backend, plug one
+  in behind the `EventStore` protocol.
+- Not magic. Bad behaviors produce bad graphs. The runtime makes the
+  badness inspectable, not absent.
+
+## Status
+
+**v1.0-rc1** (2026-05). v1.0 final ships after the first-time-user
+gate per [CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally).
+See [CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
+per-version migration notes.
+
+Major shipped milestones:
+
+- **v1.0 (rc1)** — error hierarchy rewrite with per-error reference
+  pages, doc site at [docs.activegraph.dev](https://docs.activegraph.dev/),
+  `activegraph quickstart` command, mypy `--strict` and docstring
+  coverage CI gates.
+- **v0.9** — pack format and the Diligence reference pack (8 object
+  types, 7 behaviors, 3 tools, recorded fixtures).
+- **v0.8** — operator surface: structured logging, Prometheus
+  metrics, `runtime.status()`, full `activegraph` CLI,
+  `PostgresEventStore`.
+- **v0.7** — `@tool` decorator, Cypher-subset pattern subscriptions,
+  temporal predicates.
+- **v0.6** — `@llm_behavior` with structured output, frame-aware
+  prompt construction, cost accounting.
+- **v0.5** — full event-log persistence, save/load across processes,
+  fork from any historical event, structural diff between runs.
+- **v0** — core runtime: graph, behaviors, relation behaviors,
+  patches with optimistic concurrency, views, frames, policies,
+  budgets, the trace.
+
+Roadmap items planned for v1.1 are tracked in
+[CONTRACT.md § v1.1](CONTRACT.md).
+
+## License
+
+MIT.
+
+## Contributing
+
+The core runtime stays small and sharp. Contributions to packs,
+backends, and LLM integrations are especially welcome. Open an issue
+before large changes — the abstractions are still settling.
+
+**Test discipline:** tests must remain deterministic. No live network
+calls in CI. LLM and tool tests use recorded fixtures
+(`RecordedLLMProvider`, `RecordedToolProvider`). If a contribution
+adds a test that would only pass with a live API key or live HTTP,
+it cannot land.
+
+---
+
+The graph is the world. Behaviors are physics. The trace is the proof.

activegraph-1.0.0rc2/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.0rc2"

activegraph-1.0.0rc2/activegraph/__main__.py

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

activegraph-1.0.0rc2/activegraph/behaviors/__init__.py

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