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: openclaw-style README with logo, benchmarks, and elaborate architecture
FABIOTESS327776756aff
diff --git a/README.md b/README.mdindex 06916209..0ed05de5 100644--- a/README.md+++ b/README.md@@ -1,17 +1,40 @@<!-- mcp-name: io.github.fabio-rovai/open-ontologies -->-# Open Ontologies-[](https://github.com/fabio-rovai/open-ontologies/actions/workflows/ci.yml)-[](LICENSE)-[](https://openmcp.org/servers/open-ontologies)-[](https://www.pitchhut.com/project/open-ontologies-mcp)-[](https://clawhub.ai/fabio-rovai/open-ontologies)+<p align="center">+ <img src="docs/assets/logo.png" alt="Open Ontologies" width="260">+</p>++<h1 align="center">Open Ontologies</h1>++<p align="center">+ <strong>A Terraforming MCP for Knowledge Graphs</strong><br>+ Validate, classify, and govern AI-generated ontologies. Written in Rust. Ships as a single binary.+</p>++<p align="center">+ <a href="https://github.com/fabio-rovai/open-ontologies/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/fabio-rovai/open-ontologies/ci.yml?branch=main&style=for-the-badge" alt="CI"></a>+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT"></a>+ <a href="https://openmcp.org/servers/open-ontologies"><img src="https://img.shields.io/badge/Open_MCP-open--ontologies-blue?style=for-the-badge" alt="Open MCP"></a>+ <a href="https://www.pitchhut.com/project/open-ontologies-mcp"><img src="https://img.shields.io/badge/PitchHut-open--ontologies-orange?style=for-the-badge" alt="PitchHut"></a>+ <a href="https://clawhub.ai/fabio-rovai/open-ontologies"><img src="https://img.shields.io/badge/ClawHub-open--ontologies-7c3aed?style=for-the-badge" alt="ClawHub"></a>+</p>++<p align="center">+ <a href="#quick-start-mcp--cli">Quick Start</a> ·+ <a href="#studio-desktop-app">Studio</a> ·+ <a href="#benchmarks">Benchmarks</a> ·+ <a href="#tools">Tools</a> ·+ <a href="#architecture">Architecture</a> ·+ <a href="#documentation">Docs</a>+</p>-A Terraforming MCP for Knowledge Graphs — validate, classify, and govern AI-generated ontologies.+---++Open Ontologies is a **Rust MCP server** and **desktop Studio** for AI-native ontology engineering. It exposes **42 tools** that let Claude 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 lineage audit trail.-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.+The **Studio** wraps the engine in a visual desktop environment: 3D force-directed graph, AI chat panel, Protégé-style property inspector, and lineage viewer.-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.+No JVM. No Protégé. No GUI required.---@@ -19,9 +42,9 @@ The **Studio** is a Tauri desktop app that wraps the engine in a visual environm| 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.*+*Forest ontology built entirely in natural language. Claude called `onto_clear` → `onto_load` → `onto_reason` → `onto_save` automatically.*---@@ -29,7 +52,7 @@ The **Studio** is a Tauri desktop app that wraps the engine in a visual environm### Install-#### Pre-built binaries+**Pre-built binaries:**```bash# macOS (Apple Silicon)@@ -45,19 +68,18 @@ curl -LO https://github.com/fabio-rovai/open-ontologies/releases/latest/downloadchmod +x open-ontologies-x86_64-unknown-linux-gnu && mv open-ontologies-x86_64-unknown-linux-gnu /usr/local/bin/open-ontologies```-#### Docker+**Docker:**```bashdocker pull ghcr.io/fabio-rovai/open-ontologies:latestdocker run -i ghcr.io/fabio-rovai/open-ontologies serve```-#### From source (Rust 1.85+)+**From source (Rust 1.85+):**```bashgit clone https://github.com/fabio-rovai/open-ontologies.git-cd open-ontologies-cargo build --release+cd open-ontologies && cargo build --release./target/release/open-ontologies init```@@ -85,7 +107,7 @@ Restart Claude Code. The `onto_*` tools are now available.<details><summary><strong>Claude Desktop</strong></summary>-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:```json{@@ -97,12 +119,13 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)}}```+</details><details><summary><strong>Cursor / Windsurf / any MCP-compatible IDE</strong></summary>-Add to your MCP settings (usually `.cursor/mcp.json` or equivalent):+Add to `.cursor/mcp.json` or equivalent:```json{@@ -114,6 +137,7 @@ Add to your MCP settings (usually `.cursor/mcp.json` or equivalent):}}```+</details><details>@@ -129,6 +153,7 @@ Add to your MCP settings (usually `.cursor/mcp.json` or equivalent):}}```+</details>### Build your first ontology@@ -140,20 +165,15 @@ and defined classes (VegetarianPizza, MeatyPizza, SpicyPizza).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.+Claude generates Turtle, then calls `onto_validate` → `onto_load` → `onto_stats` → `onto_lint` → `onto_query` automatically, 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+The Studio lives in [`studio/`](studio/) — a Tauri 2 desktop app that provides a visual interface on top of the same engine.-- **Rust + Cargo** — `curl https://sh.rustup.rs -sSf | sh`-- **Node.js 18+** — `brew install node`--### First-time setup+**Prerequisites:** Rust + Cargo · Node.js 18+```bash# 1. Build the engine binary (from repo root)@@ -161,112 +181,91 @@ cargo build --release# 2. Install JS dependenciescd 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+# 3. Run+PATH=/opt/homebrew/bin:~/.cargo/bin:$PATH npm run tauri dev```### 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+| Feature | Description |+| --- | --- |+| **3D Graph Canvas** | Live force-directed OWL class hierarchy (Three.js / WebGL). Drag to orbit, scroll to zoom, click to inspect, right-click to add, Delete to remove. |+| **AI Agent Chat** | Natural language ontology engineering via Claude Sonnet 4.6 + Agent SDK. Type instructions — Claude calls the right tools automatically. |+| **Property Inspector** | Protégé-style inline triple editor. Click to edit, hover to delete, `+ Add` for new triples. |+| **Lineage Panel** | Full audit trail from SQLite: plan · apply · enforce · drift · monitor · align, grouped by session. |+| **Named Save** | ⌘S to save as `~/.open-ontologies/<name>.ttl`. Auto-saves to `studio-live.ttl` after every mutation. |-Natural language ontology engineering powered by Claude Sonnet 4.6 via the Agent SDK.+**Keyboard shortcuts:** `⌘J` chat · `⌘I` inspector · `⌘S` save · `Delete` remove node-- 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+## Benchmarks-Click any node to open a Protégé-style triple editor.+### OntoAxiom — LLM Axiom Identification-- 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+[OntoAxiom](https://arxiv.org/abs/2512.05594) tests axiom identification across 9 ontologies and 3,042 ground truth axioms.-#### Lineage Panel+| Approach | F1 | vs o1 (paper best) |+| --- | --- | --- |+| o1 (paper's best) | 0.197 | — |+| Bare Claude Opus | 0.431 | **+119%** |+| **MCP extraction** | **0.717** | **+264%** |-Full audit trail of every agent action, stored in SQLite.+### Pizza Ontology — Manchester Tutorial-- Events grouped by session with a count badge-- Color-coded badges: `P` plan · `A` apply · `E` enforce · `D` drift · `M` monitor · `AL` align+One sentence input: *"Build a Pizza ontology following the Manchester tutorial specification."*-#### Named Save+| Metric | Reference (Protégé, ~4 hours) | AI-Generated (~5 min) | Coverage |+| --- | --- | --- | --- |+| Classes | 99 | 95 | **96%** |+| Properties | 8 | 8 | **100%** |+| Toppings | 49 | 49 | **100%** |+| Named Pizzas | 24 | 24 | **100%** |-- 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`+### Mushroom Classification — OWL Reasoning vs Expert Labels-### Keyboard Shortcuts+**Dataset:** UCI Mushroom Dataset — 8,124 specimens classified by mycology experts.-| Shortcut | Action |+| Metric | Result || --- | --- |-| ⌘J | Toggle Chat panel |-| ⌘I | Toggle Inspector panel |-| ⌘S | Save As… |-| Delete / Backspace | Delete selected node |+| Accuracy | **98.33%** |+| Recall (poisonous) | **100%** — zero toxic mushrooms missed |+| False negatives | **0** |+| Classification rules | 6 OWL axioms |----+### Reasoning Performance — vs HermiT-## Why This Exists+**LUBM Scaling (load + reason cycle)**-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.+| Axioms | Open Ontologies | HermiT | Speedup |+| --- | --- | --- | --- |+| 1,000 | 15ms | 112ms | **7.5×** |+| 5,000 | 14ms | 410ms | **29×** |+| 10,000 | 14ms | 1,200ms | **86×** |+| 50,000 | 15ms | 24,490ms | **1,633×** |++Full benchmark writeup: [docs/benchmarks.md](docs/benchmarks.md)---## Tools-42 tools organized by function:+42 tools organized by function — available as MCP tools (prefixed `onto_`) and CLI subcommands:| Category | Tools | Purpose |-| -------- | ----- | ------- |-| **Core** | `validate`, `load`, `save`, `clear`, `stats`, `query`, `diff`, `lint`, `convert`, `status` | RDF/OWL validation, querying, and management |-| **Remote** | `pull`, `push`, `import-owl` | Fetch/push ontologies, resolve owl:imports |+| --- | --- | --- |+| **Core** | `validate` `load` `save` `clear` `stats` `query` `diff` `lint` `convert` `status` | RDF/OWL validation, querying, and management |+| **Remote** | `pull` `push` `import-owl` | Fetch/push ontologies, resolve owl:imports || **Schema** | `import-schema` | PostgreSQL → OWL conversion |-| **Data** | `map`, `ingest`, `shacl`, `reason`, `extend` | Structured data → RDF pipeline |-| **Versioning** | `version`, `history`, `rollback` | Named snapshots and rollback |-| **Lifecycle** | `plan`, `apply`, `lock`, `drift`, `enforce`, `monitor`, `monitor-clear`, `lineage` | Terraform-style change management |-| **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 + 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.+| **Data** | `map` `ingest` `shacl` `reason` `extend` | Structured data → RDF pipeline |+| **Versioning** | `version` `history` `rollback` | Named snapshots and rollback |+| **Lifecycle** | `plan` `apply` `lock` `drift` `enforce` `monitor` `monitor-clear` `lineage` | Terraform-style change management |+| **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 + Poincaré structural) |+| **Reasoning** | `reason` `dl_explain` `dl_check` | Native OWL2-DL SHOIQ tableaux reasoner |---@@ -276,25 +275,65 @@ All tools are available both as MCP tools (prefixed `onto_`) and as CLI subcomma```mermaidflowchart TD- Claude["Claude / LLM"]- MCP["Open Ontologies MCP Server"]+ subgraph Clients["Clients"]+ Claude["Claude / LLM\nMCP stdio"]+ CLI["CLI\nonto_* subcommands"]+ Studio["Studio\nHTTP REST"]+ end- subgraph Core["Core Engine"]- GraphStore["Oxigraph Triple Store"]- StateDb["SQLite State"]+ subgraph Server["Open Ontologies Server"]+ direction TB++ subgraph Transport["Transport Layer"]+ MCP_HTTP["MCP Streamable HTTP\n/mcp"]+ REST["REST API\n/api/query · /api/update\n/api/save · /api/load · /api/lineage"]+ end++ subgraph ToolGroups["42 Tools"]+ direction LR+ Core["Core\nvalidate · load · save · clear\nstats · query · diff · lint\nconvert · status"]+ DataPipe["Data Pipeline\nmap · ingest · shacl\nreason · extend · import-schema"]+ Lifecycle["Lifecycle\nplan · apply · lock · drift\nenforce · monitor · lineage"]+ Advanced["Alignment + Clinical\nalign · crosswalk · enrich\nenrich · embed · search · similarity\ndl_explain · dl_check"]+ Version["Versioning\nversion · history · rollback"]+ end++ subgraph Core2["Core Engine"]+ GraphStore["Oxigraph Triple Store\nRDF/OWL in-memory\nSPARQL 1.1"]+ SQLite["SQLite\nlineage events\nversion snapshots\nlint/enforce feedback\nembedding vectors"]+ Reasoner["OWL2-DL Reasoner\nSHOIQ tableaux\nRDFS · OWL-RL"]+ Embedder["Embedding Engine\ntract-onnx (ONNX)\ntext + Poincaré structural"]+ endend- subgraph Tools["42 Tools + 5 Prompts"]- direction LR- Ontology["validate · load · query\nsave · diff · lint · convert"]- Data["map · ingest · shacl\nreason · extend"]- Lifecycle["plan · apply · lock\nenforce · monitor · drift"]- Advanced["align · crosswalk · enrich\nlineage · embed · search"]+ subgraph External["External Sources"]+ PG["PostgreSQL\nschema import"]+ SPARQL["Remote SPARQL\nendpoints"]+ OWL["OWL URLs\nowl:imports chains"]+ Parquet["Parquet / Arrow\nclinical crosswalks\nICD-10 · SNOMED · MeSH"]+ Files["Files\nCSV · JSON · XML\nYAML · XLSX · Parquet"]end- Claude -->|"MCP stdio"| MCP- MCP --> Tools- Tools --> Core+ Claude -->|"MCP stdio"| MCP_HTTP+ CLI -->|"subcommands"| MCP_HTTP+ Studio -->|"sessionless"| REST++ MCP_HTTP --> ToolGroups+ REST --> ToolGroups++ ToolGroups --> GraphStore+ ToolGroups --> SQLite+ ToolGroups --> Reasoner+ ToolGroups --> Embedder++ Reasoner --> GraphStore+ Embedder --> SQLite++ DataPipe --> Files+ Advanced --> Parquet+ Core --> OWL+ Core --> SPARQL+ DataPipe --> PG```### Studio@@ -311,27 +350,25 @@ flowchart TDsubgraph Tauri["Tauri 2 Shell (Rust)"]IPC["Tauri IPC\ninvoke / event"]- EngineState["EngineState\nAtomicBool + Child"]ChatState["ChatState\nstdin/stdout pipe"]- McpState["McpState\nreqwest Client"]endsubgraph Engine["Engine Sidecar (Rust / Axum)"]- MCP["/mcp\nMCP Streamable HTTP\n42 onto_* tools"]- REST["/api/query · /api/update\n/api/save · /api/load-turtle\n/api/stats · /api/lineage"]- Store["Arc<GraphStore>\nOxigraph triple store"]- DB["SQLite\nlineage · versions · feedback"]+ MCP["/mcp — MCP Streamable HTTP\n42 onto_* tools"]+ REST2["/api/query · /api/update\n/api/save · /api/load-turtle\n/api/stats · /api/lineage"]+ Store["Arc<GraphStore>\nOxigraph"]+ DB["SQLite"]endsubgraph Agent["Agent Sidecar (Node.js)"]- SDK["Claude Agent SDK\nsonnet-4-6"]- Proto["stdin/stdout\nJSON protocol"]+ SDK["Claude Sonnet 4.6\nAgent SDK"]+ Proto["stdin/stdout JSON protocol"]end- Graph -->|"SPARQL SELECT\nREST"| REST- Inspector -->|"SPARQL UPDATE\nREST"| REST- Lineage -->|"GET /api/lineage\nREST"| REST- Save -->|"POST /api/save\nREST"| REST+ Graph -->|"SPARQL SELECT · REST"| REST2+ Inspector -->|"SPARQL UPDATE · REST"| REST2+ Lineage -->|"GET /api/lineage"| REST2+ Save -->|"POST /api/save"| REST2Chat -->|"invoke send_chat_message"| IPCIPC --> ChatStateChatState -->|"stdin { type: chat }"| Proto@@ -340,7 +377,7 @@ flowchart TDSDK -->|"stdout { type: text/tool_call/done }"| ProtoProto -->|"Tauri emit agent-message"| ChatMCP --> Store- REST --> Store+ REST2 --> StoreStore --> DB```@@ -348,11 +385,11 @@ flowchart TD| Decision | Reason || --- | --- |-| UI reads use sessionless REST API | No MCP session management needed for SPARQL queries or stats |+| UI reads use sessionless REST | 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 |+| Shared `Arc<GraphStore>` | All MCP sessions and REST handlers share the same in-memory triple store |+| Agent sidecar over stdin/stdout | Keeps Node.js isolated; Tauri manages the full lifecycle |---@@ -360,12 +397,12 @@ flowchart TD| 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) |+| Engine language | Rust (edition 2024) — single binary, no JVM |+| Triple store | Oxigraph 0.4 — pure Rust RDF/SPARQL 1.1 engine |+| MCP protocol | rmcp — Streamable HTTP transport |+| State / lineage / feedback | SQLite (rusqlite) || Clinical crosswalks | Apache Arrow / Parquet |-| Embeddings | tract-onnx (pure Rust ONNX runtime, optional) |+| Embeddings runtime | tract-onnx — pure Rust ONNX (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) |@@ -377,7 +414,7 @@ flowchart TD## 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) |@@ -395,4 +432,4 @@ flowchart TDMIT-<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>+<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 on Glama"></a>diff --git a/docs/assets/logo.png b/docs/assets/logo.pngnew file mode 100644index 00000000..ea27233bBinary files /dev/null and b/docs/assets/logo.png differ