apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-21 02:28:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: document V1a config/CLI (version/storage/servers/--graph); mark RFC landed

Browse source 
Sweep `--target` → `--graph` across the user docs (cli-reference, cli, server,
policy) and update `omnigraph.example.yaml` to the v1 schema (`version: 1`,
`storage:`, `servers:`/`server:`). Add the typed-locator schema (version/storage/
servers/graph_id + strictness) to cli-reference, and a server "embedded graphs
only" note. The RFC gets an Implementation-status banner recording V1a as landed
and its divergences (`--target` removed outright — no alias; `uri:` deprecation-
warned) and corrects the stale `QueryRegistry`/config-location claims (it's in
`omnigraph-queries` / `omnigraph-config` now). testing.md gains a Config & CLI
note. Past release notes keep `--target` (accurate for those versions);
`--target-branch` untouched.
This commit is contained in:
Ragnor Comerford 2026-06-04 16:22:17 +02:00
parent c2db7b5002
commit 536eab3928
No known key found for this signature in database
7 changed files with 53 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/user/cli-reference.md
View file

@ -2,7 +2,7 @@
A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` schema. For a quick-start guide, see [cli.md](cli.md).
17 top-level command families, 40+ subcommands. All commands accept either a positional `URI`, `--uri`, or a `--target <name>` resolved against `omnigraph.yaml`.
17 top-level command families, 40+ subcommands. All commands accept either a positional `URI`, `--uri`, or a `--graph <name>` resolved against `omnigraph.yaml`.
## Top-level commands
@ -20,7 +20,7 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
| `run list \| show \| publish \| abort` | transactional run ops |
| `schema plan \| apply \| show (alias: get)` | migrations |
| `lint` (alias: `check`) | offline / graph-backed query validation. Replaces `query lint` / `query check`, which are kept as deprecated argv-level shims that print a one-line warning and rewrite to `omnigraph lint` |
| `queries validate \| list` | operate on the server-side stored-query registry (the `queries:` block). `validate` type-checks every stored query against the live schema offline (opens the selected graph; exits non-zero on any breakage), catching schema drift without restarting the server; `list` prints the selected registry's query names, MCP exposure, and typed params. For per-graph registries, pass `--target <graph>` or set `cli.graph`; with no graph selection, `list` shows only top-level `queries:`. Distinct from `lint`, which validates a single `.gq` file |
| `queries validate \| list` | operate on the server-side stored-query registry (the `queries:` block). `validate` type-checks every stored query against the live schema offline (opens the selected graph; exits non-zero on any breakage), catching schema drift without restarting the server; `list` prints the selected registry's query names, MCP exposure, and typed params. For per-graph registries, pass `--graph <graph>` or set `cli.graph`; with no graph selection, `list` shows only top-level `queries:`. Distinct from `lint`, which validates a single `.gq` file |
| `optimize` | non-destructive Lance compaction (skips tables with `Blob` columns; `--json` reports a `skipped` field) |
| `cleanup --keep N --older-than 7d --confirm` | destructive version GC |
| `embed` | offline JSONL embedding pipeline |
@ -30,11 +30,21 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
## `omnigraph.yaml` schema
```yaml
version: 1 # omit for the legacy schema (lenient, deprecation-warned);
# `1` = strict: unknown/typo'd keys are rejected at any depth
project: { name }
servers: # named remote endpoints (referenced by graphs.<>.server)
<name>: { endpoint: <https://host:port> }
graphs:
<name>:
uri: <local|s3://|http(s)://>
# Embedded XOR remote. Embedded → `storage:`; remote → `server:` (+ optional `graph_id:`).
storage: <local|s3://> # embedded; a bare string, or a block { uri, region, endpoint }
# server: <name> # remote: a `servers:` entry (mutually exclusive with storage)
# graph_id: <id> # the graph's id on that server (defaults to the entry key)
# uri: <local|s3://|http(s)://> # DEPRECATED legacy spelling of storage/server; warns at load
bearer_token_env: <ENV_NAME>
branch: <name> # optional default branch
snapshot: <version> # optional read-pinned snapshot
queries: # per-graph stored-query registry (server-role; multi-graph mode)
<query-name>: # key MUST equal the `query <name>` symbol inside the .gq
file: <path-to-.gq> # relative to this config's directory

2
docs/user/cli.md
View file

@ -60,7 +60,7 @@ Read through the HTTP API:
```bash
omnigraph query \
--target http://127.0.0.1:8080 \
--graph http://127.0.0.1:8080 \
--query ./queries.gq \
--name get_person \
--params '{"name":"Alice"}'

2
docs/user/policy.md
View file

@ -48,7 +48,7 @@ graphs:
```
**Config follows graph identity, not server mode.** A graph served by **name**
(`--target <name>` or `server.graph`) uses its own `graphs.<name>.policy.file`,
(`--graph <name>` or `server.graph`) uses its own `graphs.<name>.policy.file`,
exactly as in multi-graph mode. Top-level `policy.file` applies only to an
**anonymous** graph — one served by a bare `<URI>` with no `graphs:` entry.
Serving a **named** graph (single- or multi-graph mode) while top-level

13
docs/user/server.md
View file

@ -6,22 +6,27 @@ Axum 0.8 + tokio + utoipa-generated OpenAPI. **Two modes** (v0.6.0+): single-gra
### Single-graph mode (legacy)
`omnigraph-server <URI>` or `omnigraph-server --target <name> --config omnigraph.yaml`. Routes are flat — `/snapshot`, `/read`, `/branches`, etc.
`omnigraph-server <URI>` or `omnigraph-server --graph <name> --config omnigraph.yaml`. Routes are flat — `/snapshot`, `/read`, `/branches`, etc.
**Config follows graph identity.** A bare `<URI>` is an *anonymous* graph and uses the **top-level** `policy.file` / `queries:`. A graph chosen by **name** (`--target` / `server.graph`) uses its own `graphs.<name>.{policy.file, queries}` — the same block multi-graph mode uses. ⚠️ *Changed from v0.6.0, which always used top-level config in single mode: a named-graph config that puts `policy`/`queries` at top-level now **refuses boot** and points you at `graphs.<name>.…` (move the block there). Bare-`<URI>` single mode is unchanged.*
**Config follows graph identity.** A bare `<URI>` is an *anonymous* graph and uses the **top-level** `policy.file` / `queries:`. A graph chosen by **name** (`--graph` / `server.graph`) uses its own `graphs.<name>.{policy.file, queries}` — the same block multi-graph mode uses. ⚠️ *Changed from v0.6.0, which always used top-level config in single mode: a named-graph config that puts `policy`/`queries` at top-level now **refuses boot** and points you at `graphs.<name>.…` (move the block there). Bare-`<URI>` single mode is unchanged.*
### Multi-graph mode (v0.6.0+)
`omnigraph-server --config omnigraph.yaml` with a non-empty `graphs:` map and **no** single-mode selector (no `server.graph`, no `<URI>`, no `--target`). The server opens every configured graph in parallel at startup (bounded concurrency = 4, fail-fast on the first open error). Routes are nested under `/graphs/{graph_id}/...`. Bare flat paths return 404 in multi mode.
`omnigraph-server --config omnigraph.yaml` with a non-empty `graphs:` map and **no** single-mode selector (no `server.graph`, no `<URI>`, no `--graph`). The server opens every configured graph in parallel at startup (bounded concurrency = 4, fail-fast on the first open error). Routes are nested under `/graphs/{graph_id}/...`. Bare flat paths return 404 in multi mode.
Mode inference (four-rule matrix):
1. CLI positional `<URI>` → single
2. CLI `--target <name>` → single
2. CLI `--graph <name>` → single
3. `server.graph` in config → single
4. `--config` + non-empty `graphs:` + no single-mode selector → **multi**
5. otherwise → error with migration hint
**Embedded graphs only.** In either mode, a graph entry that targets a remote
`server:` (or a remote `http(s)://` `uri:`) is rejected at startup —
omnigraph-server serves embedded (self-contained) graphs and does not proxy
another server. Use an embedded `storage:` graph, or point a client at the remote.
### Stored-query validation at startup
If a graph declares a `queries:` registry (see [cli-reference](cli-reference.md)), the server **loads and type-checks every stored query against that graph's live schema at startup** and **refuses to boot** if any query references a type or property the schema lacks — the same fail-loud posture as a malformed policy file, so schema drift surfaces at the deploy boundary rather than at invocation. Two MCP-exposed queries claiming the same tool name is likewise a boot error. Non-blocking advisories (e.g. an MCP-exposed query with a vector parameter an agent cannot supply) are logged. Validate offline before deploying with `omnigraph queries validate`. Discover the exposed queries as a typed tool catalog with `GET /queries`, and invoke one over HTTP with `POST /queries/{name}` (both below).