aeat.adapters.outbound.llm._models module

Strict Pydantic models for the LLM package.

The public adapters.outbound.llm facade re-exports these records. LLMRequest, LLMResponse, and LLMProvider form the LLMClient boundary. CachedEntry, CacheKey, and CacheStats support LLMCache, while UsageRecord and UsageSummary support UsageRecorder. Prompt definitions are managed through PromptRegistry; validation helpers raise LLMValidationError.

class LLMProvider(*values)[source]

Bases: StrEnum

Supported providers selected by LLMClient.

ANTHROPIC
OPENAI
GEMINI
LOCAL
class MultimodalImageInput(**data)[source]

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 local 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).

Parameters:

  • content_sha256 (str)

  • base64_data (str)

content_sha256: str
base64_data: str
class LLMRequest(**data)[source]

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.

Parameters:
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, ...]
classmethod validate_prompt(value)[source]

Ensure prompts are not empty or whitespace-only.

Raises:
Return type:

str

Parameters:

value (str)

classmethod validate_system(value)[source]

Normalize empty system prompts to None.

Return type:

str | None

Parameters:

value (str | None)

classmethod validate_language(value)[source]

Validate optional ISO 639-1 language codes.

Return type:

str | None

Parameters:

value (str | None)

class LLMResponse(**data)[source]

Bases: BaseModel

Completion response returned by complete().

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

Parameters:
text: str
provider: LLMProvider
model: str
input_tokens: int
output_tokens: int
cost_estimate_usd: Decimal
cache_hit: bool
created_at: datetime
request_id: str
class PromptDefinition(**data)[source]

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(value)[source]

Ensure prompt identifiers are kebab-case.

Return type:

str

Parameters:

value (str)

class PromptRegistry(**data)[source]

Bases: BaseModel

Registry of versioned PromptDefinition values.

Parameters:

definitions (dict[str, PromptDefinition])

definitions: dict[str, PromptDefinition]
register(definition)[source]

Add or replace a prompt definition.

Return type:

None

Parameters:

definition (PromptDefinition)

get(prompt_id, version=None)[source]

Return a PromptDefinition by id and optional version.

Return type:

PromptDefinition

Parameters:

  • prompt_id (str)

  • version (int | None)

prompt_ids()[source]

Return the distinct prompt identifiers in the registry.

Return type:

tuple[str, ...]

classmethod seeded()[source]

Return a default PromptRegistry.

Return type:

PromptRegistry

class CachedEntry(**data)[source]

Bases: BaseModel

Encrypted cache record persisted by LLMCache.

Parameters:
provider: LLMProvider
model: str
prompt_hash: str
args_hash: str
response: LLMResponse
created_at: datetime
class UsageRecord(**data)[source]

Bases: BaseModel

Append-only usage record persisted by UsageRecorder.

Parameters:
prompt_id: str
caller: str
text: str
provider: LLMProvider
model: str
input_tokens: int
output_tokens: int
cost_estimate_usd: Decimal
cache_hit: bool
created_at: datetime
request_id: str
class Translation(**data)[source]

Bases: BaseModel

Translation response built on top of LLMResponse.

Parameters:
text: str
source_lang: str
target_lang: str
provider: LLMProvider
model: str
input_tokens: int
output_tokens: int
created_at: datetime
classmethod validate_translation_language(value)[source]

Validate translation language codes.

Return type:

str

Parameters:

value (str)

class CacheKey(**data)[source]

Bases: BaseModel

Derived cache key used by LLMCache.

Parameters:
provider: LLMProvider
model: str
prompt_hash: str
args_hash: str
class CacheStats(**data)[source]

Bases: BaseModel

Basic LLMCache statistics for CLI reporting.

Parameters:

  • entries (int)

  • total_bytes (int)

entries: int
total_bytes: int
class UsageSummary(**data)[source]

Bases: BaseModel

Aggregated UsageRecorder statistics.

Parameters:

  • entries (int)

  • total_input_tokens (int)

  • total_output_tokens (int)

  • total_cost_estimate_usd (Decimal)

  • since (date | None)

  • until (date | None)

entries: int
total_input_tokens: int
total_output_tokens: int
total_cost_estimate_usd: Decimal
since: date | None
until: date | None