T040: LLMProvider Protocol, request/response types, and error hierarchy

[likith1908]

Summary

Add iris_engine/contracts/llm_provider.py defining the LLMProvider Protocol, frozen dataclasses (LLMRequest, LLMResponse, LLMUsage), and the typed error hierarchy (8 classes) for the LLM adapter workstream. Single file, zero adapter dependencies, importable in a bare iris-engine install.

Task reference

• Task ID: T040
• Workstream: 004-llm-adapter-set

Why

Establishes the single authoritative contract that all four LLM adapters (T044-T047) and the selector (T041) implement against. Must land before any adapter package can be written.

Acceptance criteria

• mypy --strict passes on the module.
• Module imports with zero adapter dependencies (from iris_engine.contracts.llm_provider import LLMProvider works in a bare iris-engine install).
• docs-ci workflow passes (markdown lint + tasks structural check).
• No em-dashes introduced in new prose.
• All internal links resolve.
• No secrets, credentials, or personal names introduced.

PR checklist

• Every acceptance criterion in the task's tasks.md entry is satisfied.
• docs-ci workflow passes (markdown lint + tasks structural check).
• No em-dashes introduced in new prose.
• All internal links resolve.
• No secrets, credentials, or personal names introduced.

Notes for the reviewer

• TenantContext is re-exported from ocr_engine.py rather than redefined. One authoritative definition prevents drift between OCR and LLM callsites.
• LLMRequest.stop is list[str] | None (not tuple) per the contract doc. The dataclass is frozen=True for immutability semantics; hash() is never called on request instances so the mutable field is acceptable.
• LLMResponse.structured is BaseModel | None at the Protocol level. Callers narrow it against the schema they passed in. Using a generic TypeVar on the Protocol method would complicate structural subtype checking.
• Error hierarchy is shallow and explicit: each class maps to exactly one failure category (401/403, 429, 5xx, 400, content-policy). No inheritance between siblings; callers check the type, not the message.
• contracts/ is omitted from coverage (omit = ["*/iris_engine/contracts/*"]) - same treatment as ocr_engine.py.

Rebase note

This PR is stacked on #38 (T038+T039). Once #38 merges, rebase onto main before merging this one.

[anmolg1997]

Approved — substance is a clean, faithful port of the contract. One small tracking fix to land before merge (below).

What I verified

iris_engine/contracts/llm_provider.py matches contracts/llm-provider.md exactly:

• All 7 typed errors present and correctly mapped: LLMUnavailable (5xx/network/timeout), LLMRateLimited (429), LLMAuthenticationFailed (401/403), LLMSchemaViolation, LLMContextWindowExceeded, LLMContentFiltered, LLMInvalidRequest (400), all under LLMError.
• LLMUsage / LLMResponse / LLMRequest frozen dataclasses with the documented fields. LLMRequest defaults are sensible (temperature=0.0 for deterministic extraction, schema=None, model_hint for the extraction/classification/summary/chat routing the gateway will use later).
• LLMResponse.structured: BaseModel | None — pydantic typed, populated only when a schema was supplied. adapter_id doc-comment correctly notes "in-memory" for the stub.
• Reuses TenantContext from ocr_engine rather than redefining it, and re-exports it in __all__ — good, one shared context type across both contracts.
• Module docstring states the layer rule ("No adapter imports... importable without any LLM dependency"). iris_engine stays at the bottom; lint confirms 3 contracts kept.

Gates: lint clean, mypy clean on 20 source files, full suite 373 passed.

One fix before merge

tasks/004-llm-adapter-set/tasks.md still shows - [ ] **T040**. Every prior task PR flipped its checkbox in the same PR; this one didn't. Left as-is, main will show T040 as not-done even though it's complete — and the docs-ci structural check won't catch a stale checkbox.

Please flip it to - [x] **T040**. You're rebasing this branch anyway as the stack lands, so it's a zero-cost addition to the same push. Not requesting changes since the code needs nothing — just don't let it merge without the flip.

(Optional: T040's acceptance text references the OTEL span on complete carrying structured_output_used — that span lands with the LLM equivalent of T038, not here. If you want to mirror the OCR pattern, scope T040's acceptance to "Protocol type-checks under mypy strict; imports with zero adapter deps" the way you did for T030, and let the span clause ride with the later instrumentation task. Your call.)

Solid foundation for the four LLM adapters. Reviewing #40 (selector + stub) next.