Fix: redundancy

Author: mfortini

src/tools/group-g.ts

@@ -87,11 +87,16 @@ server.registerTool(
 - inheritedRange: range values from super-properties, each annotated with ancestor URI and label
 - effectiveDomain: deduplicated union of assertedDomain + inheritedDomain
 - effectiveRange: deduplicated union of assertedRange + inheritedRange
+- redundancy_analysis: diagnostic view of each asserted value:
+  - "redundant": identical to an inherited value — the axiom can be dropped without semantic loss
+  - "specialization": a rdfs:subClassOf of an inherited value — genuinely narrows the domain/range
+  - "new": not present in any inherited value — adds information not implied by the super-property chain
+  - summary counts per category for quick overview
 
 **Interpreting the output:**
 - If assertedDomain is empty but effectiveDomain is not → domain is inherited; no need to re-assert it on this property
 - If assertedDomain equals effectiveDomain → the domain is fully explicit, not relying on inheritance
-- If a property is asserted in the subproperty chain and the local TTL already re-asserts the same domain → that axiom is redundant
+- Use redundancy_analysis.summary to immediately see if the local TTL has redundant axioms or genuine specializations
 - owl:equivalentProperty and owl:equivalentClass expansions are not included (use query_sparql for those)`,
     inputSchema: {
       propertyUri: z.string().describe("URI of the property to inspect"),
@@ -194,6 +199,73 @@ server.registerTool(
         hasRangeLocally:  info.ranges.length  > 0,
       }));
 
+      // Redundancy analysis
+      type AnalysisEntry = {
+        value: string;
+        status: "redundant" | "specialization" | "new";
+        inherited_match?: string;
+        specializes?: string[];
+      };
+
+      const inheritedDomainValues = new Set(inheritedDomain.map(x => x.domain));
+      const inheritedRangeValues  = new Set(inheritedRange.map(x => x.range));
+
+      const classifyInitial = (asserted: string[], inheritedValues: Set<string>): AnalysisEntry[] =>
+        asserted.map(v => inheritedValues.has(v)
+          ? { value: v, status: "redundant" as const, inherited_match: v }
+          : { value: v, status: "new" as const }
+        );
+
+      let domainAnalysis = classifyInitial(assertedDomain, inheritedDomainValues);
+      let rangeAnalysis  = classifyInitial(assertedRange,  inheritedRangeValues);
+
+      // Subclass check for "new" candidates → may be specializations
+      const domainCandidates = domainAnalysis.filter(e => e.status === "new").map(e => e.value);
+      const rangeCandidates  = rangeAnalysis.filter(e => e.status === "new").map(e => e.value);
+      const allCandidates    = [...new Set([...domainCandidates, ...rangeCandidates])];
+      const allInherited     = [...new Set([...inheritedDomainValues, ...inheritedRangeValues])];
+
+      if (allCandidates.length > 0 && allInherited.length > 0) {
+        const vSub = allCandidates.map(u => `<${u}>`).join(" ");
+        const vSup = allInherited.map(u => `<${u}>`).join(" ");
+        const subResult = await executeSparql(`
+          SELECT ?sub ?sup WHERE {
+            VALUES ?sub { ${vSub} }
+            VALUES ?sup { ${vSup} }
+            ?sub rdfs:subClassOf+ ?sup .
+          }
+        `);
+        const subMap = new Map<string, string[]>();
+        for (const b of subResult.results?.bindings ?? []) {
+          const sub = b.sub?.value ?? "", sup = b.sup?.value ?? "";
+          if (!sub || !sup) continue;
+          if (!subMap.has(sub)) subMap.set(sub, []);
+          subMap.get(sub)!.push(sup);
+        }
+        const upgrade = (entries: AnalysisEntry[], inheritedValues: Set<string>): AnalysisEntry[] =>
+          entries.map(e => {
+            if (e.status !== "new") return e;
+            const supers = (subMap.get(e.value) ?? []).filter(s => inheritedValues.has(s));
+            return supers.length > 0 ? { value: e.value, status: "specialization" as const, specializes: supers } : e;
+          });
+        domainAnalysis = upgrade(domainAnalysis, inheritedDomainValues);
+        rangeAnalysis  = upgrade(rangeAnalysis,  inheritedRangeValues);
+      }
+
+      const count = (entries: AnalysisEntry[], s: string) => entries.filter(e => e.status === s).length;
+      const redundancy_analysis = {
+        domain: domainAnalysis,
+        range:  rangeAnalysis,
+        summary: {
+          domain_redundant:      count(domainAnalysis, "redundant"),
+          domain_specialization: count(domainAnalysis, "specialization"),
+          domain_new:            count(domainAnalysis, "new"),
+          range_redundant:       count(rangeAnalysis,  "redundant"),
+          range_specialization:  count(rangeAnalysis,  "specialization"),
+          range_new:             count(rangeAnalysis,  "new"),
+        },
+      };
+
       const totalRows =
         (defResult.results?.bindings?.length ?? 0) +
         (superResult.results?.bindings?.length ?? 0);
@@ -210,6 +282,7 @@ server.registerTool(
           inheritedRange,
           effectiveDomain,
           effectiveRange,
+          redundancy_analysis,
         },
         rowCount: totalRows,
       };

src/tools/group-k.ts

@@ -150,10 +150,14 @@ server.registerTool(
     title: "Inspect Concept in Local / Uploaded Ontology",
     description: `Get a full profile of a class or concept from a local or uploaded ontology.
 
-**Args (provide exactly one of file_path or upload_id):**
+**CRITICAL — file access workflow:**
+1. Try \`file_path\` first (works only if the file is readable by the MCP server process).
+2. If file_path fails for any reason → call \`get_upload_instructions\` with the local path, execute the returned curl command via Bash tool, parse the \`id\` from the JSON response, then call this tool again with \`upload_id\`.
+3. NEVER read the file content and pass it through the conversation. NEVER attempt to parse or analyse the TTL text manually. The upload workflow sends raw bytes directly from disk to server without the AI ever seeing the content — it is always faster, cheaper, and more reliable.
+
+**Args:**
 - uri: URI of the class/concept to inspect
-- file_path: Absolute path on the MCP server filesystem
-- upload_id: UUID returned by POST /upload (HTTP/remote mode)
+- file_path / upload_id: exactly one (see workflow above)
 - mode: "raw" | "effective" (default: "effective")
 
 **mode: "raw"** — only triples explicitly present in the local file:
@@ -175,8 +179,8 @@ server.registerTool(
 **Unicode SPARQL note:** oxigraph rejects prefixed names with non-ASCII local parts (e.g. \`myont:modalità_cup\`). Always use full URIs in angle brackets (\`<https://...#modalità_cup>\`) for properties or classes with Unicode in the local name.`,
     inputSchema: {
       uri: z.string().describe("URI of the class or concept to inspect"),
-      file_path: z.string().optional().describe("Absolute path to the ontology file on the server filesystem"),
-      upload_id: z.string().optional().describe("Upload UUID returned by POST /upload (HTTP mode)"),
+      file_path: z.string().optional().describe("Absolute path readable by the MCP server process. If this fails, do NOT read the file — use get_upload_instructions + Bash curl + upload_id instead."),
+      upload_id: z.string().optional().describe("UUID from POST /upload. Preferred when the file is on the client machine or file_path failed."),
       mode: z.enum(["raw", "effective"]).optional().default("effective").describe(
         '"raw": only asserted triples (own_properties, no ancestor traversal). ' +
         '"effective" (default): adds inherited_properties via rdfs:subClassOf+/skos:broader+ and data-level incoming/outgoing.'
@@ -290,10 +294,10 @@ server.registerTool(
     title: "Inspect Property in Local / Uploaded Ontology",
     description: `Get the full semantic profile of a property from a local or uploaded ontology, resolving inherited domain and range via rdfs:subPropertyOf+.
 
-**Args (provide exactly one of file_path or upload_id):**
-- uri: URI of the property to inspect
-- file_path: Absolute path on the MCP server filesystem
-- upload_id: UUID returned by POST /upload (HTTP mode)
+**CRITICAL — file access workflow:**
+1. Try \`file_path\` first (works only if the file is readable by the MCP server process).
+2. If file_path fails for any reason → call \`get_upload_instructions\` with the local path, execute the returned curl command via Bash tool, parse the \`id\` from the JSON response, then call this tool again with \`upload_id\`.
+3. NEVER read the file content and pass it through the conversation. NEVER attempt to parse or analyse the TTL text manually. The upload workflow sends raw bytes directly from disk to server without the AI ever seeing the content — it is always faster, cheaper, and more reliable.
 
 **Returns:**
 - definition: direct attributes from the local store (type, label, comment, subPropertyOf, inverseOf, functional flags)
@@ -307,6 +311,11 @@ server.registerTool(
 - inheritedRange: range values collected from super-properties, each annotated with ancestor URI and source
 - effectiveDomain: deduplicated union of assertedDomain + inheritedDomain
 - effectiveRange: deduplicated union of assertedRange + inheritedRange
+- redundancy_analysis: diagnostic view of each asserted value:
+  - "redundant": identical to an inherited value — the axiom can be dropped without semantic loss
+  - "specialization": a rdfs:subClassOf of an inherited value — genuinely narrows the domain/range
+  - "new": not present in any inherited value — adds information not implied by the super-property chain
+  - summary counts per category for quick overview
 - warnings: super-properties not resolved, remote lookup failures
 
 **owl:imports handling:** The local store typically does NOT contain imported ontologies (owl:imports declarations are not followed automatically). Super-properties from external namespaces (e.g. l0:name, l0:description from OntoPiA) are resolved against schema.gov.it automatically, making the effective semantics complete without requiring the full import chain to be loaded.
@@ -316,8 +325,8 @@ server.registerTool(
 **Unicode SPARQL note:** oxigraph rejects prefixed names with non-ASCII local parts. For properties with Unicode in the local name (e.g. \`myont:modalità_cup\`), always pass the full URI in angle brackets (\`<https://...#modalità_cup>\`).`,
     inputSchema: {
       uri: z.string().describe("URI of the property to inspect"),
-      file_path: z.string().optional().describe("Absolute path to the ontology file on the server filesystem"),
-      upload_id: z.string().optional().describe("Upload UUID returned by POST /upload (HTTP mode)"),
+      file_path: z.string().optional().describe("Absolute path readable by the MCP server process. If this fails, do NOT read the file — use get_upload_instructions + Bash curl + upload_id instead."),
+      upload_id: z.string().optional().describe("UUID from POST /upload. Preferred when the file is on the client machine or file_path failed."),
     },
     annotations: {
       readOnlyHint: true,
@@ -448,6 +457,73 @@ server.registerTool(
         hasRangeLocally:  info.localRanges.length  > 0,
       }));
 
+      // 7. Redundancy analysis
+      type AnalysisEntry = {
+        value: string;
+        status: "redundant" | "specialization" | "new";
+        inherited_match?: string;
+        specializes?: string[];
+      };
+
+      const inheritedDomainValues = new Set(inheritedDomain.map(x => x.domain));
+      const inheritedRangeValues  = new Set(inheritedRange.map(x => x.range));
+
+      const classifyInitial = (asserted: string[], inheritedValues: Set<string>): AnalysisEntry[] =>
+        asserted.map(v => inheritedValues.has(v)
+          ? { value: v, status: "redundant" as const, inherited_match: v }
+          : { value: v, status: "new" as const }
+        );
+
+      let domainAnalysis = classifyInitial(assertedDomain, inheritedDomainValues);
+      let rangeAnalysis  = classifyInitial(assertedRange,  inheritedRangeValues);
+
+      // Subclass check for "new" candidates → may be specializations
+      const domainCandidates = domainAnalysis.filter(e => e.status === "new").map(e => e.value);
+      const rangeCandidates  = rangeAnalysis.filter(e => e.status === "new").map(e => e.value);
+      const allCandidates    = [...new Set([...domainCandidates, ...rangeCandidates])];
+      const allInherited     = [...new Set([...inheritedDomainValues, ...inheritedRangeValues])];
+
+      if (allCandidates.length > 0 && allInherited.length > 0) {
+        const vSub = allCandidates.map(u => `<${u}>`).join(" ");
+        const vSup = allInherited.map(u => `<${u}>`).join(" ");
+        const subResult = runLocalSparql(store, `
+          SELECT ?sub ?sup WHERE {
+            VALUES ?sub { ${vSub} }
+            VALUES ?sup { ${vSup} }
+            ?sub rdfs:subClassOf+ ?sup .
+          }
+        `, true);
+        const subMap = new Map<string, string[]>();
+        for (const b of subResult.results.bindings) {
+          const sub = b.sub?.value ?? "", sup = b.sup?.value ?? "";
+          if (!sub || !sup) continue;
+          if (!subMap.has(sub)) subMap.set(sub, []);
+          subMap.get(sub)!.push(sup);
+        }
+        const upgrade = (entries: AnalysisEntry[], inheritedValues: Set<string>): AnalysisEntry[] =>
+          entries.map(e => {
+            if (e.status !== "new") return e;
+            const supers = (subMap.get(e.value) ?? []).filter(s => inheritedValues.has(s));
+            return supers.length > 0 ? { value: e.value, status: "specialization" as const, specializes: supers } : e;
+          });
+        domainAnalysis = upgrade(domainAnalysis, inheritedDomainValues);
+        rangeAnalysis  = upgrade(rangeAnalysis,  inheritedRangeValues);
+      }
+
+      const count = (entries: AnalysisEntry[], s: string) => entries.filter(e => e.status === s).length;
+      const redundancy_analysis = {
+        domain: domainAnalysis,
+        range:  rangeAnalysis,
+        summary: {
+          domain_redundant:      count(domainAnalysis, "redundant"),
+          domain_specialization: count(domainAnalysis, "specialization"),
+          domain_new:            count(domainAnalysis, "new"),
+          range_redundant:       count(rangeAnalysis,  "redundant"),
+          range_specialization:  count(rangeAnalysis,  "specialization"),
+          range_new:             count(rangeAnalysis,  "new"),
+        },
+      };
+
       return {
         success: true,
         data: {
@@ -459,6 +535,7 @@ server.registerTool(
           inheritedRange,
           effectiveDomain,
           effectiveRange,
+          redundancy_analysis,
           ...(warnings.length > 0 ? { warnings } : {}),
         },
         rowCount: defResult.results.bindings.length + superResult.results.bindings.length,