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: add embedding tools to workflow documentation

FABIOTESS48654b9bbcc8
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 57b8b474..e927afa7 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
[![ClawHub Skill](https://img.shields.io/badge/ClawHub-open--ontologies-7c3aed)](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 Alignment
Detect `owl:equivalentClass`, `skos:exactMatch`, `rdfs:subClassOf` candidates between two ontologies using 6 weighted signals:
@@ -525,7 +546,7 @@ flowchart TD
StateDb["SQLite State"]
end
- subgraph Tools["39 Tools + 5 Prompts"]
+ subgraph Tools["42 Tools + 5 Prompts"]
direction LR
Ontology["validate · load · query\nsave · diff · lint · convert"]
Data["map · ingest · shacl\nreason · extend"]