knowledge-graph-rdbms 0.1.0__py3-none-any.whl

kgrdbms/__init__.py

@@ -0,0 +1,50 @@
+"""kgrdbms — a label property graph on an RDBMS (SQLite).
+
+A small, dependency-free knowledge-graph core:
+
+    * a label property graph (nodes, typed directed edges, labels, JSON props)
+      backed by SQLite — no external graph database required
+    * an append-only, replayable event log with compensation (undo-as-event)
+    * a two-layer mutation gate: compiled-in invariants + configurable policy
+    * an optional MCP server exposing the graph to any MCP-aware client
+      (install the `mcp` extra)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from kgrdbms.graph import Edge, Graph, Node, default_graph_path, slug
+from kgrdbms.events import (
+    EventLog,
+    GraphEvent,
+    apply_event,
+    edge_spec,
+    node_spec,
+    replay,
+)
+from kgrdbms.policy import Decision, MutationContext, mutation_check
+from kgrdbms.invariants import InvariantViolation, enforce
+
+__all__ = [
+    "__version__",
+    # graph
+    "Graph",
+    "Node",
+    "Edge",
+    "slug",
+    "default_graph_path",
+    # events
+    "EventLog",
+    "GraphEvent",
+    "apply_event",
+    "replay",
+    "node_spec",
+    "edge_spec",
+    # policy / invariants
+    "MutationContext",
+    "Decision",
+    "mutation_check",
+    "InvariantViolation",
+    "enforce",
+]

kgrdbms/backends/__init__.py

@@ -0,0 +1,69 @@
+"""Backend registry — the pluggable data plane.
+
+An engine is a factory `(*, location, **options) -> GraphBackend` registered
+under a name. The resolver looks the name up here and calls it; it never knows
+which engines exist. Adding one is: write a module, decorate its factory with
+`@backend("name")`, import it below. No switch to edit, nothing else to touch.
+
+    from kgrdbms.backends import backend
+    from kgrdbms.backends.base import GraphBackend
+
+    @backend("myengine")
+    def open_myengine(*, location: str, **options) -> GraphBackend:
+        return MyEngineGraph(location, **options)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from kgrdbms.backends.base import GraphBackend, _StubBackend
+
+BackendFactory = Callable[..., GraphBackend]
+
+_REGISTRY: dict[str, BackendFactory] = {}
+
+
+def backend(name: str) -> Callable[[BackendFactory], BackendFactory]:
+    """Decorator: register a factory under an engine name."""
+
+    def register(factory: BackendFactory) -> BackendFactory:
+        _REGISTRY[name] = factory
+        return factory
+
+    return register
+
+
+def get_backend(name: str) -> BackendFactory:
+    """Resolve an engine name to its factory, or fail with what *is* available."""
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        have = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise ValueError(f"unknown backend {name!r}; registered engines: {have}") from None
+
+
+def available_backends() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+def open_backend(name: str, *, location: str, **options: Any) -> GraphBackend:
+    """Convenience: resolve + construct in one call."""
+    return get_backend(name)(location=location, **options)
+
+
+# Import the engine modules so their @backend(...) registrations run. New
+# engines get one line here.
+from kgrdbms.backends import sqlite as _sqlite  # noqa: E402,F401
+from kgrdbms.backends import postgres as _postgres  # noqa: E402,F401
+from kgrdbms.backends import neo4j as _neo4j  # noqa: E402,F401
+
+__all__ = [
+    "GraphBackend",
+    "_StubBackend",
+    "backend",
+    "get_backend",
+    "available_backends",
+    "open_backend",
+    "BackendFactory",
+]

kgrdbms/backends/base.py

