mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-18 02:24:27 +02:00
docs: onboarding-first README + in-repo agent skill + drop RustFS script (#257)
* docs: optimize README for dev onboarding; fix 0.7.0 staleness The README's setup half drifted from the shipped 0.7.0 CLI and led with the heaviest path (Docker + RustFS). This reworks it for fast, correct onboarding: README.md - New zero-dependency "Your first graph in 60 seconds" hero: a fully copy-pasteable local file-backed loop (schema → init → load → query → branch). - Add a correct "Serve it" section (cluster apply + omnigraph-server --cluster); the server is cluster-only on main, so the old positional-URI boot is gone. - Demote the RustFS bootstrap to "rehearse the S3 path locally"; reframe the storage bullet as "filesystem or any S3-compatible store (AWS S3, R2, MinIO, RustFS)" — RustFS is a provider, not a storage class. - Fix crate/MCP descriptions (query/mutate/load, not read/change/ingest). docs/user/quickstart.md - Fix the query example: `read --name <q> … <uri>` is removed — the query name is positional and the graph is addressed with `--store` (`omnigraph query find_people --query queries.gq --store graph.omni`). scripts/local-rustfs-bootstrap.sh - Convert to cluster mode: write a cluster.yaml (storage: s3://…), then validate → import → apply, load the fixture into the derived root with the now-required --mode, and serve with `omnigraph-server --cluster`. The old flow (`load` without --mode, `omnigraph-server <URI>` positional boot) no longer works on a cluster-only server. * docs: move agent skill into the repo, add agent-setup snippet, drop rustfs script skills/omnigraph - The operational skill (formerly `omnigraph-best-practices` in the cookbooks repo) now lives with the engine it documents, co-versioned. Renamed to `omnigraph`; repository metadata repointed here. - Broadened the description to trigger on intent — storing/retrieving/querying knowledge, agent memory, building a knowledge graph, operating Omnigraph — as well as on CLI/artifact sightings (stays ≤1024 chars). - Install: `npx skills add ModernRelay/omnigraph@omnigraph`. README - New "Set it up with an AI agent" paste snippet: installs the skill, reads the docs (URL), browses the cookbooks, and asks the user about a use case before standing up a first graph. - "Agent skill & starter graphs" section points at skills/omnigraph + cookbooks. Drop scripts/local-rustfs-bootstrap.sh - Not CI-tested (so it rotted: it broke on the cluster-only migration — positional server boot, load without --mode), demoed the now-optional S3 path, and was the most fragile artifact in the repo. Replaced with a "Testing against S3 locally" guide in deployment.md (docker run RustFS/MinIO + AWS_* env + cluster-on-S3). README/AGENTS references updated.
This commit is contained in:
parent
05cb73eda6
commit
ee4986e9a1
17 changed files with 2297 additions and 481 deletions
|
|
@ -129,49 +129,46 @@ shape above) — the simplest AWS architecture.
|
|||
unvalidated** — boot is lock-free read-only so it should compose, but it
|
||||
is not yet exercised by tests.
|
||||
|
||||
## One-Command Local RustFS Bootstrap
|
||||
## Testing against S3 locally
|
||||
|
||||
The easiest local S3-backed deployment path is:
|
||||
To exercise the S3 storage path without a cloud account, run any S3-compatible
|
||||
store in Docker and point the standard `AWS_*` environment at it. RustFS is
|
||||
shown; MinIO works the same way.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/local-rustfs-bootstrap.sh | bash
|
||||
docker run -d --name omnigraph-s3 -p 9000:9000 \
|
||||
-e RUSTFS_ACCESS_KEY=omnigraph -e RUSTFS_SECRET_KEY=omnigraph \
|
||||
-e RUSTFS_ALLOW_INSECURE_DEFAULT_CREDENTIALS=true \
|
||||
rustfs/rustfs:latest /data
|
||||
|
||||
export AWS_ACCESS_KEY_ID=omnigraph AWS_SECRET_ACCESS_KEY=omnigraph \
|
||||
AWS_REGION=us-east-1 AWS_ENDPOINT_URL_S3=http://127.0.0.1:9000 \
|
||||
AWS_ALLOW_HTTP=true AWS_S3_FORCE_PATH_STYLE=true
|
||||
|
||||
# create the bucket once (any S3 client works)
|
||||
aws --endpoint-url "$AWS_ENDPOINT_URL_S3" s3 mb s3://omnigraph-local
|
||||
```
|
||||
|
||||
The bootstrap:
|
||||
Now an `s3://…` URI works anywhere a graph or cluster root is expected. Root a
|
||||
cluster on the bucket and serve it config-free:
|
||||
|
||||
- starts a local RustFS-backed object store
|
||||
- creates a bucket and S3-backed Omnigraph graph
|
||||
- loads the checked-in context fixture
|
||||
- starts `omnigraph-server` on `127.0.0.1:8080`
|
||||
```bash
|
||||
# cluster.yaml
|
||||
# version: 1
|
||||
# storage: s3://omnigraph-local/clusters/demo
|
||||
# graphs: { demo: { schema: schema.pg } }
|
||||
|
||||
Supported behavior:
|
||||
omnigraph cluster validate --config .
|
||||
omnigraph cluster import --config .
|
||||
omnigraph cluster apply --config . --as you
|
||||
omnigraph load --data seed.jsonl --mode merge \
|
||||
s3://omnigraph-local/clusters/demo/graphs/demo.omni
|
||||
omnigraph-server --cluster s3://omnigraph-local/clusters/demo \
|
||||
--bind 127.0.0.1:8080 --unauthenticated
|
||||
```
|
||||
|
||||
- downloads the rolling `edge` binary when one exists for the current platform
|
||||
- otherwise clones `ModernRelay/omnigraph` and builds from source
|
||||
- reuses an existing RustFS container if it is already running
|
||||
|
||||
Useful overrides:
|
||||
|
||||
- `WORKDIR=/path/to/state`
|
||||
- `BUCKET=omnigraph-local`
|
||||
- `PREFIX=graphs/context`
|
||||
- `RESET_REPO=1` to delete an existing partially initialized graph prefix before recreating it
|
||||
- `BIND=127.0.0.1:8080`
|
||||
- `RUSTFS_CONTAINER_NAME=omnigraph-rustfs-demo`
|
||||
|
||||
The bootstrap expects:
|
||||
|
||||
- Docker
|
||||
- `curl`
|
||||
- either a matching release asset or a local Rust toolchain plus `git`
|
||||
|
||||
If `aws` is not installed, the script attempts a user-local AWS CLI install via
|
||||
`python3 -m pip`. Docker Desktop or another Docker daemon must already be
|
||||
running.
|
||||
|
||||
If a previous bootstrap left objects behind under the selected `PREFIX` but did
|
||||
not finish initializing the graph, rerun with `RESET_REPO=1` or choose a new
|
||||
`PREFIX`.
|
||||
The same `AWS_*` contract applies to a production object store — swap the
|
||||
endpoint and credentials. CI exercises this path against containerized RustFS.
|
||||
|
||||
## Container Deployment
|
||||
|
||||
|
|
|
|||
|
|
@ -53,10 +53,13 @@ query find_people($title: String) {
|
|||
Run it:
|
||||
|
||||
```bash
|
||||
omnigraph read --query queries.gq --name find_people \
|
||||
--params '{"title":"Engineer"}' --format table graph.omni
|
||||
omnigraph query find_people --query queries.gq \
|
||||
--params '{"title":"Engineer"}' --format table --store graph.omni
|
||||
```
|
||||
|
||||
The query name is positional; `--query` points at the `.gq` source and
|
||||
`--store` addresses the graph's storage directly.
|
||||
|
||||
The [query language](queries/index.md) covers `match`/`return`/`order`, and
|
||||
[search](search/index.md) covers vector and full-text search.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue