"""Shared Pydantic v2 models used by both bank-extractor and bank-hitl.""" import datetime as _dt from decimal import Decimal from typing import Any, Optional, Union from pydantic import BaseModel, Field from .constants import AuditStatus, TxType # ── Raw transaction (direct extractor output) ──────────────────────────────── class RawTransaction(BaseModel): """One row as extracted — all values are still strings.""" page_num: int row_num: int date_raw: str = "" desc_raw: str = "" debit_raw: str = "" credit_raw: str = "" balance_raw: str = "" source_extractor: str = "" # ── Normalised transaction ─────────────────────────────────────────────────── class NormTransaction(BaseModel): """Cleaned, typed transaction ready for auditing and export.""" page_num: int row_num: int date_raw: str = "" desc_raw: str = "" debit_raw: str = "" credit_raw: str = "" balance_raw: str = "" source_extractor: str = "" # Normalised fields date: Union[_dt.date, None] = None description: str = "" amount: Decimal = Decimal("0.00") balance_after: Union[Decimal, None] = None calculated_balance: Optional[Decimal] = None # NEW: Mathematical balance tx_type: TxType = TxType.UNKNOWN confidence: float = 1.0 audit_flags: list[str] = Field(default_factory=list) # Generated identifier tx_id: str = "" # Classification fields (populated after ClassificationPipeline runs) category: Optional[str] = None third_party: Optional[str] = None category_confidence: Optional[str] = None category_source: Optional[str] = None verified: bool = False # Human-readable payment purpose extracted from OSKO/NPP/Internet Transfer # descriptions. E.g. "home loan", "water bill and insurance", "hmo initial pay". # Populated by the classification pipeline before rule matching. # Used by osko_purpose rules and displayed to HITL reviewers. osko_purpose: Optional[str] = None # ── Page-level audit result ────────────────────────────────────────────────── class PageAudit(BaseModel): page_num: int opening_balance: Decimal = Decimal("0.00") closing_balance: Decimal = Decimal("0.00") computed_balance: Decimal = Decimal("0.00") computed_amount: Decimal = Decimal("0.00") delta: Decimal = Decimal("0.00") tx_count: int = 0 status: AuditStatus = AuditStatus.CLEAN issues: list[str] = Field(default_factory=list) # ── Statement-level audit result ───────────────────────────────────────────── class StatementAudit(BaseModel): statement_id: str = "" bank_id: str = "" period_from: Union[_dt.date, None] = None period_to: Union[_dt.date, None] = None pages: list[PageAudit] = Field(default_factory=list) overall_status: AuditStatus = AuditStatus.CLEAN total_issues: int = 0 extract_last_3_months: Optional[bool] = None # ── Extractor result container ─────────────────────────────────────────────── class ExtractorResult(BaseModel): extractor_id: str = "" raw_transactions: list[RawTransaction] = Field(default_factory=list) confidence_score: float = 0.0 page_count: int = 0 extraction_time_ms: float = 0.0 warnings: list[str] = Field(default_factory=list) page_metadata: dict[int, dict[str, Any]] = Field(default_factory=dict) # ── HITL edit record ───────────────────────────────────────────────────────── class HITLEdit(BaseModel): tx_id: str field: str old_value: str new_value: str reviewer_id: str reviewed_at: _dt.datetime reason: Union[str, None] = None # ── Coordinate-based layout extraction models ─────────────────────────────── class ColumnLayout(BaseModel): name: str # canonical: "date"|"description"|"debit"|"credit"|"balance"|"amount" header_label: str # original text in PDF x_min: float x_max: float col_type: str # "date" | "text" | "numeric" confidence: float = 1.0 # per-column detection confidence class HeaderDetectionResult(BaseModel): found: bool page_num: int header_y: float columns: list[ColumnLayout] raw_header_words: list[dict] = [] confidence: float # ── Pipeline result (returned from extract_statement) ──────────────────────── class PipelineResult(BaseModel): output_path: str = "" audit_report: StatementAudit = Field(default_factory=StatementAudit) confidence: float = 0.0 warnings: list[str] = Field(default_factory=list) transactions: list[NormTransaction] = Field(default_factory=list) extractor_used: str = "" processing_time_ms: float = 0.0