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
feat(embed): GenOM-style description-based embedding enrichment
FABIOTESS985861acc2ed
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 421d8a8b..e6a03437 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,7 @@ All notable changes to Open Ontologies are documented here.## [Unreleased]### Added+- **GenOM-style description-based embedding enrichment for `onto_embed`**. New optional `descriptions: HashMap<String, String>` field on `OntoEmbedInput`. When the map is supplied, each class IRI in the map is embedded from its description text instead of from its `rdfs:label`; IRIs absent from the map fall back to the existing label-based embedding. Returns a new `enriched: <count>` field alongside the existing `embedded: <count>` so callers can see how many classes used descriptions vs. labels. This is the MCP-native form of the GenOM pattern (Mensa et al. 2025, accepted World Wide Web Journal, which showed Qwen-32B-generated descriptions lift alignment F1 substantially over raw-label embedding): the server doesn't generate descriptions, the connected orchestrator (Claude) authors them in-conversation using its own reasoning, then passes them in via this field. Net new dependencies: zero. Behaviour with no `descriptions` map is identical to before (back-compat). New inline unit tests in `src/inputs.rs` cover the deserialization both with and without the field present.- **`ies-4.3.1` marketplace preset — frozen MIT baseline** (#25). New marketplace catalogue entry pointing at the archived `dstl/IES4` repo at tag `v4.3.1` (3 Mar 2025, MIT-licensed, last public release before the IES governance transition to DBT / IES-Org). Distinct from the existing `ies` preset (which tracks `IES-Org/ont-ies` main and shifts as upstream evolves) — use `ies-4.3.1` when you need a reproducible compliance baseline that won't drift. Source: 5,375-line Turtle artefact `ies4.ttl`, baseURI `http://ies.data.gov.uk/ontology/ies4`, the same namespace used by the existing `boro` and `ies4` enforce rule packs. Install via `onto_marketplace install ies-4.3.1`. Inline unit tests in `src/marketplace.rs` verify the URL pins to the `v4.3.1` tag (not `main`) and that the live `ies` and frozen `ies-4.3.1` presets coexist with distinct IDs and URLs.- **RRF (Reciprocal Rank Fusion) as an opt-in fusion strategy for `onto_align`**. New `OntoAlignInput.fusion` field accepts `"weighted_sum"` (default, unchanged behaviour with self-calibrating learned weights) or `"rrf"` (Cormack et al. SIGIR 2009 at k=60, validated for ontology alignment by Agent-OM at VLDB 2025). RRF is order-based rather than score-based, so it doesn't need feedback to bootstrap; it's a sensible cold-start choice when the `align_feedback` table is empty. The per-signal scores remain on each candidate's `signals` field so downstream `onto_align_feedback` calls keep working identically. New public method `AlignmentEngine::align_with_fusion(source, target, high, low, dry_run, fusion)`; the existing `align_with_thresholds(...)` and `align(...)` entry points are preserved as thin wrappers that pass `"weighted_sum"`. New `tests/align_rrf_test.rs` (5 tests) covering normalisation to [0, 1], per-signal preservation, low-threshold post-rerank filtering, weighted_sum back-compat, and weighted_sum/RRF top-pair agreement on perfect matches.- **`ies4` enforce rule pack** (#24). New built-in design-pattern pack for the [Information Exchange Standard](https://informationexchangestandard.org/), the UK cross-sector ontology framework custodied by Department for Business and Trade since March 2025 (canonical repo `IES-Org/ont-ies`). Three rules beyond the existing `boro` pack: (1) `ies4_particular_class_overlap` (severity: error) — a class cannot subclass both `ies:Particular` and `ies:ClassOfEntity`, as that violates the type-vs-token distinction foundational to IES4's 4D mereology; (2) `ies4_state_without_subject` (severity: warning) — a class subclassing `ies:State` must declare `ies:isStateOf` via owl:Restriction or have at least one instance using it (the state pattern is meaningless without a bearer); (3) `ies4_event_without_participant` (severity: warning) — a class subclassing `ies:Event` must have a participant pattern via `ies:isParticipantIn` / `ies:involvesParticipant` / `ies:hasParticipant` (events without participants are incomplete 4D models). Invoke via `onto_enforce` MCP tool or `enforce` CLI with `rule_pack = "ies4"`. Academic grounding: FOUST 7 paper "Comparing IES and BORO" (CEUR Vol-4176, JOWO 2024). New `tests/enforce_ies4_test.rs` (5 tests covering each rule's positive and negative cases, plus the instance-level participation accept path).diff --git a/src/inputs.rs b/src/inputs.rsindex 8af485f8..bbcef6fa 100644--- a/src/inputs.rs+++ b/src/inputs.rs@@ -436,6 +436,15 @@ pub struct OntoEmbedInput {pub struct_dim: Option<usize>,/// Structural training epochs. Default: 100pub struct_epochs: Option<usize>,+ /// Optional map from class IRI to a free-text description used for text-embedding+ /// in place of the class's rdfs:label. When set, classes present in the map are+ /// embedded from their description (richer semantic context); classes absent from+ /// the map fall back to the existing label-based embedding. This is the+ /// MCP-native form of the GenOM pattern (Mensa et al. 2025, accepted World Wide+ /// Web Journal): instead of the server calling an LLM to author descriptions, the+ /// connected orchestrator (Claude) authors them in-conversation and passes them+ /// in this map. Net new dependencies: zero.+ pub descriptions: Option<std::collections::HashMap<String, String>>,}#[derive(Deserialize, JsonSchema)]@@ -503,3 +512,35 @@ pub struct AlignOntologiesInput {/// Path to the target ontology filepub target_path: String,}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn onto_embed_input_accepts_optional_descriptions_map() {+ // GenOM enrichment: caller supplies {iri → description} mappings.+ // The input must deserialize when the map is provided.+ let json = serde_json::json!({+ "struct_dim": 32,+ "descriptions": {+ "http://ex.org/Cat": "A domestic feline, kept as a companion animal.",+ "http://ex.org/Dog": "A domestic canid, kept as a companion or working animal."+ }+ });+ let parsed: OntoEmbedInput = serde_json::from_value(json).expect("deserialize");+ let desc = parsed.descriptions.expect("descriptions field present");+ assert_eq!(desc.len(), 2);+ assert!(desc.get("http://ex.org/Cat").unwrap().contains("feline"));+ }++ #[test]+ fn onto_embed_input_descriptions_default_is_none() {+ // Existing callers that don't pass `descriptions` must still+ // deserialize correctly (back-compat).+ let json = serde_json::json!({});+ let parsed: OntoEmbedInput = serde_json::from_value(json).expect("deserialize");+ assert!(parsed.descriptions.is_none());+ assert!(parsed.struct_dim.is_none());+ }+}diff --git a/src/server.rs b/src/server.rsindex e3cbacea..22c7602d 100644--- a/src/server.rs+++ b/src/server.rs@@ -1486,10 +1486,23 @@ impl OpenOntologiesServer {let mut embedded_count = 0;let mut errors: Vec<String> = Vec::new();+ let mut enriched_count: usize = 0;for (iri, label) in &class_labels {+ // GenOM-style enrichment: if the caller supplied a description for this+ // IRI, embed THAT instead of the bare label. Descriptions carry richer+ // semantic context (definition prose, synonyms, role in the ontology),+ // which the GenOM paper showed lifts alignment F1 vs label-only embedding.+ let (text_to_embed, used_description) = match input+ .descriptions+ .as_ref()+ .and_then(|m| m.get(iri.as_str()))+ {+ Some(desc) if !desc.trim().is_empty() => (desc.as_str(), true),+ _ => (label.as_str(), false),+ };// Compute the text embedding (may await an HTTP call) BEFORE// locking the non-Send VecStore mutex.- match embedder.embed(label).await {+ match embedder.embed(text_to_embed).await {Ok(text_vec) => {let struct_vec = struct_embeddings.get(iri).cloned()@@ -1497,6 +1510,9 @@ impl OpenOntologiesServer {let mut vecstore = self.vecstore.lock().unwrap();vecstore.upsert(iri, &text_vec, &struct_vec);embedded_count += 1;+ if used_description {+ enriched_count += 1;+ }}Err(e) => errors.push(format!("{}: {}", iri, e)),}@@ -1512,6 +1528,7 @@ impl OpenOntologiesServer {serde_json::json!({"ok": true,"embedded": embedded_count,+ "enriched": enriched_count,"total_classes": class_labels.len(),"text_dim": embedder.dim(),"struct_dim": struct_dim,