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):

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)

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):

{
  "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)

python classify.py --ecp examples/ecp_volkswagen.json --content examples/content_northvolt_de.md

Expected Output (stdout):

{
  "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)

python classify.py --ecp examples/ecp_apple.json --content examples/content_tangential_es.md

Expected Output:

{
  "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:

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

3.2 KiB Raw Blame History Unescape Escape