cadrumo.adapters.outbound.llm.models module

Strict Pydantic models for the outbound LLM adapter.

This module is the canonical owner of request, response, provider, cache, usage, prompt, and validation record types. Consumers import these records directly from this defining module; the sibling package initializer is inert.

class MultimodalImageInput(**data)

Bases: BaseModel

One on-host-prepared image attached to a multimodal LLM request.

Transient and in-memory only. Carries the base64-encoded image bytes the provider adapter forwards to a vision model and the content address (an attachment-store SHA-256) that LLMCache folds into CacheKey. The base64 payload is never persisted – only its content address enters the cache key (sensitive-financial-data-secure-storage-only).

media_type has no default on purpose. A local runtime sniffs the bytes, but a cloud provider validates the declared type against them and refuses the pair when they disagree – so a defaulted media type is exactly how a JPEG attachment gets sent as a PNG and the read fails or, worse, is silently misinterpreted. The producer knows what it built; it declares it.

Parameters:

data (Any)

content_sha256: ContentDigest

base64_data: str

media_type: ImageMediaType

classmethod from_base64(base64_data, media_type)

Build one input from encoded image bytes and their known media type.

The single place the content address is derived, so a producer cannot pair one image’s payload with another’s digest. The address is the SHA-256 of the DECODED bytes, matching the attachment store’s own content addressing.

Parameters:

• base64_data (str) – Base64-encoded image bytes.

• media_type (ImageMediaType) – The type those bytes actually are – from the producer’s own knowledge (the page rasteriser only ever emits PNG) or from detect_image_media_type() over the raw bytes.

Return type:

MultimodalImageInput

Returns:

The transient multimodal input carrying all three fields.

class LLMRequest(**data)

Bases: BaseModel

User-facing completion request accepted by LLMClient.

Provider and model override fields select LLMProvider values for one call, and images carries transient MultimodalImageInput payloads for local vision flows.

evidence_derived defaults to False because most requests carry no taxpayer content at all – a column-role mapping reads spreadsheet headers, a corpus measurement reads a public synthetic document. The fail-closed default lives one level up, at the evidence READERS, which mark every request they build unless the caller names a public corpus: an unmarked request is therefore a deliberate statement about the content, not an omission. consent_token enters neither the cache key nor any persisted record; it exists only between its minting site and the dispatch point.

Parameters:

data (Any)

prompt: str

system: str | None

max_tokens: int | None

temperature: float | None

language: str | None

cache_key: str | None

provider_override: LLMProvider | None

model_override: str | None

images: tuple[MultimodalImageInput, ...]

evidence_derived: bool

consent_token: EvidenceConsentToken | None

classmethod validate_prompt(cls, value)

Ensure prompts are not empty or whitespace-only.

Raises:

• LLMValidationError – When the

• prompt is blank after trimming. –

Return type:

str

Parameters:

value (str)

classmethod validate_system(cls, value)

Normalize empty system prompts to None.

Return type:

str | None

Parameters:

value (str | None)

classmethod validate_language(cls, value)

Validate optional ISO 639-1 language codes.

Return type:

str | None

Parameters:

value (str | None)

class LLMResponse(**data)

Bases: BaseModel

Completion response returned by complete().

Responses are persisted inside CachedEntry records and converted into UsageRecord values for cost tracking.

Parameters:

data (Any)

text: str

provider: LLMProvider

model: str

input_tokens: int

output_tokens: int

cost_estimate_usd: Decimal | None

cache_hit: bool

created_at: datetime

request_id: str

class PromptDefinition(**data)

Bases: BaseModel

Prompt metadata stored by PromptRegistry.

Parameters:

• id (str)

• version (int)

• template (str)

• expected_output_schema (type[BaseModel] | None)

• description (str)

id: str

version: int

template: str

expected_output_schema: type[BaseModel] | None

description: str

classmethod validate_id(cls, value)

Ensure prompt identifiers are kebab-case.

Return type:

str

Parameters:

value (str)

class PromptRegistry(**data)

Bases: BaseModel

Registry of versioned PromptDefinition values.

Parameters:

data (Any)

definitions: dict[str, PromptDefinition]

register(definition)

Add or replace a prompt definition.

Return type:

None

Parameters:

definition (PromptDefinition)

get(prompt_id, version=None)

Return a PromptDefinition by id and optional version.

Return type:

PromptDefinition

Parameters:

• prompt_id (str)

• version (int | None)

classmethod seeded()

Return a default PromptRegistry.

Return type:

PromptRegistry

class CachedEntry(**data)

Bases: BaseModel

Encrypted cache record persisted by LLMCache.

Parameters:

data (Any)

provider: LLMProvider

model: str

prompt_hash: str

args_hash: str

response: LLMResponse

created_at: datetime

class UsageRecord(**data)

Bases: BaseModel

Append-only usage record persisted by UsageRecorder.

Parameters:

data (Any)

prompt_id: str

caller: str

text: str

provider: LLMProvider

model: str

input_tokens: int

output_tokens: int

cost_estimate_usd: Decimal | None

cache_hit: bool

created_at: datetime

request_id: str

class CacheKey(**data)

Bases: BaseModel

Derived cache key used by LLMCache.

Parameters:

data (Any)

provider: LLMProvider

model: str

prompt_hash: str

args_hash: str

class CacheStats(**data)

Bases: BaseModel

Basic LLMCache statistics for CLI reporting.

Parameters:

data (Any)

entries: int

total_bytes: int

class UsageSummary(**data)

Bases: BaseModel

Aggregated UsageRecorder statistics.

Parameters:

data (Any)

entries: int

total_input_tokens: int

total_output_tokens: int

total_cost_estimate_usd: Decimal | None

unpriced_entries: int

since: date | None

until: date | None