Utils

domain.enrichment.entity.utils

Summary

Text utilities for entity enrichment: description normalization, number sequence removal, candidate validity checks, and candidate extraction.

Functions

extract_candidates

extract_candidates(
    description: str,
    candidate_regexes: Iterable[re.Pattern],
) -> List[str]

Extract validated payee candidates from a description.

For each regex, reads the payee named group, checks validity, and appends the normalized key.

Parameters:

Name	Type	Description	Default
`description`	`str`	Description text to scan.	required
`candidate_regexes`	`Iterable[Pattern]`	Compiled regexes exposing a `payee` named group.	required

Returns:

Type	Description
`List[str]`	List[str]: Validated, normalized candidate keys.

is_valid_candidate

is_valid_candidate(candidate: str) -> bool

Check whether a string is a plausible entity candidate.

Rejects empty/short strings, pure-hex strings, and pure digits (unless exactly 10 digits); requires at least one letter.

Parameters:

Name	Type	Description	Default
`candidate`	`str`	Candidate string to validate.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` when the candidate is usable.

lookup_mapping

lookup_mapping(candidate: str, mapping: dict)

Look up candidate display names in a mapping.

A normalized exact key match returns the single mapped name; otherwise returns every mapped name whose key is a substring of the candidate. Falsy candidates return (None, None).

Parameters:

Name	Type	Description	Default
`candidate`	`str`	Candidate to look up.	required
`mapping`	`dict`	Mapping of normalized keys to `MappingValue` entries.	required

Returns:

Type	Description
	A single matching name, a list of substring matches, or
	`(None, None)` for falsy candidates.

normalize_description

normalize_description(text: str) -> str

Normalize a description for downstream matching.

Strips whitespace, drops page N of M markers, OCR hex blobs, separators, @ and ., collapses runs of spaces, and lower-cases the result.

Parameters:

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

Returns:

Name	Type	Description
`str`	`str`	The normalized, lower-cased description.

normalize_money_str

normalize_money_str(x) -> str

Format a number as a two-decimal string.

Parameters:

Name	Type	Description	Default
`x`		Value coercible to `float`.	required

Returns:

Name	Type	Description
`str`	`str`	The number formatted to two decimals.

normalize_person_handle

normalize_person_handle(handle: str) -> str

Normalize a UPI-style handle into a display name.

Strips the @ suffix and trailing digits, capitalizes word pieces (preserving known acronyms), and removes bracket characters; returns "" when the result is purely hex-like.

Parameters:

Name	Type	Description	Default
`handle`	`str`	Raw handle string.	required

Returns:

Name	Type	Description
`str`	`str`	The normalized person name (possibly empty).

remove_number_sequence

remove_number_sequence(
    text: str, amt: str, bal: str
) -> str

Strip digit runs that echo the amount/balance.

Builds a regex from the concatenated amount+balance digits and removes candidate runs within one edit of that digit string, collapsing the remaining whitespace.

Parameters:

Name	Type	Description	Default
`text`	`str`	Description text to clean.	required
`amt`	`str`	Transaction amount, formatted via `normalize_money_str`.	required
`bal`	`str`	Balance, formatted via `normalize_money_str`.	required

Returns:

Name	Type	Description
`str`	`str`	The cleaned description with echoed numbers removed.