aeat.application.overview._agenda module

Overview agenda: upcoming-deadline ranking with a top-of-payload next_due.

build_overview_agenda() is the application service backing aeat app overview agenda. It accepts a TaxpayerProfile and composes application.overview.build_overview_calendar() over a window anchored on the operator’s as_of date, then partitions the resulting OverviewCalendarEntry rows into overdue / due_today / due_soon cohorts. The earliest future obligation becomes next_due so the CLI can render a single “what is the next thing I have to do” answer without re-walking the calendar.

Local-only: never contacts AEAT. Pure aggregator over the deadline engine, the festivos table, and the operator’s profile values.

class OverviewAgenda(**data)[source]

Bases: BaseModel

Outcome of build_overview_agenda.

The model is the agenda-shaped projection of application.overview.OverviewCalendar: cohorts retain the original OverviewCalendarEntry rows, warnings are CalendarWarning values inherited from the calendar build, and completeness is the same CalendarCompleteness report.

Variables:

  • as_of – Date the agenda is rendered against.

  • horizon_days – Forward window the due_soon cohort honours.

  • next_due – Single earliest future obligation (closest adjusted_closes_on >= as_of); None when no future obligation falls inside the lookahead window.

  • due_today – Entries whose adjusted_closes_on equals as_of.

  • due_soon – Entries whose adjusted_closes_on falls in (as_of, as_of + horizon_days].

  • overdue – Entries whose adjusted_closes_on precedes as_of and whose user_state is LATE (filed obligations are excluded — the engine’s FILED flag suppresses them via the state mapping).

  • generated_at – UTC timestamp of when the aggregator ran.

  • warnings – Calendar warnings inherited from the underlying calendar build (under-specified profile keys).

  • completeness – Calendar completeness inherited from the underlying calendar build.

  • taxpayer_model_declared – Whether the profile carries a usable three-axis taxpayer model. When False every cohort is empty and the operator must declare their taxpayer type first.

  • incomplete_reason – “declare your taxpayer type first” guidance, present only when taxpayer_model_declared is False.

Parameters:
as_of: date
horizon_days: int
next_due: OverviewCalendarEntry | None
due_today: tuple[OverviewCalendarEntry, ...]
due_soon: tuple[OverviewCalendarEntry, ...]
overdue: tuple[OverviewCalendarEntry, ...]
generated_at: datetime
warnings: tuple[CalendarWarning, ...]
completeness: CalendarCompleteness
coverage: ObligationCoverageReport
taxpayer_model_declared: bool
incomplete_reason: str | None
build_overview_agenda(profile, *, as_of, horizon_days=14, engine=None, raw_values=None)[source]

Rank upcoming and past-due obligations around as_of.

Parameters:

  • profile (TaxpayerProfile) – The TaxpayerProfile whose obligations are ranked.

  • as_of (date) – Anchor date for the lookback / lookahead window.

  • horizon_days (int) – Number of days after as_of to include in the lookahead window.

  • engine (DeadlineEngine | None) – Optional DeadlineEngine override; defaults to the registry-backed engine when None.

  • raw_values (Mapping[str, object] | None) – Optional mapping of registry binding raw values forwarded to the deadline engine for context-sensitive deadlines.

Return type:

OverviewAgenda

Composes application.overview.build_overview_calendar() over a window that spans as_of - 90 days (so overdue obligations from the prior quarter surface) through as_of + horizon_days (so the lookahead matches the operator’s requested --horizon).

The returned next_due is the single entry with the smallest adjusted_closes_on >= as_of; if multiple obligations close on the same date, the deterministic calendar ordering (closes_on, modelo, period) resolves the tie.

Returns an OverviewAgenda.