Ports

pipelines.extraction.shared.ports

Summary

Shared leaf contracts for every extraction family (no implementation).

---

These ports are genuinely common across the pdf / email / csv / xlsx families:

• NumberPort / DatePort / DescPort / AmbiguityPort / AmountBalancePort : text-oriented parsing leaves, exercised by the pdf (and future) families.
• IngestPort : turn an ExtractionSource into something concrete each family can consume (bytes, Content, dict, ...).
• RawExpensePort : terminal mapping txn_dicts -> list[RawExpense].

Concrete implementations (re)declare the same slots with CONCRETE types in the per-family impl.py modules and in the per-bank modules; hexa.build() reads the merged MRO annotations and wires everything.

Classes

AmbiguityPort

Bases: ABC

Resolve ambiguous amount/balance interpretations.

Functions

resolve_ambiguity abstractmethod

resolve_ambiguity(
    line: str,
    ocr_amount: float,
    ocr_balance: float,
    prev_balance: float,
) -> Any

Resolve ambiguous amount/balance interpretations.

Parameters:

Name	Type	Description	Default
line	str	Raw transaction line.	required
ocr_amount	float	OCR-extracted amount.	required
ocr_balance	float	OCR-extracted balance.	required
prev_balance	float	Running balance from the previous transaction.	required

Returns:

Name	Type	Description
Any	Any	Resolution result (concrete per implementation).

AmountBalancePort

Bases: ABC

Validate + resolve a txn amount against the running balance.

Attributes:

Name	Type	Description
trust_fallback	Optional[str]	Fallback policy ("amount" or "balance").
number	NumberPort	Number extraction leaf.
ambiguity	AmbiguityPort	Ambiguity resolution leaf.

Functions

resolve abstractmethod

resolve(
    amount: float,
    balance: float,
    prev_balance: float,
    line: str,
    numbers: Optional[List[float]] = None,
) -> Tuple[float, float]

Validate and resolve a transaction amount against the balance.

Parameters:

Name	Type	Description	Default
amount	float	OCR-extracted amount.	required
balance	float	OCR-extracted balance.	required
prev_balance	float	Running balance from the previous transaction.	required
line	str	Raw transaction line.	required
numbers	Optional[List[float]]	Extracted numbers; default None.	None

Returns:

Type	Description
Tuple[float, float]	Tuple[float, float]: (signed amount, resolved balance).

DatePort

Bases: ABC

Detect, parse and reconcile transaction dates.

Functions

get_dates abstractmethod

get_dates(line: str) -> Optional[Tuple[str, str]]

Extract the leading date and the remaining line tail.

Parameters:

Name	Type	Description	Default
line	str	Text line to scan.	required

Returns:

Type	Description
Optional[Tuple[str, str]]	Optional[Tuple[str, str]]: (date_str, date_tail) when a date
Optional[Tuple[str, str]]	leads the line, else None.

parse_date abstractmethod

parse_date(date_str: str) -> datetime.date

Parse a date string into a date.

Parameters:

Name	Type	Description	Default
date_str	str	Date string, commonly DD-MM-YYYY.	required

Returns:

Type	Description
date	datetime.date: The parsed date.

reconcile_date abstractmethod

reconcile_date(
    date_str: str, prev_date_str: Optional[str]
) -> str

Reconcile an OCR date against the previous transaction date.

Parameters:

Name	Type	Description	Default
date_str	str	OCR-extracted date string.	required
prev_date_str	Optional[str]	Previous transaction date string.	required

Returns:

Name	Type	Description
str	str	Reconciliated date as DD-MM-YYYY.

reorder_lines_by_date abstractmethod

reorder_lines_by_date(txn_lines: List[str]) -> List[str]

Reorder block lines so the dated line leads.

Parameters:

Name	Type	Description	Default
txn_lines	List[str]	Transaction block lines.	required

Returns:

Type	Description
List[str]	List[str]: Lines with the dated line moved to the front.

split_line_by_date abstractmethod

split_line_by_date(line: str) -> List[str]

Split a line into segments at date boundaries.

Parameters:

Name	Type	Description	Default
line	str	Text line (possibly two transactions merged).	required

Returns:

Type	Description
List[str]	List[str]: Line segments split at date boundaries.

DescPort

Bases: ABC

Extract a clean transaction description.

Attributes:

Name	Type	Description
starters	List[str]	Description starter markers to slice at.

Functions

extract_description abstractmethod

extract_description(description: str) -> str

Extract and clean the transaction description.

Parameters:

Name	Type	Description	Default
description	str	Raw description text.	required

Returns:

Name	Type	Description
str	str	Cleaned description.

ExtractionSource dataclass

ExtractionSource(
    source_type: str,
    bank: str,
    pipeline: str,
    path: Optional[str],
    trust_fallback: Optional[str],
)

Nested attribute struct describing where to pull content from.

Attributes:

Name	Type	Description
source_type	str	Source family tag (pdf, email, csv, xlsx, llama).
bank	str	Bank tag (axis, icici).
pipeline	str	Pipeline tag (heuristic, llm, tabular).
path	Optional[str]	Path to the source content, when applicable.
trust_fallback	Optional[str]	Fallback policy for amount/balance trust.

IngestPort

Bases: ABC

Turn an ExtractionSource into a concrete content payload.

Attributes:

Name	Type	Description
source_type	str	Source-type tag declared by the concrete root.

Functions

materialize abstractmethod

materialize(source) -> Any

Convert a raw source into a concrete content payload.

Parameters:

Name	Type	Description	Default
source		Raw source (via ExtractionSource) to materialize.	required

Returns:

Name	Type	Description
Any	Any	Concrete payload (bytes, Content, dict, list, or str).

NumberPort

Bases: ABC

Extract monetary numbers from OCR/text lines.

Functions

get_numbers abstractmethod

get_numbers(line: str) -> List[float]

Extract monetary numbers from a line.

Parameters:

Name	Type	Description	Default
line	str	Text line to scan.	required

Returns:

Type	Description
List[float]	List[float]: Cleaned monetary numbers found in the line.

get_opening_balance abstractmethod

get_opening_balance(line: str) -> Optional[float]

Extract the opening balance from a line.

Parameters:

Name	Type	Description	Default
line	str	Text line to scan.	required

Returns:

Type	Description
Optional[float]	Optional[float]: The opening balance when found, else None.

RawExpensePort

Bases: ABC

txn_dicts → list[RawExpense], balance-chained (terminal).

Functions

build abstractmethod

build(txn_dicts) -> List[Any]

Build raw expenses from txn dicts (terminal stage).

Parameters:

Name	Type	Description	Default
txn_dicts		List of structured transaction dicts.	required

Returns:

Type	Description
List[Any]	List[Any]: Raw expense records.