Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

docs(studio): correct README claims about tool count, model, SDK, binary and paths

FABIOTESS65146506db76
diff --git a/studio/README.md b/studio/README.md
index 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 studio
npm 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`: