Abc

pipelines.extraction.pdf.abc

Summary

Abstract contracts for the pdf (OCR text) extraction graph (no implementation).

---

The pdf family is the classic heuristic text chain:

ingest → raw_lines → txn_blocks → txn_dicts → raw_expense

Non-PDF families (email / csv / xlsx) do NOT extend this root — they have their own stage chains (see email/abc.py and shared/tabular.py).

The annotations on each class declare WHAT it needs. Concrete implementations (re)declare the same port slots with CONCRETE types to inform which implementation is used, and implement the @abstractmethod bodies.

Classes

BucketFinderPort

Bases: ABC

Divide raw_lines into account buckets at B/F markers.

Attributes:

Name	Type	Description
number	NumberPort	Number extraction leaf.

Functions

get_opening_balance_buckets abstractmethod

get_opening_balance_buckets(
    lines: List[str],
    *,
    limit_first: bool = False,
    line_offset: int = 0
) -> List[tuple]

Divide raw lines into account buckets at B/F markers.

Parameters:

Name	Type	Description	Default
lines	List[str]	Raw text lines.	required
limit_first	bool	Keep only the first bucket. Defaults to False.	False
line_offset	int	Offset added to starting indices. Defaults to 0.	0

Returns:

Type	Description
List[tuple]	List[tuple]: (start, end, opening_balance) bucket triples.

PDFExtractionPipeline

Bases: ABC

Root — wires ingest → raw_lines → txn_blocks → txn_dicts → raw_expenses.

Attributes:

Name	Type	Description
source	ExtractionSource	The extraction source descriptor.
pipeline	str	Pipeline tag; defaults to "heuristic".
trust_fallback		Fallback policy for amount/balance trust.
ingest	IngestPort	Ingest stage.
raw_lines	RawLinesPort	Raw-lines stage.
txn_blocks	TxnBlocksPort	Txn-blocks stage.
txn_dicts	TxnDictsPort	Txn-dicts stage.
raw_expense	RawExpensePort	Terminal raw-expense stage.

Functions

run abstractmethod

run(source) -> List[Any]

Run the pdf extraction chain.

Parameters:

Name	Type	Description	Default
source		Raw extraction source.	required

Returns:

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

RawLinesPort

Bases: ABC

content → list of raw text lines.

Attributes:

Name	Type	Description
covert_to_image	bool	Whether to binarize pages via image conversion.

Functions

extract abstractmethod

extract(content) -> List[str]

Extract raw OCR text lines from content.

Parameters:

Name	Type	Description	Default
content		Materialized content payload.	required

Returns:

Type	Description
List[str]	List[str]: Raw text lines.

SplitterPort

Bases: ABC

Split bucket line-groups into transaction blocks.

Attributes:

Name	Type	Description
number	NumberPort	Number extraction leaf.
date	DatePort	Date parsing leaf.

Functions

split_blocks abstractmethod

split_blocks(
    lines: List[str],
    *,
    has_header: bool = False,
    min_numbers: int = 3,
    detect_date_ranges: bool = False
) -> List[str]

Split bucket line-groups into transaction blocks.

Parameters:

Name	Type	Description	Default
lines	List[str]	Lines belonging to one account bucket.	required
has_header	bool	Whether a header precedes the rows.	False
min_numbers	int	Minimum numbers for a split.	3
detect_date_ranges	bool	Detect date-range lines.	False

Returns:

Type	Description
List[str]	List[str]: Transaction block texts.

TransactionParserPort

Bases: ABC

Parse one transaction block into a structured dict.

Attributes:

Name	Type	Description
min_numbers	int	Minimum numbers for a block.
amount_index	int	Index of the amount in the number list.
balance_index	int	Index of the balance in the number list.
number	NumberPort	Number extraction leaf.
date	DatePort	Date parsing leaf.
desc	DescPort	Description extraction leaf.
amount_balance	AmountBalancePort	Amount/balance resolution leaf.

Functions

parse abstractmethod

parse(
    txn_text: str, prev_date_str, prev_balance: float
) -> Dict[str, Any]

Parse one transaction block into a structured dict.

Parameters:

Name	Type	Description	Default
txn_text	str	Transaction block text.	required
prev_date_str		Previous transaction date string.	required
prev_balance	float	Running balance from the previous transaction.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Parsed transaction dict.

TxnBlocksPort

Bases: ABC

raw_lines → txn_blocks (opening_balance → list[block strings]).

Attributes:

Name	Type	Description
has_header	bool	Whether a header precedes the rows.
min_numbers	int	Minimum numbers for block splitting.
detect_date_ranges	bool	Detect date-range lines.
limit_first	bool	Keep only the first bucket.
line_offset	int	Offset added to starting indices.
bucket_finder	BucketFinderPort	Bucket-finding stage.
splitter	SplitterPort	Block-splitting stage.

Functions

extract abstractmethod

extract(raw_lines: List[str]) -> Dict[float, List[str]]

Extract txn blocks keyed by opening balance.

Parameters:

Name	Type	Description	Default
raw_lines	List[str]	Raw OCR text lines.	required

Returns:

Type	Description
Dict[float, List[str]]	Dict[float, List[str]]: Opening balance → block texts.

TxnDictsPort

Bases: ABC

txn_blocks → list of structured txn dicts.

Attributes:

Name	Type	Description
min_numbers	int	Minimum numbers for a block.
amount_index	int	Index of the amount in the number list.
balance_index	int	Index of the balance in the number list.
parser	TransactionParserPort	Transaction parsing stage.

Functions

extract abstractmethod

extract(txn_blocks: Dict[float, List[str]]) -> Any

Extract structured txn dicts from txn blocks.

Parameters:

Name	Type	Description	Default
txn_blocks	Dict[float, List[str]]	Opening balance → block texts.	required

Returns:

Name	Type	Description
Any	Any	List of txn dicts.