Python support for OmniGraph

[aaltshuler]

Migrated from Discussion #144 (opened by @aaltshuler on 2026-06-06) when Discussions were retired — every proposal now enters as an issue (see GOVERNANCE.md).

Migrated from issue #91 (opened by @czxxing) under our updated contribution model — feature ideas live in Discussions, not Issues (see CONTRIBUTING.md).

Original request (@czxxing):

Are there plans to add support for the Python language? It would be a great feature to have — and if possible, an estimated timeline?

Context for discussion: OmniGraph is Rust-first; the public SDK today is TypeScript (@modernrelay/omnigraph). A Python SDK/binding is a reasonable ask — use this thread to gauge interest and shape what it would cover (client SDK over the HTTP API? PyO3 bindings to the engine?). Maintainers will weigh in on roadmap fit.

[memmmmike]

Grounded requirements from a real port attempt, in case they help shape scope. I moved an existing knowledge graph (people + typed relationships, previously on an embedded Python graph DB) onto omnigraph 0.10.0 last night. Everything went through the CLI because no Python surface exists; the friction list below is exactly what an SDK would have absorbed.

What the port actually needed, in order:

1. Build the JSONL envelopes from Python objects — nodes as {"type", "data"}, edges as {"edge", "from", "to", "data"}. This was a hand-rolled ~25-line export script; graph.load(nodes_iter, edges_iter) with the envelope handled internally is the single highest-value call.
2. Invoke stored queries with params and get typed rows back — the equivalent of graph.query("connected", a=..., b=...) returning dicts, not a table-formatted string scraped from the CLI.
3. Mutations with receipts — insert/delete via a stored mutation, returning the commit identity (Expose exact write receipts for mutation and load #479's write receipts are the right shape to surface).
4. Branch operations — create/merge as plain methods.

Paper cuts an SDK could smooth (all hit within the first hour):

• A property named id silently collides with the internal physical column (bug: a node property named id silently collides with the implicit physical id column, and @key then fails claiming the property is undeclared #529). An SDK that validates the schema client-side, or at least surfaces the server's error with the property name, would have saved the longest debugging detour of the port.
• The enforced schema-uppercase / query-lowercase edge-ident flip (docs fix in docs: quickstart branch commands take --store; state the enforced edge-ident case flip #530) — an SDK that takes the declared edge name and handles the convention removes the trap entirely.
• Filters are exact and case-sensitive by design; my previous stack normalized case at query time. A documented lower:-style normalized-column recipe in the SDK docs would set expectations early.

One scope suggestion: embedded local-file mode (./graph.omni) is the mode a Python data/ML user will touch first — it needs zero infrastructure and is what made my port attempt cheap enough to try on a whim. If the SDK's v1 speaks only to omnigraph-server over HTTP, that first-contact story is lost; a thin wrapper that shells the CLI against a local store (or bindings to the embedded engine) would cover it until native bindings exist.

Happy to be a test user for an early cut against a real dataset.