graph-ted-db 0.1.0__py3-none-any.whl

graph_ted_db/__init__.py

@@ -0,0 +1,23 @@
+"""Local property-graph storage for Python: open a folder and query it in-process (import graph_ted_db)."""
+
+from graph_ted_db.engine import CypherError
+from graph_ted_db.store import (
+    EdgeRecord,
+    GraphStore,
+    NodeRecord,
+    Tombstone,
+    VectorRecord,
+    init_graph,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "CypherError",
+    "EdgeRecord",
+    "GraphStore",
+    "NodeRecord",
+    "Tombstone",
+    "VectorRecord",
+    "__version__",
+    "init_graph",
+]

graph_ted_db/__main__.py

@@ -0,0 +1,3 @@
+from graph_ted_db.cli import main
+
+raise SystemExit(main())

graph_ted_db/cli.py

@@ -0,0 +1,367 @@
+"""Command-line entry: `graph-ted-db` (alias `graphted-db`)."""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from graph_ted_db import __version__
+from graph_ted_db.engine import CypherError
+from graph_ted_db.store import GraphFormatError, GraphStore, init_graph, load_graph_meta
+
+UPDATED_BY_ENV = "GRAPH_TED_DB_UPDATED_BY"
+
+
+def _who(explicit: str | None) -> str:
+    """Author string for written records: --by, else $GRAPH_TED_DB_UPDATED_BY, else empty.
+
+    Never the OS login name: records travel with the folder when it is synced.
+    """
+    if explicit:
+        return explicit
+    return os.environ.get(UPDATED_BY_ENV, "")
+
+
+def _parse_prop(raw: str) -> tuple[str, Any]:
+    key, sep, value = raw.partition("=")
+    if not key or sep != "=":
+        raise argparse.ArgumentTypeError(f"expected key=value, got {raw!r}")
+    try:
+        return key, json.loads(value)
+    except json.JSONDecodeError:
+        return key, value
+
+
+def _store(path: Path) -> GraphStore:
+    root = path.expanduser().resolve()
+    if not (root / "graph.json").is_file():
+        raise GraphFormatError(f"no graph at {path}; create one with `graph-ted-db init {path}`")
+    return GraphStore.open(root)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="graph-ted-db",
+        description="Local property-graph storage. Open a folder and query it in-process; no database server for the default path.",
+        epilog="The graphted-db command is the same entry point.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_p = sub.add_parser("init", help="create an empty graph folder")
+    init_p.add_argument("path", type=Path)
+    init_p.add_argument("--name", default="graph")
+    init_p.add_argument("--exist-ok", action="store_true")
+
+    info_p = sub.add_parser("info", help="print graph.json for a folder")
+    info_p.add_argument(
+        "--check",
+        action="store_true",
+        help="also open the store and print problem counts (skipped lines, files still syncing)",
+    )
+    info_p.add_argument("path", type=Path)
+
+    put_n = sub.add_parser("put-node", help="create or overwrite a node (LWW)")
+    put_n.add_argument("path", type=Path)
+    put_n.add_argument("--id", dest="record_id", default=None)
+    put_n.add_argument("--label", action="append", default=[])
+    put_n.add_argument("--prop", action="append", default=[], type=_parse_prop)
+    put_n.add_argument(
+        "--by",
+        "--updated-by",
+        dest="updated_by",
+        default=None,
+        help="author stored on the record (default: $GRAPH_TED_DB_UPDATED_BY, else empty)",
+    )
+
+    get_n = sub.add_parser("get-node", help="print one node as JSON")
+    get_n.add_argument("path", type=Path)
+    get_n.add_argument("record_id")
+
+    ls_n = sub.add_parser("ls-nodes", help="print live nodes as JSON lines")
+    ls_n.add_argument("path", type=Path)
+
+    del_n = sub.add_parser("delete-node", help="tombstone a node")
+    del_n.add_argument("path", type=Path)
+    del_n.add_argument("record_id")
+    del_n.add_argument(
+        "--by",
+        "--updated-by",
+        dest="updated_by",
+        default=None,
+        help="author stored on the record (default: $GRAPH_TED_DB_UPDATED_BY, else empty)",
+    )
+
+    put_e = sub.add_parser("put-edge", help="create or overwrite an edge (LWW)")
+    put_e.add_argument("path", type=Path)
+    put_e.add_argument("--type", required=True, dest="edge_type")
+    put_e.add_argument("--from", required=True, dest="from_id")
+    put_e.add_argument("--to", required=True, dest="to_id")
+    put_e.add_argument("--id", dest="record_id", default=None)
+    put_e.add_argument("--prop", action="append", default=[], type=_parse_prop)
+    put_e.add_argument(
+        "--by",
+        "--updated-by",
+        dest="updated_by",
+        default=None,
+        help="author stored on the record (default: $GRAPH_TED_DB_UPDATED_BY, else empty)",
+    )
+
+    get_e = sub.add_parser("get-edge", help="print one edge as JSON")
+    get_e.add_argument("path", type=Path)
+    get_e.add_argument("record_id")
+
+    ls_e = sub.add_parser("ls-edges", help="print live edges as JSON lines")
+    ls_e.add_argument("path", type=Path)
+
+    del_e = sub.add_parser("delete-edge", help="tombstone an edge")
+    del_e.add_argument("path", type=Path)
+    del_e.add_argument("record_id")
+    del_e.add_argument(
+        "--by",
+        "--updated-by",
+        dest="updated_by",
+        default=None,
+        help="author stored on the record (default: $GRAPH_TED_DB_UPDATED_BY, else empty)",
+    )
+
+    compact_p = sub.add_parser(
+        "compact",
+        help="rewrite canonical shards to LWW winners (keeps conflict copies)",
+    )
+    compact_p.add_argument("path", type=Path)
+
+    export_p = sub.add_parser(
+        "export", help="write the current state (live records) to one JSONL file, for backup"
+    )
+    export_p.add_argument("path", type=Path)
+    export_p.add_argument("out", type=Path, help="export file (outside the graph folder)")
+
+    import_p = sub.add_parser("import", help="create a new graph folder from an export file")
+    import_p.add_argument("export_file", type=Path)
+    import_p.add_argument("dest", type=Path, help="new graph folder (must not exist yet)")
+    import_p.add_argument("--name", default=None)
+
+    doctor_p = sub.add_parser(
+        "doctor",
+        help="repair torn JSONL, rebuild labels, report dangling edges (--fix tombstones them)",
+        description=(
+            "Repair torn JSONL lines, remove leftover tmp files, rebuild labels.json, and report "
+            "dangling edges (an endpoint is not a live node). Dangling edges are only reported "
+            "unless --fix is given."
+        ),
+    )
+    doctor_p.add_argument("path", type=Path)
+    doctor_p.add_argument(
+        "--fix",
+        action="store_true",
+        help=(
+            "tombstone dangling edges. Permanent, and it syncs to every device: in a synced "
+            "folder, wait until sync has finished, because an edge can arrive before its nodes"
+        ),
+    )
+
+    cypher_p = sub.add_parser(
+        "cypher", help="run an openCypher query (supported subset; see docs/cypher.md)"
+    )
+    cypher_p.add_argument("path", type=Path)
+    cypher_p.add_argument("query", nargs="?", default=None, help="query; omit to read stdin")
+    cypher_p.add_argument(
+        "--params",
+        default="{}",
+        help="JSON object of query parameters",
+    )
+    cypher_p.add_argument(
+        "--by",
+        "--updated-by",
+        dest="updated_by",
+        default=None,
+        help='author stored on written records (default: $GRAPH_TED_DB_UPDATED_BY, else "cypher")',
+    )
+
+    serve_p = sub.add_parser(
+        "serve",
+        help="localhost HTTP daemon (POST /cypher, GET /health); see docs/http.md",
+    )
+    serve_p.add_argument("path", type=Path, help="graph folder to serve")
+    serve_p.add_argument("--host", default=None, help="bind address (default 127.0.0.1)")
+    serve_p.add_argument("--port", type=int, default=None, help="TCP port (default 8099)")
+    serve_p.add_argument(
+        "--token",
+        default=None,
+        help="HTTP token (or GRAPH_TED_DB_TOKEN); required when --host is not loopback",
+    )
+    serve_p.add_argument(
+        "--max-records",
+        type=int,
+        default=None,
+        help="truncate query results after this many rows (default 500)",
+    )
+
+    args, extra = parser.parse_known_args(argv)
+    # Python < 3.12 argparse binds the optional `query` positional before it
+    # sees later options, so `cypher PATH --params P QUERY` leaves QUERY over.
+    if getattr(args, "command", None) == "cypher" and args.query is None and len(extra) == 1:
+        args.query, extra = extra[0], []
+    if extra:
+        parser.error(f"unrecognized arguments: {' '.join(extra)}")
+    try:
+        return _dispatch(args)
+    except (
+        OSError,
+        RuntimeError,
+        GraphFormatError,
+        FileExistsError,
+        ValueError,
+        CypherError,
+        json.JSONDecodeError,
+    ) as exc:
+        print(f"graph-ted-db: {exc}", file=sys.stderr)
+        return 1
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    if args.command == "init":
+        meta = init_graph(args.path, name=args.name, exist_ok=args.exist_ok)
+        print(f"initialized {args.path} id={meta.id} name={meta.name}")
+        return 0
+    if args.command == "info":
+        meta = load_graph_meta(args.path)
+        print(
+            f"{meta.name} id={meta.id} format={meta.format} "
+            f"v{meta.format_version} created_at={meta.created_at}"
+        )
+        if args.check:
+            store = _store(args.path)
+            problems = store.problems()
+            print(
+                f"writer={store.writer_id} writers={len(store.writers())} "
+                + " ".join(f"{k}={v}" for k, v in problems.items())
+            )
+            return 1 if any(problems.values()) else 0
+        return 0
+    if args.command == "import":
+        from graph_ted_db.store import import_export
+
+        imported = import_export(args.export_file, args.dest, name=args.name)
+        print(f"imported into {args.dest} id={imported.meta.id}")
+        return 0
+
+    store = _store(args.path)
+    if args.command == "export":
+        counts = store.export(args.out)
+        print(" ".join(f"{k}={v}" for k, v in counts.items()))
+        return 0
+
+    if args.command == "put-node":
+        rec = store.make_node(
+            labels=args.label,
+            props=dict(args.prop),
+            record_id=args.record_id,
+            updated_by=_who(args.updated_by),
+        )
+        print(json.dumps(rec.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "get-node":
+        found_node = store.get_node(args.record_id)
+        if found_node is None:
+            print(f"graph-ted-db: node {args.record_id} not found", file=sys.stderr)
+            return 1
+        print(json.dumps(found_node.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "ls-nodes":
+        for rec in store.iter_nodes():
+            print(json.dumps(rec.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "delete-node":
+        tomb = store.delete_node(args.record_id, updated_by=_who(args.updated_by))
+        print(json.dumps(tomb.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "put-edge":
+        edge = store.make_edge(
+            type=args.edge_type,
+            from_id=args.from_id,
+            to_id=args.to_id,
+            props=dict(args.prop),
+            record_id=args.record_id,
+            updated_by=_who(args.updated_by),
+        )
+        print(json.dumps(edge.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "get-edge":
+        found_edge = store.get_edge(args.record_id)
+        if found_edge is None:
+            print(f"graph-ted-db: edge {args.record_id} not found", file=sys.stderr)
+            return 1
+        print(json.dumps(found_edge.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "ls-edges":
+        for edge in store.iter_edges():
+            print(json.dumps(edge.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "delete-edge":
+        tomb = store.delete_edge(args.record_id, updated_by=_who(args.updated_by))
+        print(json.dumps(tomb.to_dict(), ensure_ascii=False))
+        return 0
+    if args.command == "compact":
+        store.compact()
+        print(f"compacted {args.path}")
+        return 0
+    if args.command == "doctor":
+        report = store.doctor(fix=args.fix)
+        print(report.summary(), end="")
+        return 0
+    if args.command == "cypher":
+        query = args.query if args.query is not None else sys.stdin.read()
+        params = json.loads(args.params) if args.params else {}
+        if not isinstance(params, dict):
+            raise ValueError("--params must be a JSON object")
+        rows = store.execute(query, params, updated_by=_who(args.updated_by) or "cypher")
+        for row in rows:
+            print(json.dumps(row, ensure_ascii=False))
+        return 0
+    if args.command == "serve":
+        from graph_ted_db.server import (
+            DEFAULT_HOST,
+            DEFAULT_PORT,
+            LOOPBACK_HOSTS,
+            MAX_QUERY_RECORDS,
+            serve,
+        )
+
+        host = args.host or DEFAULT_HOST
+        port = DEFAULT_PORT if args.port is None else args.port
+        max_records = MAX_QUERY_RECORDS if args.max_records is None else args.max_records
+        if args.token is not None:
+            token = args.token.strip()
+        else:
+            token = os.environ.get("GRAPH_TED_DB_TOKEN", "").strip()
+        if host not in LOOPBACK_HOSTS and not token:
+            print(
+                "graph-ted-db: refusing to bind off loopback without a token "
+                "(pass --token or set GRAPH_TED_DB_TOKEN)",
+                file=sys.stderr,
+            )
+            return 1
+        try:
+            serve(store, host=host, port=port, max_records=max_records, token=token)
+        except OSError as exc:
+            if exc.errno in (errno.EADDRINUSE, 10048):  # 10048: WSAEADDRINUSE
+                print(
+                    f"graph-ted-db: port {port} in use; pass --port "
+                    "(another graph-ted-db serve may still be running)",
+                    file=sys.stderr,
+                )
+                return 1
+            raise
+        return 0
+    raise AssertionError(f"unhandled command {args.command}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graph_ted_db/driver/__init__.py

@@ -0,0 +1,16 @@
+"""Optional Graphiti GraphDriver. Import GraphTedDbDriver from .graphiti."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def __getattr__(name: str) -> Any:
+    if name == "GraphTedDbDriver":
+        from graph_ted_db.driver.graphiti import GraphTedDbDriver
+
+        return GraphTedDbDriver
+    raise AttributeError(name)
+
+
+__all__ = ["GraphTedDbDriver"]

graph_ted_db/driver/graphiti.py

@@ -0,0 +1,201 @@
+"""graphiti-core GraphDriver over a graph-ted-db folder or HTTP serve.
+
+Reports GraphProvider.NEO4J so Graphiti emits the query dialect this engine's openCypher subset targets.
+Pass an http(s) URL to use serve (one process owns the folder). Pass a
+filesystem path to open GraphStore in-process (library / CLI use).
+Install graphiti-core in the process that constructs this driver.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from pathlib import Path
+from typing import Any
+
+from graph_ted_db.driver.http import (
+    get_health,
+    is_http_url,
+    normalize_base,
+    post_cypher,
+    post_cypher_many,
+)
+from graph_ted_db.store import GraphStore, init_graph
+from graph_ted_db.store.init import GraphFormatError
+
+try:
+    from graphiti_core.driver.driver import (
+        GraphDriver,
+        GraphDriverSession,
+        GraphProvider,
+    )
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "GraphTedDbDriver requires graphiti-core. Install it in the Graphiti MCP environment."
+    ) from exc
+
+
+def _params_from_kwargs(kwargs: dict[str, Any]) -> dict[str, Any]:
+    kwargs = dict(kwargs)
+    kwargs.pop("routing_", None)
+    kwargs.pop("database_", None)
+    nested = kwargs.pop("params", None)
+    params: dict[str, Any] = dict(nested) if isinstance(nested, dict) else {}
+    params.update(kwargs)
+    return params
+
+
+class GraphTedDbSession(GraphDriverSession):
+    provider = GraphProvider.NEO4J
+
+    def __init__(self, driver: GraphTedDbDriver):
+        self.driver = driver
+        self.store = driver.store
+        self._batch: list[tuple[str, dict[str, Any]]] | None = None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return None
+
+    async def close(self):
+        return None
+
+    def _enqueue(self, query: str | list, kwargs: dict[str, Any]) -> None:
+        assert self._batch is not None
+        if isinstance(query, list):
+            for cypher, params in query:
+                self._batch.append((str(cypher), dict(params or {})))
+            return
+        self._batch.append((str(query), _params_from_kwargs(kwargs)))
+
+    async def run(self, query: str | list, **kwargs: Any) -> Any:
+        if self._batch is not None:
+            self._enqueue(query, kwargs)
+            return None
+        if self.driver._http:
+            if isinstance(query, list):
+                statements = [(str(cypher), dict(params or {})) for cypher, params in query]
+                await asyncio.to_thread(post_cypher_many, self.driver._http, statements)
+            else:
+                await asyncio.to_thread(
+                    post_cypher,
+                    self.driver._http,
+                    str(query),
+                    _params_from_kwargs(kwargs),
+                )
+            return None
+        assert self.store is not None
+        if isinstance(query, list):
+            for cypher, params in query:
+                await self._execute_store(cypher, dict(params or {}))
+            return None
+        await self._execute_store(query, _params_from_kwargs(kwargs))
+        return None
+
+    async def _execute_store(self, query: str, params: dict[str, Any]) -> list:
+        """Run queries off the event loop, unless this thread already holds the store lock.
+
+        ``execute_write`` keeps the file lock on the loop thread and calls
+        ``run`` from there. Moving that call to a worker would see the lock
+        as re-entrant and corrupt ``_lock_depth``.
+        """
+        assert self.store is not None
+        if self.store._tx is not None or self.store._lock_depth:
+            return self.store.execute(str(query), params)
+        return await asyncio.to_thread(self.store.execute, str(query), params)
+
+    async def execute_write(self, func, *args, **kwargs):
+        if self.driver._http:
+            self._batch = []
+            try:
+                result = await func(self, *args, **kwargs)
+                statements = self._batch
+                self._batch = None
+                if statements:
+                    await asyncio.to_thread(post_cypher_many, self.driver._http, statements)
+                return result
+            except Exception:
+                self._batch = None
+                raise
+        assert self.store is not None
+        with self.store._lock():
+            self.store._begin_unlocked()
+            try:
+                result = await func(self, *args, **kwargs)
+                self.store._commit_unlocked()
+                return result
+            except Exception:
+                self.store._rollback_unlocked()
+                raise
+
+
+class GraphTedDbDriver(GraphDriver):
+    provider = GraphProvider.NEO4J
+    aoss_client = None
+    fulltext_syntax = ""
+
+    def __init__(self, root: str | Path, *, data_dir: Path | None = None):
+        super().__init__()
+        raw = str(root).strip()
+        if is_http_url(raw):
+            self._http: str | None = normalize_base(raw)
+            self.store = None
+        else:
+            self._http = None
+            path = Path(raw).expanduser().resolve()
+            try:
+                self.store = GraphStore.open(path, data_dir=data_dir)
+            except GraphFormatError:
+                init_graph(path, name=path.name, exist_ok=True)
+                self.store = GraphStore.open(path, data_dir=data_dir)
+        self._database = "neo4j"
+        self.client = self
+
+    async def execute_query(self, cypher_query_, **kwargs: Any):
+        params = _params_from_kwargs(kwargs)
+        if self._http:
+            rows = await asyncio.to_thread(
+                post_cypher,
+                self._http,
+                str(cypher_query_),
+                params,
+                max_records=0,
+            )
+            return rows, None, None
+        assert self.store is not None
+        if self.store._tx is not None or self.store._lock_depth:
+            rows = self.store.execute(str(cypher_query_), params)
+        else:
+            rows = await asyncio.to_thread(self.store.execute, str(cypher_query_), params)
+        return rows, None, None
+
+    def session(self, database: str | None = None) -> GraphTedDbSession:
+        del database
+        return GraphTedDbSession(self)
+
+    async def close(self) -> None:
+        return None
+
+    def close_sync(self) -> None:
+        return None
+
+    def delete_all_indexes(self) -> Coroutine:
+        async def _noop():
+            return None
+
+        return _noop()
+
+    async def verify_connectivity(self) -> None:
+        if self._http:
+            try:
+                await asyncio.to_thread(get_health, self._http)
+                return
+            except ValueError:
+                rows = await asyncio.to_thread(post_cypher, self._http, "RETURN 1 AS ok")
+        else:
+            assert self.store is not None
+            rows = await asyncio.to_thread(self.store.execute, "RETURN 1 AS ok")
+        if not rows or rows[0].get("ok") not in (1, "1"):
+            raise RuntimeError("graph-ted-db connectivity check failed")