110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
# 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`
|