116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# CLI Interface Contract: Article Consolidation and Hygiene Runtime
|
|
|
|
**Feature Branch**: `006-article-consolidation-runtime`
|
|
**Date**: 2026-08-23
|
|
**Contract Version**: `1.0.0`
|
|
**Status**: Complete
|
|
|
|
---
|
|
|
|
## 1. Invocation Model
|
|
|
|
The runtime executes as a single-article ephemeral Python CLI command. It processes exactly one article input payload and one ECP profile snapshot per invocation, writing output artifacts and state atomically based on paths declared in the versioned configuration, and exiting cleanly with standard exit codes.
|
|
|
|
---
|
|
|
|
## 2. Command Synopsis
|
|
|
|
### 2.1 Main Consolidation Command
|
|
|
|
```bash
|
|
python -m src.cli.consolidate \
|
|
--input-article <path/to/article.json> \
|
|
--ecp-snapshot <path/to/ecp_snapshot.json> \
|
|
--config <path/to/runtime_config.json>
|
|
```
|
|
|
|
### 2.2 Operational Commands
|
|
|
|
```bash
|
|
# Preflight Validation
|
|
python -m src.cli.preflight --config <path/to/runtime_config.json>
|
|
|
|
# Smoke Test
|
|
python -m src.cli.smoke --config <path/to/runtime_config.json> --fixture <path/to/fixture.json>
|
|
|
|
# Reconcile State & Telemetry
|
|
python -m src.cli.reconcile --config <path/to/runtime_config.json>
|
|
|
|
# Resend Pending Telemetry
|
|
python -m src.cli.telemetry_flush --config <path/to/runtime_config.json>
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Options & Arguments
|
|
|
|
### `src.cli.consolidate`
|
|
|
|
| Option | Flag | Type | Required | Description |
|
|
|:---|:---|:---|:---|:---|
|
|
| `--input-article` | `-i` | File Path | Yes | Path to single-article JSON input unit |
|
|
| `--ecp-snapshot` | `-e` | File Path | Yes | Path to canonical ECP profile snapshot JSON |
|
|
| `--config` | `-c` | File Path | Yes | Path to approved runtime configuration file |
|
|
|
|
### `src.cli.smoke`
|
|
|
|
| Option | Flag | Type | Required | Description |
|
|
|:---|:---|:---|:---|:---|
|
|
| `--config` | `-c` | File Path | Yes | Path to approved runtime configuration file |
|
|
| `--fixture` | `-f` | File Path | Yes | Path to smoke test input fixture JSON |
|
|
|
|
### `src.cli.preflight` / `reconcile` / `telemetry_flush`
|
|
|
|
| Option | Flag | Type | Required | Description |
|
|
|:---|:---|:---|:---|:---|
|
|
| `--config` | `-c` | File Path | Yes | Path to approved runtime configuration file |
|
|
|
|
*Note on Paths & Options*: All persistence paths (output directory, SQLite database) belong strictly to the versioned configuration file to prevent discrepancies with the deterministic execution fingerprint.
|
|
|
|
---
|
|
|
|
## 4. Exit Codes
|
|
|
|
| Code | Meaning | Description |
|
|
|:---|:---|:---|
|
|
| `0` | Success / Handled Rejection | Article successfully processed (`completed_text` or `rejected_ecp`). |
|
|
| `1` | Input Article / ECP Error | Input article or ECP schema failed local validation (`failed_validation`). |
|
|
| `2` | Configuration / Preflight Error | Preflight verification failed, config hash mismatch, missing credentials, or invalid config file. |
|
|
| `3` | Processing Failure | LLM hygiene, enrichment, or gateway fallback failed (`failed_processing`). |
|
|
| `4` | Persistence Failure | File write, rename, or SQLite lock timeout failed. |
|
|
|
|
---
|
|
|
|
## 5. Output Protocol
|
|
|
|
### 5.1 stdout (Machine-Readable JSON)
|
|
Every execution emits a single structured JSON object on stdout:
|
|
|
|
1. **`consolidate` (Fingerprint Established)**: Emits the complete manifest JSON complying with [`manifest-output.schema.json`](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/006-article-consolidation-runtime/contracts/manifest-output.schema.json).
|
|
2. **`consolidate` (Article Validation Failure before Fingerprint)**: Emits a structured article failure JSON (Exit Code `1`):
|
|
```json
|
|
{
|
|
"status": "failed_validation",
|
|
"error_codes": ["INVALID_ARTICLE_SCHEMA"],
|
|
"message": "Input article payload contains unparseable JSON or schema violation"
|
|
}
|
|
```
|
|
3. **Configuration / Preflight Failure (Exit Code `2`)**: Emits a technical configuration envelope (without inventing article error codes):
|
|
```json
|
|
{
|
|
"status": "configuration_error",
|
|
"config_error_code": "CONFIG_HASH_MISMATCH",
|
|
"message": "Runtime configuration SHA-256 does not match certified release-metadata.json"
|
|
}
|
|
```
|
|
4. **Operational Commands**: Emit their specific structured JSON reports (Exit Code `0` on success, `2` on failure):
|
|
- `preflight`: `{ "status": "ok", "config_version": "1.0.0", "certified_hash_match": true, "checks": [...] }`
|
|
- `smoke`: `{ "status": "ok", "fingerprint": "...", "duration_ms": 124.5 }`
|
|
- `reconcile`: `{ "status": "ok", "reconciled_articles": 0, "fixed_states": 0 }`
|
|
- `telemetry_flush`: `{ "status": "ok", "flushed_events": 5, "remaining_pending": 0 }`
|
|
|
|
### 5.2 stderr (Sanitized Technical Logs)
|
|
Emits structured JSON log lines containing timestamps, log levels, event codes, error details, and trace correlation IDs.
|
|
- **Structural Sanitization**: Strips HTTP `Authorization`, `Proxy-Authorization`, `X-Api-Key` headers, and token query parameters.
|
|
- **Exact Token Replacement**: Replaces exact string values of all loaded environment secrets (`GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `LANGFUSE_SECRET_KEY`) with `[REDACTED]`.
|