# Domain Glossary

- **Constrained Decoding**: Grammar-level restriction of token sampling probabilities to ensure generated text matches a target JSON schema.
- **Prompt Injection**: A security vulnerability where untrusted input text overrides system prompt instructions.
- **Schema Firewall**: A validation boundary enforcing strict data model invariants prior to downstream ingestion.
- **Instructor**: A Python library built on Pydantic that patches LLM clients (OpenAI, Anthropic, Mistral) to enforce structured responses adhering strictly to Pydantic schemas via function/tool calling.
- **Domain Exception Firewall**: An architectural boundary where third-party framework exceptions are intercepted and re-raised as domain exceptions to prevent infrastructure details from leaking.
- **Fast-Fail Configuration**: Validating required credentials and configuration parameters during initialization to fail immediately rather than during runtime requests.
- **Tier-1 Network Transport Retry**: The first resilience tier: automatic retry of LLM API calls on transient transport failures (connection drops, timeouts), HTTP 429 rate limits, and 5xx server errors using exponential backoff.
- **Retry Predicate**: A callable passed to Tenacity's `retry_if_exception` that classifies an exception as retryable (True) or fatal (False). Enables declarative, SDK-agnostic retry policy definition.
- **Exponential Backoff**: Delay strategy where sleep grows multiplicatively per attempt (multiplier=1, min=2, max=10 => 2s, 4s, 8s, capped 10s) to avoid thundering-herd on recovering providers.
- **Retry Exhaustion Boundary**: The point after `max_retries_network` attempts where the wrapped exception is re-raised (reraise=True), triggering the Engine's `NetworkTransportError` domain layer.
- **RateLimitError (HTTP 429)**: OpenAI SDK exception signaling provider rate limiting. Classified as retryable because the quota typically resets within seconds.
- **Tier-2 Schema Self-Correction Loop**: A resilience mechanism where the LLM is re-prompted with Pydantic `ValidationError` feedback up to `max_retries` times until it produces a schema-compliant output.
- **InstructorRetryException**: Exception raised by the Instructor library when all schema self-correction retries are exhausted, containing `failed_attempts` metadata.
- **FailedAttempt**: NamedTuple in Instructor representing a single failed generation attempt with `attempt_number`, `exception`, and optional `completion`.
- **Network Error Classification**: Determining whether an exception originates from transport/rate-limit/5xx failures (Tier-1) vs schema validation failures (Tier-2) by inspecting exception cause chains.
- **Content-Hash Deduplication Cache**: A local KV store keyed by a deterministic SHA-256 hash of the input payload to skip redundant LLM invocations for identical content.
- **SHA-256 Content Keying**: Hashing raw article text concatenated with the model name to produce a 64-character hex digest uniquely identifying a generation request.
- **Cache Hit**: A request whose content hash matches an existing cache entry, returning the stored record without invoking the LLM.
- **Cache Miss**: A request whose content hash has no matching cache entry, requiring a fresh LLM call followed by cache population.
- **is_cached Metadata Flag**: A boolean field on `ArticleExtractionRecord` indicating whether the record was served from the deduplication cache rather than a fresh LLM call.
- **Thread-Safe Cache**: A cache guarded by a `threading.Lock` to prevent race conditions during concurrent read/write access in async batch processing.
- **JSON Persistence**: Best-effort serialization of cache entries to a JSON file, enabling cache survival across process restarts.
- **Cache Eviction on Validation Failure**: Removing a cached entry when its stored JSON fails Pydantic schema validation, ensuring schema integrity.
- **LRU Eviction**: A bounded cache policy using `OrderedDict` where the least-recently-used entry is removed when the store exceeds `max_entries`.
- **CORS (Cross-Origin Resource Sharing)**: An HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources.
- **FastAPI ASGI Application**: An Asynchronous Server Gateway Interface framework designed for building modern, high-performance web APIs with Python 3.8+ based on standard Python type hints.
- **Liveness Probe / Health Check**: An HTTP endpoint (`/health`) used by orchestrators to determine whether a microservice container is running and capable of handling traffic.
- **Single Extraction Endpoint**: An HTTP POST route (`/v1/extract`) designed to process individual untrusted news payloads synchronously and return a validated `ArticleExtractionRecord`.
- **Input Firewall DTO**: A Data Transfer Object (`SingleExtractionRequest`) that enforces constraints on incoming API payloads prior to internal domain processing.
- **Async Concurrency Control**: Managing multiple asynchronous tasks concurrently using synchronization primitives to control task execution concurrency.
- **Semaphore Bounding**: A concurrency control technique using counting semaphores (`asyncio.Semaphore`) to restrict simultaneous LLM requests to a maximum threshold, preventing provider rate limits.
- **Partial Failure Aggregation**: A batch execution pattern where individual task failures are logged and tracked as metrics rather than throwing an exception that cancels the overall batch operation.
- **Extraction Telemetry Registry**: An in-memory aggregation component that records real-time operational metrics (total requests, success rate, cache hit rate, latency, token consumption, and USD cost) per extraction request.
- **Schema Inspector**: A diagnostic validation component utilizing Pydantic V2 introspection to analyze incoming raw JSON payloads against structural schema firewalls, identifying field type mismatches, missing required fields, and constraint violations.
- **Circular Log Buffer**: A fixed-size FIFO log queue that retains the latest execution and inspection trace records for real-time monitoring dashboard visualization.
- **Zero-Schema-Drift Firewall**: A strict schema validation enforcement strategy ensuring that 100% of LLM-generated output records strictly conform to the expected Pydantic domain models.
- **Schema Unit Testing**: Automated test suite designed to verify field constraints, custom validators, default values, and type invariants of Pydantic V2 domain models and DTOs.
- **Boundary Value Testing**: Testing strategy focused on lower, upper, and exact boundary values (e.g. `0.0`, `1.0`, `-0.1`, `1.5`) to validate field constraint validators.
- **XML Tag Delimitation & Sanitization**: Technique enclosing untrusted user content within explicit XML tags (`<untrusted_news_payload>`) while neutralizing nested closing tag breakout attempts.
- **Developer Authority System Isolation**: Architectural prompt structure enforcing system instructions over user payload content, treating embedded user overrides purely as data strings to analyze.
- **Heuristic Injection Keyword Scanner**: Lightweight pre-execution pattern matching mechanism that scans untrusted payloads for common prompt injection triggers prior to model processing.
- **Indirect Prompt Injection**: A prompt injection attack delivered via third-party untrusted data (e.g. news article text or web pages) rather than directly from the user prompt.
- **XML Tag Breakout**: An injection tactic attempting to close developer-defined XML content boundaries (e.g. sending `</untrusted_news_payload>`) to inject adversarial system commands outside the data context.
- **Two-Tier Resilience Pipeline**: Multi-stage fault tolerance mechanism separating network-level transport retries (Tier-1) from schema-level structural self-correction loops (Tier-2).
- **Exponential Backoff & Jitter**: Retry policy increasing wait durations exponentially between attempts with jitter to safely recover from HTTP 429 rate limits and 5xx server errors.
- **Schema Self-Correction Turn**: Feedback loop where Pydantic validation tracebacks are appended to message history for immediate model structural repair.
- **Deduplication Short-Circuiting**: Optimization technique utilizing SHA-256 content hashes to return cached extraction records without triggering redundant LLM calls.
- **Benchmark Dataset Evaluation**: Automated execution of structured extraction across a standardized corpus of 100 ground-truth news articles to quantify schema compliance, latency, and security resilience.
- **Schema Compliance Rate**: The percentage of extractions that successfully conform to Pydantic V2 data contracts without schema drift or validation failures.
- **Prompt Injection Resilience Rate**: The percentage of evaluation test cases containing adversarial system override instructions that were safely neutralized by the security delimitation layer.
- **P95 Latency Bounding**: The 95th percentile execution latency metric measured across all benchmark extractions to ensure SLA compliance under batch conditions.
- **Multi-Stage Build**: A Docker build optimization technique that separates build dependencies from final runtime assets, significantly reducing image size and attack surface.
- **Non-Root User (UID 10001)**: An unprivileged system user account created inside the container runtime to prevent execution as root (UID 0) and mitigate container escape vulnerabilities.
- **Liveness Probe**: An automated healthcheck mechanism (e.g. HTTP GET /health) used by container orchestrators to determine whether the application process is functioning correctly.
- **no-new-privileges**: A Docker security flag preventing processes inside the container from gaining additional privileges through setuid or setgid binaries.