@@ -0,0 +1,104 @@
+"""The backend contract and a raising skeleton for new engines.
+
+`GraphBackend` is the finite method surface the rest of kgrdbms depends on
+(service.py for writes, the read paths for queries). Any engine that implements
+it can sit behind an ontology name — SQLite today, Postgres or Neo4j tomorrow.
+
+`_StubBackend` is a courtesy: it implements every method by raising a clear
+"not implemented yet" so a new engine can be registered and *routed to*
+immediately, failing loudly per-call with exactly what's missing. Subclass it,
+set `engine`, and replace methods one at a time as you build the real thing.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator, Protocol, runtime_checkable
+
+from kgrdbms.graph import Edge, Node
+
+
+@runtime_checkable
+class GraphBackend(Protocol):
+    """The uniform graph surface. The interface is engine-agnostic; the *cost*
+    of each call is not (a deep traversal is ~7µs of index lookups on SQLite and
+    a pointer-chase under a Bolt round-trip on Neo4j) — which is exactly why the
+    control plane routes by workload rather than pretending engines are fungible.
+    """
+
+    # writes — the gated path in service.py calls these
+    def add_node(self, *args: Any, **kwargs: Any) -> Node: ...
+    def add_label(self, node_id: str, *labels: str) -> None: ...
+    def set_property(self, node_id: str, key: str, value: Any) -> None: ...
+    def delete_node(self, node_id: str) -> bool: ...
+    def add_edge(self, *args: Any, **kwargs: Any) -> Edge: ...
+    def delete_edge(self, from_node: str, to_node: str, type: str) -> int: ...
+    def incident_edges(self, node_id: str) -> list[Edge]: ...
+    # reads
+    def node(self, id: str) -> Node | None: ...
+    def nodes_by_kind(self, kind: str) -> list[Node]: ...
+    def nodes_by_label(self, label: str) -> list[Node]: ...
+    def out(self, node_id: str, edge_type: str | None = ...) -> list[tuple[Edge, Node]]: ...
+    def in_(self, node_id: str, edge_type: str | None = ...) -> list[tuple[Edge, Node]]: ...
+    def neighborhood(self, node_id: str, depth: int = ...) -> dict[str, Node]: ...
+    def shortest_path(self, from_id: str, to_id: str, max_depth: int = ...) -> list[Node] | None: ...
+    def descendants(self, node_id: str, edge_type: str, max_depth: int = ...) -> list[Node]: ...
+    def count_nodes_by_kind(self) -> dict[str, int]: ...
+    def count_edges_by_type(self) -> dict[str, int]: ...
+    def total_nodes(self) -> int: ...
+    def total_edges(self) -> int: ...
+    # bulk: a context manager that defers commits to one transaction
+    def batch(self) -> Any: ...
+    def close(self) -> None: ...
+
+
+class _StubBackend:
+    """A registered-but-unbuilt engine: every method raises with what's missing.
+
+    Satisfies `GraphBackend` structurally (all methods present), so the resolver
+    will route to it and each call fails loudly rather than silently. Subclass,
+    set `engine`, override as you implement.
+    """
+
+    engine = "stub"
+
+    def __init__(self, location: str, **options: Any) -> None:
+        self.location = location
+        self.options = options
+
+    def _todo(self, method: str) -> Any:
+        raise NotImplementedError(
+            f"{self.engine} backend: .{method}() not implemented yet "
+            f"(location={self.location!r}). Override it on {type(self).__name__}."
+        )
+
+    # writes
+    def add_node(self, *a: Any, **k: Any) -> Node: return self._todo("add_node")
+    def add_label(self, *a: Any, **k: Any) -> None: return self._todo("add_label")
+    def set_property(self, *a: Any, **k: Any) -> None: return self._todo("set_property")
+    def delete_node(self, *a: Any, **k: Any) -> bool: return self._todo("delete_node")
+    def add_edge(self, *a: Any, **k: Any) -> Edge: return self._todo("add_edge")
+    def delete_edge(self, *a: Any, **k: Any) -> int: return self._todo("delete_edge")
+    def incident_edges(self, *a: Any, **k: Any) -> list[Edge]: return self._todo("incident_edges")
+    # reads
+    def node(self, *a: Any, **k: Any) -> Node | None: return self._todo("node")
+    def nodes_by_kind(self, *a: Any, **k: Any) -> list[Node]: return self._todo("nodes_by_kind")
+    def nodes_by_label(self, *a: Any, **k: Any) -> list[Node]: return self._todo("nodes_by_label")
+    def out(self, *a: Any, **k: Any) -> list[tuple[Edge, Node]]: return self._todo("out")
+    def in_(self, *a: Any, **k: Any) -> list[tuple[Edge, Node]]: return self._todo("in_")
+    def neighborhood(self, *a: Any, **k: Any) -> dict[str, Node]: return self._todo("neighborhood")
+    def shortest_path(self, *a: Any, **k: Any) -> list[Node] | None: return self._todo("shortest_path")
+    def descendants(self, *a: Any, **k: Any) -> list[Node]: return self._todo("descendants")
+    def count_nodes_by_kind(self, *a: Any, **k: Any) -> dict[str, int]: return self._todo("count_nodes_by_kind")
+    def count_edges_by_type(self, *a: Any, **k: Any) -> dict[str, int]: return self._todo("count_edges_by_type")
+    def total_nodes(self, *a: Any, **k: Any) -> int: return self._todo("total_nodes")
+    def total_edges(self, *a: Any, **k: Any) -> int: return self._todo("total_edges")
+
+    @contextmanager
+    def batch(self) -> Iterator["_StubBackend"]:
+        """A no-op batch — writes inside still raise via _todo when attempted."""
+        yield self
+
+    def close(self) -> None:
+        """Closing a never-opened stub is a no-op (keeps resolver cleanup safe)."""
+        return None

kgrdbms/backends/neo4j.py

@@ -0,0 +1,45 @@
+"""Neo4j engine — STUB.
+
+Strategic role: the *escalation target* for a specific ontology whose workload
+turns deep. kgrdbms's own benchmark measured the crossover — shallow point reads
+favour embedded SQLite by ~30-60×, but a 1,000-deep traversal favours Neo4j's
+index-free adjacency by ~76×. So this engine isn't a replacement for the default;
+it's where the control plane *routes a heavy ontology* while everything else
+stays embedded. Different engine per ontology, one uniform interface.
+
+Implementation sketch (when we build it):
+  * `location` is a Bolt URI (+ auth in `options`); methods compile to Cypher.
+    `shortest_path` -> `shortestPath((a)-[*]-(b))`, `descendants` -> variable-
+    length `MATCH`, point lookups -> `MATCH (n {id:$id})`.
+  * Neo4j is its OWN source of truth, so the event log MUST live in the control
+    plane (SQLite): apply each gated event to Neo4j as a projection, keep the
+    log — that's how audit / replay / undo survive a non-relational backend.
+    That seam is now built: the resolver already pairs any non-sqlite backend
+    with a `_ControlPlaneLogStore` (an events.db sidecar) via
+    `EventLog(store, projection=backend)`, exactly as the live postgres engine
+    uses it. A Neo4j engine just implements the `GraphBackend` surface; the log
+    plumbing is done.
+  * Mind the Bolt round-trip (~0.4ms) — it's the fixed cost the workload router
+    is weighing against SQLite's in-process ~7µs.
+
+Stubbed: `location` stored, no driver opened; every method raises via
+`_StubBackend` with what's missing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kgrdbms.backends import backend
+from kgrdbms.backends.base import GraphBackend, _StubBackend
+
+
+class Neo4jGraph(_StubBackend):
+    engine = "neo4j"
+    # TODO: open a Bolt driver to `self.location`, and override _StubBackend's
+    # methods with Cypher. Pair with a control-plane event log (see module docs).
+
+
+@backend("neo4j")
+def open_neo4j(*, location: str, **options: Any) -> GraphBackend:
+    return Neo4jGraph(location, **options)