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: add embedding tools to workflow documentation
FABIOTESS48654b9bbcc8
diff --git a/CLAUDE.md b/CLAUDE.mdindex 98744062..099fc2b9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -77,6 +77,9 @@ Claude dynamically decides the next tool call based on what the previous tool re| `onto_lineage` | To view the session's lineage trail (plan → enforce → apply → monitor → drift) || `onto_lint_feedback` | To accept/dismiss a lint issue — teaches lint to suppress repeatedly dismissed warnings || `onto_enforce_feedback` | To accept/dismiss an enforce violation — teaches enforce to suppress repeatedly dismissed violations |+| `onto_embed` | After loading an ontology — generates text + Poincaré structural embeddings for all classes |+| `onto_search` | To find classes by natural language description — requires onto_embed first |+| `onto_similarity` | To compute embedding similarity between two specific IRIs |## Ontology Lifecycle@@ -137,6 +140,30 @@ When applying an ontology to external data:10. Call `onto_extend` to run ingest → SHACL → reason in one call+## Semantic Search & Embedding Workflow++When exploring or aligning ontologies using semantic embeddings:++### Setup++1. Ensure the embedding model is downloaded (`open-ontologies init`)+2. Call `onto_load` to load the ontology+3. Call `onto_embed` to generate text + structural embeddings for all classes++### Search++4. Call `onto_search` with a natural language query — returns most similar classes+5. Use `mode: "text"` for label/definition similarity, `mode: "structure"` for hierarchy position, `mode: "product"` for combined++### Compare++6. Call `onto_similarity` with two IRIs to see cosine + Poincaré distance between them++### Alignment Enhancement++7. When running `onto_align`, embedding similarity is automatically used as signal #7 if embeddings are loaded+8. This catches semantically equivalent classes that have different labels (e.g., Vehicle ↔ Automobile)+## Enforcer Rules (Optional)If [OpenCheir](https://github.com/fabio-rovai/opencheir) is also connected as an MCP server, its enforcer rules provide workflow safety:diff --git a/README.md b/README.mdindex 57b8b474..e927afa7 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@[](https://clawhub.ai/fabio-rovai/open-ontologies)-Open Ontologies is a standalone MCP server and CLI for AI-native ontology engineering. It exposes 39 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 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.Written in Rust, ships as a single binary. No JVM, no Protege, no GUI.@@ -203,7 +203,7 @@ This is not a fixed pipeline. Claude is the orchestrator — it decides what to## Tools-39 tools organized by function:+42 tools organized by function:| Category | Tools | Purpose || -------- | ----- | ------- |@@ -216,6 +216,7 @@ This is not a fixed pipeline. Claude is the orchestrator — it decides what to| **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 — teach lint/enforce to stop repeating dismissed warnings |+| **Embeddings** | `embed`, `search`, `similarity` | Dual-space semantic search (text + Poincaré structural) || **Reasoning** | `reason` (rdfs, owl-rl, owl-rl-ext, owl-dl), `dl_explain`, `dl_check` | Native SHOIQ tableaux reasoner |All tools are available both as MCP tools (prefixed `onto_`) and as CLI subcommands.@@ -320,6 +321,26 @@ flowchart LR**Feedback** — Lint and enforce learn from your decisions. Dismiss a warning 3 times and it's suppressed; accept it once and it sticks. Same self-calibrating pattern used by `align` and `drift`.+### Semantic Embeddings (Poincaré Vector Store)++Open Ontologies includes a built-in dual-space vector store for semantic search and alignment:++- **Text embeddings** via ONNX model (bge-small-en-v1.5) — captures label/definition similarity+- **Structural embeddings** via Poincaré ball — captures hierarchy position (root classes near center, leaves near boundary)+- **Product search** — combines both spaces for best results++```text+onto_load → onto_embed → onto_search "domestic animal"+```++The embedding model (~33MB) is downloaded on `open-ontologies init`. All inference runs locally via tract (pure Rust ONNX runtime) — no API keys or external services needed.++| Tool | Purpose |+| ---- | ------- |+| `onto_embed` | Generate embeddings for all classes in the loaded ontology |+| `onto_search` | Semantic search by natural language query |+| `onto_similarity` | Compare two IRIs by embedding similarity |+### Schema AlignmentDetect `owl:equivalentClass`, `skos:exactMatch`, `rdfs:subClassOf` candidates between two ontologies using 6 weighted signals:@@ -525,7 +546,7 @@ flowchart TDStateDb["SQLite State"]end- subgraph Tools["39 Tools + 5 Prompts"]+ subgraph Tools["42 Tools + 5 Prompts"]direction LROntology["validate · load · query\nsave · diff · lint · convert"]Data["map · ingest · shacl\nreason · extend"]