Ambiguity

pipelines.extraction.shared.ambiguity

Summary

Ambiguity resolution — faithful port of domain.extraction.ambiguity.

Candidate generation and three-mode dispatch, ported verbatim so the hexa PDF path matches OG logic. The LLM-specific resolver is kept as an optional hook (resolver); pause/CLI behaviour is preserved via PauseForResolution.

Classes

AmbiguityHandler

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

Three-mode ambiguity dispatcher: resolved_choices -> resolver -> pause -> CLI.

Attributes:

Name	Type	Description
`fetch_request_id`	`str`	Identifier correlating this resolution to a fetch request.
`pause_on_ambiguity`	`bool`	Whether to raise `PauseForResolution` when unresolved.
`resolved_choices`	`dict`	Cache of previously resolved candidate keys.
`resolver`	`Optional[Callable]`	Optional LLM/machine resolver hook.

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
)

Resolve ambiguous amount/balance candidate pairs.

Validates the candidate pairs against the running balance and returns the unique valid interpretation. When multiple valid interpretations remain it consults resolved_choices, then the optional resolver hook, then either raises PauseForResolution or falls back to CLI resolution.

Parameters:

Name	Description	Default
`line`	Raw transaction line being resolved.	required
`ocr_amount`	OCR-extracted amount.	required
`ocr_balance`	OCR-extracted balance.	required
`prev_balance`	Running balance from the previous transaction.	required
`candidates`	Collection of candidate (amount, balance) pairs.	required

Returns:

Type	Description
	Set of a single (amount, balance) pair, or `None` when no valid
	interpretation exists.

Raises:

Type	Description
`PauseForResolution`	When multiple interpretations remain and `pause_on_ambiguity` is enabled.

AmbiguousCandidateFound

AmbiguousCandidateFound(candidates: set)

Bases: ValueError

Raised when candidate generation produces multiple valid interpretations.

Attributes:

Name	Type	Description
`candidates`	`set`	Ambiguous candidate (amount, balance) pairs.

AmountBalanceNotFound

Bases: ValueError

Raised when no valid amount/balance interpretation can be found.

PauseForResolution

PauseForResolution(
    line,
    ocr_amount,
    ocr_balance,
    prev_balance,
    candidates,
    fetch_request_id: str = "",
)

Bases: Exception

Signal that ambiguous candidates need human resolution.

Attributes:

Name	Type	Description
`line`		Raw transaction line being resolved.
`ocr_amount`		OCR-extracted amount.
`ocr_balance`		OCR-extracted balance.
`prev_balance`		Running balance from the previous transaction.
`candidates`		Candidate (amount, balance) pairs.
`fetch_request_id`	`str`	Fetch request ID used for correlation.

ResolutionContext

ResolutionContext(
    amount,
    balance,
    prev_balance,
    line,
    numbers,
    handler=None,
    trust_fallback=None,
    missing_number_candidates=None,
)

Resolves amount/balance pairs, generating candidates when direct validation fails.

Attributes:

Name	Type	Description
`amount`	`float`	Absolute-rounded OCR amount.
`balance`	`float`	Rounded OCR balance.
`prev_balance`	`float`	Rounded running balance.
`line`		Raw transaction line being resolved.
`numbers`		Extracted numbers from the transaction line.
`tolerance`	`float`	Allowed rounding difference.
`handler`		Optional `AmbiguityHandler` used when ambiguity surfaces.
`trust_fallback`		Optional fallback policy (`"amount"` or `"balance"`).
`missing_number_candidates`		Optional candidate hook for one-number lines.
`adjustors`		Ordered list of candidate generator callables.

Initialize a resolution context.

Parameters:

Name	Description	Default
`amount`	OCR-extracted transaction amount.	required
`balance`	OCR-extracted closing balance.	required
`prev_balance`	Running balance from the previous transaction.	required
`line`	Raw transaction line being resolved.	required
`numbers`	Extracted numbers from the transaction line.	required
`handler`	Optional `AmbiguityHandler` for ambiguous candidates.	`None`
`trust_fallback`	Optional fallback policy (`"amount"` or `"balance"`).	`None`
`missing_number_candidates`	Optional callable providing candidates for one-number lines.	`None`

Functions

resolve

1	`resolve()`

Resolve to a validated (amount, balance) pair.

Applies direct sign validation first, then trust fallbacks, then walks the ordered candidate generators. Raises when nothing reconciles.

Returns:

Type	Description
	Two-tuple of signed amount and validated balance.

Raises:

Type	Description
`AmountBalanceNotFound`	When no candidate interpretation reconciles with the running balance.

Functions

clean_num

clean_num(s: str) -> float

Convert a numeric string to a float, handling decimals and paise.

A bare integer string is treated as paise (divided by 100); strings with a decimal point use the decimal part directly.

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.

get_numbers

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

Extract monetary numbers from OCR/text lines.

Parameters:

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

Returns:

Type	Description
`List[float]`	List[float]: Cleaned numeric values found in the text.

validate_signs

validate_signs(
    amount, balance, prev_balance, tolerance=1.0
)

Validate a (amount, balance) interpretation against the running balance.

Parameters:

Name	Type	Description	Default
`amount`		OCR-extracted transaction amount.	required
`balance`		OCR-extracted closing balance.	required
`prev_balance`		Running balance from the previous transaction.	required
`tolerance`	`float`	Allowed rounding difference. Defaults to 1.0.	`1.0`

Returns:

Type	Description
	Two-tuple of signed amount and validated balance, or `(None, None)`
	when no sign combination reconciles with the running balance.