File size: 5,529 Bytes
fbb917f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
"""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