cadrumo.application.aggregation.service module¶

Central per-modelo aggregation service contracts.

This module owns the non-CLI service boundary for the aggregate command surface. It routes a strict PerModeloAggregationCommand to the provider family that owns the requested modelo and returns a typed PerModeloAggregationResult without requiring CLI-local conversion logic.

The service is distinct from the live calculate source mesh. Retenciones, counterpart, and foreign-assets providers return per-modelo aggregation payloads for operator-facing aggregation/reporting flows; source-derived values that feed calculation use CalculationSourceResolution from application.aggregation.source_mesh.

Providers: retenciones (111/115/123/180/190/193), counterpart (347/349), and foreign_assets (720).

Core types: ModeloRevision.

class PerModeloAggregationContributor(*values)[source]¶

Bases: StrEnum

Implemented aggregation-contributor families owned by cadrumo.application.aggregation.

Names the contributor-role axis (which backend family aggregates a modelo’s ledger evidence), distinct from the settled ModeloSourceResolver calculate-mesh port. The member string values (retenciones / counterpart / foreign_assets) are unchanged.

RETENCIONES¶

COUNTERPART¶

FOREIGN_ASSETS¶

class PerModeloAggregationLogFields(**data)[source]¶

Bases: BaseModel

Stable, non-secret log fields emitted by the aggregation service.

Parameters:: data (Any)

service_name: str¶

modelo: ModeloCode¶

period: Period¶

provider: PerModeloAggregationContributor¶

observation_count: NonNegativeInt¶

source_kind_count: NonNegativeInt¶

result_row_count: NonNegativeInt¶

as_extra()[source]¶

Return a typed logging extra payload with stable field names.

Return type:: LogExtra

class PerModeloAggregationCommand(**data)[source]¶

Bases: BaseModel

Command payload for a per-modelo aggregation run.

modelo is deliberately NOT ModeloCode here, though the result and contract models beside it are. Which modelos this service supports is registry-driven, and the CLI contract allows a late refusal for exactly that reason provided it names the accepted set. Typing the field would refuse a malformed code at construction with a generic shape error instead, losing the listing the operator needs.

Parameters:: data (Any)

modelo: str¶

period: Period¶

retencion_observations: tuple[RetencionObservation, ...]¶

counterpart_observations: tuple[CounterpartObservation, ...]¶

foreign_asset_observations: tuple[ForeignAssetIngestObservation, ...]¶

withholding_observations: tuple[WithholdingObservation, ...]¶

class PerModeloAggregationResult(**data)[source]¶

Bases: BaseModel

Result envelope returned by the central per-modelo aggregation service.

Parameters:: data (Any)

modelo: ModeloCode¶

period: Period¶

provider: PerModeloAggregationContributor¶

aggregation: PerModeloAggregationPayload¶

source_kinds: tuple[BindingSourceKind, ...]¶

log_fields: PerModeloAggregationLogFields¶

provider_for_modelo(modelo, *, operation)[source]¶

Return the provider family for a supported modelo.

Returns a PerModeloAggregationContributor member identifying the aggregation family that owns the given modelo number.

Return type:

PerModeloAggregationContributor

Parameters:

modelo (str)
operation (PinnedAuthorityOperation)

aggregate_per_modelo(command, *, operation)[source]¶

Run the central application aggregation service for one modelo.

Returns a PerModeloAggregationResult.

Return type:

PerModeloAggregationResult

Parameters:

command (PerModeloAggregationCommand)
operation (PinnedAuthorityOperation)