# 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`