activegraph 1.1.0__tar.gz → 1.2.0__tar.gz

{activegraph-1.1.0/activegraph.egg-info → activegraph-1.2.0}/PKG-INFO

@@ -1,10 +1,14 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.1.0
+Version: 1.2.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/yoheinakajima/activegraph
+Project-URL: Documentation, https://docs.activegraph.ai/
+Project-URL: Repository, https://github.com/yoheinakajima/activegraph
+Project-URL: Changelog, https://docs.activegraph.ai/about/changelog/
+Project-URL: Issues, https://github.com/yoheinakajima/activegraph/issues
 Keywords: graph,agents,event-sourcing,runtime
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -32,6 +36,10 @@ Requires-Dist: pydantic>=2; extra == "openai"
 Provides-Extra: sqlite
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
+Provides-Extra: falkordb
+Requires-Dist: falkordb>=1.0; extra == "falkordb"
+Provides-Extra: falkordb-embedded
+Requires-Dist: falkordblite>=0.10; extra == "falkordb-embedded"
 Provides-Extra: prometheus
 Requires-Dist: prometheus_client>=0.20; extra == "prometheus"
 Provides-Extra: opentelemetry
@@ -303,23 +311,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - 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 a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). 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)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -340,8 +359,9 @@ Major shipped milestones:
   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).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.1.0 → activegraph-1.2.0}/README.md

@@ -240,23 +240,34 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations
 - 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 a production graph database. The event log lives in SQLite
+  (default) or Postgres behind the `EventStore` protocol; the
+  materialized graph lives behind the `GraphStore` protocol —
+  in-memory by default, or [FalkorDB](https://docs.activegraph.ai/guides/using-falkordb/)
+  for a real, traversable graph backend. For a different
+  high-throughput store, plug one in behind either protocol.
 - Not magic. Bad behaviors produce bad graphs. The runtime makes the
   badness inspectable, not absent.
 
 ## Status
 
-**v1.0 (stable)** (2026-05). 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)
-ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
-output fix and a README "Concepts at a glance" index. See
-[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
-per-version migration notes.
+**v1.2.0 (stable)** (2026-07). v1.0 shipped in May 2026 after a
+three-rc external user-test gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally);
+v1.1.0 and v1.2.0 followed. See [CHANGELOG.md](CHANGELOG.md) for the
+full v0 → v1.2 history and per-version migration notes.
 
 Major shipped milestones:
 
+- **v1.2** — the `GraphStore` seam: the materialized projection
+  becomes pluggable, with `FalkorDBGraphStore` (native edges, Cypher
+  query push-down) as the first external backend, contributed by
+  [@dudizimber](https://github.com/dudizimber); the test suite
+  becomes a CI gate.
+- **v1.1** — bounded LLM retries for transient provider failures,
+  `inspect --memo` / `inspect --search`, `fork --set`, OpenAI
+  tool-shape parity, `OpenTelemetryMetrics`, and the
+  spec-vs-impl drift gates.
 - **v1.0** — error hierarchy rewrite with per-error reference
   pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
@@ -277,8 +288,9 @@ Major shipped milestones:
   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).
+Roadmap items for the current cycle are tracked in
+[ROADMAP.md](ROADMAP.md); unscheduled candidates live in
+[FUTURE_IDEAS.md](FUTURE_IDEAS.md).
 
 ## License
 

{activegraph-1.1.0 → activegraph-1.2.0}/activegraph/__init__.py

