# 📖 Technical Glossary: AI Watcher CLI Wrapper This glossary defines key software engineering, AI, and FinOps concepts used throughout **Project 3: Wrapper CLI**. --- ## 🛠️ Software Engineering & CLI Concepts ### Engineering Blueprint Reuse The practice of reusing a proven infrastructure baseline (configuration files, linting, CI/CD) as a standardized starting point for new projects, thus avoiding the need to recreate the initial setup. ### Unified Command Interface Automation design pattern where a single central file (Makefile) acts as the unified entrypoint for all operational tasks (build, lint, test, run, docker), abstracting away toolchain specifics. ### Single Responsibility Principle (SRP) A software design principle (the "S" in SOLID) stating that a class, module, or file should have only one reason to change, promoting code modularity and testability. ### 12-Factor App (Methodology) A set of 12 best practices for building modern web or CLI applications. The rule regarding configuration requires strict separation between source code and configuration (which varies across environments), with the latter being stored in environment variables. ### detect-secrets A security tool (often used as a pre-commit hook) developed by Yelp. It uses heuristics and entropy to scan source code before committing, blocking the accidental insertion of plaintext passwords, tokens, or API keys into a Git repository. ### Declarative Dependency Management A paradigm where the developer declares the desired state of the system (e.g., `typer` version `^0.12.0` in `pyproject.toml`) and trusts a tool (like Poetry) to resolve and install the dependency tree, creating a single, deterministic source of truth. ### CLI (Command Line Interface) Text-based user interface allowing users to interact with applications by typing commands into a terminal. ### Typer Modern Python CLI framework powered by Type Hints and Click for building self-documenting CLI tools with automatic parameter validation. ### Declarative CLI Framework Software engineering pattern where CLI interface structure (arguments, options, types, help menus) is declared directly via function signatures and Python Type Hints. ### Automatic Source Type Detection CLI UX pattern where the application inspects input payload values to infer target type (`URL`, `FILE`, or `TEXT`) automatically without forcing explicit CLI flags in common scenarios. ### Fail-Fast Validation Engineering design rule dictating that input validation occurs at the system edge, raising domain exceptions immediately before invoking resource-heavy pipelines. ### Positional Argument vs CLI Option - **Positional Argument**: Mandatory CLI parameter identified by its relative position in the command invocation (e.g., `source` in `scan `). - **CLI Option (Flag)**: Optional parameter prefixed with one or two dashes (e.g., `-t` or `--text`), overriding or altering command execution behavior. ### Rich Python library for rich terminal rendering (styled panels, syntax highlighting, Markdown, tables, progress bars, spinners). ### Facade Pattern Structural design pattern providing a simplified, unified interface in front of complex subsystems (e.g., multi-source extraction orchestrator). ### Pydantic Validation Layer Architectural pattern where Pydantic `BaseModel` with constrained fields (`Field(min_length=1)`) is placed at system boundaries to enforce business rules declaratively, catching invalid data before it propagates into core logic. ### Factory-style Dispatch A lightweight routing pattern using an `if/elif/else` chain on an enum value to select the appropriate function or strategy, without requiring a formal registry or inversion-of-control container. ## 🤖 Artificial Intelligence & LLM Concepts ### Structured Output Technique forcing an LLM to return data conforming strictly to a JSON schema or Pydantic model instead of unstructured free text. ### System Prompt (Prompt System) High-level initial instruction given to an LLM to assign its persona (e.g., *Senior AI Analyst*), context, and constraints before user content is provided. ### Temperature & Top_P Parameters controlling LLM determinism. Low temperature (0.0 – 0.3) minimizes variability and enhances factual accuracy required for technical analysis. --- ## 💰 FinOps & Observability Concepts ### FinOps (Financial Operations) Discipline uniting engineering, finance, and product teams to optimize cloud and API costs (e.g., token usage tracking, cost per million tokens). ### Prompt Tokens vs. Completion Tokens - **Prompt Tokens**: Tokens sent to the model (system prompt + source text). - **Completion Tokens**: Tokens generated by the model in its response. ### SHA-256 Hashing & Idempotency Hashing technique uniquely identifying input content. Submitting identical content yields cached results without incurring API costs (idempotency). ### Exponential Backoff with Jitter Retry strategy increasing wait time exponentially between failed attempts, adding random jitter to prevent overwhelming target APIs. ### Exception Hierarchy An architecture pattern where custom exception classes inherit from a common base class. This enables granular error handling and targeted feedback without generic interpreter crashes. ### Pure Functions & I/O Separation An architectural practice separating side-effect-heavy I/O operations (like reading files) from deterministic pure functions (like text normalization), enabling highly predictable and instantaneous unit tests. ### HTML Cleaning Pipeline A sequence of operations designed to parse raw HTML, remove non-content noisy tags (like script, style, nav, footer), and extract human-readable text to minimize token consumption for the LLM. ### Pydantic V2 Data Contract Architectural boundary validation pattern using Pydantic V2 models to parse and enforce strict type contracts, default factories, and value constraints on incoming LLM JSON outputs. ### Immutable Data Entity (`frozen=True`) Domain modeling pattern enforcing read-only data objects post-instantiation (`ConfigDict(frozen=True)`), preventing accidental side-effect mutations across pipeline stages. ### FinOps Telemetry Schema Schema design pattern embedding operational cost metrics (`prompt_tokens`, `completion_tokens`, `estimated_cost_usd`, `execution_time_seconds`) alongside domain deliverables within a single entity. ### System Prompt Engineering The practice of crafting high-precision system instructions that specify LLM persona, output format, domain rules, and boundaries to guarantee structured data delivery. ### Few-Shot Schema Grounding Providing complete, validated exemplar outputs within prompt context to guide the model toward exact syntax and schema adherence matching `AnalysisReport.model_validate_json()`. ### Zero-Naked-Code-Fence Constraint Instructing the LLM to output pure JSON without markdown triple-backtick code fences to streamline downstream parsing and avoid syntax stripping errors. ### LLMClient Domain component encapsulating REST interactions with LLM APIs via HTTPX, timing execution, stripping markdown fences, injecting FinOps telemetry, and validating returned `AnalysisReport` models. ### FinOps Cost Matrix A mapping dictionary of LLM model identifiers to prompt and completion rates per 1,000 tokens used to compute financial operational expenditure in real time. ### Markdown Fence Stripping A pre-processing utility function stripping leading ```json and trailing ``` markdown code block syntax from raw LLM responses before JSON deserialization. ### Demo Mode / Mocked Response An operational mode in developer tools where external network services are bypassed, and static or programmatic mock data conforming to domain schemas is returned to enable offline testing and zero-cost iteration. ### Short-Circuit Evaluation Bypassing heavy or costly operations (such as HTTP REST network calls to LLM endpoints) early in code execution when specific flag conditions (e.g. `--demo`) are satisfied. ### Synthetic Telemetry Simulated performance and financial metrics (token counts, USD cost estimates, execution latency) attached to mock responses to test FinOps reporting interfaces without live API consumption. ### Pricing Matrix A dictionary mapping model identifiers to their input/output token rates (USD per 1M tokens). The Wrapper CLI matrix covers 40+ models across 8 providers (OpenAI, Google, Anthropic, Meta, Mistral, DeepSeek, Cohere, Amazon). ### Per-1M Token Pricing Industry standard (2025+) denominating model rates per 1,000,000 tokens rather than per 1,000. Simplifies mental math and aligns with official pricing pages. ### UnknownModelError Custom exception (`WatcherError` → `UnknownModelError`) raised when `calculate_cost()` receives a model name not found in the pricing matrix. Enforces strict FinOps tracking by rejecting unknown models with a helpful error message listing supported models. ### Token Cost Rounding Financial cost rounded to 6 decimal places using Python's `round()` to avoid floating-point noise in reports while capturing sub-cent precision. ### Metrics Injection The process of populating execution metadata (latency, token counts, calculated costs) into standard domain data structures during output parsing. ### Usage Metadata API response payload structure containing token consumption metrics (`promptTokenCount`, `candidatesTokenCount`, `prompt_tokens`, `completion_tokens`). ### Rich Panel A UI component in the Rich Python library that draws styled border boxes around terminal text or renderables. ### Rich Markdown A renderable class in Rich that parses Markdown strings and displays them with terminal formatting inside console applications. ### FinOps Telemetry Table A dedicated CLI table component displaying operational resource usage metrics (token counts, financial cost in USD, and execution latency) for LLM API calls. ### Financial Impact Thresholding Visual color-coding rule applied to monetary values (< $0.01 green for low cost, < $0.05 yellow for moderate cost, >= $0.05 red for high cost) to give immediate visual awareness of query expenditure. ### Format Interoperability The capacity of a CLI application to export its structured domain outputs into standardized interchange formats (JSON, Markdown) for integration with external pipelines or human documentation. ### Markdown Report Rendering The process of converting structured Pydantic data models into human-readable Markdown files including header tables, bulleted lists, and structured sections. ### Content Hash Persistence Storing calculated analysis results keyed by a cryptographic SHA-256 digest of input text to ensure deterministic and idempotent cache hits. ### Idempotent Inference Bypassing Eliminating redundant LLM API requests and token costs by reusing verified analysis artifacts when processing identical input content. ### Cache TTL (Time-To-Live) The duration in seconds for which a cached analysis report remains valid before requiring re-evaluation from the primary LLM model. ### Automated Cache Purging Automated background cleanup during initialization that sweeps expired or malformed entries from the JSON cache file on disk. ### Cache Bypass Flag (--no-cache) A CLI option that skips both reading from and writing to the local disk cache, executing fresh LLM analysis without modifying existing cache data. ### Tenacity & Resilience - **Exponential Backoff**: A retry algorithm that multiplies the wait time between successive failed attempts exponentially (e.g. 2s, 4s, 8s) to give remote services time to recover. - **Jitter**: Randomized variation added to backoff delays to prevent synchronized client retries from overwhelming a recovering server (thundering herd problem). - **Rate Limiting (HTTP 429)**: An HTTP status code returned by an API indicating the client has sent too many requests within a given window. - **Transient Error**: A temporary failure condition (such as network drops, server timeouts, or temporary load shedding) expected to resolve upon retrying. - **Graceful Failure**: A software design pattern where runtime errors are caught, formatted, and presented cleanly without crashing the process or exposing raw stack traces. - **Exit Status / Code**: An integer value returned by a process to its parent shell upon completion (0 for success, non-zero e.g. 1 for errors). - **Rich Error Panel**: A styled terminal block rendered with the Rich library displaying error messages inside a red border box on stderr. ### Extractor Unit Testing & SSRF Mocking - **Connect-time SSRF Guard**: A security mechanism that checks resolved target IP addresses at socket connection setup to prevent TOCTOU DNS-rebinding attacks. - **Ingestion Facade Pattern**: A design pattern exposing a single `extract()` interface that dispatches to specific text, file, or URL extractors based on `SourceType`. - **Deterministic Transport Mocking**: Testing pattern where network transports and socket calls return pre-configured responses without making real I/O requests. ### LLM Client Unit Testing & Mocks (Step 9.2) - **HTTPX Client Mocking**: Technique of replacing real HTTPX transport clients with `MagicMock` objects to simulate REST API responses without network activity. - **Tenacity Retry Simulation**: Testing strategy for validating exponential backoff logic by controlling side effects on mocked methods and suppressing sleep delays. - **Schema Parsing Validation**: Verifying that raw candidate responses from Gemini/OpenAI API formats parse cleanly into immutable Pydantic V2 `AnalysisReport` models. ### FinOps & Cache Unit Testing (Step 9.3) - **Deterministic Business Logic Verification**: Testing software components with fixed input sets to guarantee consistent, reproducible financial and caching outputs without external network dependencies. - **Pytest Fixture (`tmp_path`)**: A built-in Pytest fixture providing a unique `pathlib.Path` temporary directory for each test function, automatically cleaned up post-execution. - **Cache Invalidation & TTL (Time-To-Live)**: Mechanism where cached entries expire and become invalid after a predefined duration (in seconds), forcing a re-fetch of fresh data. - **FinOps Pricing Matrix Invariance**: Guarantee that cost calculations accurately reflect predefined token rates per 1M tokens across all supported model tiers without silent fallback behavior. ### End-to-End CLI Integration Testing (Step 9.4) - **End-to-End (E2E) CLI Testing**: Testing methodology where the CLI application is invoked via its top-level entrypoint to verify that all internal subsystems (CLI argument parsing, content extraction, business logic, formatting, and disk I/O) work cohesively. - **CliRunner Test Harness**: A test utility provided by Click/Typer that invokes CLI commands programmatically, capturing standard output, standard error, exit codes, and exceptions in an isolated context. - **Pipeline Component Integration**: The structural interaction and data flow between input ingestion (extractor), processing (LLM client analysis / cache), and output rendering (Rich console / export formatters). ### Multi-Stage CLI Containerization (Step 10.1) - **ENTRYPOINT Directive**: A Dockerfile instruction specifying the default command executed when a container starts, allowing arguments passed to `docker run` to be appended directly to the executable. - **Multi-Stage Docker Build**: A container image optimization technique using multiple `FROM` statements in a single Dockerfile to separate the build environment from the final runtime image, reducing image size and attack surface. - **Unprivileged Container Execution**: Running application processes inside a container as a non-root system user (`appuser`) to mitigate security risks in shared or multi-tenant runtime environments. ### Runtime Secrets Injection (Step 10.2) - **Dynamic Runtime Secret Injection**: Supplying API keys and sensitive credentials to containerized applications at runtime via environment variables, avoiding credential persistence in container images. - **Zero-Baked Secrets**: A security standard ensuring no API keys, tokens, or credentials are hardcoded or embedded into container filesystem layers. - **Environment Variable Alias Resolution**: Configuring settings parsers to map multiple standard environment variable names to a single internal credential field. ### Documentation Finalization & Integrity (Step 10.3) - **Documentation-as-Product**: The practice of applying software engineering rigor (linting, automated testing, version control, CI/CD gates) to technical documentation. - **Documentation Drift**: The divergence over time between actual code behavior and written documentation, mitigated by automated test validation. - **Onboarding Friction**: The measure of setup time and operational complexity required for an external developer to clone a repository, build, and execute a working feature.