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

class PerModeloAggregationContributor(*values)[source]

Bases: StrEnum

Implemented aggregation-contributor families owned by aeat.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 PerModeloAggregationContributorContract(**data)[source]

Bases: BaseModel

Backend-owned contract for one aggregation provider family.

Parameters:
provider: PerModeloAggregationContributor
modelos: tuple[str, ...]
service_owner: str
accepted_source_kinds: tuple[BindingSourceKind, ...]
class PerModeloAggregationLogFields(**data)[source]

Bases: BaseModel

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

Parameters:
service_name: str
modelo: str
period: Period
provider: PerModeloAggregationContributor
observation_count: int
source_kind_count: int
result_row_count: int
as_extra()[source]

Return a logging extra payload with stable field names.

Return type:

Mapping[str, object]

class PerModeloAggregationContract(**data)[source]

Bases: BaseModel

Complete backend contract consumed by current and future adapters.

Parameters:
schema_version: str
service_owner: str
providers: tuple[PerModeloAggregationContributorContract, ...]
accepted_source_kinds: tuple[BindingSourceKind, ...]
error_codes: tuple[str, ...]
class PerModeloAggregationCommand(**data)[source]

Bases: BaseModel

Command payload for a per-modelo aggregation run.

Parameters:
modelo: str
period: Period
retencion_observations: tuple[RetencionObservation, ...]
counterpart_observations: tuple[CounterpartObservation, ...]
foreign_asset_observations: tuple[ForeignAssetIngestObservation, ...]
withholding_observations: tuple[WithholdingObservation, ...]
property provider: PerModeloAggregationContributor

Return the provider family selected by modelo.

Returns a PerModeloAggregationContributor.

class PerModeloAggregationResult(**data)[source]

Bases: BaseModel

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

Parameters:
modelo: str
period: Period
provider: PerModeloAggregationContributor
aggregation: PerModeloAggregationPayload
source_kinds: tuple[BindingSourceKind, ...]
log_fields: PerModeloAggregationLogFields
build_per_modelo_aggregation_contract()[source]

Build the immutable backend-owned aggregation contract.

Returns a PerModeloAggregationContract enumerating every registered provider, accepted source kinds, and known error codes.

Return type:

PerModeloAggregationContract

get_per_modelo_aggregation_contract()[source]

Return the cached backend-owned PerModeloAggregationContract.

Return type:

PerModeloAggregationContract

provider_for_modelo(modelo)[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)

aggregate_per_modelo(command)[source]

Run the central application aggregation service for one modelo.

Returns a PerModeloAggregationResult.

Return type:

PerModeloAggregationResult

Parameters:

command (PerModeloAggregationCommand)