Impl

pipelines.extraction.pdf.impl

Summary

Concrete pdf-family implementations.

The pdf family is the OCR text chain; each concrete class REDECLARES its port slots with CONCRETE types — this pinned typing is what informs the ports to be used, exactly as in the old pipelines/extraction_pipeline_impl.py.

This models the real domain/extraction pdf path as a hexa composition tree:

ImplDatePort : port of domain.extraction.ports.date.DatePort
ImplBucketFinderPort: port of BucketFinderAdaptor.get_opening_balance_buckets
ImplSplitterPort : port of TransactionSplitterAdaptor.split_blocks
ImplTransactionParserPort: port of TransactionParserAdaptor.parse
ImplRawLinesPort : port of PdfRawLinesAdaptor (ocr_all_pages + normalize)

Classes

ImplAmbiguityPort

ImplAmbiguityPort(
    fetch_request_id: str = "",
    pause_on_ambiguity: bool = True,
    resolved_choices: Optional[dict] = None,
    resolver: Optional[Callable] = None,
)

Bases: AmbiguityPort, AmbiguityHandler

Concrete ambiguity leaf — delegates to AmbiguityHandler.

Initialize the ambiguity handler.

Parameters:

Name	Type	Description	Default
`fetch_request_id`	`str`	Identifier correlating this resolution to a fetch request. Defaults to `""`.	`''`
`pause_on_ambiguity`	`bool`	Whether to raise `PauseForResolution` when unresolved. Defaults to `True`.	`True`
`resolved_choices`	`Optional[dict]`	Prior choices keyed by candidate key. Defaults to `None` (becomes an empty dict).	`None`
`resolver`	`Optional[Callable]`	Optional resolver hook. Defaults to `None`.	`None`

Functions

resolve_ambiguity

resolve_ambiguity(
    line,
    ocr_amount,
    ocr_balance,
    prev_balance,
    candidates=None,
)

Resolve ambiguity via AmbiguityHandler.resolve_ambiguity.

Parameters:

Name	Description	Default
`line`	Raw transaction line.	required
`ocr_amount`	OCR amount.	required
`ocr_balance`	OCR balance.	required
`prev_balance`	Previous transaction balance.	required
`candidates`	Candidate (amount, balance) pairs; default `set()`.	`None`

Returns:

Type	Description
	Set with the chosen pair, or `None`.

ImplAmountBalancePort

Bases: AmountBalancePort

Concrete amount/balance leaf — resolves via ResolutionContext.

Attributes:

Name	Type	Description
`number`	`ImplNumberPort`	Number extraction leaf.
`ambiguity`	`ImplAmbiguityPort`	Ambiguity resolution leaf.
`handler`	`Optional[AmbiguityHandler]`	Optional override handler.
`trust_fallback`	`Optional[str]`	Fallback policy.

Functions

adjust_balance

adjust_balance(balance: float, line: str) -> float

Adjust an OCR balance (no-op base).

Parameters:

Name	Type	Description	Default
`balance`	`float`	OCR balance.	required
`line`	`str`	Transaction line.	required

Returns:

Name	Type	Description
`float`	`float`	The balance, unmodified.

missing_number_candidates

missing_number_candidates(ctx)

Provide candidates for one-number lines (no-op base).

Parameters:

Name	Type	Description	Default
`ctx`		The active `ResolutionContext`.	required

Returns:

Type	Description
	None.

resolve

resolve(amount, balance, prev_balance, line, numbers=None)

Resolve (amount, balance) via ResolutionContext.

Parameters:

Name	Description	Default
`amount`	OCR amount.	required
`balance`	OCR balance (adjusted first).	required
`prev_balance`	Previous transaction balance.	required
`line`	Raw transaction line.	required
`numbers`	Extracted numbers; default None.	`None`

Returns:

Type	Description
	(signed amount, resolved balance) tuple.

ImplBucketFinderPort

Bases: BucketFinderPort

Concrete bucket finder — splits raw lines at B/F and opening markers.

Attributes:

Name	Type	Description
`number`	`ImplNumberPort`	Number extraction leaf.

Functions

get_opening_balance_buckets

get_opening_balance_buckets(
    lines, *, limit_first=False, line_offset=0
)

Divide raw lines into opening-balance buckets.

Parameters:

Name	Description	Default
`lines`	Raw text lines.	required
`limit_first`	Keep only the first bucket.	`False`
`line_offset`	Offset added to starting indices.	`0`

