Initial public Omnigraph repository

README.md

@@ -0,0 +1,154 @@
+# Omnigraph
+
+Omnigraph is a typed property graph database built on Lance. It combines
+schema-first graph modeling, typed queries and mutations, Git-style graph
+workflows, and storage that runs equally well on a local directory or an
+`s3://` URI.
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | bash
+```
+
+This installs `omnigraph` and `omnigraph-server` into `~/.local/bin`. If no
+tagged release exists for your platform yet, the installer falls back to a
+source build.
+
+## One-Command Local RustFS Bootstrap
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/local-rustfs-bootstrap.sh | bash
+```
+
+That bootstrap:
+
+- starts RustFS on `127.0.0.1:9000`
+- creates a bucket and S3-backed repo
+- loads the checked-in context fixture
+- launches `omnigraph-server` on `127.0.0.1:8080`
+
+Docker must be installed and running first.
+
+## Good Fit For
+
+- Team knowledge graphs and internal context graphs
+- Research, decisions, and evidence tracking
+- Collaborative knowledge systems with reviewable changes
+- Private self-hosted graph backends for local or on-prem AI tooling
+
+## Why Omnigraph
+
+- Typed schema, typed queries, and typed mutations
+- Git-style graph workflows: branches, commits, merges, and transactional runs
+- Local-first and S3-native storage with snapshot-pinned reads
+- Graph traversal plus text, fuzzy, BM25, vector, and RRF search in one runtime
+- Policy as code for server-side access control
+
+## Quick Start
+
+From a checkout of this repo:
+
+```bash
+cargo build --workspace
+
+cargo run -p omnigraph-cli -- init \
+  --schema crates/omnigraph/tests/fixtures/test.pg \
+  ./repo.omni
+
+cargo run -p omnigraph-cli -- load \
+  --data crates/omnigraph/tests/fixtures/test.jsonl \
+  ./repo.omni
+
+cargo run -p omnigraph-cli -- read \
+  ./repo.omni \
+  --query crates/omnigraph/tests/fixtures/test.gq \
+  --name friends_of \
+  --params '{"name":"Alice"}'
+```
+
+`init` also scaffolds an `omnigraph.yaml` next to the repo if one does not
+already exist.
+
+## Run A Server
+
+Serve the same repo over HTTP:
+
+```bash
+cargo run -p omnigraph-server -- ./repo.omni --bind 127.0.0.1:8080
+```
+
+Then query it remotely:
+
+```bash
+cargo run -p omnigraph-cli -- read \
+  --target http://127.0.0.1:8080 \
+  --query crates/omnigraph/tests/fixtures/test.gq \
+  --name get_person \
+  --params '{"name":"Alice"}'
+```
+
+Server routes include `/healthz`, `/snapshot`, `/export`, `/read`, `/change`,
+`/ingest`, `/branches`, `/runs`, and `/commits`.
+
+To require auth, set `OMNIGRAPH_SERVER_BEARER_TOKEN` on the server and set the
+matching bearer token env var in your CLI target config.
+
+## Common Commands
+
+Core repo flow:
+
+```bash
+omnigraph init --schema ./schema.pg ./repo.omni
+omnigraph load --data ./data.jsonl --mode overwrite ./repo.omni
+omnigraph snapshot ./repo.omni --branch main --json
+omnigraph read ./repo.omni --query ./queries.gq --name get_person --params '{"name":"Alice"}'
+omnigraph change ./repo.omni --query ./queries.gq --name insert_person --params '{"name":"Mina","age":28}'
+omnigraph branch create --uri ./repo.omni --from main feature-x
+omnigraph branch merge --uri ./repo.omni feature-x --into main
+```
+
+More CLI examples, config patterns, and admin commands live in
+[docs/cli.md](docs/cli.md).
+
+## Production Features
+
+- Branches, commits, merge-base-aware graph merges, and transactional runs
+- Snapshot-pinned reads across local and S3-backed repos
+- Traversal plus text, fuzzy, BM25, vector, and RRF search
+- Axum server for reads, changes, export, branches, commits, and runs
+- Cedar-based server-side authorization
+
+## Docs
+
+- [Install guide](docs/install.md)
+- [CLI guide](docs/cli.md)
+- [Deployment guide](docs/deployment.md)
+
+## Build And Test
+
+```bash
+cargo build --workspace
+cargo check --workspace
+cargo test --workspace
+```
+
+Notes:
+
+- Rust stable toolchain, edition 2024
+- CI runs `cargo test --workspace --locked`
+- Full CI and some local test flows require `protobuf-compiler`
+- S3 integration tests expect an S3-compatible endpoint such as RustFS
+
+## Workspace Crates
+
+- `crates/omnigraph-compiler`: shared schema/query parser, typechecker, catalog, and IR lowering
+- `crates/omnigraph`: storage/runtime, branching, merge, change detection, and query execution
+- `crates/omnigraph-cli`: CLI for init/load/ingest/read/change/branch/snapshot/export/policy operations
+- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, commits, and runs
+
+## Contributing
+
+Please open an issue, spec, or design discussion before sending large code
+changes. Design feedback and concrete problem statements are the fastest way to
+collaborate on the roadmap.