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(studio): correct README claims about tool count, model, SDK, binary and paths
FABIOTESS65146506db76
diff --git a/studio/README.md b/studio/README.mdindex e054b68c..2e19fc7d 100644--- a/studio/README.md+++ b/studio/README.md@@ -11,8 +11,8 @@ The graph view renders your OWL ontology as a live 3D force-directed graph power**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+ - `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.@@ -22,20 +22,22 @@ The graph view renders your OWL ontology as a live 3D force-directed graph power- **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)+- **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. This is also wired to the `engine-ready` Tauri event on startup.### AI Agent Chat-Natural language ontology engineering via the Claude Agent SDK.+Natural language ontology engineering via a model provider chosen at runtime.**How it works:**- The agent runs as a Node.js sidecar process (`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:<port>/mcp`, port 8137 by default, passed down from the Rust host), giving Claude access to all 42 ontology tools (`onto_load`, `onto_query`, `onto_validate`, `onto_lint`, `onto_reason`, `onto_enforce`, `onto_plan`, `onto_apply`, `onto_save`, `onto_diff`, `onto_align`, `onto_embed`, `onto_search`, and more).+- The sidecar connects a model to the Open Ontologies engine via its MCP endpoint (`http://localhost:<port>/mcp`, port 8137 by default, passed down from the Rust host), giving it access to the engine's full tool set: `src/server.rs` currently declares roughly 103 `onto_*` tools (`onto_load`, `onto_query`, `onto_validate`, `onto_lint`, `onto_reason`, `onto_enforce`, `onto_plan`, `onto_apply`, `onto_save`, `onto_diff`, `onto_align`, `onto_embed`, `onto_search`, and many more) -- check that file for the current count rather than trusting a number here, since it grows.+- Provider selection (`providers/alias.ts`'s `selectProvider`) is a fallback chain, not a fixed SDK: `ONTO_PROVIDER=anthropic|openai|claude-cli` forces one; otherwise an explicit `ONTO_LLM_BASE_URL` selects an OpenAI-compatible endpoint; otherwise a present `ANTHROPIC_API_KEY` selects Anthropic; otherwise it falls back to a **local** OpenAI-compatible endpoint (`http://localhost:8081/v1` by default). This local fallback exists because an app launched from Finder has no shell environment, so an unconditional Anthropic default died with an authentication error before the first token.+- The Anthropic path (`providers/anthropic.ts`) calls the raw `@anthropic-ai/sdk` Messages API directly, not the separate Claude Agent SDK package. Its default model is `claude-opus-5` (`ONTO_LLM_MODEL` overrides it), used only when the fallback chain above actually selects Anthropic.- 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 (not persisted to disk).- After any mutation tool call (`onto_load`, `onto_apply`, `onto_reason`, etc.), the frontend detects `mutated: true` in the `done` message and triggers a graph refresh.@@ -47,7 +49,7 @@ Natural language ontology engineering via the Claude Agent SDK.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 — removes that triple immediately+- Hover over a triple row to reveal the `×` delete button, which removes that triple immediately- The `+ Add` button at the bottom opens a form with:- Predicate quick-pick: `rdfs:label`, `rdfs:comment`, `rdfs:subClassOf`, `owl:equivalentClass`, `skos:definition`, `skos:altLabel`, `owl:deprecated`- Value type toggle: **Literal** or **URI**@@ -76,13 +78,13 @@ React UI (Vite + Tailwind)└── Tauri 2 shell├── Engine sidecar → open-ontologies (Rust/Axum/Oxigraph)│ ├── /mcp MCP Streamable HTTP (tools/call, initialize…)- │ ├── /api/stats GET — graph statistics (triples, classes, props, individuals)- │ ├── /api/query POST { query } — SPARQL SELECT- │ ├── /api/update POST { query } — SPARQL UPDATE (INSERT/DELETE)- │ ├── /api/load POST { path } — load TTL file into store- │ ├── /api/save POST { path, format } — save store to file- │ └── /api/lineage GET — lineage events from SQLite- └── Agent sidecar → Node.js (Claude Agent SDK)+ │ ├── /api/stats GET (graph statistics: triples, classes, props, individuals)+ │ ├── /api/query POST { query } (SPARQL SELECT)+ │ ├── /api/update POST { query } (SPARQL UPDATE: INSERT/DELETE)+ │ ├── /api/load POST { path } (load TTL file into store)+ │ ├── /api/save POST { path, format } (save store to file)+ │ └── /api/lineage GET (lineage events from SQLite)+ └── Agent sidecar → Node.js (@anthropic-ai/sdk, or a local OpenAI-compatible endpoint)├── stdin: { type: 'chat', message } / { type: 'reset' }└── stdout: { type: 'text' | 'tool_call' | 'done' | 'error' | 'session' }```@@ -93,7 +95,7 @@ React UI (Vite + Tailwind)| --- | --- || Reads go through 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 |+| Agent writes go through MCP `tools/call` | Whichever provider is active manages its own MCP session, and 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 (spawns, kills on exit) |@@ -111,39 +113,44 @@ The live working file is `~/.open-ontologies/studio-live.ttl`. On startup the en| State | Zustand 5 || Engine | Rust, Axum 0.8, Oxigraph 0.4 (SPARQL), SQLite || MCP | rmcp 1 (Streamable HTTP transport) |-| AI agent | Claude Sonnet 4.6 via Agent SDK (Node.js sidecar) |+| AI agent | Node.js sidecar; `claude-opus-5` via `@anthropic-ai/sdk` when `ANTHROPIC_API_KEY` is set, otherwise a local OpenAI-compatible endpoint by default (see `providers/alias.ts`) |## Running### 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)-- **Engine binary** — must be built once before first run (see below)+- **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)+- **Engine binary**: must be built once before first run (see below)++`studio/` is a subdirectory of the `open-ontologies` repository, not a sibling repository: the engine's own `Cargo.toml` lives at the repo root, one level up from `studio/`.### First-time setup```bash-# 1. Build the engine binary-cd ../open-ontologies+# 1. Build the engine binary, from the repository root (the parent of studio/)+cd ..cargo build --release# This produces: target/release/open-ontologies-# The studio symlink at src-tauri/binaries/open-ontologies-aarch64-apple-darwin-# already points to it — no extra step needed.+# studio/src-tauri/binaries/open-ontologies-aarch64-apple-darwin is a real,+# tracked ~40MB binary, not a symlink: copy the freshly built binary over it+# (the filename encodes the target triple; substitute your own platform's if+# it differs from Apple Silicon macOS).+cp target/release/open-ontologies studio/src-tauri/binaries/open-ontologies-aarch64-apple-darwin# 2. Install JS dependencies-cd ../open-ontologies-studio+cd studionpm install```### Start the app```bash-PATH=/opt/homebrew/bin:/Users/fabio/.cargo/bin:$PATH npm run tauri dev+npm run tauri dev```-The `PATH` prefix is required because the macOS default shell PATH doesn't include Homebrew (`/opt/homebrew/bin`) or Cargo (`~/.cargo/bin`), which Tauri needs to find `node` and `cargo` when it spawns subprocesses.+If `node` or `cargo` are not already resolvable when Tauri spawns subprocesses (for example, the macOS default shell PATH does not include Homebrew's `/opt/homebrew/bin` or Cargo's `~/.cargo/bin` by default), prefix the command with your own PATH, e.g. `PATH=/opt/homebrew/bin:$HOME/.cargo/bin:$PATH npm run tauri dev`.Tauri will:@@ -156,15 +163,10 @@ Tauri will:## Development```bash-# Rebuild engine after changes to open-ontologies/-cd ../open-ontologies && /Users/fabio/.cargo/bin/cargo build --release-```--The engine sidecar binary is a symlink:--```text-src-tauri/binaries/open-ontologies-aarch64-apple-darwin- → ../../open-ontologies/target/release/open-ontologies+# Rebuild the engine after changes to the sources at the repository root,+# then copy the fresh binary over the tracked copy studio/ ships (see above).+cd .. && cargo build --release+cp target/release/open-ontologies studio/src-tauri/binaries/open-ontologies-aarch64-apple-darwin```The agent sidecar is pre-bundled at `src-tauri/sidecars/agent/dist/index.js`. Rebuild after changes to `index.ts`: