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.

feat(embed): GenOM-style description-based embedding enrichment

FABIOTESS985861acc2ed
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.rs
index 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: 100
pub 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 file
pub 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.rs
index 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,