aeat.application._workflow_review_models module

Shared leaf models for the workflow and review packages.

workflow and review need each other’s pydantic models at runtime: WorkflowEvent is instantiated by review actions and embedded as a field type on InvoiceReviewRecord and LedgerReviewRecord; those two review records are in turn embedded as field types on WorkflowState. Neither side can import the other’s public facade without re-entering a partially-initialised package during Python’s import machinery (the facade __init__ for either package pulls in the other), and pydantic’s eager field-type resolution makes the dependency runtime-bound rather than annotation-only, so neither side of the former direct cross-import was TYPE_CHECKING-deferrable.

This module is the structural fix: it is a leaf with no dependency on either workflow or review, so both packages import these four names from here instead of from each other. workflow re-exports WorkflowEvent and utc_now() from its facade; review re-exports InvoiceReviewRecord and LedgerReviewRecord from its facade. Consumers outside these two packages are unaffected — they already import through the public facades, which keep re-exporting the same names.

This module is private application-layer plumbing consumed only by workflow and review; it is not part of the application public surface and carries no __all__.

See also

WorkflowState

Workflow aggregate that embeds review records from this leaf module.

InvoiceReviewRecord

Public review facade export for invoice annotations.

LedgerReviewRecord

Public review facade export for ledger transaction annotations.

BucketId

Bucket identifier type carried by workflow events.

class WorkflowEvent(**data)[source]

Bases: BaseModel

One operator-visible event emitted by a mutating workflow verb.

Events are appended to bucket_events so the operator can audit which actions ran, when, and against which object. action names the verb (e.g. "profile.created"); reason carries a free-form human-readable annotation; bucket_id and object_id are optional pointers to the affected resource.

Parameters:

  • action (str)

  • reason (str)

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • object_id (str | None)

  • at (datetime)

action: str
reason: str
bucket_id: BucketId | None
object_id: str | None
at: datetime
class LedgerReviewRecord(**data)[source]

Bases: BaseModel

Workflow attention annotation for one persisted transaction.

Durable transaction facts are not stored here. Classification, category, business percentage, tax fields, evidence references, skip/final-disposition state, and corrections live on the bucket-scoped transaction catalogue.

Parameters:
transaction_id: str
history: tuple[WorkflowEvent, ...]
updated_at: datetime
class InvoiceReviewRecord(**data)[source]

Bases: BaseModel

Workflow annotations for one persisted invoice.

Parameters:
invoice_id: str
fields: dict[str, str]
history: tuple[WorkflowEvent, ...]
updated_at: datetime