Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
docs: unify README into single cohesive document with screenshots
FABIOTESS613a6ce3b6a5
diff --git a/README.md b/README.mdindex f2d139aa..06916209 100644--- a/README.md+++ b/README.md@@ -7,29 +7,30 @@[](https://www.pitchhut.com/project/open-ontologies-mcp)[](https://clawhub.ai/fabio-rovai/open-ontologies)-A Terraforming MCP for Knowledge Graphs: validate, classify, and govern AI-generated ontologies.+A Terraforming MCP for Knowledge Graphs — validate, classify, and govern AI-generated ontologies.-Open Ontologies is a standalone MCP server and CLI for AI-native ontology engineering. It exposes 42 tools and 5 workflow prompts that let Claude validate, query, diff, lint, version, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — plus plan changes, detect drift, enforce design patterns, monitor health, align ontologies, track lineage, and learn from user feedback.+Open Ontologies is a **Rust MCP server** and **desktop Studio** for AI-native ontology engineering. It exposes 42 tools that let Claude (or any MCP client) build, validate, query, diff, lint, version, reason over, align, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — with Terraform-style lifecycle management, clinical crosswalks, semantic embeddings, and a full audit trail.-Written in Rust, ships as a single binary. No JVM, no Protégé, no GUI.+The **Studio** is a Tauri desktop app that wraps the engine in a visual environment: 3D force-directed graph, AI chat panel, Protégé-style property inspector, lineage viewer, and named save.----## Contents+## Screenshots-- [MCP Server / CLI](#quick-start) — use Open Ontologies from Claude Code, Claude Desktop, or any MCP client-- [Studio](#studio) — desktop GUI for visual ontology engineering (Tauri + React + 3D graph)+| Full UI | 3D Graph |+|---|---|+|  |  |++*Forest ontology built entirely through natural language: "Build me an ontology about a forest ecosystem." Claude called `onto_clear` → `onto_load` → `onto_reason` → `onto_save` automatically.*----## Quick Start+## Quick Start (MCP / CLI)-### 1. Install+### Install#### Pre-built binaries-Download from [GitHub Releases](https://github.com/fabio-rovai/open-ontologies/releases/latest):-```bash# macOS (Apple Silicon)curl -LO https://github.com/fabio-rovai/open-ontologies/releases/latest/download/open-ontologies-aarch64-apple-darwin@@ -60,7 +61,7 @@ cargo build --release./target/release/open-ontologies init```-### 2. Connect to your MCP client+### Connect to your MCP client<details><summary><strong>Claude Code</strong></summary>@@ -130,7 +131,7 @@ Add to your MCP settings (usually `.cursor/mcp.json` or equivalent):```</details>-### 3. Build your first ontology+### Build your first ontology```textBuild me a Pizza ontology following the Manchester University tutorial.@@ -141,9 +142,111 @@ Validate it, load it, and show me the stats.Claude generates Turtle, then automatically calls `onto_validate` → `onto_load` → `onto_stats` → `onto_lint` → `onto_query`, fixing errors along the way.+---++## Studio (Desktop App)++The Studio lives in [`studio/`](studio/) and provides a visual interface on top of the same engine.++### Prerequisites++- **Rust + Cargo** — `curl https://sh.rustup.rs -sSf | sh`+- **Node.js 18+** — `brew install node`++### First-time setup++```bash+# 1. Build the engine binary (from repo root)+cargo build --release++# 2. Install JS dependencies+cd studio && npm install+```++### Run++```bash+cd studio+PATH=/opt/homebrew/bin:/Users/fabio/.cargo/bin:$PATH npm run tauri dev+```++The `PATH` prefix is required because macOS doesn't expose Homebrew or Cargo to subprocess shells.++On startup Tauri will:++1. Compile the Rust shell (~1 min first run, fast after)+2. Start Vite dev server on `localhost:1420`+3. Open the app window+4. Spawn the engine sidecar (`open-ontologies serve-http --port 8080`)+5. Spawn the AI agent sidecar (Node.js, 3s after engine)++### Rebuild after changes++```bash+# Engine changes (src/):+cargo build --release++# Agent sidecar changes (studio/src-tauri/sidecars/agent/index.ts):+cd studio/src-tauri/sidecars/agent && npm run build+```++### Studio Features++#### 3D Graph Canvas++Live force-directed graph (Three.js / WebGL) of your OWL class hierarchy.++- **Drag** to orbit · **Scroll** to zoom · **Click node** to inspect · **Right-click** to add class · **Delete** to remove+- On load, fires two SPARQL queries: all `owl:Class` nodes + all `rdfs:subClassOf` edges+- Nodes are spheres with floating label sprites; selected node highlighted in amber+- Auto-refreshes after every agent mutation or UI edit via `window.__refreshGraph()`++#### AI Agent Chat++Natural language ontology engineering powered by Claude Sonnet 4.6 via the Agent SDK.++- Type any instruction: *"Add a Mammal hierarchy"*, *"Run OWL reasoning"*, *"Validate and fix issues"*+- Claude calls the engine's 42 MCP tools automatically, iterating until the result is correct+- After any mutation, the graph refreshes and the ontology is auto-saved+- Slash commands: `/build`, `/expand`, `/validate`, `/reason`, `/query`, `/stats`, `/save`++#### Property Inspector++Click any node to open a Protégé-style triple editor.++- Click any value to edit inline (Enter saves, Escape cancels)+- Hover a row to reveal the `×` delete button+- `+ Add` opens a form with predicate quick-pick (`rdfs:label`, `rdfs:subClassOf`, `owl:equivalentClass`, etc.) and Literal/URI toggle++#### Lineage Panel++Full audit trail of every agent action, stored in SQLite.++- Events grouped by session with a count badge+- Color-coded badges: `P` plan · `A` apply · `E` enforce · `D` drift · `M` monitor · `AL` align++#### Named Save++- Click `💾` or press **⌘S** to save with a custom filename+- All saves go to `~/.open-ontologies/<name>.ttl`+- Auto-save after every mutation writes to `~/.open-ontologies/studio-live.ttl`++### Keyboard Shortcuts++| Shortcut | Action |+| --- | --- |+| ⌘J | Toggle Chat panel |+| ⌘I | Toggle Inspector panel |+| ⌘S | Save As… |+| Delete / Backspace | Delete selected node |++---+## Why This Exists-Single-shot LLM ontology generation has real problems: no validation, no verification, no iteration, no persistence, no scale, no integration. Open Ontologies solves all of these with a proper RDF/SPARQL engine (Oxigraph) exposed as MCP tools that Claude calls automatically.+Single-shot LLM ontology generation has real problems: no validation, no verification, no iteration, no persistence, no scale, no integration. Open Ontologies solves all of these with a proper RDF/SPARQL engine (Oxigraph) exposed as MCP tools that Claude calls automatically — and a desktop Studio that makes the results visible in real time.++---## Tools@@ -160,13 +263,17 @@ Single-shot LLM ontology generation has real problems: no validation, no verific| **Alignment** | `align`, `align-feedback` | Cross-ontology class matching with self-calibrating confidence || **Clinical** | `crosswalk`, `enrich`, `validate-clinical` | ICD-10 / SNOMED / MeSH crosswalks || **Feedback** | `lint-feedback`, `enforce-feedback` | Self-calibrating suppression |-| **Embeddings** | `embed`, `search`, `similarity` | Dual-space semantic search (text + Poincare structural) |+| **Embeddings** | `embed`, `search`, `similarity` | Dual-space semantic search (text + Poincaré structural) || **Reasoning** | `reason`, `dl_explain`, `dl_check` | Native OWL2-DL SHOIQ tableaux reasoner |All tools are available both as MCP tools (prefixed `onto_`) and as CLI subcommands.+---+## Architecture+### Engine+```mermaidflowchart TDClaude["Claude / LLM"]@@ -190,106 +297,7 @@ flowchart TDTools --> Core```-## Documentation--| Topic | Link |-| ----- | ---- |-| Quickstart | [docs/quickstart.md](docs/quickstart.md) |-| Data Pipeline | [docs/data-pipeline.md](docs/data-pipeline.md) |-| Ontology Lifecycle | [docs/lifecycle.md](docs/lifecycle.md) |-| Schema Alignment | [docs/alignment.md](docs/alignment.md) |-| OWL2-DL Reasoning | [docs/reasoning.md](docs/reasoning.md) |-| Semantic Embeddings | [docs/embeddings.md](docs/embeddings.md) |-| Clinical Crosswalks | [docs/clinical.md](docs/clinical.md) |-| Benchmarks | [docs/benchmarks.md](docs/benchmarks.md) |-| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |-| Changelog | [CHANGELOG.md](CHANGELOG.md) |--## Stack--- **Rust** (edition 2024) — single binary, no JVM-- **Oxigraph 0.4** — pure Rust RDF/SPARQL engine-- **rmcp** — MCP protocol implementation-- **SQLite** (rusqlite) — state, versions, lineage, feedback, embeddings-- **Apache Arrow/Parquet** — clinical crosswalk file format-- **tract-onnx** — pure Rust ONNX runtime for text embeddings (optional)-- **tokenizers** — HuggingFace tokenizer (optional)--## License--MIT--<a href="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies"><img width="380" height="200" src="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies/badge" /></a>-------## Studio--A desktop ontology engineering environment powered by AI. Built with Tauri 2, React 19, and the Open Ontologies engine.--### Features--#### 3D Graph Canvas--The graph view renders your OWL ontology as a live 3D force-directed graph powered by `3d-force-graph` (Three.js / WebGL).--**How it works:**--- On connection, the canvas fires two SPARQL queries against the engine's in-memory Oxigraph store:- - `SELECT ?c ?label WHERE { ?c a owl:Class . OPTIONAL { ?c rdfs:label ?label } }` — fetches all named classes- - `SELECT ?sub ?parent WHERE { ?sub rdfs:subClassOf ?parent . ?sub a owl:Class }` — fetches the subclass hierarchy-- Nodes are spheres with floating canvas-text label sprites. The selected node is highlighted in amber; others are blue.-- Edges are directed arrows (subClassOf → parent direction) with 60% opacity.-- The graph uses Three.js warm lighting (ambient + directional) on a `#1e1e2e` background.-- A `ResizeObserver` keeps the canvas sized to its container on every layout change.--**Interaction:**--- **Drag** to orbit the scene-- **Scroll** to zoom in/out-- **Click a node** — selects it, flies the camera toward it (800ms ease), and opens the Property Inspector-- **Click background** — deselects-- **Right-click** — opens the Add Class dialog at the cursor position-- **Delete / Backspace** — deletes the selected class (fires two SPARQL DELETE statements, then saves and refreshes)--**Refresh:** After any mutation (agent, inspector, delete, add), `window.__refreshGraph()` is called to re-query the store and redraw.--#### AI Agent Chat--Natural language ontology engineering via the Claude Agent SDK.--**How it works:**-- The agent runs as a Node.js sidecar process (`studio/src-tauri/sidecars/agent/`), spawned by Tauri 3 seconds after the engine starts.-- The sidecar connects Claude to the Open Ontologies engine via its MCP endpoint (`http://localhost:8080/mcp`), giving Claude access to all 42 ontology tools.-- The Tauri Rust backend communicates with the sidecar over stdin/stdout using a simple JSON protocol (`{ type: 'chat', message }` in, `{ type: 'text' | 'tool_call' | 'done' | 'error' }` out).-- Multi-turn sessions are maintained in-memory within the sidecar process.-- After any mutation tool call, the frontend detects `mutated: true` in the `done` message and triggers a graph refresh.--**Slash commands:** `/build`, `/expand`, `/validate`, `/reason`, `/query`, `/stats`, `/save`--#### Property Inspector--Protégé-style property editing for any selected node.--- Click any literal or URI value to edit it inline (Enter saves, Escape cancels)-- Hover over a triple row to reveal the `×` delete button-- The `+ Add` button opens a form with predicate quick-pick and Literal/URI toggle-- All edits call SPARQL UPDATE via REST, then save to file--#### Lineage Panel--Full audit trail of every agent action, stored in SQLite and exposed via `GET /api/lineage`.--- Events grouped by session with a count badge-- Color-coded operation badges: `P` plan, `A` apply, `E` enforce, `D` drift, `M` monitor, `AL` align--#### Named Save--- Click `💾` or press **⌘S** to save with a custom filename-- Saves to `~/.open-ontologies/<name>.ttl`-- All auto-saves after mutations persist to `~/.open-ontologies/studio-live.ttl`--### Studio Architecture+### Studio```mermaidflowchart TD@@ -336,80 +344,55 @@ flowchart TDStore --> DB```+### Design decisions+| Decision | Reason || --- | --- |-| Reads go through sessionless REST API | No MCP session management needed for SPARQL queries or stats |+| UI reads use sessionless REST API | No MCP session management needed for SPARQL queries or stats || UI writes use REST `/api/update` + `/api/save` | Avoids session lifecycle issues in the Tauri WebKit webview || Agent writes go through MCP `tools/call` | The Agent SDK manages its own MCP session; Claude needs the full tool set || Shared `Arc<GraphStore>` | All MCP sessions and all REST handlers operate on the same in-memory triple store || Agent sidecar over stdin/stdout | Keeps Node.js process isolated; Tauri manages lifecycle |-### Studio Stack+---++## Stack| Layer | Tech || --- | --- |+| Engine | Rust (edition 2024), single binary |+| Triple store | Oxigraph 0.4 (pure Rust RDF/SPARQL) |+| MCP protocol | rmcp (Streamable HTTP transport) |+| State / lineage | SQLite (rusqlite) |+| Clinical crosswalks | Apache Arrow / Parquet |+| Embeddings | tract-onnx (pure Rust ONNX runtime, optional) || Desktop shell | Tauri 2 || Frontend | React 19, Vite 7, TypeScript 5.8, Tailwind CSS 4 || 3D graph | 3d-force-graph 1.79 (Three.js / WebGL) |-| State | Zustand 5 |-| Engine | Rust, Axum 0.8, Oxigraph 0.4 (SPARQL), SQLite |-| MCP | rmcp 1 (Streamable HTTP transport) |+| UI state | Zustand 5 || AI agent | Claude Sonnet 4.6 via Agent SDK (Node.js sidecar) |-### Running the Studio--#### Prerequisites--- **Rust + Cargo** — install via `curl https://sh.rustup.rs -sSf | sh`-- **Node.js 18+** — install via Homebrew: `brew install node`-- **Tauri CLI** — installed as a dev dependency (`npm install` handles this)--#### First-time setup--```bash-# 1. Build the engine binary-cargo build --release-# Produces: target/release/open-ontologies-# The studio symlink at studio/src-tauri/binaries/open-ontologies-aarch64-apple-darwin-# already points to it — no extra step needed.--# 2. Install JS dependencies-cd studio-npm install-```--#### Start the app--```bash-cd studio-PATH=/opt/homebrew/bin:/Users/fabio/.cargo/bin:$PATH npm run tauri dev-```--The `PATH` prefix is required because the macOS default shell PATH doesn't include Homebrew or Cargo when Tauri spawns subprocesses.--Tauri will:+----1. Compile the Rust shell (first run ~1 min, subsequent runs fast)-2. Start the Vite dev server on `localhost:1420`-3. Open the app window-4. Spawn the engine sidecar (`open-ontologies serve-http --port 8080`)-5. Spawn the agent sidecar (Node.js, after 3s delay)+## Documentation-#### Rebuild after changes+| Topic | Link |+| ----- | ---- |+| Quickstart | [docs/quickstart.md](docs/quickstart.md) |+| Data Pipeline | [docs/data-pipeline.md](docs/data-pipeline.md) |+| Ontology Lifecycle | [docs/lifecycle.md](docs/lifecycle.md) |+| Schema Alignment | [docs/alignment.md](docs/alignment.md) |+| OWL2-DL Reasoning | [docs/reasoning.md](docs/reasoning.md) |+| Semantic Embeddings | [docs/embeddings.md](docs/embeddings.md) |+| Clinical Crosswalks | [docs/clinical.md](docs/clinical.md) |+| Benchmarks | [docs/benchmarks.md](docs/benchmarks.md) |+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |+| Changelog | [CHANGELOG.md](CHANGELOG.md) |-```bash-# After changes to the engine (src/):-cargo build --release+----# After changes to the agent sidecar (studio/src-tauri/sidecars/agent/index.ts):-cd studio/src-tauri/sidecars/agent && npm run build-```+## License-#### Keyboard Shortcuts+MIT-| Shortcut | Action |-| --- | --- |-| ⌘J | Toggle Chat panel |-| ⌘I | Toggle Inspector panel |-| ⌘S | Save As… |-| Delete / Backspace | Delete selected node |+<a href="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies"><img width="380" height="200" src="https://glama.ai/mcp/servers/fabio-rovai/open-ontologies/badge" alt="Open Ontologies MCP server on Glama" /></a>diff --git a/studio/docs/screenshots/studio-graph.png b/studio/docs/screenshots/studio-graph.pngnew file mode 100644index 00000000..9ccdee17Binary files /dev/null and b/studio/docs/screenshots/studio-graph.png differdiff --git a/studio/docs/screenshots/studio-overview.png b/studio/docs/screenshots/studio-overview.pngnew file mode 100644index 00000000..9d0f1bebBinary files /dev/null and b/studio/docs/screenshots/studio-overview.png differ