TextNLPClassifierApp/specs/001-multilingual-entity-classifier/contracts/cli-contract.md

CLI Contract & Interface Specification (POC)

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

---

1. Command Line Interface

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.