Tabular

pipelines.extraction.shared.tabular

Summary

Shared tabular extraction core (csv + xlsx families).

---

Both the csv and xlsx families are "direct table" pipelines: the bank parser emits the exact typed table and the pipeline owns all policy — signs come from the withdrawal/deposit columns and balances are adjusted as we go so the emitted sequence is always balance-chained. No number extraction, bucket finding, splitting, or ambiguity resolution occurs (unlike the pdf family).

Shared here (both families import from this module):

• TableReaderPort : abstract contract, implemented per format/bank.
• TabularTxnDictsPort : abstract contract for records -> txn dicts.
• TabularExtractionPipeline: the graph root (ingest -> table_reader -> txn_dicts -> raw_expense) with a concrete run driving the three shared stages.
• signed_amount / adjust_balances / tabular_to_txn_dict : the balance-chain policy, ported from OG domain.extraction.pipelines.tabular.
• objects_to_txn_dict / ObjectsTxnDictsPort : the llama-family variant — already-structured statement objects map straight to txn dicts with their STATED balances trusted (no re-chaining), ported from OG domain.extraction.pipelines.llama_parser.to_txn_dict.
• TableParserMixin : format-agnostic header/alias/typing logic, ported from OG IciciTableParserMixin (homed with the icici xlsx parser); the axis csv reader overrides its column_aliases (DR/CR inversion).

Classes

ImplObjectsTxnDictsPort

Bases: ObjectsTxnDictsPort

Functions

build

build(objects)

Build txn dicts from already-structured objects (impl).

Parameters:

Name	Type	Description	Default
objects		Structured statement objects.	required

Returns:

Type	Description
	List of txn dicts.

ImplTabularTxnDictsPort

Bases: TabularTxnDictsPort

Functions

build

build(records)

Build balance-chained txn dicts from typed records (impl).

Parameters:

Name	Type	Description	Default
records		Typed table records.	required

Returns:

Type	Description
	List of txn dicts.

ObjectsTxnDictsPort

Bases: ABC

already-structured objects → list of txn dicts (stated balances trusted).

Functions

build abstractmethod

build(
    objects: List[Dict[str, Any]],
) -> List[Dict[str, Any]]

Build txn dicts from already-structured objects.

Parameters:

Name	Type	Description	Default
objects	List[Dict[str, Any]]	Structured statement objects.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Txn dicts.

TableParserMixin

Format-agnostic typed table reading shared by csv and xlsx readers.

Default aliases/required columns model the icici export; the axis csv reader overrides column_aliases (with the DR/CR inversion).

Attributes:

Name	Type	Description
column_aliases	Dict[str, List[str]]	Alias lookup for header matching.
max_header_scan	int	Max rows scanned for the header row.
required_columns	Tuple[str, ...]	Columns that must be present.

TableReaderPort

Bases: ABC

content → list of typed table records (in sheet/file order).

Functions

read abstractmethod

read(content) -> List[Dict[str, Any]]

Read typed table records from content.

Parameters:

Name	Type	Description	Default
content		Materialized content payload.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Typed table records in source order.

TabularExtractionPipeline

Bases: ABC

Root — direct-table chain: ingest → table_reader → txn_dicts → raw_expense.

Attributes:

Name	Type	Description
source	ExtractionSource	The extraction source descriptor.
pipeline	str	Pipeline tag; defaults to "tabular".
ingest	IngestPort	Ingest stage.
table_reader	TableReaderPort	Table reading stage.
txn_dicts	TabularTxnDictsPort	Txn-dict building stage.
raw_expense	RawExpensePort	Terminal raw-expense stage.

Functions

run

run(source) -> List[Any]

Run the direct-table extraction chain.

Parameters:

Name	Type	Description	Default
source		Raw extraction source.	required

Returns:

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

TabularTxnDictsPort

Bases: ABC

records → list of txn dicts, balance-chained (terminal rules live here).

Functions

build abstractmethod

build(
    records: List[Dict[str, Any]],
) -> List[Dict[str, Any]]

Build balance-chained txn dicts from typed records.

Parameters:

Name	Type	Description	Default
records	List[Dict[str, Any]]	Typed table records.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Txn dicts.

Functions

adjust_balances

adjust_balances(
    records: List[Dict[str, Any]],
) -> List[Dict[str, Any]]

Walk records in table order, correcting balances to the running chain.

The first record anchors on its stated balance. Every subsequent record keeps its stated balance only when it continues the chain exactly; otherwise the balance is adjusted to prev + amount.

Parameters:

Name	Type	Description	Default
records	List[Dict[str, Any]]	Records in table order to chain.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: The same records with corrected balances.

objects_to_txn_dict

objects_to_txn_dict(obj: Dict[str, Any]) -> Dict[str, Any]

Map an already-structured statement object onto the txn-dict shape.

Faithful port of OG domain.extraction.pipelines.llama_parser.to_txn_dict: the object already carries a signed-able amount plus an explicit direction (DEBIT/CREDIT), so the balance is TRUSTED as stated — no re-chaining, unlike the tabular policy. Direction handling accepts the enum instance, "Direction.CREDIT"-style prefixed strings, and any casing, mirroring the OG helper.

Parameters:

Name	Type	Description	Default
obj	Dict[str, Any]	Structured statement object.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Txn dict with txn_date, particulars, amount, balance,
Dict[str, Any]	and direction keys.

signed_amount

signed_amount(record: Dict[str, Any]) -> float

Compute the signed amount from deposit minus withdrawal.

Parameters:

Name	Type	Description	Default
record	Dict[str, Any]	Typed table record.	required

Returns:

Name	Type	Description
float	float	Deposit minus withdrawal, rounded to 2 places.

tabular_to_txn_dict

tabular_to_txn_dict(
    record: Dict[str, Any],
) -> Dict[str, Any]

Map a typed table record onto the standard txn-dict shape.

Parameters:

Name	Type	Description	Default
record	Dict[str, Any]	Typed, balance-chained table record.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Txn dict with txn_date, particulars, amount, balance,
Dict[str, Any]	and direction keys.