From a68896c4a02fa908d878fc537e3cbd98ea4fb065 Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Tue, 16 Jun 2026 12:36:11 +0200 Subject: [PATCH] docs(readme): embedded quick-start run-through + trimmed Clients (#266) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(readme): add embedded quick-start run-through + trim Clients - Quick start: a copy-pasteable embedded (local file) run-through (schema → init → load → query → branch), followed by a "Storage backends" table that surfaces the one thing that changes across embedded / S3 object storage / RustFS-MinIO — the graph address — with a pointer to cluster mode for served multi-graph deployments. - Clients: collapse to a two-line pointer (npm packages + omnigraph-ts repo); Python SDK marked coming soon. * docs(readme,quickstart): fix init addressing + drop non-parsing schema commas Addresses PR review (both verified against source): - README "Storage backends": `init` takes the graph address as a positional argument, not `--store` (`Command::Init { uri: String }`) — Codex. Table now shows bare addresses and a note on which flag each verb uses. - docs/user/quickstart.md: drop trailing commas in the schema. The .pg grammar (`prop_decl = { ident ~ ":" ~ type_ref ~ annotation* }`, node body `(prop_decl | body_constraint)*`, comma not in WHITESPACE) has no comma rule, so `name: String,` fails to parse — Greptile. --- README.md | 54 +++++++++++++++++++++++++++++++---------- docs/user/quickstart.md | 4 +-- 2 files changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e1a99f6..df3563c 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,45 @@ brew tap ModernRelay/tap brew install ModernRelay/tap/omnigraph ``` +## Quick start + +The fastest path is an **embedded, local file-backed graph** — no server, no +object store, no Docker: + +```bash +# A schema and one row of data +cat > schema.pg <<'PG' +node Person { + slug: String @key + name: String + title: String? +} +PG +echo '{"type":"Person","data":{"slug":"alice","name":"Alice","title":"Engineer"}}' > people.jsonl + +# Create → load (--mode is required) → query +omnigraph init --schema schema.pg ./graph.omni +omnigraph load --data people.jsonl --mode overwrite --store ./graph.omni +omnigraph query find_people --store ./graph.omni --params '{"t":"Engineer"}' \ + -e 'query find_people($t: String) { match { $p: Person { title: $t } } return { $p.name } }' + +# Branch, write in isolation, merge — Git-style across the whole graph +omnigraph branch create --from main review/new-hires --store ./graph.omni +omnigraph branch merge review/new-hires --into main --store ./graph.omni +``` + +**Storage backends** — the same flow runs on any backend; only the graph address changes: + +| Backend | Use it for | Graph address | +|---|---|---| +| **Embedded** (local filesystem) | dev, demos, single machine — the default | `./graph.omni` | +| **Object storage** (AWS S3, R2, GCS-S3) | shared, multi-host, durable | `s3://bucket/graph.omni` (+ the `AWS_*` env) | +| **RustFS / MinIO** | rehearse the S3 path locally, no cloud account | `s3://…` against a local endpoint → [deployment guide](docs/user/deployment.md#testing-against-s3-locally) | + +`init` takes the address as its positional argument (`omnigraph init --schema schema.pg
`); `load`, `query`, and `branch` take it via `--store
`. + +For a **served, multi-graph deployment** (the cluster model), see [Common Commands](#common-commands) below. + ## Set it up with an AI agent Omnigraph is built to be set up by coding agents. Paste this into Claude Code, @@ -143,19 +182,8 @@ profiles, and policy/queries tooling. For programmatic access to a running `omnigraph-server`: -- **TypeScript SDK** — [`@modernrelay/omnigraph`](https://www.npmjs.com/package/@modernrelay/omnigraph) ([source](https://github.com/ModernRelay/omnigraph-ts/tree/main/packages/sdk)). Instance-per-client, typed errors, camelCase types, async-iterator streaming export. - - ```bash - npm install @modernrelay/omnigraph - ``` - -- **Model Context Protocol server** — [`@modernrelay/omnigraph-mcp`](https://www.npmjs.com/package/@modernrelay/omnigraph-mcp) ([source](https://github.com/ModernRelay/omnigraph-ts/tree/main/packages/mcp)). Bridges Omnigraph to LLM hosts (Claude Desktop, Claude Code, …) over stdio. Exposes tools and resources for schema, branches, queries, mutations, ingest, and bundles curated best-practices guidance from the cookbook. - - ```bash - npm install -g @modernrelay/omnigraph-mcp - ``` - -Both packages are versioned in lockstep with `omnigraph-server` on major.minor: `@modernrelay/omnigraph@X.Y.*` targets `omnigraph-server@X.Y.*`. See [`ModernRelay/omnigraph-ts`](https://github.com/ModernRelay/omnigraph-ts) for the monorepo. +- **TypeScript SDK + MCP server** — [`@modernrelay/omnigraph`](https://www.npmjs.com/package/@modernrelay/omnigraph) and [`@modernrelay/omnigraph-mcp`](https://www.npmjs.com/package/@modernrelay/omnigraph-mcp), versioned in lockstep with `omnigraph-server`. Source, docs, and examples: [`ModernRelay/omnigraph-ts`](https://github.com/ModernRelay/omnigraph-ts). +- **Python SDK** — coming soon. ## Docs diff --git a/docs/user/quickstart.md b/docs/user/quickstart.md index dd8c2e7..ae98e7c 100644 --- a/docs/user/quickstart.md +++ b/docs/user/quickstart.md @@ -12,8 +12,8 @@ A schema (`.pg`) declares your node and edge types. Save this as `schema.pg`: ``` node Person { - name: String, - title: String?, + name: String + title: String? } ```