@@ -61,7 +61,10 @@ from activegraph.store import (
     DuplicateEventError,
     EventNotFoundError,
     EventStore,
+    FalkorDBGraphStore,
+    GraphStore,
     InMemoryEventStore,
+    InMemoryGraphStore,
     InvalidStoreURL,
     NonSerializableEventError,
     RunRecord,
@@ -142,11 +145,14 @@ __all__ = [
     "EventNotFoundError",
     "EventStore",
     "ExecutionError",
+    "FalkorDBGraphStore",
     "Frame",
     "FrozenClock",
     "Graph",
+    "GraphStore",
     "IDGen",
     "InMemoryEventStore",
+    "InMemoryGraphStore",
     "IncompatibleRuntimeState",
     "InternalEvaluatorError",
     "InvalidActivateAfter",
@@ -224,4 +230,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"

activegraph-1.2.0/activegraph/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core primitives. Knows nothing about runtime or behaviors."""
+
+from activegraph.core.graph_store import GraphStore, InMemoryGraphStore
+
+__all__ = [
+    "GraphStore",
+    "InMemoryGraphStore",
+]

{activegraph-1.1.0 → activegraph-1.2.0}/activegraph/core/graph.py

@@ -28,6 +28,7 @@ from typing import Any, Callable, Optional
 
 from activegraph.core.clock import Clock
 from activegraph.core.event import Event
+from activegraph.core.graph_store import GraphStore, InMemoryGraphStore
 from activegraph.core.ids import IDGen
 from activegraph.core.patch import Patch
 
@@ -104,16 +105,19 @@ class Graph:
         ids: Optional[IDGen] = None,
         clock: Optional[Clock] = None,
         run_id: Optional[str] = None,
+        graph_store: Optional[GraphStore] = None,
     ) -> None:
         self.ids = ids or IDGen()
         self.clock = clock or Clock()
         # CONTRACT v0.5 #6: every graph has a run_id.
         self.run_id: str = run_id or self.ids.run()
 
-        # projected state — touched ONLY by apply_event (CONTRACT v0.5 #15)
-        self._objects: dict[str, Object] = {}
-        self._relations: dict[str, Relation] = {}
-        self._patches: dict[str, Patch] = {}
+        # projected state — touched ONLY by apply_event (CONTRACT v0.5 #15).
+        # v1.2: the projection lives behind a GraphStore so it can be kept
+        # in process memory (the default) or pushed into an external graph
+        # database. `self._state` is the materialized current-state view; it
+        # is NOT the durable event log (that is `self._store`, an EventStore).
+        self._state: GraphStore = graph_store or InMemoryGraphStore()
 
         # the log
         self._events: list[Event] = []
@@ -147,19 +151,19 @@ class Graph:
         return frozenset(self._replayed_ids)
 
     def get_object(self, id_: str) -> Optional[Object]:
-        return self._objects.get(id_)
+        return self._state.get_object(id_)
 
     def get_relation(self, id_: str) -> Optional[Relation]:
-        return self._relations.get(id_)
+        return self._state.get_relation(id_)
 
     def get_patch(self, id_: str) -> Optional[Patch]:
-        return self._patches.get(id_)
+        return self._state.get_patch(id_)
 
     def all_objects(self) -> list[Object]:
-        return list(self._objects.values())
+        return self._state.all_objects()
 
     def all_relations(self) -> list[Relation]:
-        return list(self._relations.values())
+        return self._state.all_relations()
 
     def get_relations(
         self,
@@ -167,19 +171,25 @@ class Graph:
         type: Optional[str] = None,
         direction: str = "both",
     ) -> list[Relation]:
-        out: list[Relation] = []
-        for r in self._relations.values():
-            if type is not None and r.type != type:
-                continue
-            if object_id is not None:
-                if direction == "outgoing" and r.source != object_id:
-                    continue
-                if direction == "incoming" and r.target != object_id:
-                    continue
-                if direction == "both" and object_id not in (r.source, r.target):
-                    continue
-            out.append(r)
-        return out
+        # Pushed down to the store via find_relations (see graph_store.py).
+        # Decompose the (object_id, direction) axis into source/target slots:
+        # "outgoing"/"incoming" map to a single directional filter; "both"
+        # needs source-OR-target, which find_relations (AND-only) can't express,
+        # so we push the type filter and apply the membership test here. An
+        # unrecognized direction keeps the v0 quirk of ignoring object_id.
+        if object_id is None:
+            return self._state.find_relations(type=type)
+        if direction == "outgoing":
+            return self._state.find_relations(source=object_id, type=type)
+        if direction == "incoming":
+            return self._state.find_relations(target=object_id, type=type)
+        if direction == "both":
+            return [
+                r
+                for r in self._state.find_relations(type=type)
+                if object_id in (r.source, r.target)
+            ]
+        return self._state.find_relations(type=type)
 
     def relations(
         self,
@@ -197,40 +207,27 @@ class Graph:
         relation. ``Graph.get_relations(object_id=, type=, direction=)``
         stays as a backward-compatible alias.
         """
-        out: list[Relation] = []
-        for r in self._relations.values():
-            if source is not None and r.source != source:
-                continue
-            if target is not None and r.target != target:
-                continue
-            if type is not None and r.type != type:
-                continue
-            out.append(r)
-        return out
+        # Pushed down to the store (find_relations applies the same AND filter).
+        return self._state.find_relations(source=source, target=target, type=type)
 
     def neighborhood(self, object_id: str, depth: int = 1) -> tuple[list[Object], list[Relation]]:
-        if object_id not in self._objects:
-            return ([], [])
-        seen_objs = {object_id}
-        frontier = {object_id}
-        seen_rels: set[str] = set()
-        for _ in range(depth):
-            next_frontier: set[str] = set()
-            for r in self._relations.values():
-                if r.source in frontier or r.target in frontier:
-                    seen_rels.add(r.id)
-                    if r.source not in seen_objs:
-                        next_frontier.add(r.source)
-                    if r.target not in seen_objs:
-                        next_frontier.add(r.target)
-            seen_objs |= next_frontier
-            frontier = next_frontier
-            if not frontier:
-                break
-        return (
-            [self._objects[i] for i in seen_objs if i in self._objects],
-            [self._relations[i] for i in seen_rels if i in self._relations],
-        )
+        # Pushed down to the store (default is the same BFS; FalkorDB uses a
+        # native variable-length path query). See GraphStore.neighborhood.
+        return self._state.neighborhood(object_id, depth)
+
+    def match_chain(self, node_types, rels):
+        # Pushed down to the store: the default mirrors the matcher's
+        # structural chain walk; FalkorDB resolves the whole chain in one
+        # Cypher query. Node {prop: value} equality and WHERE stay in the
+        # matcher (Python). See GraphStore.match_chain.
+        return self._state.match_chain(node_types, rels)
+
+    def objects_in_types(self, types: list[str]) -> list[Object]:
+        # Pushed down to the store: OR-of-types in one query (FalkorDB uses
+        # ``type IN [...]``); the default single-pass scan preserves order.
+        # Used by the view builder for type-scoped views. See
+        # GraphStore.find_objects_in_types.
+        return self._state.find_objects_in_types(types)
 
     def objects(
         self,
@@ -244,10 +241,10 @@ class Graph:
         and outside behaviors. `Graph.query(object_type=...)` is kept
         as a backward-compatible alias.
         """
+        # Type filter is pushed down to the store via find_objects; the
+        # ``where`` predicate is evaluated in Python over that subset.
         out: list[Object] = []
-        for o in self._objects.values():
-            if type is not None and o.type != type:
-                continue
+        for o in self._state.find_objects(type):
             if where and not _eval_where_on_object(where, o):
                 continue
             out.append(o)
@@ -267,7 +264,8 @@ class Graph:
         return self.objects(type=object_type, where=where)
 
     def has_object_of_type(self, type_: str) -> bool:
-        return any(o.type == type_ for o in self._objects.values())
+        # Pushed down via find_objects (scopes the scan to ``type_``).
+        return bool(self._state.find_objects(type_))
 
     # ---------- listener API (runtime hooks here) ----------
 
@@ -399,7 +397,7 @@ class Graph:
             timestamp=self.clock.now(),
         )
         self.emit(event)
-        return self._objects[obj_id]
+        return self._state.get_object(obj_id)
 
     def add_relation(
         self,
@@ -418,8 +416,8 @@ class Graph:
         clean = _strip_provenance(copy.deepcopy(data or {}))
         # v0.9: relation type validation (source/target type rules).
         if self._pack_relation_validator is not None:
-            src_obj = self._objects.get(source)
-            tgt_obj = self._objects.get(target)
+            src_obj = self._state.get_object(source)
+            tgt_obj = self._state.get_object(target)
             self._pack_relation_validator(
                 type,
                 src_obj.type if src_obj else None,
@@ -456,7 +454,7 @@ class Graph:
             timestamp=self.clock.now(),
         )
         self.emit(event)
-        return self._relations[rel_id]
+        return self._state.get_relation(rel_id)
 
     def remove_relation(
         self,
@@ -466,7 +464,7 @@ class Graph:
         caused_by: Optional[str] = None,
         frame_id: Optional[str] = None,
     ) -> None:
-        if relation_id not in self._relations:
+        if self._state.get_relation(relation_id) is None:
             return
         event = Event(
             id=self.ids.event(),
@@ -487,7 +485,7 @@ class Graph:
         caused_by: Optional[str] = None,
         frame_id: Optional[str] = None,
     ) -> None:
-        if object_id not in self._objects:
+        if self._state.get_object(object_id) is None:
             return
         event = Event(
             id=self.ids.event(),
@@ -514,7 +512,7 @@ class Graph:
         tool_request_event_ids: Optional[list[str]] = None,
     ) -> Patch:
         """Auto-apply shortcut: build patch, version-check, emit applied/rejected."""
-        obj = self._objects.get(target)
+        obj = self._state.get_object(target)
         if obj is None:
             raise KeyError(f"unknown object: {target}")
         clean = _strip_provenance(copy.deepcopy(updates))
@@ -552,7 +550,7 @@ class Graph:
             timestamp=self.clock.now(),
         )
         self.emit(event)
-        return self._patches[patch.id]
+        return self._state.get_patch(patch.id)
 
     def propose_patch(
         self,
@@ -570,7 +568,7 @@ class Graph:
     ) -> Patch:
         # Strip "object:" / "relation:" prefix if present (README sugar).
         normalized = target.split(":", 1)[1] if ":" in target else target
-        obj = self._objects.get(normalized)
+        obj = self._state.get_object(normalized)
         expected_version = obj.version if obj else 0
         clean = _strip_provenance(copy.deepcopy(value))
         patch = Patch(
@@ -602,7 +600,7 @@ class Graph:
             timestamp=self.clock.now(),
         )
         self.emit(event)
-        return self._patches[patch.id]
+        return self._state.get_patch(patch.id)
 
     def apply_patch(
         self,
@@ -612,7 +610,7 @@ class Graph:
         caused_by: Optional[str] = None,
         frame_id: Optional[str] = None,
     ) -> Event:
-        patch = self._patches.get(patch_id)
+        patch = self._state.get_patch(patch_id)
         if patch is None:
             raise KeyError(f"unknown patch: {patch_id}")
         if patch.status != "proposed":
@@ -620,7 +618,7 @@ class Graph:
             raise InvalidPatchLifecycleState(
                 patch_id=patch_id, current_status=patch.status,
             )
-        target_obj = self._objects.get(patch.target)
+        target_obj = self._state.get_object(patch.target)
         current_version = target_obj.version if target_obj else 0
         if current_version != patch.expected_version:
             return self._reject(
@@ -667,8 +665,8 @@ class Graph:
         caused_by: Optional[str],
         frame_id: Optional[str],
     ) -> Event:
-        patch = self._patches[patch_id]
-        current = self._objects.get(patch.target)
+        patch = self._state.get_patch(patch_id)
+        current = self._state.get_object(patch.target)
         event = Event(
             id=self.ids.event(),
             type="patch.rejected",
@@ -732,57 +730,71 @@ def apply_event(graph: Graph, event: Event) -> None:
 
     if t == "object.created":
         o = p["object"]
-        graph._objects[o["id"]] = Object(
-            id=o["id"],
-            type=o["type"],
-            data=copy.deepcopy(o["data"]),
-            version=o["version"],
-            provenance=copy.deepcopy(o["provenance"]),
+        graph._state.put_object(
+            Object(
+                id=o["id"],
+                type=o["type"],
+                data=copy.deepcopy(o["data"]),
+                version=o["version"],
+                provenance=copy.deepcopy(o["provenance"]),
+            )
         )
 
     elif t == "object.removed":
-        graph._objects.pop(p["id"], None)
-        # cascade: drop relations touching it
-        for rid in [
-            r.id for r in graph._relations.values() if p["id"] in (r.source, r.target)
-        ]:
-            graph._relations.pop(rid, None)
+        graph._state.remove_object(p["id"])
+        # cascade: drop relations touching it. Pushed down to two scoped
+        # lookups (out-edges + in-edges) instead of scanning every relation;
+        # on FalkorDB these are index-backed queries. Dedupe by id so a
+        # self-loop (source == target) is removed once.
+        touching = graph._state.find_relations(
+            source=p["id"]
+        ) + graph._state.find_relations(target=p["id"])
+        seen: set[str] = set()
+        for r in touching:
+            if r.id in seen:
+                continue
+            seen.add(r.id)
+            graph._state.remove_relation(r.id)
 
     elif t == "relation.created":
         r = p["relation"]
-        graph._relations[r["id"]] = Relation(
-            id=r["id"],
-            source=r["source"],
-            target=r["target"],
-            type=r["type"],
-            data=copy.deepcopy(r["data"]),
-            provenance=copy.deepcopy(r["provenance"]),
+        graph._state.put_relation(
+            Relation(
+                id=r["id"],
+                source=r["source"],
+                target=r["target"],
+                type=r["type"],
+                data=copy.deepcopy(r["data"]),
+                provenance=copy.deepcopy(r["provenance"]),
+            )
         )
 
     elif t == "relation.removed":
-        graph._relations.pop(p["id"], None)
+        graph._state.remove_relation(p["id"])
 
     elif t == "patch.proposed":
         patch_dict = p["patch"]
-        graph._patches[patch_dict["id"]] = _patch_from_dict(patch_dict)
+        graph._state.put_patch(_patch_from_dict(patch_dict))
 
     elif t == "patch.applied":
         patch_dict = p["patch"]
         patch = _patch_from_dict({**patch_dict, "status": "applied"})
-        graph._patches[patch.id] = patch
-        obj = graph._objects.get(patch.target)
+        graph._state.put_patch(patch)
+        obj = graph._state.get_object(patch.target)
         if obj is not None:
             if patch.op == "update":
                 obj.data.update(patch.value)
             elif patch.op == "replace":
                 obj.data = copy.deepcopy(patch.value)
             obj.version += 1
+            graph._state.put_object(obj)
 
     elif t == "patch.rejected":
-        existing = graph._patches.get(p["patch_id"])
+        existing = graph._state.get_patch(p["patch_id"])
         if existing is not None:
             existing.status = "rejected"
             existing.rejection_reason = p["reason"]
+            graph._state.put_patch(existing)
 
 
 def _patch_from_dict(d: dict[str, Any]) -> Patch: