# CLI Contract & Interface Specification (POC)

**Feature**: `001-multilingual-entity-classifier`
**Status**: Completed

---

## 1. Command Line Interface

```bash
python classify.py --ecp <path-to-ecp.json> --content <path-to-content.md> [--output <path-to-result.json>] [--enable-embeddings] [--enable-llm]
```

### 1.1 Arguments & Options

| Parameter | Type | Required | Description |
|---|---|---|---|
| `--ecp` | Path (`string`) | **Yes** | Absolute or relative path to the ECP Snapshot JSON file |
| `--content` | Path (`string`) | **Yes** | Absolute or relative path to the Markdown content file |
| `--output`, `-o` | Path (`string`) | No | Destination path to write result JSON. If omitted, prints JSON to `stdout`. |
| `--enable-embeddings` | Flag (`bool`) | No | Enables Tier 2 local multilingual vector similarity adapter (default: false). |
| `--enable-llm` | Flag (`bool`) | No | Enables Tier 3 LLM fallback adapter for ambiguous cases (default: false). |
| `--version`, `-v` | Flag (`bool`) | No | Displays version and exits. |
| `--help`, `-h` | Flag (`bool`) | No | Displays help message. |

---

## 2. Standard Streams & Exit Codes

### 2.1 Exit Codes

- `0`: Success (classification completed normally, result JSON written to file or stdout).
- `1`: Validation / Processing Error (invalid arguments, malformed input, missing fields, structured error JSON printed to stderr or output file).

### 2.2 Standard Output (`stdout`) / Standard Error (`stderr`)

- If `--output` is provided:
  - Success result is saved to the specified file.
  - On error, error JSON is written to the output file (if accessible) and emitted to `stderr`.
- If `--output` is NOT provided:
  - On success: formatted JSON is printed directly to `stdout`.
  - On error: structured error JSON is printed to `stderr`.