Returns:

Type	Description
	List of `(start, end, opening_balance)` triples.

ImplDatePort

Bases: DatePort

Concrete date leaf: parse, split, reconcile, and reorder dates.

Functions

get_dates

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

Extract the leading date and text tail from a line.

Parameters:

Name	Type	Description	Default
`line`	`str`	Text line.	required

Returns:

Type	Description
`Optional[Tuple[str, str]]`	Optional[Tuple[str, str]]: `(date_str, date_tail)` or `None`.

parse_date

parse_date(date_str: str) -> datetime.date

Parse DD-MM-YYYY (or DD/MM/YYYY) into a date.

Parameters:

Name	Type	Description	Default
`date_str`	`str`	Date string.	required

Returns:

Type	Description
`date`	datetime.date: The parsed date.

reconcile_date

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 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`.

reconcile_date_full

reconcile_date_full(
    date_str: str, prev: datetime.date
) -> Optional[str]

Reconcile a date string against a full reference date.

Parameters:

Name	Type	Description	Default
`date_str`	`str`	OCR date string.	required
`prev`	`date`	Previous transaction date.	required

Returns:

Type	Description
`Optional[str]`	Optional[str]: Reconciliated `DD-MM-YYYY` string or `None`.

reconcile_date_partial

reconcile_date_partial(
    date_str: str, prev: datetime.date
) -> Optional[str]

Reconcile a partial MM-YYYY date against a reference date.

Parameters:

Name	Type	Description	Default
`date_str`	`str`	Partial OCR date string.	required
`prev`	`date`	Previous transaction date.	required

Returns:

Type	Description
`Optional[str]`	Optional[str]: Reconciliated `DD-MM-YYYY` string or `None`.

reorder_lines_by_date

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

Move the dated line to the front of a transaction block.

Parameters:

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

Returns:

Type	Description
`List[str]`	List[str]: Reordered lines.

Raises:

Type	Description
`ValueError`	When no dated line is present in the block.

split_line_by_date

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

Split a merged line into segments at date boundaries.

Parameters:

Name	Type	Description	Default
`line`	`str`	Possibly merged OCR line.	required

Returns:

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

ImplDescPort

Bases: DescPort

Concrete description leaf — slices at the first starter marker.

Attributes:

Name	Type	Description
`starters`	`Optional[List[str]]`	Description starter markers.

Functions

extract_description

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.

Raises:

Type	Description
`NotImplementedError`	When no starters are configured.

fix_ocr

fix_ocr(text: str) -> str

Fix OCR artifacts in the description text (no-op base).

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to fix.	required

Returns:

Name	Type	Description
`str`	`str`	Fixed text.

ImplNumberPort

Bases: NumberPort

Concrete number leaf — prefers trailing decimals, else the last numbers.

Functions

get_numbers

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

Extract monetary numbers, preferring trailing decimals.

Parameters:

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

Returns:

Type	Description
`List[float]`	List[float]: Cleaned monetary numbers.

get_opening_balance

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

Return the last number as the opening balance.

Parameters:

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

Returns:

Type	Description
`Optional[float]`	Optional[float]: The last number, else `None`.

ImplPDFExtractionPipeline

Bases: PDFExtractionPipeline

Concrete pdf graph root.

Attributes:

Name	Type	Description
`pipeline`	`str`	Pipeline tag ("heuristic").
`trust_fallback`		Fallback policy for amount/balance trust.
`ingest`	`ImplIngestPort`	Ingest stage.
`raw_lines`	`ImplRawLinesPort`	Raw-lines stage.
`txn_blocks`	`ImplTxnBlocksPort`	Txn-blocks stage.
`txn_dicts`	`ImplTxnDictsPort`	Txn-dicts stage.
`raw_expense`	`ImplRawExpensePort`	Terminal raw-expense stage.

Functions

run

run(source)

Run the pdf extraction chain end-to-end.

Parameters:

Name	Type	Description	Default
`source`		Raw extraction source.	required

Returns:

Type	Description
	List of raw expense records.

ImplRawLinesPort

Bases: RawLinesPort

Concrete raw-lines leaf — OCRs PDF bytes into text lines.

Attributes:

Name	Type	Description
`covert_to_image`	`bool`	Binarize pages via image conversion.

Functions

extract

extract(content)

Extract raw OCR text lines from content.

Parameters:

Name	Type	Description	Default
`content`		PDF bytes, Content, or dict payload.	required

Returns:

Type	Description
	List of raw text lines.

Raises:

Type	Description
`TypeError`	When content is not PDF bytes or Content with `.raw`.

ImplSplitterPort

Bases: SplitterPort

Concrete splitter — splits bucket lines into transaction blocks.

Attributes:

Name	Type	Description
`number`	`ImplNumberPort`	Number extraction leaf.
`date`	`ImplDatePort`	Date parsing leaf.

Functions

split_blocks

split_blocks(
    lines,
    *,
    has_header=False,
    min_numbers=3,
    detect_date_ranges=False
)

Split bucket lines into transaction blocks.

Parameters:

Name	Description	Default
`lines`	Bucket lines.	required
`has_header`	Whether a header precedes the rows.	`False`
`min_numbers`	Minimum numbers for a split.	`3`
`detect_date_ranges`	Detect date-range lines.	`False`

Returns:

Type	Description
	List of transaction block texts.

ImplTransactionParserPort

Bases: TransactionParserPort

Concrete transaction parser — one block to one txn dict.

Attributes:

Name	Type	Description
`number`	`ImplNumberPort`	Number extraction leaf.
`date`	`ImplDatePort`	Date parsing leaf.
`desc`	`ImplDescPort`	Description extraction leaf.
`amount_balance`	`ImplAmountBalancePort`	Amount/balance resolution leaf.

Functions

parse

parse(txn_text, prev_date_str, prev_balance)

Parse a transaction block into a txn dict.

Parameters:

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

Returns:

Type	Description
	Txn dict, or `None` when the block has no usable date/numbers.

ImplTxnBlocksPort

Bases: TxnBlocksPort

Concrete txn-blocks stage — buckets plus per-bucket splitting.

Attributes:

Name	Type	Description
`bucket_finder`	`ImplBucketFinderPort`	Bucket-finding leaf.
`splitter`	`ImplSplitterPort`	Block-splitting leaf.

Functions

extract

extract(raw_lines)

Extract txn blocks keyed by opening balance.

Parameters:

Name	Type	Description	Default
`raw_lines`		Raw OCR text lines.	required

Returns:

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

ImplTxnDictsPort

Bases: TxnDictsPort

Concrete txn-dicts stage — parses blocks in balance-chained order.

Attributes:

Name	Type	Description
`parser`	`ImplTransactionParserPort`	Transaction parsing leaf.

Functions

extract

extract(txn_blocks)

Extract balance-chained txn dicts from blocks.

Parameters:

Name	Type	Description	Default
`txn_blocks`		Opening balance → block texts.	required

Returns:

Type	Description
	List of txn dicts.

Functions

clean_num

clean_num(s: str) -> float

Port of domain.extraction.ports.pdf.clean_num.

Parameters:

Name	Type	Description	Default
`s`	`str`	Numeric string to clean.	required

Returns:

Name	Type	Description
`float`	`float`	Parsed numeric value; `0.0` when the string has no digits.

normalize

normalize(text: str) -> str

Normalize OCR text: fix artifacts, strip separators, drop commas.

Parameters:

Name	Type	Description	Default
`text`	`str`	Raw OCR text.	required

Returns:

Name	Type	Description
`str`	`str`	Normalized text.

ocr_all_pages

ocr_all_pages(
    pdf_bytes: bytes, covert_to_image: bool = None
) -> list

Run OCR over every PDF page, returning per-page text.

Parameters:

Name	Type	Description	Default
`pdf_bytes`	`bytes`	PDF file bytes.	required
`covert_to_image`	`bool`	Binarize pages through image conversion.	`None`

Returns:

Name	Type	Description
`list`	`list`	One OCR text string per page.

Raises:

Type	Description
`ImportError`	When pytesseract/Pillow are unavailable.

rasterize_pdf

rasterize_pdf(
    pdf_bytes: bytes, out_dir: str, dpi: int = 300
) -> list

Rasterize PDF bytes into JPEG page images via pdftoppm.

Parameters:

Name	Type	Description	Default
`pdf_bytes`	`bytes`	PDF file bytes.	required
`out_dir`	`str`	Directory to write the PDF and page images.	required
`dpi`	`int`	Render resolution. Defaults to 300.	`300`

Returns:

Name	Type	Description
`list`	`list`	Sorted list of generated JPEG page paths.