dbx-tools-graphiti
Run Graphiti REST, MCP, model routing, and PostgreSQL-backed graph memory from one Python runtime. Use embedded PostgreSQL for local persistence or connect to an external PostgreSQL or Lakebase database.
Start the server
uv add 'dbx-tools-graphiti[dev]'
GRAPHITI_LISTEN=tcp://127.0.0.1:8000 \
uv run python -m dbx_tools.graphiti
The application exposes:
- FastAPI documentation at
/docs. - OpenAPI at
/openapi.json. - Health, search, and ingestion routes, including
/healthcheckand/search. - Direct tool operations under
/tools/*. - Streamable HTTP MCP at
/mcp/.
The direct HTTP and MCP operations share the same operation definitions. OpenAPI includes field-level argument descriptions for AppKit tool registration.
From this repository, start the local runtime with an explicit configured profile:
cd packages/py/graphiti
DATABRICKS_CONFIG_PROFILE=<profile> \
uv run --extra dev python -m dbx_tools.graphiti
Print the OpenAPI document
Generate the OpenAPI JSON without starting PostgreSQL or model clients:
python -m dbx_tools.graphiti docs
The command writes the document to standard output and exits.
Configure Graphiti
The Python server and Node supervisor use the same environment contract:
| Setting | Default | Purpose |
|---|---|---|
DATABRICKS_CONFIG_PROFILE |
Python SDK default credentials | Selects a Databricks CLI profile. |
MODEL_CLASS |
chat-fast |
Selects the chat model capability class. |
TEMPERATURE |
1 |
Sets the Graphiti LLM sampling temperature from 0 through 2. |
LLM_STRUCTURED_OUTPUT_MODE |
json_object |
Selects the structured-output mode passed to Graphiti. |
GRAPHITI_LISTEN |
tcp://127.0.0.1:7272 |
Sets the HTTP listener. |
GRAPHITI_TOKEN |
Unset | Requires one bearer token for every Graphiti HTTP endpoint. |
GRAPHITI_HOME |
Platform data directory | Sets the embedded runtime data directory. |
DATABASE_URL or LAKEBASE_ENDPOINT |
Unset | Selects external PostgreSQL or Lakebase. Omit both for embedded PostgreSQL. |
GRAPHITI_DATABASE_SCHEMA |
dbx_tools_graphiti |
Selects the PostgreSQL schema for graph tables. |
DBX_TOOLS_GRAPHITI_STARTUP_TIMEOUT_MS |
180000 |
Limits startup time for Node-supervised processes. |
PostgreSQL settings such as PGHOST, PGPORT, PGDATABASE, PGUSER, and
PGSSLMODE follow the shared dbx-tools Postgres option schema.
Understand model selection
The process creates one auth client and one model client at startup. It selects
the chat endpoint by modelClass and independently selects the highest-ranked
embedding endpoint. REST and MCP reuse the same model clients. The auth client
adds refreshed Databricks headers to each model request.
Graphiti reads embedding dimensions from discovered endpoint metadata before it initializes PostGraph. Startup fails when the selected endpoint doesn't publish a positive dimension. There is no model-name or dimension fallback.
Use Graphiti from Python
Use the importable runtime without starting Uvicorn:
from dbx_tools.graphiti.runtime import GraphitiRuntime
async with GraphitiRuntime.from_options(
{"profile": "MY-PROFILE", "modelClass": "chat-fast"}
) as runtime:
graphiti = runtime.graphiti
In a Databricks notebook or Lakeflow Job, omitted auth options use the Python
SDK's default WorkspaceClient. Pass profile only when you need to select an
explicit Databricks CLI profile.
Graphiti depends on dbx-tools-node-runtime. A normal pip installation works
on Databricks serverless compute without system Node.js or npm:
%pip install dbx-tools-graphiti
The shared runtime uses system npm when available. Otherwise, its first binding
load installs a compatible nodejs-wheel and PythonMonkey into the active
Python environment.
Choose database persistence
Install the optional embedded runtime when you don't provide databaseUrl:
uv add 'dbx-tools-graphiti[dev]'
Embedded mode starts PostgreSQL with pgvector and persists data under
GRAPHITI_HOME or the platform data directory. The PostgreSQL process stops
with the runtime. Its data remains for the next start.
Pass a PostgreSQL URL to use an existing database. A passwordless non-local URL, Lakebase resource path, or Lakebase project name is resolved by the generated Lakebase client. It adds a short-lived credential when asyncpg opens a physical connection without persisting that credential in the URL.
Lakebase mode uses GRAPHITI_DATABASE_SCHEMA, which defaults to
dbx_tools_graphiti, because application identities normally can't write to
public. If no vector extension exists, Graphiti installs it in that schema.
If the database has an existing vector installation, Graphiti uses that
extension schema for type resolution.
Wait for memory writes
The direct HTTP and MCP add_memory operation queues a write and returns
immediately. Call wait_for_memory_queue before stopping a short-lived runtime
when queued work must be durable. Queue processing errors are logged with their
tracebacks and raised by the wait operation.
Use add_memory_sync when the request must wait for persistence.
get_queue_status reports the pending count and worker state.
When you create an episode, omit uuid and use the generated UUID for later
retrieval. A supplied uuid selects an existing episode to update.
Understand operational limits
- Embedded PostgreSQL requires the
devextra. Without an external database or that extra, startup fails. - External PostgreSQL must support the
vectorextension. The runtime installs it only when the connected identity has permission. - Queued
add_memorycalls can outlive the request that submitted them. Useadd_memory_syncorwait_for_memory_queuebefore shutdown when required. GRAPHITI_TOKENis one shared HTTP bearer token. It doesn't replace Databricks model authentication or provide per-user authorization.- Set
GRAPHITI_TOKENbefore you exposeGRAPHITI_LISTENon a non-loopback interface. - Model and embedding discovery happens at startup. A model endpoint change requires a runtime restart before selection runs again.
1 maintainer
Metadata
1 maintainer
Release files for dbx-tools-graphiti 0.9.133
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dbx_tools_graphiti-0.9.133.tar.gz | 637.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dbx_tools_graphiti-0.9.133-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / dbx_tools_graphiti-0.9.133.tar.gz
| Download URL | dbx_tools_graphiti-0.9.133.tar.gz |
|---|---|
| Size | 637.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
40fe1c10ac06eac982c8e1b3ae4f24f34d1eaaf933e335cb9ed5cff06035d53d
|
|
BLAKE2b-256 checksum How to use checksums |
fdeabd42ccd2777a41c27717c2161d4219498b0466be8eee0ec207e69e92194d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / dbx_tools_graphiti-0.9.133-py3-none-any.whl
| Download URL | dbx_tools_graphiti-0.9.133-py3-none-any.whl |
|---|---|
| Size | 671.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a3ae079abef0415c63a8ca6f256d9116676abdc4fbcd966adfb4ae760308999
|
|
BLAKE2b-256 checksum How to use checksums |
da20113a87a1cf8627344bf646fecf5df257be3b34c12f13c3d8f0e18001773a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
