aeat.domain.transactions._model_tier module¶

Model capability tiers for the LLM classifier.

Decouples consumer code from the shifting sands of model IDs at each provider. The operator picks a capability tier (LOW / MEDIUM / HIGH) and a provider (claude / antigravity / codex); resolve_profile() returns the current ModelProfile whose model_id meets the tier floor for that provider.

Rationale:

Model IDs change every few months (sonnet-4.5, gemini-3-pro, o3 -> o4). Hard-coding IDs in CLI flags forces consumers to chase them. A stable tier + alias table is a better interface.
Thinking models (multi-step reasoning, chain-of-thought) classify ambiguous transactions more accurately than single-shot models but cost more tokens. Surfacing the ModelCapability axis lets the operator pick a trade-off.
Classification accuracy on realistic autónomo data is acceptable at ModelTier.MEDIUM and above; ModelTier.LOW models are prone to ignoring the strict JSON schema or picking the wrong classification on ambiguous inputs. MINIMUM_CLASSIFICATION_TIER enforces this floor.

class ModelTier(*values)[source]¶

Bases: IntEnum

Ordered capability tier. Comparison operators work as expected.

Variables:

LOW – Cheap / fast models prone to schema drift on ambiguous inputs.
MEDIUM – Solid single-shot reasoning; the floor for the classification pipeline.
HIGH – Top-tier models with strong multi-step reasoning.

LOW¶

MEDIUM¶

HIGH¶

class ModelCapability(*values)[source]¶

Bases: StrEnum

Whether the model natively does multi-step reasoning before answering.

Variables:

NON_THINKING – Single-shot models that emit one response without internal chain-of-thought passes.
THINKING – Models that perform explicit multi-step reasoning before producing the final answer.

NON_THINKING¶

THINKING¶

class ModelProfile(provider, alias, model_id, tier, capability)[source]¶

Bases: object

One concrete model at one provider, tagged with its capability tier.

Variables:

provider – Lower-case provider name (claude / antigravity / codex).
alias – Stable human-friendly identifier, e.g. claude-sonnet. The operator uses this on the CLI; the tool maps it to model_id.
model_id – Current provider-specific model argument. MAY be empty when the provider CLI defaults to the right model (e.g. codex picks its own default).
tier – Capability tier.
capability – Thinking vs non-thinking.

Parameters:

provider (str)
alias (str)
model_id (str)
tier (ModelTier)
capability (ModelCapability)

provider: str¶

alias: str¶

model_id: str¶

tier: ModelTier¶

capability: ModelCapability¶

MINIMUM_CLASSIFICATION_TIER: ModelTier¶

Minimum ModelTier permitted for the classification pipeline.

The observable failure mode at ModelTier.LOW is schema drift (the model returns prose instead of JSON, or picks a classification outside the allow-list) on more than a handful of transactions per batch, which defeats the confidence filter downstream consumers rely on.

catalogue()[source]¶

Return the full known-model catalogue.

Return type:: tuple[ModelProfile, ...]
Returns:: A tuple of every registered ModelProfile, in the catalogue’s declared order.

profiles_for_provider(provider)[source]¶

Return every profile registered for provider.

Parameters:: provider (str) – Provider name; matched case-insensitively against ModelProfile.provider.
Return type:: tuple[ModelProfile, ...]
Returns:: A tuple of every ModelProfile registered for the normalised provider name. Empty tuple when no profile matches.

resolve_profile(provider, *, alias=None, minimum_tier=ModelTier.MEDIUM)[source]¶

Resolve an optional alias to a ModelProfile for provider.

When alias is None, the default is the LOWEST-tier profile at or above minimum_tier for the provider (cheap but capable).

Parameters:

provider (str) – Provider name (matched case-insensitively).
alias (str | None) – Optional capability-tier alias; when None the cheapest-meets-minimum profile is chosen.
minimum_tier (ModelTier) – Refuses aliases (and default selections) below this tier. Defaults to MINIMUM_CLASSIFICATION_TIER.

Return type:

ModelProfile

Returns:

The resolved ModelProfile.

Raises:

TransactionError – If the provider is unknown, if the alias is unknown for that provider, or if the resolved profile’s tier is below minimum_tier.