dbx-tools-graphiti 0.6.111__tar.gz

dbx_tools_graphiti-0.6.111/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: dbx-tools-graphiti
+Version: 0.6.111
+Summary: Native Graphiti MCP and Neo4j launcher with mise-managed prerequisites
+Requires-Python: >=3.10
+Project-URL: Source, https://github.com/reggie-db/dbx-tools/tree/main/packages/py/graphiti
+Description-Content-Type: text/markdown
+
+# `dbx-tools-graphiti`
+
+Native launcher for [Graphiti](https://github.com/getzep/graphiti) with a local
+Neo4j backend. It runs both services directly as host processes; it does not use
+Docker, Podman, or another container runtime.
+
+Install from PyPI:
+
+```bash
+uv add dbx-tools-graphiti
+```
+
+Or install the current `main` branch:
+
+```bash
+uv add "dbx-tools-graphiti @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/graphiti"
+```
+
+## Key features
+
+- launches upstream Graphiti's HTTP MCP server at `http://127.0.0.1:8000/mcp/`;
+- runs Neo4j Community 5.26 as a native background process;
+- provisions Java 21 and `uv` through `mise use -g` only when absent;
+- pins Graphiti and Neo4j versions for repeatable local environments;
+- caches downloads, Python dependencies, Neo4j data, credentials, and logs;
+- supports foreground or background operation without vendoring Graphiti code.
+
+## Quick start
+
+`mise` must already be installed. The launcher handles Java and `uv` itself.
+
+```bash
+export OPENAI_API_KEY=...
+uv run dbx-graphiti start
+```
+
+The first run downloads about 120 MB of Neo4j plus the pinned Graphiti release,
+creates Graphiti's `uv` environment, generates a local Neo4j password, starts
+Neo4j, and then runs Graphiti in the foreground. Later runs reuse all of it.
+
+For background operation:
+
+```bash
+uv run dbx-graphiti up
+uv run dbx-graphiti status
+uv run dbx-graphiti down
+```
+
+## Commands
+
+| Command  | Behavior                                                                      |
+| -------- | ----------------------------------------------------------------------------- |
+| `setup`  | Provision tools and populate the local cache without starting services.       |
+| `start`  | Start Neo4j, then run Graphiti in the foreground. This is the default.        |
+| `up`     | Start both services in the background.                                        |
+| `down`   | Stop the managed Graphiti and Neo4j processes.                                |
+| `status` | Print process state and the MCP URL as JSON.                                  |
+| `env`    | Print resolved Neo4j connection settings as JSON. Treat its output as secret. |
+
+Arguments after `start` or `up` are forwarded to upstream Graphiti. For example:
+
+```bash
+uv run dbx-graphiti start -- --port 9000 --group-id my-agent
+```
+
+## Provisioning and caching
+
+The package deliberately keeps orchestration separate from Graphiti itself:
+
+1. It checks `mise where java@21` and `mise where uv@0.11`.
+2. A missing tool is installed globally with `mise use -g --yes`.
+3. Neo4j Community `5.26.12` is downloaded from `dist.neo4j.org` and unpacked.
+4. Graphiti `v0.29.3` is downloaded from its GitHub release tag.
+5. `uv sync --project <checkout>/mcp_server` creates the upstream environment.
+6. A generated Neo4j password is stored with mode `0600` and supplied to
+   Graphiti through its documented environment variables.
+
+The cache root is:
+
+- macOS: `~/Library/Application Support/dbx-tools/graphiti`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/dbx-tools/graphiti`
+- Windows: `%LOCALAPPDATA%/dbx-tools/graphiti`
+
+Set `DBX_GRAPHITI_HOME` to override it. Removing the directory clears the
+download cache and permanently removes the local graph data.
+
+## Configuration
+
+The packaged default fixes the database provider to Neo4j and otherwise follows
+upstream Graphiti environment names. Common settings are:
+
+| Variable            | Default                  |
+| ------------------- | ------------------------ |
+| `OPENAI_API_KEY`    | Required                 |
+| `MODEL_NAME`        | `gpt-4.1-mini`           |
+| `EMBEDDER_MODEL`    | `text-embedding-3-small` |
+| `GRAPHITI_GROUP_ID` | `main`                   |
+| `GRAPHITI_HOST`     | `127.0.0.1`              |
+| `GRAPHITI_PORT`     | `8000`                   |
+| `NEO4J_URI`         | `bolt://127.0.0.1:7687`  |
+| `NEO4J_DATABASE`    | `neo4j`                  |
+
+Explicit `NEO4J_*` values override generated defaults, which lets the Graphiti
+process use an existing Neo4j server. The launcher still manages its local
+Neo4j process; use upstream Graphiti directly if lifecycle ownership belongs to
+an external database administrator.
+
+Graphiti owns MCP tools, graph behavior, LLM calls, embeddings, and migrations.
+This package owns only repeatable installation, configuration, and process
+lifecycle. See the [upstream MCP server documentation](https://github.com/getzep/graphiti/tree/main/mcp_server)
+for its complete API and provider configuration.

dbx_tools_graphiti-0.6.111/README.md

@@ -0,0 +1,111 @@
+# `dbx-tools-graphiti`
+
+Native launcher for [Graphiti](https://github.com/getzep/graphiti) with a local
+Neo4j backend. It runs both services directly as host processes; it does not use
+Docker, Podman, or another container runtime.
+
+Install from PyPI:
+
+```bash
+uv add dbx-tools-graphiti
+```
+
+Or install the current `main` branch:
+
+```bash
+uv add "dbx-tools-graphiti @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/graphiti"
+```
+
+## Key features
+
+- launches upstream Graphiti's HTTP MCP server at `http://127.0.0.1:8000/mcp/`;
+- runs Neo4j Community 5.26 as a native background process;
+- provisions Java 21 and `uv` through `mise use -g` only when absent;
+- pins Graphiti and Neo4j versions for repeatable local environments;
+- caches downloads, Python dependencies, Neo4j data, credentials, and logs;
+- supports foreground or background operation without vendoring Graphiti code.
+
+## Quick start
+
+`mise` must already be installed. The launcher handles Java and `uv` itself.
+
+```bash
+export OPENAI_API_KEY=...
+uv run dbx-graphiti start
+```
+
+The first run downloads about 120 MB of Neo4j plus the pinned Graphiti release,
+creates Graphiti's `uv` environment, generates a local Neo4j password, starts
+Neo4j, and then runs Graphiti in the foreground. Later runs reuse all of it.
+
+For background operation:
+
+```bash
+uv run dbx-graphiti up
+uv run dbx-graphiti status
+uv run dbx-graphiti down
+```
+
+## Commands
+
+| Command  | Behavior                                                                      |
+| -------- | ----------------------------------------------------------------------------- |
+| `setup`  | Provision tools and populate the local cache without starting services.       |
+| `start`  | Start Neo4j, then run Graphiti in the foreground. This is the default.        |
+| `up`     | Start both services in the background.                                        |
+| `down`   | Stop the managed Graphiti and Neo4j processes.                                |
+| `status` | Print process state and the MCP URL as JSON.                                  |
+| `env`    | Print resolved Neo4j connection settings as JSON. Treat its output as secret. |
+
+Arguments after `start` or `up` are forwarded to upstream Graphiti. For example:
+
+```bash
+uv run dbx-graphiti start -- --port 9000 --group-id my-agent
+```
+
+## Provisioning and caching
+
+The package deliberately keeps orchestration separate from Graphiti itself:
+
+1. It checks `mise where java@21` and `mise where uv@0.11`.
+2. A missing tool is installed globally with `mise use -g --yes`.
+3. Neo4j Community `5.26.12` is downloaded from `dist.neo4j.org` and unpacked.
+4. Graphiti `v0.29.3` is downloaded from its GitHub release tag.
+5. `uv sync --project <checkout>/mcp_server` creates the upstream environment.
+6. A generated Neo4j password is stored with mode `0600` and supplied to
+   Graphiti through its documented environment variables.
+
+The cache root is:
+
+- macOS: `~/Library/Application Support/dbx-tools/graphiti`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/dbx-tools/graphiti`
+- Windows: `%LOCALAPPDATA%/dbx-tools/graphiti`
+
+Set `DBX_GRAPHITI_HOME` to override it. Removing the directory clears the
+download cache and permanently removes the local graph data.
+
+## Configuration
+
+The packaged default fixes the database provider to Neo4j and otherwise follows
+upstream Graphiti environment names. Common settings are:
+
+| Variable            | Default                  |
+| ------------------- | ------------------------ |
+| `OPENAI_API_KEY`    | Required                 |
+| `MODEL_NAME`        | `gpt-4.1-mini`           |
+| `EMBEDDER_MODEL`    | `text-embedding-3-small` |
+| `GRAPHITI_GROUP_ID` | `main`                   |
+| `GRAPHITI_HOST`     | `127.0.0.1`              |
+| `GRAPHITI_PORT`     | `8000`                   |
+| `NEO4J_URI`         | `bolt://127.0.0.1:7687`  |
+| `NEO4J_DATABASE`    | `neo4j`                  |
+
+Explicit `NEO4J_*` values override generated defaults, which lets the Graphiti
+process use an existing Neo4j server. The launcher still manages its local
+Neo4j process; use upstream Graphiti directly if lifecycle ownership belongs to
+an external database administrator.
+
+Graphiti owns MCP tools, graph behavior, LLM calls, embeddings, and migrations.
+This package owns only repeatable installation, configuration, and process
+lifecycle. See the [upstream MCP server documentation](https://github.com/getzep/graphiti/tree/main/mcp_server)
+for its complete API and provider configuration.

dbx_tools_graphiti-0.6.111/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "dbx-tools-graphiti"
+version = "0.6.111"
+description = "Native Graphiti MCP and Neo4j launcher with mise-managed prerequisites"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/graphiti"
+
+[project.scripts]
+dbx-graphiti = "dbx_tools.graphiti.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.graphiti"
+module-root = "src"
+namespace = true

dbx_tools_graphiti-0.6.111/pyproject.toml.orig

@@ -0,0 +1,24 @@
+# ~~ Generated by projen. To modify, edit .projenrc.js and run "bunx projen".
+
+[project]
+name = "dbx-tools-graphiti"
+version = "0.6.111"
+description = "Native Graphiti MCP and Neo4j launcher with mise-managed prerequisites"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [ ]
+
+  [project.urls]
+  Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/graphiti"
+
+  [project.scripts]
+  dbx-graphiti = "dbx_tools.graphiti.cli:main"
+
+[build-system]
+requires = [ "uv_build>=0.11.28,<0.12.0" ]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.graphiti"
+module-root = "src"
+namespace = true

dbx_tools_graphiti-0.6.111/src/dbx_tools/graphiti/__init__.py

@@ -0,0 +1,5 @@
+"""Native Graphiti MCP and Neo4j launcher."""
+
+from .runtime import GRAPHITI_VERSION, NEO4J_VERSION, RuntimePaths
+
+__all__ = ["GRAPHITI_VERSION", "NEO4J_VERSION", "RuntimePaths"]

dbx_tools_graphiti-0.6.111/src/dbx_tools/graphiti/__main__.py

@@ -0,0 +1,5 @@
+"""Run the Graphiti launcher."""
+
+from .cli import main
+
+main()

dbx_tools_graphiti-0.6.111/src/dbx_tools/graphiti/cli.py

@@ -0,0 +1,51 @@
+"""Command-line interface for the native Graphiti stack."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from collections.abc import Sequence
+
+from .runtime import Runtime
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="dbx-graphiti",
+        description="Run Graphiti MCP with a local native Neo4j backend (no containers).",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("setup", help="Install pinned native prerequisites")
+    start = subparsers.add_parser("start", help="Start Neo4j and Graphiti in the foreground")
+    start.add_argument("graphiti_args", nargs=argparse.REMAINDER)
+    up = subparsers.add_parser("up", help="Start Neo4j and Graphiti in the background")
+    up.add_argument("graphiti_args", nargs=argparse.REMAINDER)
+    subparsers.add_parser("down", help="Stop Graphiti and Neo4j")
+    subparsers.add_parser("status", help="Show native process status")
+    subparsers.add_parser("env", help="Print resolved connection settings")
+
+    parsed = parser.parse_args(argv)
+    runtime = Runtime()
+    command = parsed.command or "start"
+    if command == "setup":
+        runtime.setup()
+        print(f"Graphiti is ready under {runtime.paths.root}")
+    elif command in {"start", "up"}:
+        if not os.getenv("OPENAI_API_KEY"):
+            parser.error("OPENAI_API_KEY is required by the default Graphiti configuration")
+        extra_args = getattr(parsed, "graphiti_args", [])
+        if extra_args[:1] == ["--"]:
+            extra_args = extra_args[1:]
+        result = runtime.start(foreground=command == "start", extra_args=extra_args)
+        if command == "up":
+            print(f"Graphiti started with PID {result}; MCP: http://127.0.0.1:8000/mcp/")
+        elif result:
+            raise SystemExit(result)
+    elif command == "down":
+        runtime.stop()
+    elif command == "status":
+        print(json.dumps(runtime.status(), indent=2))
+    elif command == "env":
+        state = runtime.read_state()
+        print(json.dumps(runtime.connection_settings(str(state["neo4j_password"])), indent=2))

dbx_tools_graphiti-0.6.111/src/dbx_tools/graphiti/config.yaml

@@ -0,0 +1,41 @@
+server:
+  transport: "http"
+  host: ${GRAPHITI_HOST:127.0.0.1}
+  port: ${GRAPHITI_PORT:8000}
+
+llm:
+  provider: "openai"
+  model: ${MODEL_NAME:gpt-4.1-mini}
+  max_tokens: 4096
+  structured_output_mode: ${LLM_STRUCTURED_OUTPUT_MODE:json_schema}
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+
+embedder:
+  provider: "openai"
+  model: ${EMBEDDER_MODEL:text-embedding-3-small}
+  dimensions: 1536
+  providers:
+    openai:
+      api_key: ${OPENAI_API_KEY}
+      api_url: ${OPENAI_API_URL:https://api.openai.com/v1}
+      organization_id: ${OPENAI_ORGANIZATION_ID:}
+
+database:
+  provider: "neo4j"
+  providers:
+    neo4j:
+      uri: ${NEO4J_URI:bolt://127.0.0.1:7687}
+      username: ${NEO4J_USER:neo4j}
+      password: ${NEO4J_PASSWORD}
+      database: ${NEO4J_DATABASE:neo4j}
+      use_parallel_runtime: false
+
+graphiti:
+  group_id: ${GRAPHITI_GROUP_ID:main}
+  episode_id_prefix: ${EPISODE_ID_PREFIX:}
+  user_id: ${USER_ID:mcp_user}
+  entity_types: []

dbx_tools_graphiti-0.6.111/src/dbx_tools/graphiti/runtime.py

@@ -0,0 +1,318 @@
+"""Installation and native process lifecycle for Graphiti and Neo4j."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import shutil
+import signal
+import subprocess
+import sys
+import tarfile
+import time
+import urllib.request
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+GRAPHITI_VERSION = "0.29.3"
+NEO4J_VERSION = "5.26.12"
+JAVA_VERSION = "21"
+UV_VERSION = "0.11"
+
+
+def default_data_dir() -> Path:
+    """Return the per-user directory containing downloads, data, and logs."""
+    override = os.getenv("DBX_GRAPHITI_HOME")
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "dbx-tools" / "graphiti"
+    if os.name == "nt":
+        return (
+            Path(os.getenv("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+            / "dbx-tools"
+            / "graphiti"
+        )
+    return (
+        Path(os.getenv("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+        / "dbx-tools"
+        / "graphiti"
+    )
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+    """Resolved filesystem layout for one Graphiti installation."""
+
+    root: Path
+
+    @classmethod
+    def default(cls) -> RuntimePaths:
+        return cls(default_data_dir())
+
+    @property
+    def graphiti(self) -> Path:
+        return self.root / "graphiti" / GRAPHITI_VERSION
+
+    @property
+    def neo4j(self) -> Path:
+        return self.root / "neo4j" / NEO4J_VERSION
+
+    @property
+    def neo4j_data(self) -> Path:
+        return self.root / "data" / "neo4j"
+
+    @property
+    def state(self) -> Path:
+        return self.root / "state.json"
+
+    @property
+    def log(self) -> Path:
+        return self.root / "graphiti.log"
+
+
+class Runtime:
+    """Provision and run a pinned native Graphiti stack."""
+
+    def __init__(self, paths: RuntimePaths | None = None) -> None:
+        self.paths = paths or RuntimePaths.default()
+
+    def setup(self) -> None:
+        self._require_mise()
+        self._ensure_mise_tool("java", JAVA_VERSION)
+        self._ensure_mise_tool("uv", UV_VERSION)
+        self.paths.root.mkdir(parents=True, exist_ok=True)
+        self._install_neo4j()
+        self._install_graphiti()
+        self._ensure_state()
+
+    def start(self, *, foreground: bool = True, extra_args: list[str] | None = None) -> int:
+        self.setup()
+        state = self.read_state()
+        self._start_neo4j(state["neo4j_password"])
+        command = self.graphiti_command(extra_args or [])
+        environment = self.environment(state["neo4j_password"])
+        if foreground:
+            return subprocess.call(command, cwd=self.paths.graphiti / "mcp_server", env=environment)
+        with self.paths.log.open("ab") as output:
+            process = subprocess.Popen(
+                command,
+                cwd=self.paths.graphiti / "mcp_server",
+                env=environment,
+                stdout=output,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,
+            )
+        state["graphiti_pid"] = process.pid
+        self._write_state(state)
+        return process.pid
+
+    def stop(self) -> None:
+        state = self.read_state(required=False)
+        pid = state.pop("graphiti_pid", None)
+        if pid and _is_running(pid):
+            os.kill(pid, signal.SIGTERM)
+        if (self.paths.neo4j / "bin" / "neo4j").exists():
+            self._neo4j_command("stop", check=False)
+        if state:
+            self._write_state(state)
+
+    def status(self) -> dict[str, object]:
+        state = self.read_state(required=False)
+        pid = state.get("graphiti_pid")
+        neo4j_running = False
+        if (self.paths.neo4j / "bin" / "neo4j").exists():
+            result = self._neo4j_command("status", check=False, capture_output=True)
+            neo4j_running = result.returncode == 0
+        return {
+            "home": str(self.paths.root),
+            "graphiti": "running" if isinstance(pid, int) and _is_running(pid) else "stopped",
+            "graphiti_pid": pid,
+            "neo4j": "running" if neo4j_running else "stopped",
+            "mcp_url": "http://127.0.0.1:8000/mcp/",
+        }
+
+    def graphiti_command(self, extra_args: list[str]) -> list[str]:
+        config = resources.files("dbx_tools.graphiti").joinpath("config.yaml")
+        return [
+            "mise",
+            "exec",
+            f"uv@{UV_VERSION}",
+            "--",
+            "uv",
+            "run",
+            "--project",
+            str(self.paths.graphiti / "mcp_server"),
+            "python",
+            str(self.paths.graphiti / "mcp_server" / "main.py"),
+            "--config",
+            str(config),
+            "--database-provider",
+            "neo4j",
+            *extra_args,
+        ]
+
+    def environment(self, password: str) -> dict[str, str]:
+        environment = os.environ.copy()
+        environment.setdefault("NEO4J_URI", "bolt://127.0.0.1:7687")
+        environment.setdefault("NEO4J_USER", "neo4j")
+        environment.setdefault("NEO4J_PASSWORD", password)
+        environment.setdefault("NEO4J_DATABASE", "neo4j")
+        return environment
+
+    def connection_settings(self, password: str) -> dict[str, str]:
+        """Return only the Neo4j settings callers need to connect."""
+        environment = self.environment(password)
+        return {
+            name: environment[name]
+            for name in ("NEO4J_URI", "NEO4J_USER", "NEO4J_PASSWORD", "NEO4J_DATABASE")
+        }
+
+    def _require_mise(self) -> None:
+        if not shutil.which("mise"):
+            raise RuntimeError("mise is required; install it from https://mise.jdx.dev")
+
+    def _ensure_mise_tool(self, tool: str, version: str) -> None:
+        result = subprocess.run(
+            ["mise", "where", f"{tool}@{version}"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        if result.returncode:
+            subprocess.run(["mise", "use", "-g", "--yes", f"{tool}@{version}"], check=True)
+
+    def _install_neo4j(self) -> None:
+        if (self.paths.neo4j / "bin" / "neo4j").exists():
+            return
+        archive = self.paths.root / f"neo4j-community-{NEO4J_VERSION}-unix.tar.gz"
+        url = f"https://dist.neo4j.org/neo4j-community-{NEO4J_VERSION}-unix.tar.gz"
+        _download(url, archive)
+        target_parent = self.paths.neo4j.parent
+        target_parent.mkdir(parents=True, exist_ok=True)
+        with tarfile.open(archive, "r:gz") as bundle:
+            _extract_archive(bundle, target_parent)
+        extracted = target_parent / f"neo4j-community-{NEO4J_VERSION}"
+        extracted.rename(self.paths.neo4j)
+        archive.unlink()
+
+    def _install_graphiti(self) -> None:
+        if (self.paths.graphiti / "mcp_server" / "main.py").exists():
+            return
+        archive = self.paths.root / f"graphiti-{GRAPHITI_VERSION}.tar.gz"
+        url = f"https://github.com/getzep/graphiti/archive/refs/tags/v{GRAPHITI_VERSION}.tar.gz"
+        _download(url, archive)
+        target_parent = self.paths.graphiti.parent
+        target_parent.mkdir(parents=True, exist_ok=True)
+        with tarfile.open(archive, "r:gz") as bundle:
+            _extract_archive(bundle, target_parent)
+        extracted = target_parent / f"graphiti-{GRAPHITI_VERSION}"
+        extracted.rename(self.paths.graphiti)
+        archive.unlink()
+        subprocess.run(
+            [
+                "mise",
+                "exec",
+                f"uv@{UV_VERSION}",
+                "--",
+                "uv",
+                "sync",
+                "--project",
+                str(self.paths.graphiti / "mcp_server"),
+            ],
+            check=True,
+        )
+
+    def _ensure_state(self) -> None:
+        if self.paths.state.exists():
+            return
+        password = secrets.token_urlsafe(24)
+        self._write_state({"neo4j_password": password})
+        subprocess.run(
+            self._mise_java_command(
+                self.paths.neo4j / "bin" / "neo4j-admin",
+                "dbms",
+                "set-initial-password",
+                password,
+            ),
+            env=self._neo4j_environment(),
+            check=True,
+        )
+
+    def _start_neo4j(self, password: str) -> None:
+        del password
+        result = self._neo4j_command("status", check=False)
+        if result.returncode:
+            self._neo4j_command("start")
+        deadline = time.monotonic() + 60
+        while time.monotonic() < deadline:
+            result = self._neo4j_command("status", check=False)
+            if result.returncode == 0:
+                return
+            time.sleep(1)
+        raise RuntimeError("Neo4j did not become ready within 60 seconds")
+
+    def _neo4j_command(
+        self,
+        action: str,
+        *,
+        check: bool = False,
+        capture_output: bool = False,
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            self._mise_java_command(self.paths.neo4j / "bin" / "neo4j", action),
+            env=self._neo4j_environment(),
+            text=True,
+            check=check,
+            capture_output=capture_output,
+        )
+
+    def _mise_java_command(self, executable: Path, *arguments: str) -> list[str]:
+        return ["mise", "exec", f"java@{JAVA_VERSION}", "--", str(executable), *arguments]
+
+    def _neo4j_environment(self) -> dict[str, str]:
+        environment = os.environ.copy()
+        environment["NEO4J_HOME"] = str(self.paths.neo4j)
+        environment["NEO4J_CONF"] = str(self.paths.neo4j / "conf")
+        environment["NEO4J_server_directories_data"] = str(self.paths.neo4j_data)
+        environment["NEO4J_server_default__listen__address"] = "127.0.0.1"
+        return environment
+
+    def read_state(self, *, required: bool = True) -> dict[str, object]:
+        if not self.paths.state.exists():
+            if required:
+                raise RuntimeError("Graphiti is not set up; run `dbx-graphiti setup`")
+            return {}
+        return json.loads(self.paths.state.read_text())
+
+    def _write_state(self, state: dict[str, object]) -> None:
+        self.paths.root.mkdir(parents=True, exist_ok=True)
+        self.paths.state.write_text(json.dumps(state, indent=2) + "\n")
+        self.paths.state.chmod(0o600)
+
+
+def _download(url: str, target: Path) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = target.with_suffix(f"{target.suffix}.part")
+    with urllib.request.urlopen(url) as response, temporary.open("wb") as output:
+        shutil.copyfileobj(response, output)
+    temporary.replace(target)
+
+
+def _extract_archive(bundle: tarfile.TarFile, destination: Path) -> None:
+    destination = destination.resolve()
+    for member in bundle.getmembers():
+        extracted = (destination / member.name).resolve()
+        if destination not in extracted.parents and extracted != destination:
+            raise RuntimeError(f"Archive member escapes destination: {member.name}")
+    bundle.extractall(destination)
+
+
+def _is_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True