TextNLPClassifierApp/specs/006-article-consolidation-runtime/quickstart.md

Quickstart Guide: Article Consolidation and Hygiene Runtime

Feature Branch: 006-article-consolidation-runtime
Date: 2026-08-23
Status: Complete

---

1. Prerequisites & Environment Setup

The runtime is built using the repository's standard Python packaging defined in pyproject.toml (requires-python = ">=3.10").

Installation

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # ou .venv\Scripts\activate

# Install package and dependencies in editable mode
pip install -e .

Environment Secrets

Set provider credentials and Langfuse secrets via environment variables:

# Model Gateway Provider Keys
export GROQ_API_KEY="gsk_samplekey1234567890abcdef"
export DEEPSEEK_API_KEY="sk_samplekey1234567890abcdef"

# Observability
export LANGFUSE_PUBLIC_KEY="pk-lf-samplepublickey123456"
export LANGFUSE_SECRET_KEY="sk-lf-samplesecretkey123456"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

---

2. Local Validation Configuration (Fixture Only)

Note

The configuration below is a local development fixture (runtime_config.local.json), certified against packaged src/core/release-metadata.json. Timeouts, retries, pricing, and limits shown here are exclusive to local testing fixtures and do not represent production calibrated defaults.

{
  "config_version": "1.0.0",
  "paths": {
    "output_dir": "./out",
    "sqlite_db": "./out/runtime_state.db"
  },
  "roles": {
    "runtime_primary": {
      "role_config_version": "1.0.0",
      "provider": "groq",
      "model": "openai/gpt-oss-20b",
      "endpoint_url": "https://api.groq.com/openai/v1/chat/completions",
      "timeout_seconds": 15,
      "max_retries": 2,
      "parameters": { "temperature": 0.0 },
      "hygiene_prompt_version": "1.0.0",
      "hygiene_schema_version": "1.0.0",
      "enrichment_prompt_version": "1.0.0",
      "enrichment_schema_version": "1.0.0"
    },
    "runtime_fallback": {
      "role_config_version": "1.0.0",
      "provider": "deepseek",
      "model": "deepseek-v4-flash",
      "endpoint_url": "https://api.deepseek.com/v1/chat/completions",
      "timeout_seconds": 15,
      "max_retries": 2,
      "parameters": { "temperature": 0.0 },
      "hygiene_prompt_version": "1.0.0",
      "hygiene_schema_version": "1.0.0",
      "enrichment_prompt_version": "1.0.0",
      "enrichment_schema_version": "1.0.0"
    }
  },
  "prompts": {
    "article_content_hygiene": {
      "path": "prompts/article_content_hygiene.v1.txt",
      "version": "1.0.0",
      "hash": "f8a9c2b1d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
    },
    "article_sentiment_tags": {
      "path": "prompts/article_sentiment_tags.v1.txt",
      "version": "1.0.0",
      "hash": "d4e1b7a2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
    }
  },
  "ecp": {
    "canonical_schema_reference": "src/adapters/ecp/schemas/ecp-profile.schema.json",
    "classifier_module": "src.classifier.InherenceClassifier"
  },
  "limits": {
    "max_input_bytes": 5242880,
    "context_strategy": "fail_before_provider"
  },
  "pricing": {
    "primary_input_1k": 0.0001,
    "primary_output_1k": 0.0002,
    "fallback_input_1k": 0.0001,
    "fallback_output_1k": 0.0002
  },
  "langfuse": {
    "environment": "local_dev",
    "trace_content_policy": "metadata_only"
  },
  "sqlite": {
    "busy_timeout_ms": 5000
  }
}

---

3. Operational Execution Scenarios

Scenario A: Preflight Validation

Validates local configuration file exact byte hash against packaged src/core/release-metadata.json, prompt file hashes, schema compatibility, filesystem permissions, clock sync, and validated credentials before accepting live traffic.

python -m src.cli.preflight --config runtime_config.local.json

Expected Outcome: Exit code 0, structured JSON confirmation on stdout that all preflight checks passed.

---

Scenario B: End-to-End Processing (Approved Article)

Executes consolidation on an article with direct ECP inherence.

python -m src.cli.consolidate \
  --input-article examples/sample_article_valid.json \
  --ecp-snapshot examples/sample_ecp_snapshot.json \
  --config runtime_config.local.json

Expected Outcome:

• Exit code 0.
• Output manifest ./out/<fingerprint>.result.json created with final_status: "completed_text" and generate_markdown: true.
• Published Markdown ./out/<fingerprint>.md created with YAML front matter.
• SQLite state table updated to completed_text.
• stdout emits the complete JSON manifest matching manifest-output.schema.json.

---

Scenario C: ECP Rejection (Zero Markdown)

Executes consolidation on a non-inherent article (TANGENTIAL or NOT_RELATED).

python -m src.cli.consolidate \
  --input-article examples/sample_article_tangential.json \
  --ecp-snapshot examples/sample_ecp_snapshot.json \
  --config runtime_config.local.json

Expected Outcome:

• Exit code 0.
• Manifest ./out/<fingerprint>.result.json created with final_status: "rejected_ecp" and generate_markdown: false.
• Zero <fingerprint>.md file created for this execution fingerprint.
• SQLite state table updated to ecp_rejected.
• stdout emits the complete JSON manifest matching manifest-output.schema.json.

---

Scenario D: Idempotent Execution & Replay

Re-executes the command on a previously completed article fingerprint.

python -m src.cli.consolidate \
  --input-article examples/sample_article_valid.json \
  --ecp-snapshot examples/sample_ecp_snapshot.json \
  --config runtime_config.local.json

Expected Outcome:

• Immediate return without re-invoking LLM providers.
• Output JSON manifest on stdout matches previously persisted result.

---

4. Automated Quality Evaluation & Test Commands

# 1. Run static multi-parser zero-regex check (Python AST + JSON pattern check + Promptfoo YAML check)
python -m tests.scripts.check_zero_regex

# 2. Run unit and all 9 contract tests (including the 20 real reference units)
pytest tests/unit tests/contract -v

# 3. Run security tests (SEC-001 to SEC-008)
pytest tests/security -v

# 4. Run load test (100 articles/hour benchmark)
pytest tests/load -v

# 5. Run mock integration tests, fault injection (10 scenarios), and operations resilience (FR-081)
pytest tests/integration tests/fault_injection -v

# 6. Run offline Promptfoo evaluations
npx promptfoo eval -c evals/promptfoo.config.yaml