feat(classifier): add multilingual ECP inherence classifier POC

2026-08-20 00:51:02 -03:00
parent d371b81aa4
commit 67cc40f91a
175 changed files with 30399 additions and 703 deletions
@@ -0,0 +1,205 @@
+# Data Models & Schemas (POC)
+
+**Feature**: `001-multilingual-entity-classifier`
+**Status**: Completed
+
+---
+
+## 1. Input Schemas
+
+### 1.1 ECP Snapshot Schema (`snapshot.json`)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ECPSnapshot",
+  "type": "object",
+  "required": [
+    "target_entity_id",
+    "target_name",
+    "aliases",
+    "domain",
+    "anchors"
+  ],
+  "properties": {
+    "target_entity_id": {
+      "type": "string",
+      "description": "Unique identifier of the entity"
+    },
+    "target_name": {
+      "type": "string",
+      "description": "Canonical name of the entity"
+    },
+    "aliases": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Multilingual aliases, acronyms, and trade names"
+    },
+    "domain": {
+      "type": "string",
+      "description": "Primary industry, category, or domain of the entity"
+    },
+    "anchors": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Key domain concepts, topics, and contextual keywords"
+    },
+    "negative_anchors": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "Homonym disambiguators or exclusion terms"
+    },
+    "graph_version": {
+      "type": "string",
+      "default": "1.0.0",
+      "description": "Version timestamp or hash of the source graph"
+    },
+    "related_entities": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "required": ["entity_id", "name", "relation_type", "weight"],
+        "properties": {
+          "entity_id": { "type": "string" },
+          "name": { "type": "string" },
+          "aliases": { "type": "array", "items": { "type": "string" }, "default": [] },
+          "relation_type": { "type": "string" },
+          "weight": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
+          "scope": { "type": "string", "default": "general" },
+          "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0, "default": 1.0 }
+        }
+      }
+    }
+  }
+}
+```
+
+### 1.2 Content Item Schema (`content.md`)
+
+- **Format**: Plain Markdown document (`.md` or `.txt`).
+- **Validation Rules**:
+  - Must not be empty (minimum 5 non-whitespace characters).
+  - Must contain readable text in UTF-8 encoding.
+
+---
+
+## 2. Output Schemas
+
+### 2.1 Classification Success Result Schema (`result.json`)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ClassificationResult",
+  "type": "object",
+  "required": [
+    "decision",
+    "is_inherent",
+    "confidence",
+    "detected_language",
+    "matched_anchors",
+    "negative_matches",
+    "graph_matches",
+    "evidence",
+    "rationale",
+    "warnings"
+  ],
+  "properties": {
+    "decision": {
+      "type": "string",
+      "enum": [
+        "DIRECT_INHERENT",
+        "CONTEXTUAL_INHERENT",
+        "TANGENTIAL",
+        "NOT_RELATED"
+      ]
+    },
+    "is_inherent": {
+      "type": "boolean",
+      "description": "Derived: true if DIRECT_INHERENT or CONTEXTUAL_INHERENT; false if TANGENTIAL or NOT_RELATED"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Normalized confidence score of the classification"
+    },
+    "detected_language": {
+      "type": "string",
+      "description": "Detected ISO-639-1 code (pt, en, es, de, it, fr, etc.)"
+    },
+    "matched_anchors": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Entity aliases and direct anchors identified in text"
+    },
+    "negative_matches": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Negative anchors found in text"
+    },
+    "graph_matches": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "entity_id": { "type": "string" },
+          "name": { "type": "string" },
+          "relation_type": { "type": "string" },
+          "weight": { "type": "number" }
+        }
+      },
+      "description": "Related entities from snapshot matched in text"
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Extracted textual snippets from Markdown justifying the decision"
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Concise explanation of the classification verdict"
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Non-fatal warnings encountered during processing"
+    }
+  }
+}
+```
+
+### 2.2 Error Result Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ClassificationError",
+  "type": "object",
+  "required": [
+    "error_code",
+    "message",
+    "details"
+  ],
+  "properties": {
+    "error_code": {
+      "type": "string",
+      "enum": [
+        "invalid_ecp_json",
+        "invalid_markdown",
+        "unsupported_language",
+        "empty_content",
+        "missing_required_field"
+      ]
+    },
+    "message": {
+      "type": "string"
+    },
+    "details": {
+      "type": "object"
+    }
+  }
+}
+```