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,109 @@
+# Quickstart & Validation Guide (POC)
+
+**Feature**: `001-multilingual-entity-classifier`
+**Status**: Completed
+
+---
+
+## 1. Prerequisites & Installation
+
+- Python 3.10+
+- Virtual environment (optional, standard library only for Tier 1):
+  ```bash
+  python -m venv .venv
+  .venv\Scripts\activate   # Windows
+  # source .venv/bin/activate # Linux/Mac
+  pip install pytest
+  ```
+
+---
+
+## 2. Basic CLI Usage Examples
+
+### 2.1 Direct Inherence (Portuguese)
+```bash
+python classify.py --ecp examples/ecp_petrobras.json --content examples/content_presal_pt.md --output out/petrobras_result.json
+```
+
+**Expected Output (`out/petrobras_result.json`)**:
+```json
+{
+  "decision": "DIRECT_INHERENT",
+  "is_inherent": true,
+  "confidence": 0.95,
+  "detected_language": "pt",
+  "matched_anchors": ["Petrobras", "Petróleo Brasileiro S.A.", "pré-sal"],
+  "negative_matches": [],
+  "graph_matches": [],
+  "evidence": ["...a Petrobras anunciou ampliação da produção na camada pré-sal..."],
+  "rationale": "Direct match of target entity aliases with high contextual anchor density.",
+  "warnings": []
+}
+```
+
+### 2.2 Contextual Inherence via Graph Snapshot (German)
+```bash
+python classify.py --ecp examples/ecp_volkswagen.json --content examples/content_northvolt_de.md
+```
+
+**Expected Output (`stdout`)**:
+```json
+{
+  "decision": "CONTEXTUAL_INHERENT",
+  "is_inherent": true,
+  "confidence": 0.88,
+  "detected_language": "de",
+  "matched_anchors": [],
+  "negative_matches": [],
+  "graph_matches": [
+    {
+      "entity_id": "ent_northvolt",
+      "name": "Northvolt",
+      "relation_type": "SUPPLIER_OF",
+      "weight": 0.85
+    }
+  ],
+  "evidence": ["...Northvolt liefert Batteriezellen für europäische Elektrofahrzeuge..."],
+  "rationale": "Matched connected entity Northvolt from ECP snapshot with strong supplier relationship to Volkswagen.",
+  "warnings": []
+}
+```
+
+### 2.3 Tangential Mention (Spanish)
+```bash
+python classify.py --ecp examples/ecp_apple.json --content examples/content_tangential_es.md
+```
+
+**Expected Output**:
+```json
+{
+  "decision": "TANGENTIAL",
+  "is_inherent": false,
+  "confidence": 0.35,
+  "detected_language": "es",
+  "matched_anchors": ["Apple"],
+  "negative_matches": [],
+  "graph_matches": [],
+  "evidence": ["...el dilema fue como la manzana de la discordia en la reunión..."],
+  "rationale": "Single passing mention without supporting tech domain anchors or entity context.",
+  "warnings": ["Low contextual density for target entity."]
+}
+```
+
+---
+
+## 3. Running the Controlled 24-Case Benchmark
+
+Execute the automated test suite measuring classification precision across all 6 languages and 4 decision types:
+
+```bash
+pytest tests/test_benchmark_24.py -v
+```
+
+**Benchmark Matrix (6 × 4 = 24 test pairs)**:
+- 🇧🇷 **Portuguese (`pt`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`
+- 🇺🇸 **English (`en`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`
+- 🇪🇸 **Spanish (`es`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`
+- 🇩🇪 **German (`de`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`
+- 🇮🇹 **Italian (`it`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`
+- 🇫🇷 **French (`fr`)**: `DIRECT`, `CONTEXTUAL`, `TANGENTIAL`, `NOT_RELATED`