3v324v23's picture
Merge Conflict solved | Build error solved
205f25f
Raw History Blame Contribute Delete
5.53 kB
"""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