The Expenses Service domain layer: business knowledge, models, ports, enrichment and fetch pipelines, with zero I/O.
The domain package holds the rules of the Expenses Service: pydantic models, abstract ports, and the enrichment/fetch pipeline logic. No module here touches the network, the database, or user-facing HTTP; all external effects flow through ports implemented by the infrastructure layer and injected at the composition root.
"},{"location":"domain/#domain--installation","title":"Installation","text":"Install the Expenses Service with its development tooling:
pip install -e \".[dev]\"\nResolve the lazily cached entity enrichment pipeline and run it over a minimal state payload:
```python\nfrom domain.enrichment.entity.pipeline import get_entity_pipeline\n\npipeline = get_entity_pipeline()\nresult = pipeline.enrich({\"candidate\": {\"flags\": []}, \"tags\": []})\n```\ninterface (OpenAPI/FastAPI routes) \u2192 domain (business rules, zero I/O) \u2192 infra (MongoDB, SSE, OCR, LLM providers). Each layer imports only the one below it.hexa.build.Guarantees:
Lifecycle:
doc-forge from its GSDFC docstrings; source remains the single source of truth.Account domain: the Account aggregate, its Mongo document schema, and CRUD service wiring.
"},{"location":"domain/account/models/","title":"Models","text":""},{"location":"domain/account/models/#domain.account.models","title":"domain.account.models","text":""},{"location":"domain/account/models/#domain.account.models--summary","title":"Summary","text":"Define the Account aggregate model shared by the service and storage layers.
"},{"location":"domain/account/models/#domain.account.models-classes","title":"Classes","text":""},{"location":"domain/account/models/#domain.account.models.Account","title":"Account","text":" Bases: BaseModel
Account aggregate: banking details plus the owning user.
Attributes:
Name Type Descriptionname str Display name of the account.
number str Account number; empty when unknown.
type str Account kind, e.g. \"bank\".
currency str Currency code the account operates in, e.g. \"INR\".
owner User User that owns the account.
"},{"location":"domain/account/ports/","title":"Ports","text":"Port wiring for the account aggregate: Mongo repository and CRUD service wiring.
"},{"location":"domain/account/ports/db/","title":"Db","text":""},{"location":"domain/account/ports/db/#domain.account.ports.db","title":"domain.account.ports.db","text":""},{"location":"domain/account/ports/db/#domain.account.ports.db--summary","title":"Summary","text":"Mongo persistence for accounts: document schema and repository factory.
"},{"location":"domain/account/ports/db/#domain.account.ports.db-classes","title":"Classes","text":""},{"location":"domain/account/ports/db/#domain.account.ports.db.AccountDocument","title":"AccountDocument","text":" Bases: Account, BaseDocument
Mongo document form of :class:Account with a populated owner reference.
Attributes:
Name Type Descriptionowner UserDocument Populated owner document stored as a reference.
"},{"location":"domain/account/ports/db/#domain.account.ports.db-functions","title":"Functions","text":""},{"location":"domain/account/ports/db/#domain.account.ports.db.create_account_repo","title":"create_account_repo","text":"create_account_repo(user_repo: Any = None)\nCreate a Mongo-backed account repository wired for owner population.
Parameters:
Name Type Description Defaultuser_repo Any User repository used to populate the owner reference.
None Returns:
Name Type DescriptionAny Mongo-backed account repository configured with a replace-owner population rule.
"},{"location":"domain/account/ports/service/","title":"Service","text":""},{"location":"domain/account/ports/service/#domain.account.ports.service","title":"domain.account.ports.service","text":""},{"location":"domain/account/ports/service/#domain.account.ports.service--summary","title":"Summary","text":"CRUD service wiring for the account aggregate via the hexa container.
"},{"location":"domain/account/ports/service/#domain.account.ports.service-classes","title":"Classes","text":""},{"location":"domain/account/ports/service/#domain.account.ports.service.AccountCrudsService","title":"AccountCrudsService","text":" Bases: CrudsServiceAdaptor[Account, AccountDocument]
Account CRUD service resolving :class:Account documents from a repo.
Instances are created by :func:get_account_service. The model and schema class attributes bind the domain model and its document type.
get_account_service(repo) -> AccountCrudsService\nBuild an account CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed account repository from :func:create_account_repo.
Returns:
Name Type DescriptionAccountCrudsService AccountCrudsService Ready-to-use account CRUD service.
"},{"location":"domain/enrichment/","title":"Enrichment","text":"Enrichment domain: rule-driven pipelines that resolve payee entities and tags from raw expense descriptions, backed by YAML pattern registries.
Provides the shared pattern data models (models), the registry-aware pipeline node base (nodes), and two pipeline families: entity (entity/payee resolution) and tags (flag and tag attachment).
Guarantees:
Lifecycle:
dagpipe graph from packaged resources and caches it per pipeline name; nodes are wired with their pattern registry and node config at load time.Exception types raised by the enrichment domain when a tag alias cannot be resolved to a seeded tag.
"},{"location":"domain/enrichment/exceptions/#domain.enrichment.exceptions--notes","title":"Notes","text":"Guarantees:
NewTagFoundError(tag_name: str)\n Bases: Exception
Raised when an alias matches a tag name that has no seed entry.
Attributes:
Name Type Descriptiontag_name str The tag name that matched but was not found.
message str The message text passed to the exception base class, prompting manual seeding.
"},{"location":"domain/enrichment/models/","title":"Models","text":""},{"location":"domain/enrichment/models/#domain.enrichment.models","title":"domain.enrichment.models","text":""},{"location":"domain/enrichment/models/#domain.enrichment.models--summary","title":"Summary","text":"Pydantic models for enrichment patterns: a discriminated union of pattern payloads (Pattern) and a versioned PatternRegistry lookup table compiled by the pipeline loaders.
Guarantees:
Pattern discriminates on the type field, so a payload whose marker does not match its shape fails pydantic validation.Lifecycle:
resources/patterns/*.yaml files and treated as read-only after construction. Bases: BasePattern
Ordered list pattern, e.g. negative candidate lists.
Attributes:
Name Type Descriptiontype Literal[ARRAY] Constant marker for this shape.
array List The ordered list payload.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.BasePattern","title":"BasePattern","text":" Bases: BaseModel
Base class for all pattern payloads.
Attributes:
Name Type Descriptiontype PatternType Discriminator identifying the concrete pattern shape.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.KeywordsPattern","title":"KeywordsPattern","text":" Bases: BasePattern
Keyword list pattern.
Attributes:
Name Type Descriptiontype Literal[KEYWORDS] Constant marker for this shape.
items List[str] Keywords that match, in any order.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.MappingPattern","title":"MappingPattern","text":" Bases: BasePattern
Key/value mapping pattern.
Attributes:
Name Type Descriptiontype Literal[MAPPING] Constant marker for this shape.
mapping Dict[str, Union[str, MappingValue, List]] Mapping keys to bare strings, structured values, or lists.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.MappingValue","title":"MappingValue","text":" Bases: BaseModel
A single mapping entry value carrying an id and display name.
Attributes:
Name Type Descriptionid str Stable identifier for the mapped value.
name str Human-readable display name.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.PatternRegistry","title":"PatternRegistry","text":" Bases: BaseModel
Versioned registry of named enrichment patterns.
Accessors dispatch on the runtime pattern type and raise TypeError when the stored pattern has a different shape than requested.
Attributes:
Name Type Descriptionversion int Registry schema version.
patterns Dict[str, Pattern] Named patterns keyed by their registry name.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.PatternRegistry-functions","title":"Functions","text":""},{"location":"domain/enrichment/models/#domain.enrichment.models.PatternRegistry.array","title":"array","text":"array(name: str) -> List\nReturn the array payload of a named ArrayPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Name Type DescriptionList List The pattern's array payload.
Raises:
Type DescriptionTypeError If the stored pattern is not an ArrayPattern.
get(name: str) -> Pattern\nReturn the pattern registered under name.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Name Type DescriptionPattern Pattern The stored pattern payload.
Raises:
Type DescriptionKeyError If no pattern is registered under name.
keywords(name: str) -> List[str]\nReturn the keyword items of a named KeywordsPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionList[str] List[str]: The pattern's item keywords.
Raises:
Type DescriptionTypeError If the stored pattern is not a KeywordsPattern.
mapping(name: str) -> Dict[str, str]\nReturn the mapping of a named MappingPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionDict[str, str] Dict[str, str]: The pattern's key/value mapping.
Raises:
Type DescriptionTypeError If the stored pattern is not a MappingPattern.
regex(name: str) -> re.Pattern\nReturn the compiled regex of a named RegexPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionPattern re.Pattern: The pattern's compiled regex.
Raises:
Type DescriptionTypeError If the stored pattern is not a RegexPattern.
regex_list(name: str) -> List[re.Pattern]\nReturn compiled regexes of a named RegexListPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionList[Pattern] List[re.Pattern]: The pattern's compiled regexes.
Raises:
Type DescriptionTypeError If the stored pattern is not a RegexListPattern.
regex_map(name: str) -> List[Tuple[re.Pattern, str]]\nReturn compiled regex/value pairs of a RegexMapPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionList[Tuple[Pattern, str]] List[Tuple[re.Pattern, str]]: Compiled regex and value pairs.
Raises:
Type DescriptionTypeError If the stored pattern is not a RegexMapPattern.
rules(name: str) -> List[Dict]\nReturn the rule list of a named RulesPattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Type DescriptionList[Dict] List[Dict]: The pattern's rule dicts.
Raises:
Type DescriptionTypeError If the stored pattern is not a RulesPattern.
template(name: str) -> str\nReturn the template string of a named TemplatePattern.
Parameters:
Name Type Description Defaultname str Registry name of the pattern.
requiredReturns:
Name Type Descriptionstr str The pattern's template string.
Raises:
Type DescriptionTypeError If the stored pattern is not a TemplatePattern.
Bases: str, Enum
Discriminator values selecting a concrete pattern shape.
Attributes:
Name Type DescriptionKEYWORDS PatternType Keyword list pattern (KeywordsPattern).
MAPPING PatternType Key/value mapping pattern (MappingPattern).
ARRAY PatternType Plain array pattern (ArrayPattern).
RULES PatternType Rule list pattern (RulesPattern).
REGEX PatternType Single regex pattern (RegexPattern).
REGEX_LIST PatternType List of regexes (RegexListPattern).
REGEX_MAP PatternType Regex-to-value mapping (RegexMapPattern).
TEMPLATE PatternType String template pattern (TemplatePattern).
Bases: BasePattern
List of regular expressions pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX_LIST] Constant marker for this shape.
patterns List[str] Regex sources compiled by compile_all.
compile_all(flags: int = re.IGNORECASE) -> List[re.Pattern]\nCompile every regex source in this pattern.
Parameters:
Name Type Description Defaultflags int Regex flags passed to re.compile; defaults to re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionList[Pattern] List[re.Pattern]: One compiled regex per source.
Raises:
Type Descriptionerror If any source is not valid regex.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexMapPattern","title":"RegexMapPattern","text":" Bases: BasePattern
Regex-to-value mapping pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX_MAP] Constant marker for this shape.
mapping Dict[str, str] Regex sources mapped to match values.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexMapPattern-functions","title":"Functions","text":""},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexMapPattern.compile_all","title":"compile_all","text":"compile_all(\n flags: int = re.IGNORECASE,\n) -> List[Tuple[re.Pattern, str]]\nCompile every regex in the mapping paired with its value.
Parameters:
Name Type Description Defaultflags int Regex flags passed to re.compile; defaults to re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionList[Tuple[Pattern, str]] List[Tuple[re.Pattern, str]]: Compiled regex and value pairs.
Raises:
Type Descriptionerror If any source is not valid regex.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexPattern","title":"RegexPattern","text":" Bases: BasePattern
Single regular expression pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX] Constant marker for this shape.
pattern str Regex source used to compile a matcher.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexPattern-functions","title":"Functions","text":""},{"location":"domain/enrichment/models/#domain.enrichment.models.RegexPattern.compile","title":"compile","text":"compile(flags: int = re.IGNORECASE) -> re.Pattern\nCompile this pattern's regex source.
Parameters:
Name Type Description Defaultflags int Regex flags passed to re.compile; defaults to re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionPattern re.Pattern: The compiled regex.
Raises:
Type Descriptionerror If pattern is not valid regex.
Bases: BasePattern
List of rule dictionaries pattern.
Attributes:
Name Type Descriptiontype Literal[RULES] Constant marker for this shape.
rules List[Dict] Rule dicts consumed by flag/tag rule evaluators.
"},{"location":"domain/enrichment/models/#domain.enrichment.models.TemplatePattern","title":"TemplatePattern","text":" Bases: BasePattern
String template pattern.
Attributes:
Name Type Descriptiontype Literal[TEMPLATE] Constant marker for this shape.
format str Template string returned by the registry accessor.
"},{"location":"domain/enrichment/nodes/","title":"Nodes","text":""},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes","title":"domain.enrichment.nodes","text":""},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes--summary","title":"Summary","text":"Shared dagpipe nodes for the enrichment pipelines: a registry-aware node base class plus the amount-based flag evaluator.
Nodes resolve pipeline state by forking into enriched states; concrete node sets live in the entity and tags subpackages.
Guarantees:
Lifecycle:
set_registry and set_config are invoked by the pipeline loaders when a pipeline is built and cached. Bases: RegistryNode
Attach amount-comparison flags derived from raw.amount.
Evaluates the configured amount-based flag mapping (an array of flag tokens such as amount_greater_than_500) against the absolute amount in the state and appends each matching flag to candidate.flags.
Flags already present on the candidate are left untouched. When new flags are added the node forks the state with the updated flag list; otherwise it yields the state unchanged. Encoded values use underscores for the decimal point (e.g. amount_equal_to_5_00).
property","text":"amount_based_flag_mapping\nReturn the configured amount-based flag tokens.
Returns:
Type DescriptionThe array of flag tokens from the mapped registry pattern.
"},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes.AmountBasedFlagNode.config","title":"configproperty","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
resolve(state: State) -> Iterable[State]\nEvaluate amount-based flags and yield updated states.
Parameters:
Name Type Description Defaultstate State Pipeline state carrying raw.amount and candidate.flags.
Yields:
Name Type DescriptionState Iterable[State] The updated state with new amount flags, or the input
Iterable[State] state unchanged when nothing matched.
"},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes.AmountBasedFlagNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes.AmountBasedFlagNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: Node, ABC
Base node for enrichment pipelines.
Subclasses receive a PatternRegistry and a node-specific config dict from the pipeline loader, and read their decision inputs through registry accessors.
set_registry and set_config install instance-level values; the class defaults them to None until a loader wires a node.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/nodes/#domain.enrichment.nodes.RegistryNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Entity enrichment: pipeline loading and entity resolution nodes.
The loader compiles the packaged pipeline.yaml and patterns/*.yaml resources into a cached dagpipe pipeline; the resolution nodes turn raw descriptions into a payee entity (id, name, type, logo) through aliases, normalized signals, candidates, and flag-driven rules.
Identity helpers for entity enrichment: text normalization, entity id derivation, candidate canonicalization, and entity state payload construction.
"},{"location":"domain/enrichment/entity/identity/#domain.enrichment.entity.identity-functions","title":"Functions","text":""},{"location":"domain/enrichment/entity/identity/#domain.enrichment.entity.identity.build_entity","title":"build_entity","text":"build_entity(\n name: str,\n entity_type: str = \"merchant\",\n entity_logo: str | None = None,\n) -> dict\nBuild the entity payload spread into pipeline state.
Parameters:
Name Type Description Defaultname str Entity display name.
requiredentity_type str Entity type, defaults to \"merchant\".
'merchant' entity_logo str | None Logo URL/path, or None.
None Returns:
Name Type Descriptiondict dict A payload mapping the entity.* keys accepted by
dict dagpipe state forks.
canonicalize_candidate(candidate: str | None) -> str | None\nCanonicalize a candidate value for comparisons.
Parameters:
Name Type Description Defaultcandidate str | None Raw candidate string.
requiredReturns:
Type Descriptionstr | None str | None: The normalized candidate key, or None for falsy
str | None input.
"},{"location":"domain/enrichment/entity/identity/#domain.enrichment.entity.identity.normalize_key","title":"normalize_key","text":"normalize_key(text: str | None) -> str | None\nNormalize arbitrary text to a comparison key.
Applies NFKC unicode normalization, lower-cases, and strips surrounding whitespace.
Parameters:
Name Type Description Defaulttext str | None Text to normalize; None passes through.
Returns:
Type Descriptionstr | None str | None: The normalized key, or None for None input.
to_entity_id(name: str | None) -> str | None\nDerive a stable slug id from a name.
Empty/falsy names yield None. Non-alphanumeric runs are replaced with a single underscore and edge underscores are trimmed.
Parameters:
Name Type Description Defaultname str | None Entity name to slugify.
requiredReturns:
Type Descriptionstr | None str | None: The slug id, or None when name is falsy.
Loader for the entity enrichment pipeline.
Compiles the packaged pipeline.yaml plus the patterns/*.yaml registries into a cached dagpipe pipeline, wiring every registry-aware node with its registry and node config.
get_entity_pipeline()\nReturn the lazily cached entity pipeline.
Builds (once) and reuses the pipeline across calls.
Returns:
Type DescriptionThe cached entity pipeline instance.
"},{"location":"domain/enrichment/entity/pipeline/#domain.enrichment.entity.pipeline.load","title":"load","text":"load() -> Pipeline\nLoad and wire the entity enrichment pipeline.
Reads the packaged pipeline.yaml, builds the pipeline graph, and installs the merged pattern registry and per-node config onto each node that supports it.
Returns:
Name Type DescriptionPipeline Pipeline The wired dagpipe pipeline.
Raises:
Type DescriptionFileNotFoundError If the packaged pipeline.yaml is missing.
Entity resolution nodes for the enrichment pipeline.
Each node advances the entity candidate: alias-based entity assignment, description normalization, candidate extraction, flag-based candidate handling, flag-driven entity setting, and a final fallback.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver-classes","title":"Classes","text":""},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.CandidateBasedFlagsNode","title":"CandidateBasedFlagsNode","text":" Bases: RegistryNode
Attach candidate-keyword flags derived from the candidate value.
For each flag in the configured mapping, when any keyword appears in the (lower-cased) candidate value and the flag is not already present, the flag is appended to candidate.flags.
property","text":"candidate_based_flag_mapping\nReturn the candidate-keyword flag mapping.
Returns:
Type DescriptionThe mapping dict from the registry.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.CandidateBasedFlagsNode.config","title":"configproperty","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
resolve(state: State) -> Iterable[State]\nAppend matched candidate-keyword flags to the state.
Parameters:
Name Type Description Defaultstate State Pipeline state with a candidate value and flags.
requiredYields:
Name Type DescriptionState Iterable[State] The updated state, or the input state when no flag
Iterable[State] changed.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.CandidateBasedFlagsNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.CandidateBasedFlagsNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Resolve an entity directly from alias regexes.
When entity.name is already set, or no candidate value exists, the state passes through unchanged. Otherwise the first alias regex that matches the candidate produces the entity payload with a confidence delta of -0.25 and the resolved_by=entity_alias metadata marker.
A fork is yielded immediately on the first matching alias; no further aliases are considered.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.EntityAliasNode-attributes","title":"Attributes","text":""},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.EntityAliasNode.config","title":"configproperty","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
property","text":"default_logo_mapping\nReturn the default logo mapping by entity type.
Returns:
Type DescriptionThe mapping dict from the registry, defaulting to
ENTITY_DEFAULT_LOGO_MAPPING.
property","text":"entity_alias_regex\nReturn the compiled alias regex/value pairs.
Returns:
Type DescriptionThe compiled regex-map entries from the registry.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.EntityAliasNode.entity_type_mapping","title":"entity_type_mappingproperty","text":"entity_type_mapping\nReturn the entity-type mapping for assigned entities.
Returns:
Type DescriptionThe mapping dict from the registry, defaulting to
ENTITY_TYPE_MAPPING.
resolve(state: State) -> Iterable[State]\nAssign the entity from the first alias matching the candidate.
Parameters:
Name Type Description Defaultstate State Pipeline state with candidate.value.
Yields:
Name Type DescriptionState Iterable[State] The forked state with the entity payload, or the input
Iterable[State] state when nothing matched.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.EntityAliasNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.EntityAliasNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Extract entity candidates from the normalized signals.
Produces a candidate per regex match and per /-split part; when nothing matched, falls back to canonicalized space-split items and finally to an empty (-0.75) fork. Negative candidates are skipped throughout.
property","text":"candidate_regex\nReturn the compiled candidate extraction regexes.
Returns:
Type DescriptionThe compiled regex list from the registry.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.ExtractCandidatesNode.config","title":"configproperty","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
property","text":"negative_candidates\nReturn the negative candidate tokens to skip.
Returns:
Type DescriptionThe array of negative candidate strings from the registry.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.ExtractCandidatesNode-functions","title":"Functions","text":""},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.ExtractCandidatesNode.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nYield one state fork per extracted candidate.
Parameters:
Name Type Description Defaultstate State Pipeline state with populated signals.
Yields:
Name Type DescriptionState Iterable[State] A forked state per candidate, each carrying
Iterable[State] candidate.value; or a single -0.75 fork when no
Iterable[State] candidate was found.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.ExtractCandidatesNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.ExtractCandidatesNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Assign a last-resort entity when nothing resolved.
Valid candidates become the merchant (-0.25); otherwise the entity falls back to Unknown with type other (-0.50), using the default logo paths.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
resolve(state: State) -> Iterable[State]\nFork the state with a fallback entity.
Parameters:
Name Type Description Defaultstate State Pipeline state with an optional candidate value.
requiredYields:
Name Type DescriptionState Iterable[State] The forked state with the fallback entity payload.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.FallbackNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.FallbackNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Normalize the raw description into signal fields.
Removes the amount/balance number sequences from the description and populates signals.raw, signals.items (space-split) and signals.parts (slash-split) for downstream nodes.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
resolve(state: State) -> Iterable[State]\nFork the state with the normalized description signals.
Parameters:
Name Type Description Defaultstate State Pipeline state with raw.description, raw.amount and raw.balance.
Yields:
Name Type DescriptionState Iterable[State] The forked state carrying the derived signals.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.NormalizeDescriptionNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.NormalizeDescriptionNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Set the entity from flag-based entity rules.
Each rule config may carry all/any conditions over the candidate flags; the first satisfied rule emits its payee as the entity with a resolved_by=set_entity marker. When no rule fires and no entity exists yet, a -0.25 fork is yielded.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
property","text":"default_logo_mapping\nReturn the default logo mapping by entity type.
Returns:
Type DescriptionThe mapping dict from the registry, defaulting to
ENTITY_DEFAULT_LOGO_MAPPING.
property","text":"entity_type_mapping\nReturn the entity-type mapping for assigned entities.
Returns:
Type DescriptionThe mapping dict from the registry, defaulting to
ENTITY_TYPE_MAPPING.
property","text":"flags_based_entity_rules\nReturn the flag-based entity rules.
Returns:
Type DescriptionThe rule list from the registry.
"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.SetEntityNode-functions","title":"Functions","text":""},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.SetEntityNode.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nApply flag-based entity rules and fork the entity state.
Parameters:
Name Type Description Defaultstate State Pipeline state with candidate flags.
requiredYields:
Name Type DescriptionState Iterable[State] The forked state with the entity payload when a rule
Iterable[State] fires; the input state when an entity already exists; or a
Iterable[State] -0.25 fork otherwise.
set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/entity/resolver/#domain.enrichment.entity.resolver.SetEntityNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Text utilities for entity enrichment: description normalization, number sequence removal, candidate validity checks, and candidate extraction.
"},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils-functions","title":"Functions","text":""},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils.extract_candidates","title":"extract_candidates","text":"extract_candidates(\n description: str,\n candidate_regexes: Iterable[re.Pattern],\n) -> List[str]\nExtract 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 Defaultdescription str Description text to scan.
requiredcandidate_regexes Iterable[Pattern] Compiled regexes exposing a payee named group.
Returns:
Type DescriptionList[str] List[str]: Validated, normalized candidate keys.
"},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils.is_valid_candidate","title":"is_valid_candidate","text":"is_valid_candidate(candidate: str) -> bool\nCheck 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 Defaultcandidate str Candidate string to validate.
requiredReturns:
Name Type Descriptionbool bool True when the candidate is usable.
lookup_mapping(candidate: str, mapping: dict)\nLook 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 Defaultcandidate str Candidate to look up.
requiredmapping dict Mapping of normalized keys to MappingValue entries.
Returns:
Type DescriptionA single matching name, a list of substring matches, or
(None, None) for falsy candidates.
normalize_description(text: str) -> str\nNormalize 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 Defaulttext str Raw description text.
requiredReturns:
Name Type Descriptionstr str The normalized, lower-cased description.
"},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils.normalize_money_str","title":"normalize_money_str","text":"normalize_money_str(x) -> str\nFormat a number as a two-decimal string.
Parameters:
Name Type Description Defaultx Value coercible to float.
Returns:
Name Type Descriptionstr str The number formatted to two decimals.
"},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils.normalize_person_handle","title":"normalize_person_handle","text":"normalize_person_handle(handle: str) -> str\nNormalize 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 Defaulthandle str Raw handle string.
requiredReturns:
Name Type Descriptionstr str The normalized person name (possibly empty).
"},{"location":"domain/enrichment/entity/utils/#domain.enrichment.entity.utils.remove_number_sequence","title":"remove_number_sequence","text":"remove_number_sequence(\n text: str, amt: str, bal: str\n) -> str\nStrip 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 Defaulttext str Description text to clean.
requiredamt str Transaction amount, formatted via normalize_money_str.
bal str Balance, formatted via normalize_money_str.
Returns:
Name Type Descriptionstr str The cleaned description with echoed numbers removed.
"},{"location":"domain/enrichment/tags/","title":"Tags","text":"Tag enrichment: pipeline loading and flag/tag nodes.
The loader compiles the packaged tag pipeline and pattern resources; the nodes attach entity-based flags and apply flag-based tag rules to a resolved entity.
"},{"location":"domain/enrichment/tags/flags/","title":"Flags","text":""},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags","title":"domain.enrichment.tags.flags","text":""},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags--summary","title":"Summary","text":"Flag and tag nodes for the tag enrichment pipeline.
Rules nodes derive entity-based flags from the resolved entity and apply flag-based rules to attach tags.
"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags-classes","title":"Classes","text":""},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.EntityBasedFlagsNode","title":"EntityBasedFlagsNode","text":" Bases: RegistryNode
Attach entity-matched flags and reset the tag list.
Keeps only the amount_* candidate flags and, for each entity-based flag whose keyword equals the lower-cased entity name, appends the flag. Always forks with the final flag list and an empty tags list.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
property","text":"entity_based_flag_mapping\nReturn the entity-based flag mapping.
Returns:
Type DescriptionThe mapping dict from the registry.
"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.EntityBasedFlagsNode-functions","title":"Functions","text":""},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.EntityBasedFlagsNode.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nApply entity-matched flags to the state.
Parameters:
Name Type Description Defaultstate State Pipeline state with an entity name and candidate flags.
requiredYields:
Name Type DescriptionState Iterable[State] The forked state with updated flags and empty tags.
"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.EntityBasedFlagsNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.EntityBasedFlagsNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Bases: RegistryNode
Assign tags from flag-based tag rules.
For each rule with all/any conditions satisfied by the candidate flags, appends the rule's emitted tags to the current tag list (avoiding duplicates) and forks when anything changed.
property","text":"config\nReturn the node config installed by the pipeline loader.
Returns:
Type DescriptionThe node configuration dict, or None before wiring.
property","text":"flags_based_tags_rules\nReturn the flag-based tag rules.
Returns:
Type DescriptionThe rule list from the registry.
"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.SetTagsNode-functions","title":"Functions","text":""},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.SetTagsNode.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nApply flag-based tag rules to the state.
Parameters:
Name Type Description Defaultstate State Pipeline state with candidate flags and current tags.
requiredYields:
Name Type DescriptionState Iterable[State] The updated state, or the input state when no tag
Iterable[State] changed.
"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.SetTagsNode.set_config","title":"set_config","text":"set_config(config)\nInstall the node-specific config on this node.
Parameters:
Name Type Description Defaultconfig The config dict read from the pipeline YAML for this node's id.
required"},{"location":"domain/enrichment/tags/flags/#domain.enrichment.tags.flags.SetTagsNode.set_registry","title":"set_registry","text":"set_registry(registry)\nInstall the pattern registry on this node.
Parameters:
Name Type Description Defaultregistry The PatternRegistry instance to use for lookups.
Loader for the tag enrichment pipeline.
Compiles the packaged tag pipeline.yaml plus patterns/*.yaml registries into a cached dagpipe pipeline, wiring every registry-aware node with its registry and node config.
get_tag_pipeline()\nReturn the lazily cached tag pipeline.
Builds (once) and reuses the pipeline across calls.
Returns:
Type DescriptionThe cached tag pipeline instance.
"},{"location":"domain/enrichment/tags/pipeline/#domain.enrichment.tags.pipeline.load","title":"load","text":"load() -> Pipeline\nLoad and wire the tag enrichment pipeline.
Reads the packaged pipeline.yaml, builds the pipeline graph, and installs the merged pattern registry and per-node config onto each node that supports it.
Returns:
Name Type DescriptionPipeline Pipeline The wired dagpipe pipeline.
Raises:
Type DescriptionFileNotFoundError If the packaged pipeline.yaml is missing.
Entity domain: the Entity aggregate, its Mongo document schema, enrichment adaptor, and CRUD service wiring.
"},{"location":"domain/entity/models/","title":"Models","text":""},{"location":"domain/entity/models/#domain.entity.models","title":"domain.entity.models","text":""},{"location":"domain/entity/models/#domain.entity.models--summary","title":"Summary","text":"Define the Entity aggregate model with default-logo resolution.
"},{"location":"domain/entity/models/#domain.entity.models-classes","title":"Classes","text":""},{"location":"domain/entity/models/#domain.entity.models.Entity","title":"Entity","text":" Bases: BaseModel
Entity (payee) model: a merchant, person, transfer, or other kind.
Attributes:
Name Type Descriptionname str Display name of the entity.
type str Entity kind used to pick the default logo, e.g. \"merchant\".
logo str | None Logo URL/path; filled with a per-type default when unset.
NotesGuarantees: After validation, logo is always a non-empty value; a missing logo is replaced using :data:DEFAULT_LOGO_MAP keyed by type.
Port wiring for the entity aggregate: Mongo repository, enrichment adaptor, and CRUD service wiring.
"},{"location":"domain/entity/ports/db/","title":"Db","text":""},{"location":"domain/entity/ports/db/#domain.entity.ports.db","title":"domain.entity.ports.db","text":""},{"location":"domain/entity/ports/db/#domain.entity.ports.db--summary","title":"Summary","text":"Mongo persistence for entities: document schema with an in-memory cache.
"},{"location":"domain/entity/ports/db/#domain.entity.ports.db-classes","title":"Classes","text":""},{"location":"domain/entity/ports/db/#domain.entity.ports.db.EntityDocument","title":"EntityDocument","text":" Bases: Entity, BaseDocument
Mongo document form of :class:Entity read through an in-memory cache.
create_entity_repo()\nCreate a Mongo-backed entity repository with an in-memory cache.
Returns:
Name Type DescriptionAny Mongo-backed entity repository using an in-memory cache backend.
"},{"location":"domain/entity/ports/enrichment/","title":"Enrichment","text":""},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment","title":"domain.entity.ports.enrichment","text":""},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment--summary","title":"Summary","text":"Entity enrichment port: expose the shared entity enrichment pipeline as an async callable.
"},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment-classes","title":"Classes","text":""},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment.EntityEnrichmentAdaptor","title":"EntityEnrichmentAdaptor","text":"EntityEnrichmentAdaptor(**kwargs)\nAdaptor exposing the entity enrichment pipeline as an async callable.
Initialize the adaptor with the shared entity pipeline.
Parameters:
Name Type Description Default**kwargs dict Ignored; kept for dependency-injection compatibility.
{}"},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment.EntityEnrichmentAdaptor-functions","title":"Functions","text":""},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment.EntityEnrichmentAdaptor.__call__","title":"__call__ async","text":"__call__(payload: dict) -> dict\nRun the entity enrichment pipeline on payload.
Parameters:
Name Type Description Defaultpayload dict Enrichment input, e.g. payee text and hints.
requiredReturns:
Name Type Descriptiondict dict Enriched payload carrying the resolved entity information.
"},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment-functions","title":"Functions","text":""},{"location":"domain/entity/ports/enrichment/#domain.entity.ports.enrichment.get_entity_enrichment_svc","title":"get_entity_enrichment_svc","text":"get_entity_enrichment_svc(\n **kwargs,\n) -> EntityEnrichmentAdaptor\nBuild an entity enrichment service adaptor.
Parameters:
Name Type Description Default**kwargs dict Passed through to the adaptor constructor.
{} Returns:
Name Type DescriptionEntityEnrichmentAdaptor EntityEnrichmentAdaptor Ready-to-use entity enrichment adaptor.
"},{"location":"domain/entity/ports/service/","title":"Service","text":""},{"location":"domain/entity/ports/service/#domain.entity.ports.service","title":"domain.entity.ports.service","text":""},{"location":"domain/entity/ports/service/#domain.entity.ports.service--summary","title":"Summary","text":"CRUD service wiring for the entity aggregate via the hexa container.
"},{"location":"domain/entity/ports/service/#domain.entity.ports.service-classes","title":"Classes","text":""},{"location":"domain/entity/ports/service/#domain.entity.ports.service.EntityCrudsService","title":"EntityCrudsService","text":" Bases: CrudsServiceAdaptor[Entity, EntityDocument]
Entity CRUD service resolving :class:Entity documents from a repo.
Instances are created by :func:get_entity_service. The model and schema class attributes bind the domain model and its document type.
get_entity_service(repo) -> EntityCrudsService\nBuild an entity CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed entity repository from :func:create_entity_repo.
Returns:
Name Type DescriptionEntityCrudsService EntityCrudsService Ready-to-use entity CRUD service.
"},{"location":"domain/expense/","title":"Expense","text":"Expense domain: the Expense aggregate, converters, Mongo document schema, and CRUD service wiring.
"},{"location":"domain/expense/models/","title":"Models","text":""},{"location":"domain/expense/models/#domain.expense.models","title":"domain.expense.models","text":""},{"location":"domain/expense/models/#domain.expense.models--summary","title":"Summary","text":"Define the Expense aggregate model (entity, account, tags, and amount) shared across layers.
"},{"location":"domain/expense/models/#domain.expense.models-classes","title":"Classes","text":""},{"location":"domain/expense/models/#domain.expense.models.Expense","title":"Expense","text":" Bases: BaseModel
Expense transaction linking an entity, account, and tags.
Attributes:
Name Type Descriptionentity Entity Payee entity the expense was incurred with.
amount float Transaction amount.
account Account Account the expense was paid from.
tags List[Tag] Tags classified against the expense.
occurred_at str Date the expense occurred, as DD-MM-YYYY.
fetch_request Optional[str] ID of the fetch request that produced the expense; None when not sourced from a request.
Port wiring for expenses: converters, Mongo repository, and CRUD service wiring.
"},{"location":"domain/expense/ports/converters/","title":"Converters","text":""},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters","title":"domain.expense.ports.converters","text":""},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters--summary","title":"Summary","text":"Converters bridging enriched fetch-request output and Expense aggregates for MongoDB storage.
"},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters-classes","title":"Classes","text":""},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters-functions","title":"Functions","text":""},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters.enriched_to_expenses","title":"enriched_to_expensesasync","text":"enriched_to_expenses(\n enriched_list: List[EnrichedExpense],\n fetch_request: FetchRequest,\n entity_svc,\n tag_svc,\n fetch_request_id: Optional[str] = None,\n) -> List[Expense]\nConvert enriched expenses into Expense aggregates ready for storage.
Each enriched expense is expanded into an Expense referencing the account of fetch_request and resolved entity and tag objects.
Parameters:
Name Type Description Defaultenriched_list List[EnrichedExpense] Enriched expenses to convert.
requiredfetch_request FetchRequest Fetch request providing the source account.
requiredentity_svc Any Entity CRUD service used to resolve or create payees.
requiredtag_svc Any Tag CRUD service used to resolve tags by name.
requiredfetch_request_id Optional[str] Fetch request ID recorded on expenses; falls back to fetch_request.id when omitted.
None Returns:
Type DescriptionList[Expense] List[Expense]: Converted expense aggregates.
Raises:
Type DescriptionValueError When an enriched tag name does not exist.
"},{"location":"domain/expense/ports/converters/#domain.expense.ports.converters.expense_to_storage","title":"expense_to_storage","text":"expense_to_storage(expense: Expense) -> None\nConvert Expense FK fields to ObjectIds in-place for MongoDB storage.
Raises ValueError if any FK field lacks an ObjectId \u2014 prevents storing embedded subdocuments instead of references.
Parameters:
Name Type Description Defaultexpense Expense Expense to normalize for storage.
requiredRaises:
Type DescriptionValueError When entity, account, or any tag lacks an ObjectId.
Mongo persistence for expenses: document schema with populated references and repository factory.
"},{"location":"domain/expense/ports/db/#domain.expense.ports.db-classes","title":"Classes","text":""},{"location":"domain/expense/ports/db/#domain.expense.ports.db.ExpenseDocument","title":"ExpenseDocument","text":" Bases: Expense, BaseDocument
Mongo document form of :class:Expense with populated references.
Attributes:
Name Type Descriptionentity EntityDocument Populated payee entity document.
account AccountDocument Populated account document.
tags List[TagDocument] Populated tag documents.
"},{"location":"domain/expense/ports/db/#domain.expense.ports.db-functions","title":"Functions","text":""},{"location":"domain/expense/ports/db/#domain.expense.ports.db.create_expense_repo","title":"create_expense_repo","text":"create_expense_repo(\n entity_repo: Any, account_repo: Any, tag_repo: Any\n)\nCreate a Mongo-backed expense repository wired for reference population.
Parameters:
Name Type Description Defaultentity_repo Any Entity repository used to populate entity.
account_repo Any Account repository used to populate account.
tag_repo Any Tag repository used to populate tags.
Returns:
Name Type DescriptionAny Mongo-backed expense repository configured with entity, account, and tag population rules.
"},{"location":"domain/expense/ports/service/","title":"Service","text":""},{"location":"domain/expense/ports/service/#domain.expense.ports.service","title":"domain.expense.ports.service","text":""},{"location":"domain/expense/ports/service/#domain.expense.ports.service--summary","title":"Summary","text":"CRUD service wiring for the expense aggregate via the hexa container.
"},{"location":"domain/expense/ports/service/#domain.expense.ports.service-classes","title":"Classes","text":""},{"location":"domain/expense/ports/service/#domain.expense.ports.service.ExpenseCrudsService","title":"ExpenseCrudsService","text":" Bases: CrudsServiceAdaptor[Expense, ExpenseDocument]
Expense CRUD service resolving :class:Expense documents from a repo.
Instances are created by :func:get_expense_service. The model and schema class attributes bind the domain model and its document type.
get_expense_service(repo) -> ExpenseCrudsService\nBuild an expense CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed expense repository from :func:create_expense_repo.
Returns:
Name Type DescriptionExpenseCrudsService ExpenseCrudsService Ready-to-use expense CRUD service.
"},{"location":"domain/fetch_pipeline/","title":"Fetch Pipeline","text":"Fetch pipeline domain: orchestrates expense extraction from bank statement sources.
Covers extraction-stage driving (pdf, email, tabular, llama), ambiguity pausing, enrichment, expense persistence, and progress-event streaming, plus the models and ports the orchestrator depends on.
"},{"location":"domain/fetch_pipeline/models/","title":"Models","text":""},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models","title":"domain.fetch_pipeline.models","text":""},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models--summary","title":"Summary","text":"Data models for fetch pipeline progress reporting and ambiguity resolution.
"},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models-classes","title":"Classes","text":""},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models.Ambiguity","title":"Ambiguity","text":" Bases: BaseModel
Record of an ambiguity pause awaiting resolution.
Attributes:
Name Type Descriptionfetch_request_id PyObjectId Owning fetch request.
step_index int Pipeline stage index at which the pause occurred.
line str Raw OCR line that triggered the ambiguity.
ocr_amount float Amount read from the OCR line.
ocr_balance float Balance read from the OCR line.
prev_balance float Balance carried into the ambiguous transaction.
candidates List[AmbiguityCandidate] Amount/balance candidates offered for resolution.
chosen Optional[AmbiguityCandidate] Candidate selected by the resolver, if any.
resolved_at Optional[str] ISO timestamp of resolution, if resolved.
status str Lifecycle status, defaulting to \"pending\".
Bases: BaseModel
Amount/balance pair offered as a resolution candidate.
Attributes:
Name Type Descriptionamount float Candidate transaction amount.
balance float Candidate balance after the transaction.
"},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models.ProgressEvent","title":"ProgressEvent","text":" Bases: BaseModel
SSE progress event emitted while a fetch request runs.
Attributes:
Name Type Descriptionfetch_request_id str Owning fetch request id.
step str Progress step name.
status str Progress status value.
message ProgressMessage Detail payload; defaults to an empty message.
timestamp str ISO timestamp of the event.
"},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models.ProgressMessage","title":"ProgressMessage","text":" Bases: BaseModel
Optional detail payload attached to a progress event.
Attributes:
Name Type Descriptionlines Optional[int] Count of raw lines processed.
blocks Optional[int] Count of transaction blocks produced.
count Optional[int] Count of items at the current step.
unit Optional[str] Unit label for count.
raw_ocr_line Optional[str] Raw OCR line, e.g. the ambiguous line.
error Optional[str] Error message when the step failed.
"},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models.ProgressStatus","title":"ProgressStatus","text":" Bases: str, Enum
Lifecycle status values for a progress step.
Attributes:
Name Type DescriptionSTARTED ProgressStatus Step began.
COMPLETED ProgressStatus Step finished.
SKIPPED ProgressStatus Step was not needed.
PAUSED ProgressStatus Step paused for ambiguity resolution.
PROGRESS ProgressStatus Step is in progress.
FAILED ProgressStatus Step failed.
"},{"location":"domain/fetch_pipeline/models/#domain.fetch_pipeline.models.ProgressStep","title":"ProgressStep","text":" Bases: str, Enum
Pipeline stage names used in progress events.
Attributes:
Name Type DescriptionRAW_LINES ProgressStep Raw OCR line extraction step.
TXN_BLOCKS ProgressStep Transaction block grouping step.
TXN_DICTS ProgressStep Transaction dict construction step.
RESUME_EXTRACT ProgressStep Resume-from-saved-stages step.
EXTRACT ProgressStep Continued extraction step.
PAUSED ProgressStep Ambiguity pause state.
RAW_EXPENSES ProgressStep Raw expense materialization step.
ENRICH_ENTITY ProgressStep Entity enrichment step.
ENRICH_TAGS ProgressStep Tag enrichment step.
SAVE_EXPENSES ProgressStep Expense persistence step.
"},{"location":"domain/fetch_pipeline/ports/","title":"Ports","text":"Ports for the fetch pipeline domain.
Thin adaptors and factories binding persistence, enrichment, messaging and service infrastructure to the domain models.
"},{"location":"domain/fetch_pipeline/ports/db/","title":"Db","text":""},{"location":"domain/fetch_pipeline/ports/db/#domain.fetch_pipeline.ports.db","title":"domain.fetch_pipeline.ports.db","text":""},{"location":"domain/fetch_pipeline/ports/db/#domain.fetch_pipeline.ports.db--summary","title":"Summary","text":"Persistence port for fetch pipeline ambiguity records.
Maps the Ambiguity model to a Mongo-backed document and exposes a repo factory for the ambiguities collection.
Bases: Ambiguity, BaseDocument
Mongo document for ambiguity records.
Combines the domain Ambiguity model with the mongo_ops document base for repository persistence.
create_ambiguity_repo()\nCreate the ambiguity repository backed by Mongo.
Returns:
Type DescriptionRepository over the ambiguities collection.
Enrichment port for the fetch pipeline: orchestrates entity and tag pipelines over raw expenses.
Adapts the domain fetch-request models to the enrichment pipeline state payloads and back to enriched expenses.
"},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment-classes","title":"Classes","text":""},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment.EnrichmentOrchestratorAdaptor","title":"EnrichmentOrchestratorAdaptor","text":"EnrichmentOrchestratorAdaptor(\n *, entity_pipeline=None, tags_pipeline=None\n)\nDrive entity and tag enrichment for raw expenses.
Runs the entity pipeline over a raw expense state payload, builds an EnrichedExpense, then runs the tags pipeline over its payload and fills the tag list.
Attributes:
Name Type Descriptionentity_pipeline Pipeline resolving the payee entity; defaults to the cached entity pipeline.
tags_pipeline Pipeline resolving tags; defaults to the cached tags pipeline.
"},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment.EnrichmentOrchestratorAdaptor-functions","title":"Functions","text":""},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment.EnrichmentOrchestratorAdaptor.enrich","title":"enrichasync","text":"enrich(raw: RawExpense) -> EnrichedExpense\nEnrich a raw expense into an enriched expense.
Parameters:
Name Type Description Defaultraw RawExpense Raw expense parsed from the statement.
requiredReturns:
Name Type DescriptionEnrichedExpense EnrichedExpense The enriched expense with payee, entity
EnrichedExpense metadata and tags.
"},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment-functions","title":"Functions","text":""},{"location":"domain/fetch_pipeline/ports/enrichment/#domain.fetch_pipeline.ports.enrichment.get_enrichment_orchestrator","title":"get_enrichment_orchestrator","text":"get_enrichment_orchestrator(\n **kwargs,\n) -> EnrichmentOrchestratorAdaptor\nBuild an enrichment orchestrator adaptor.
Parameters:
Name Type Description Default**kwargs Optional entity_pipeline / tags_pipeline overrides.
{} Returns:
Name Type DescriptionEnrichmentOrchestratorAdaptor EnrichmentOrchestratorAdaptor A configured orchestrator.
"},{"location":"domain/fetch_pipeline/ports/messaging/","title":"Messaging","text":""},{"location":"domain/fetch_pipeline/ports/messaging/#domain.fetch_pipeline.ports.messaging","title":"domain.fetch_pipeline.ports.messaging","text":""},{"location":"domain/fetch_pipeline/ports/messaging/#domain.fetch_pipeline.ports.messaging--summary","title":"Summary","text":"Messaging port for fetch pipeline progress events.
Wraps the SSE in-memory bus used to stream progress to connected clients.
"},{"location":"domain/fetch_pipeline/ports/messaging/#domain.fetch_pipeline.ports.messaging-classes","title":"Classes","text":""},{"location":"domain/fetch_pipeline/ports/messaging/#domain.fetch_pipeline.ports.messaging.ProgressEventBus","title":"ProgressEventBus","text":"ProgressEventBus()\nPublish and replay progress events for a fetch request.
NotesBacked by an SSEInMemoryBus[ProgressEvent]; events are kept in memory only.
get_events(fr_id: str) -> List[ProgressEvent]\nReturn the events published for a fetch request.
Parameters:
Name Type Description Defaultfr_id str Fetch request id.
requiredReturns:
Type DescriptionList[ProgressEvent] List[ProgressEvent]: Events seen for that request.
"},{"location":"domain/fetch_pipeline/ports/messaging/#domain.fetch_pipeline.ports.messaging.ProgressEventBus.publish","title":"publishasync","text":"publish(event: ProgressEvent) -> None\nPublish a progress event to subscribers.
Parameters:
Name Type Description Defaultevent ProgressEvent The event to broadcast.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"domain/fetch_pipeline/ports/service/","title":"Service","text":""},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service","title":"domain.fetch_pipeline.ports.service","text":""},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service--summary","title":"Summary","text":"Service port for fetch pipeline ambiguity CRUD.
Exposes a Hexa-built CRUD service over the ambiguity model/document.
"},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service-classes","title":"Classes","text":""},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service.AmbiguityCrudsService","title":"AmbiguityCrudsService","text":" Bases: CrudsServiceAdaptor[Ambiguity, AmbiguityDocument]
CRUD service for ambiguity records.
Attributes:
Name Type Descriptionmodel Ambiguity Domain model class.
schema AmbiguityDocument Persistence document class.
"},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service-functions","title":"Functions","text":""},{"location":"domain/fetch_pipeline/ports/service/#domain.fetch_pipeline.ports.service.get_ambiguity_service","title":"get_ambiguity_service","text":"get_ambiguity_service(repo) -> AmbiguityCrudsService\nBuild the ambiguity CRUD service bound to a repo.
Parameters:
Name Type Description Defaultrepo Repository instance used for persistence.
requiredReturns:
Name Type DescriptionAmbiguityCrudsService AmbiguityCrudsService The wired service.
"},{"location":"domain/fetch_pipeline/utils/","title":"Utils","text":"Utility helpers for the fetch pipeline: OCR text handling and pipeline stage driving.
"},{"location":"domain/fetch_pipeline/utils/ocr/","title":"Ocr","text":""},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr","title":"domain.fetch_pipeline.utils.ocr","text":""},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr--summary","title":"Summary","text":"OCR helpers for statement images and PDFs.
Covers number cleaning, tesseract text normalization, PDF rasterization, and per-page OCR with optional binarization.
"},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr-functions","title":"Functions","text":""},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr.clean_num","title":"clean_num","text":"clean_num(s: str) -> float\nParse a numeric token into a float amount.
Strips non-digits and divides by the correct power of ten based on the recorded decimal part; a token without digits yields 0.0.
Parameters:
Name Type Description Defaults str Raw numeric string.
requiredReturns:
Name Type Descriptionfloat float Parsed value.
"},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr.normalize","title":"normalize","text":"normalize(text: str) -> str\nNormalize a raw OCR string for parsing.
Fixes a tesseract digit misread, expands pipes to spaces, trims stray punctuation from the leading edge (including the replacement character), and removes commas.
Parameters:
Name Type Description Defaulttext str Raw OCR output.
requiredReturns:
Name Type Descriptionstr str Normalized text.
"},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr.ocr_all_pages","title":"ocr_all_pages","text":"ocr_all_pages(\n pdf_bytes: bytes, covert_to_image: bool = None\n) -> list\nOCR every page of a PDF in a temporary directory.
With covert_to_image pages are binarized and OCRed with the numeric-mode OEM 3 config; otherwise they are OCRed with the default PSM 6 config.
Parameters:
Name Type Description Defaultpdf_bytes bytes Raw PDF content.
requiredcovert_to_image bool When truthy, binarize pages to images before OCR.
None Returns:
Name Type Descriptionlist list OCR text, one string per page.
"},{"location":"domain/fetch_pipeline/utils/ocr/#domain.fetch_pipeline.utils.ocr.rasterize_pdf","title":"rasterize_pdf","text":"rasterize_pdf(\n pdf_bytes: bytes, out_dir: str, dpi: int = 300\n) -> list\nRasterize a PDF into per-page JPEGs.
Writes the bytes as input.pdf in out_dir and invokes pdftoppm at the requested DPI.
Parameters:
Name Type Description Defaultpdf_bytes bytes Raw PDF content.
requiredout_dir str Directory used to write the PDF and JPEG outputs.
requireddpi int Rasterization resolution, defaults to 300.
300 Returns:
Name Type Descriptionlist list Sorted list of JPEG path strings.
Raises:
Type DescriptionCalledProcessError If pdftoppm fails.
Pipeline orchestration for fetch requests.
Drives extraction stages (pdf, email, tabular, llama), persists partial output on every stage, pauses on ambiguity, enriches raw expenses, saves expense documents, and emits SSE progress events. The orchestrator depends on injected services and the fetch pipeline ports.
"},{"location":"domain/fetch_pipeline/utils/pipeline/#domain.fetch_pipeline.utils.pipeline--notes","title":"Notes","text":"Guarantees:
Lifecycle:
PauseForResolution after saving the paused request state; the caller decides whether to resume later.PipelineOrchestrator(\n fr_svc,\n ambiguity_svc,\n expense_svc,\n pdf_fetcher: PdfFetcher,\n email_fetcher: EmailFetcher,\n xlsx_fetcher: XlsxFetcher,\n csv_fetcher: CsvFetcher,\n sse: ProgressEventBus,\n pause_on_ambiguity: bool = True,\n resolver: Optional[Callable] = None,\n resolved_choices: Optional[dict] = None,\n entity_svc=None,\n tag_svc=None,\n cache_store=None,\n)\nOrchestrate extraction, enrichment and persistence for a fetch request.
Drives the extraction root over fetched content, persists partial stage output, pauses on ambiguity, enriches raw expenses, saves expense documents through the injected services, and streams progress events via the SSE bus.
Attributes:
Name Type Descriptionfr_svc Fetch request service used to read and save the request.
ambiguity_svc Service persisting ambiguity records.
expense_svc Service creating expense documents.
pdf_fetcher PdfFetcher Fetcher for PDF sources.
email_fetcher EmailFetcher Fetcher for email sources.
xlsx_fetcher XlsxFetcher Fetcher for xlsx sources.
csv_fetcher CsvFetcher Fetcher for csv sources.
sse ProgressEventBus Bus streaming progress events.
pause_on_ambiguity bool Whether ambiguity is paused for resolution.
resolver Optional ambiguity resolver callback.
resolved_choices dict Pre-chosen ambiguity resolutions.
entity_svc Optional entity service used for expense creation.
tag_svc Optional tag service used for expense creation.
cache_store Optional read-cache store invalidated after saving.
"},{"location":"domain/fetch_pipeline/utils/pipeline/#domain.fetch_pipeline.utils.pipeline.PipelineOrchestrator-functions","title":"Functions","text":""},{"location":"domain/fetch_pipeline/utils/pipeline/#domain.fetch_pipeline.utils.pipeline.PipelineOrchestrator.run_pipeline","title":"run_pipelineasync","text":"run_pipeline(fr_id: str) -> None\nRun the full fetch pipeline for a request.
Reads the request, builds the extractor, fetches content, extracts raw expenses, enriches them, and persists expense documents.
Parameters:
Name Type Description Defaultfr_id str Fetch request id.
requiredReturns:
Name Type DescriptionNone None Nothing.
NotesAn ambiguity pause is re-raised as PauseForResolution after the paused state has been saved.
Fetch request domain: models and ports describing statement fetch requests.
Covers the fetch request aggregate (source, account, pipeline, trust fallback), raw/enriched expense models, and the persistence and service ports used by the fetch pipeline.
"},{"location":"domain/fetch_request/models/","title":"Models","text":""},{"location":"domain/fetch_request/models/#domain.fetch_request.models","title":"domain.fetch_request.models","text":""},{"location":"domain/fetch_request/models/#domain.fetch_request.models--summary","title":"Summary","text":"Models for fetch requests: source variety, direction and pipeline enums, raw/enriched expenses, and the fetch request aggregate.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models-classes","title":"Classes","text":""},{"location":"domain/fetch_request/models/#domain.fetch_request.models.Bank","title":"Bank","text":" Bases: str, Enum
Supported statement banks.
Attributes:
Name Type DescriptionAXIS Bank Axis Bank.
ICICI Bank ICICI Bank.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.CsvSource","title":"CsvSource","text":" Bases: FileSource
CSV file source.
Attributes:
Name Type Descriptiontype Literal[CSV] Constant source type marker.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.Direction","title":"Direction","text":" Bases: str, Enum
Cashflow direction of a transaction.
Attributes:
Name Type DescriptionDEBIT Direction Money out of the account.
CREDIT Direction Money into the account.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.EmailSource","title":"EmailSource","text":" Bases: Source
Email statement source.
Attributes:
Name Type Descriptionfrom_email str Sender address filter.
subject str Subject line filter.
raw_terms List[str] Free-text search terms.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.EnrichedExpense","title":"EnrichedExpense","text":" Bases: BaseModel
Raw expense with enrichment results attached.
Attributes:
Name Type Descriptionraw_expense RawExpense The source raw expense.
payee str Resolved payee/entity name.
entity_type str Entity type, defaulting to merchant.
entity_logo str | None Logo path/url, if any.
tags List[str] Resolved tags.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.FetchRequest","title":"FetchRequest","text":" Bases: BaseModel
A request to fetch and process a statement.
Attributes:
Name Type Descriptionsource Union[EmailSource, PdfSource, XlsxSource, CsvSource, FileSource] Statement source describing how to fetch the data.
account Account Account the statement belongs to.
start_date datetime Statement window start.
end_date datetime Statement window end.
status str Processing status, defaulting to pending.
pipeline Pipeline Extraction pipeline to use.
trust_fallback Optional[TrustFallback] Optional balance-chain trust policy.
fingerprint str Deduplication fingerprint for the request.
completed_at Optional[datetime] Completion timestamp, if finished.
error_message Optional[str] Failure message, if failed.
retry_count int Number of retries attempted.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.FileSource","title":"FileSource","text":" Bases: Source
File-based statement source.
Attributes:
Name Type Descriptionpath str Path to the uploaded file.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.PdfSource","title":"PdfSource","text":" Bases: FileSource
PDF file source.
Attributes:
Name Type Descriptiontype Literal[PDF] Constant source type marker.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.Pipeline","title":"Pipeline","text":" Bases: str, Enum
Extraction pipeline choice for a fetch request.
Attributes:
Name Type DescriptionHEURISTIC Pipeline Rule/heuristic extraction pipeline.
LLM Pipeline LLM-assisted extraction pipeline.
LLAMA_PARSE Pipeline LlamaParse table-direct extraction pipeline.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.RawExpense","title":"RawExpense","text":" Bases: BaseModel
A single transaction parsed from a statement.
Attributes:
Name Type Descriptiondate str Expense date as DD-MM-YYYY.
amount float Transaction amount.
balance float Account balance after transaction.
description str Complete reconstructed transaction description.
raw_lines List[str] Raw OCR/text lines that form this transaction.
direction Direction Either Direction.DEBIT or Direction.CREDIT.
Bases: BaseModel
Base statement source carrying extraction progress state.
Attributes:
Name Type Descriptionbank Bank Statement bank, defaulting to Bank.ICICI.
type SourceType Source kind discriminator.
raw_lines List[str] Raw OCR/text lines extracted so far.
txn_blocks Dict[str, Any] Transaction blocks keyed by order id.
txn_dicts List[RawExpense] Parsed raw expenses.
enrichment_dicts List[EnrichedExpense] Enriched expenses.
txn_dicts_count int Number of parsed raw expenses.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.SourceType","title":"SourceType","text":" Bases: str, Enum
Statement source kinds.
Attributes:
Name Type DescriptionFILE SourceType Generic file source.
EMAIL SourceType Email source.
PDF SourceType PDF file source.
XLSX SourceType Spreadsheet source.
CSV SourceType CSV source.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.TrustFallback","title":"TrustFallback","text":" Bases: str, Enum
Per-FetchRequest policy for broken balance chains.
When set, resolution skips OCR-style candidate guesswork entirely and always trusts the configured column: - AMOUNT: keep the transaction amount, derive balance as prev \u00b1 amount. - BALANCE: keep the stated balance, derive amount from the balance delta.
Attributes:
Name Type DescriptionAMOUNT TrustFallback Trust the transaction amount; balance is derived as prev \u00b1 amount.
BALANCE TrustFallback Trust the stated balance; amount is derived from the balance delta.
"},{"location":"domain/fetch_request/models/#domain.fetch_request.models.XlsxSource","title":"XlsxSource","text":" Bases: FileSource
XLSX file source.
Attributes:
Name Type Descriptiontype Literal[XLSX] Constant source type marker.
"},{"location":"domain/fetch_request/ports/","title":"Ports","text":"Ports for the fetch request domain.
Thin adaptors and factories binding the Mongo-backed fetch request document and the Hexa-built CRUD service to the domain model.
"},{"location":"domain/fetch_request/ports/db/","title":"Db","text":""},{"location":"domain/fetch_request/ports/db/#domain.fetch_request.ports.db","title":"domain.fetch_request.ports.db","text":""},{"location":"domain/fetch_request/ports/db/#domain.fetch_request.ports.db--summary","title":"Summary","text":"Persistence port for fetch requests.
Maps the FetchRequest model (with a populated account reference) to a Mongo-backed document and exposes the repo factory with population rules.
Bases: FetchRequest, BaseDocument
Mongo document for fetch requests.
Attributes:
Name Type Descriptionaccount AccountDocument Populated account reference.
"},{"location":"domain/fetch_request/ports/db/#domain.fetch_request.ports.db-functions","title":"Functions","text":""},{"location":"domain/fetch_request/ports/db/#domain.fetch_request.ports.db.create_fetch_request_repo","title":"create_fetch_request_repo","text":"create_fetch_request_repo(\n account_repo: Any = None, user_repo: Any = None\n)\nCreate the fetch request repository with account population.
Parameters:
Name Type Description Defaultaccount_repo Any Repository used to populate account references.
None user_repo Any Reserved for user population; currently unused.
None Returns:
Type DescriptionRepository over the fetch_requests collection configured with
population rules.
"},{"location":"domain/fetch_request/ports/service/","title":"Service","text":""},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service","title":"domain.fetch_request.ports.service","text":""},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service--summary","title":"Summary","text":"Service port for fetch requests.
Exposes a Hexa-built CRUD service with stage-saving helpers used by the fetch pipeline orchestrator.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service-classes","title":"Classes","text":""},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService","title":"FetchRequestCrudsService","text":" Bases: CrudsServiceAdaptor[FetchRequest, FetchRequestDocument]
CRUD service for fetch requests with pipeline stage helpers.
Attributes:
Name Type Descriptionmodel FetchRequest Domain model class.
schema FetchRequestDocument Persistence document class.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService-functions","title":"Functions","text":""},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService.save_enrichment","title":"save_enrichmentasync","text":"save_enrichment(\n id: PyObjectId, enrichment_dicts: list\n) -> None\nPersist the enriched expense dicts on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredenrichment_dicts list Enriched expense dicts.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService.save_raw_lines","title":"save_raw_linesasync","text":"save_raw_lines(id: PyObjectId, raw_lines: list) -> None\nPersist the extracted raw lines on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredraw_lines list Raw OCR/text lines.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService.save_txn_blocks","title":"save_txn_blocksasync","text":"save_txn_blocks(id: PyObjectId, txn_blocks: dict) -> None\nPersist the extracted transaction blocks on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredtxn_blocks dict Transaction blocks keyed by order id.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService.save_txn_dicts","title":"save_txn_dictsasync","text":"save_txn_dicts(\n id: PyObjectId, txn_dicts: list, txn_dicts_count: int\n) -> None\nPersist the parsed transaction dicts and count on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredtxn_dicts list Raw expense dicts.
requiredtxn_dicts_count int Number of parsed transaction dicts.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"domain/fetch_request/ports/service/#domain.fetch_request.ports.service.FetchRequestCrudsService.update_status","title":"update_statusasync","text":"update_status(\n id: PyObjectId,\n status: str,\n error_message: Optional[str] = None,\n retry_count: Optional[int] = None,\n) -> bool\nUpdate the request status, optionally carrying failure detail.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredstatus str New status value.
requirederror_message Optional[str] Message recorded when failing.
None retry_count Optional[int] Retry counter recorded when failing.
None Returns:
Name Type Descriptionbool bool True when a document was patched.
Raises:
Type DescriptionValueError If status == \"failed\" and either error_message or retry_count is None.
get_fetch_request_service(repo) -> FetchRequestCrudsService\nBuild the fetch request CRUD service bound to a repo.
Parameters:
Name Type Description Defaultrepo Repository instance used for persistence.
requiredReturns:
Name Type DescriptionFetchRequestCrudsService FetchRequestCrudsService The wired service.
"},{"location":"domain/fetcher/","title":"Fetcher","text":"Fetcher domain: adaptors that pull raw statements from email, spreadsheet, and PDF sources.
"},{"location":"domain/fetcher/ports/","title":"Ports","text":"Port wiring for the fetcher domain: email, spreadsheet, and PDF fetchers.
"},{"location":"domain/fetcher/ports/email/","title":"Email","text":""},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email","title":"domain.fetcher.ports.email","text":""},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email--summary","title":"Summary","text":"Email fetcher: pull statement messages from Gmail and convert them to omniread content.
"},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email-classes","title":"Classes","text":""},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email.EmailFetcher","title":"EmailFetcher","text":"EmailFetcher(\n credentials_path: str,\n token_path: str,\n scopes: List[str],\n)\nFetch emails through Gmail and convert each message to :class:Content.
Lifecycle: Construction performs OAuth credential resolution once; a missing or expired token is refreshed automatically by the credential store.
Initialize the Gmail-backed email reader.
Parameters:
Name Type Description Defaultcredentials_path str Path to the OAuth client credentials JSON.
requiredtoken_path str Path to the persisted OAuth token pickle.
requiredscopes List[str] OAuth scopes to request.
required"},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email.EmailFetcher-functions","title":"Functions","text":""},{"location":"domain/fetcher/ports/email/#domain.fetcher.ports.email.EmailFetcher.fetch","title":"fetch","text":"fetch(query: str) -> List[Content]\nReturn every message matching the Gmail query as content.
Parameters:
Name Type Description Defaultquery str Gmail search query, e.g. from:x label:statements.
Returns:
Type DescriptionList[Content] List[Content]: HTML content per matching message.
"},{"location":"domain/fetcher/ports/file/","title":"File","text":""},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file","title":"domain.fetcher.ports.file","text":""},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file--summary","title":"Summary","text":"File fetchers: read spreadsheet statements (XLSX, CSV) into omniread content.
"},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file-classes","title":"Classes","text":""},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.CsvFetcher","title":"CsvFetcher","text":"CsvFetcher()\nFetch a statement from a CSV file through a filesystem scraper.
"},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.CsvFetcher-functions","title":"Functions","text":""},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.CsvFetcher.fetch","title":"fetchasync","text":"fetch(csv_path: Path) -> Content\nRead the statement content of csv_path.
Parameters:
Name Type Description Defaultcsv_path Path Filesystem path to the CSV file.
requiredReturns:
Name Type DescriptionContent Content Extracted statement content.
"},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.XlsxFetcher","title":"XlsxFetcher","text":"XlsxFetcher()\nFetch a statement from an XLSX file through a filesystem scraper.
"},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.XlsxFetcher-functions","title":"Functions","text":""},{"location":"domain/fetcher/ports/file/#domain.fetcher.ports.file.XlsxFetcher.fetch","title":"fetchasync","text":"fetch(xlsx_path: Path) -> Content\nRead the statement content of xlsx_path.
Parameters:
Name Type Description Defaultxlsx_path Path Filesystem path to the XLSX file.
requiredReturns:
Name Type DescriptionContent Content Extracted statement content.
"},{"location":"domain/fetcher/ports/pdf/","title":"Pdf","text":""},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf","title":"domain.fetcher.ports.pdf","text":""},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf--summary","title":"Summary","text":"PDF fetcher: read statement PDFs into omniread content.
"},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf-classes","title":"Classes","text":""},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf.PdfFetcher","title":"PdfFetcher","text":"PdfFetcher()\nFetch a statement from a PDF file through a filesystem scraper.
"},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf.PdfFetcher-functions","title":"Functions","text":""},{"location":"domain/fetcher/ports/pdf/#domain.fetcher.ports.pdf.PdfFetcher.fetch","title":"fetchasync","text":"fetch(pdf_path: Path) -> Content\nRead the statement content of pdf_path.
Parameters:
Name Type Description Defaultpdf_path Path Filesystem path to the PDF file.
requiredReturns:
Name Type DescriptionContent Content Extracted statement content.
"},{"location":"domain/report/","title":"Report","text":"Report domain: snapshot query and cube models, sparse cube store, and the report service.
"},{"location":"domain/report/models/","title":"Models","text":""},{"location":"domain/report/models/#domain.report.models","title":"domain.report.models","text":""},{"location":"domain/report/models/#domain.report.models--summary","title":"Summary","text":"Report domain models: snapshot query, cube series, and API response.
Pure models plus date/period helpers consumed by the report service. Functions here are side-effect free; they only parse, normalize, and validate report definitions and period labels.
"},{"location":"domain/report/models/#domain.report.models-classes","title":"Classes","text":""},{"location":"domain/report/models/#domain.report.models.Report","title":"Report","text":" Bases: BaseModel
API response for a sliced report view.
Attributes:
Name Type Descriptionid str Snapshot ID the view was served from.
name str Snapshot name.
query ReportQuery Normalized query the snapshot was built from.
generated_at str ISO-8601 timestamp of cube generation.
created_at str ISO-8601 timestamp of snapshot creation.
flow str Flow the view was sliced to.
granularities List[str] Granularities present in the view.
period_ids List[str] All period IDs available, sorted chronologically.
payees List[str] Every payee present in the cube.
tags List[str] Every tag path present in the cube.
buckets List[ReportBucket] Buckets forming the sliced view.
"},{"location":"domain/report/models/#domain.report.models.ReportBucket","title":"ReportBucket","text":" Bases: BaseModel
A flow x group-dimension slice of a report, keyed per granularity.
Attributes:
Name Type Descriptionflow str Flow this bucket covers, e.g. \"inflows\".
group_key Dict[str, List[str]] Dimension filters defining the bucket.
series Dict[str, List[ReportPeriod]] Periods per granularity.
"},{"location":"domain/report/models/#domain.report.models.ReportMetrics","title":"ReportMetrics","text":" Bases: BaseModel
Aggregated metrics over a slice of transactions.
Attributes:
Name Type Descriptionoutflows float Sum of absolute negative amounts.
inflows float Sum of positive amounts.
sum float Net total of all amounts.
count int Number of transactions contributing amounts.
avg float Mean transaction amount.
min float Minimum transaction amount.
max float Maximum transaction amount.
first_date Optional[str] Earliest transaction date, DD-MM-YYYY.
last_date Optional[str] Latest transaction date, DD-MM-YYYY.
cadence Optional[float] Mean gap in days between consecutive dates.
frequency Optional[float] Frequency per day derived from cadence.
"},{"location":"domain/report/models/#domain.report.models.ReportPeriod","title":"ReportPeriod","text":" Bases: BaseModel
One period slice of a cube level: metrics plus the contributing transactions.
Attributes:
Name Type Descriptionperiod_id str Canonical period label.
start Optional[str] Inclusive ISO start boundary.
end Optional[str] Exclusive ISO end boundary.
metrics ReportMetrics Aggregated metrics for the period.
txns List[Any] Transactions contributing to the period.
"},{"location":"domain/report/models/#domain.report.models.ReportQuery","title":"ReportQuery","text":" Bases: BaseModel
Definition of a report snapshot. Bounds the data set; dimensions are sliced at read time.
Attributes:
Name Type Descriptionname str Snapshot name; empty for an auto-generated name.
granularities List[str] Granularities to precompute in the cube.
group_dims List[str] Dimensions to group by, e.g. \"payee\", \"tag\".
flow str Flow filter: inflows, outflows, or both.
accounts Optional[List[str]] Account names to include; all when None.
ignore_self bool Exclude self-transfer tagged expenses.
start_date str Inclusive start boundary, DD-MM-YYYY.
end_date str Inclusive end boundary, DD-MM-YYYY.
min_amount Optional[float] Minimum absolute amount to include.
max_amount Optional[float] Maximum absolute amount to include.
"},{"location":"domain/report/models/#domain.report.models.ReportSnapshot","title":"ReportSnapshot","text":" Bases: BaseModel
Stored metadata for a precomputed report cube.
Attributes:
Name Type Descriptionname str Snapshot name.
query ReportQuery Normalized query the cube was built from.
signature str Canonical fingerprint of the normalized query.
generated_at str ISO-8601 timestamp of cube generation.
"},{"location":"domain/report/models/#domain.report.models-functions","title":"Functions","text":""},{"location":"domain/report/models/#domain.report.models.compute_metrics","title":"compute_metrics","text":"compute_metrics(txns: List[dict]) -> ReportMetrics\nCompute aggregate metrics over a list of transaction dicts.
Parameters:
Name Type Description Defaulttxns List[dict] Transactions with amount and occurred_at keys.
Returns:
Name Type DescriptionReportMetrics ReportMetrics Aggregated metrics; empty (zeroed) metrics when no amounts are present.
"},{"location":"domain/report/models/#domain.report.models.expand_tag_hierarchy","title":"expand_tag_hierarchy","text":"expand_tag_hierarchy(tag_path: str) -> List[str]\nGiven 'food,restaurants' return ['food', 'food,restaurants'] (every ancestor prefix).
Parameters:
Name Type Description Defaulttag_path str Comma-joined tag hierarchy path, or \"untagged\".
Returns:
Type DescriptionList[str] List[str]: Every ancestor prefix of the path, or [\"untagged\"].
normalize_date(value: str) -> str\nCanonicalize a date to the DD-MM-YYYY format (no time).
Parameters:
Name Type Description Defaultvalue str Date string in any supported input format.
requiredReturns:
Name Type Descriptionstr str Date in canonical DD-MM-YYYY form.
Raises:
Type DescriptionValueError When the value cannot be parsed as a date.
"},{"location":"domain/report/models/#domain.report.models.normalize_granularities","title":"normalize_granularities","text":"normalize_granularities(\n values: Optional[Union[str, Sequence[str]]] = None,\n) -> List[str]\nCanonicalize + validate the granularities to precompute. Empty/default -> all period types.
Parameters:
Name Type Description Defaultvalues Optional[Union[str, Sequence[str]]] Granularity names, a single name, or None for the defaults.
None Returns:
Type DescriptionList[str] List[str]: Deduplicated, canonical granularity names.
Raises:
Type DescriptionValueError When a value is not a supported granularity.
"},{"location":"domain/report/models/#domain.report.models.normalize_period_label","title":"normalize_period_label","text":"normalize_period_label(value: str, granularity: str) -> str\nCanonicalize a period label to the period_key format for a granularity.
Parameters:
Name Type Description Defaultvalue str Raw period label, e.g. W03-2024 or Q2-2024.
granularity str Granularity the label belongs to.
requiredReturns:
Name Type Descriptionstr str Canonical period label, or the input unchanged when it cannot be normalized.
"},{"location":"domain/report/models/#domain.report.models.parse_date","title":"parse_date","text":"parse_date(value: str) -> Optional[datetime.date]\nParse a date string into a date, else None.
Parameters:
Name Type Description Defaultvalue str Date string in DD-MM-YYYY, YYYY-MM-DD, or DD/MM/YYYY form.
requiredReturns:
Type DescriptionOptional[date] Optional[datetime.date]: The parsed date, or None when unparseable.
period_bounds(dt: datetime.date, period_type: str)\nCalendar (start, end) boundaries for a period, as dates. end is exclusive.
Parameters:
Name Type Description Defaultdt date Any date inside the period.
requiredperiod_type str Granularity: daily, weekly, monthly, quarterly, or yearly.
requiredReturns:
Name Type Descriptiontuple (start, end) date boundaries; end is exclusive.
Raises:
Type DescriptionValueError When the period type is unknown.
"},{"location":"domain/report/models/#domain.report.models.period_key","title":"period_key","text":"period_key(dt: datetime.date, period_type: str) -> str\nReturn the period label containing dt for a granularity.
Parameters:
Name Type Description Defaultdt date Date to bucket.
requiredperiod_type str Granularity: daily, weekly, monthly, quarterly, yearly, or all.
requiredReturns:
Name Type Descriptionstr str Canonical period label for the given granularity.
Raises:
Type DescriptionValueError When the period type is unknown.
"},{"location":"domain/report/models/#domain.report.models.period_sort_key","title":"period_sort_key","text":"period_sort_key(label: str)\nChronological sort key for a concrete period label (within one granularity).
Parameters:
Name Type Description Defaultlabel str Period label, e.g. 2024-W03, 2024-Jun, or 2024.
Returns:
Name Type Descriptiontuple Sort key of (year, sub) where sub ranks within the year.
quarterly_label(year: int, quarter: int) -> str\nBuild the canonical label for a calendar quarter.
Parameters:
Name Type Description Defaultyear int Four-digit calendar year.
requiredquarter int Quarter number in 1..4.
Returns:
Name Type Descriptionstr str Quarterly label, e.g. 2024-Apr-Jun.
range_label(\n start_date: str = \"\", end_date: str = \"\"\n) -> str\nBuild the start:end range label for a date window ('' when unbounded).
Parameters:
Name Type Description Defaultstart_date str Start boundary date; empty for unbounded start.
'' end_date str End boundary date; empty for unbounded end.
'' Returns:
Name Type Descriptionstr str start:end label, or an empty string when both bounds are empty.
Raises:
Type DescriptionValueError When the start date is after the end date.
"},{"location":"domain/report/ports/","title":"Ports","text":"Port wiring for reports: Mongo repository, cube store, and the report service.
"},{"location":"domain/report/ports/db/","title":"Db","text":""},{"location":"domain/report/ports/db/#domain.report.ports.db","title":"domain.report.ports.db","text":""},{"location":"domain/report/ports/db/#domain.report.ports.db--summary","title":"Summary","text":"Mongo persistence for report snapshots: document schema and repository factory.
"},{"location":"domain/report/ports/db/#domain.report.ports.db-classes","title":"Classes","text":""},{"location":"domain/report/ports/db/#domain.report.ports.db.ReportSnapshotDocument","title":"ReportSnapshotDocument","text":" Bases: ReportSnapshot, BaseDocument
Mongo document form of :class:ReportSnapshot storing the cube metadata.
create_report_repo()\nCreate a Mongo-backed report snapshot repository.
Returns:
Name Type DescriptionAny Mongo-backed report snapshot repository.
"},{"location":"domain/report/ports/service/","title":"Service","text":""},{"location":"domain/report/ports/service/#domain.report.ports.service","title":"domain.report.ports.service","text":""},{"location":"domain/report/ports/service/#domain.report.ports.service--summary","title":"Summary","text":"Report service: validate snapshot queries, precompute sparse cubes, and synthesize sliced report views.
A snapshot is keyed by the canonical signature of its normalized query; the sparse cube data lives in the configured :class:ReportStore while snapshot metadata is persisted through the report repository.
ReportService(\n expense_svc: ExpenseCrudsService,\n tag_svc: TagCrudsService,\n store: ReportStore,\n report_repo=None,\n)\nBuild, persist, and serve precomputed report snapshots.
NotesInstances are created by :func:get_report_service. The service scans expenses in batches, expands tag hierarchies, and persists period series into the configured :class:ReportStore.
Initialize the report service with its dependencies.
Parameters:
Name Type Description Defaultexpense_svc ExpenseCrudsService Expense CRUD service used as the cube source.
requiredtag_svc TagCrudsService Tag CRUD service used to expand tag hierarchies and resolve ignore tags.
requiredstore ReportStore Key-value store for cube period data.
requiredreport_repo Any Report snapshot repository; defaults to :func:create_report_repo when omitted.
None"},{"location":"domain/report/ports/service/#domain.report.ports.service.ReportService-functions","title":"Functions","text":""},{"location":"domain/report/ports/service/#domain.report.ports.service.ReportService.delete_snapshot","title":"delete_snapshot async","text":"delete_snapshot(report_id: str) -> bool\nDelete a snapshot and all of its cube keys from the store.
Parameters:
Name Type Description Defaultreport_id str Snapshot ID to delete.
requiredReturns:
Name Type Descriptionbool bool True when the snapshot existed and was deleted.
async","text":"fetch_report(\n report_id: str,\n granularities: Optional[List[str]] = None,\n period_ids: Optional[List[str]] = None,\n flow: str = \"outflows\",\n payees: Optional[List[str]] = None,\n tags: Optional[List[str]] = None,\n) -> Optional[Report]\nSlice a stored snapshot into a report API response.
\"*\" in payees or tags expands to every value stored in the cube meta.
Parameters:
Name Type Description Defaultreport_id str Snapshot ID to slice.
requiredgranularities Optional[List[str]] Granularities to include; defaults to the snapshot's own.
None period_ids Optional[List[str]] Period labels to filter to.
None flow str Flow to serve; both includes inflows and outflows.
'outflows' payees Optional[List[str]] Payee filters applied per bucket.
None tags Optional[List[str]] Tag path filters applied per bucket.
None Returns:
Type DescriptionOptional[Report] Optional[Report]: The sliced report view, or None when the snapshot does not exist.
async","text":"generate_snapshot(\n query: ReportQuery,\n) -> ReportSnapshotDocument\nValidate a query and return an existing or newly built snapshot.
If a snapshot with the same canonical signature already exists it is returned directly; otherwise a fresh cube is built and persisted.
Parameters:
Name Type Description Defaultquery ReportQuery Raw snapshot definition.
requiredReturns:
Name Type DescriptionReportSnapshotDocument ReportSnapshotDocument The existing or newly created snapshot.
"},{"location":"domain/report/ports/service/#domain.report.ports.service.ReportService.list_snapshots","title":"list_snapshotsasync","text":"list_snapshots(\n offset: int = 0, limit: int = DEFAULT_LIMIT\n) -> List[ReportSnapshotDocument]\nList stored snapshots, newest first.
Parameters:
Name Type Description Defaultoffset int Number of snapshots to skip.
0 limit int Maximum number of snapshots to return.
DEFAULT_LIMIT Returns:
Type DescriptionList[ReportSnapshotDocument] List[ReportSnapshotDocument]: Snapshots ordered by creation time, newest first.
"},{"location":"domain/report/ports/service/#domain.report.ports.service-functions","title":"Functions","text":""},{"location":"domain/report/ports/service/#domain.report.ports.service.get_report_service","title":"get_report_service","text":"get_report_service(\n expense_svc, tag_svc, store, report_repo=None\n) -> ReportService\nBuild a report service with the given dependencies.
Parameters:
Name Type Description Defaultexpense_svc Any Expense CRUD service used as the cube source.
requiredtag_svc Any Tag CRUD service used to expand tag hierarchies.
requiredstore Any Report store backing cube data.
requiredreport_repo Any Report snapshot repository; defaults to :func:create_report_repo when omitted.
None Returns:
Name Type DescriptionReportService ReportService Ready-to-use report service.
"},{"location":"domain/report/ports/service/#domain.report.ports.service.query_signature","title":"query_signature","text":"query_signature(query: ReportQuery) -> str\nCanonical fingerprint of a snapshot definition (list order-insensitive).
Parameters:
Name Type Description Defaultquery ReportQuery Snapshot definition to fingerprint.
requiredReturns:
Name Type Descriptionstr str SHA-256 hex digest of the normalized definition.
"},{"location":"domain/report/ports/store/","title":"Store","text":""},{"location":"domain/report/ports/store/#domain.report.ports.store","title":"domain.report.ports.store","text":""},{"location":"domain/report/ports/store/#domain.report.ports.store--summary","title":"Summary","text":"Sparse key-value store that backs precomputed report cubes outside Mongo.
Implementations should map each method onto a persistent backend (e.g. Redis); every method below raises NotImplementedError in the base class until overridden.
String key-value store used to persist report cube data.
Methods are asynchronous; all raise NotImplementedError in this base class and are expected to be overridden by concrete backends.
async","text":"clear() -> None\nRemove every entry this store holds.
Raises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/report/ports/store/#domain.report.ports.store.ReportStore.close","title":"closeasync","text":"close() -> None\nRelease any resources held by the store.
Raises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/report/ports/store/#domain.report.ports.store.ReportStore.delete","title":"deleteasync","text":"delete(key: str) -> None\nRemove the entry stored under key.
Parameters:
Name Type Description Defaultkey str Storage key to remove.
requiredRaises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/report/ports/store/#domain.report.ports.store.ReportStore.get","title":"getasync","text":"get(key: str) -> Optional[str]\nReturn the value stored under key, or None when absent.
Parameters:
Name Type Description Defaultkey str Storage key.
requiredReturns:
Type DescriptionOptional[str] Optional[str]: Stored value, or None.
Raises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/report/ports/store/#domain.report.ports.store.ReportStore.scan","title":"scanasync","text":"scan(pattern: str) -> List[str]\nReturn every stored key matching pattern.
Parameters:
Name Type Description Defaultpattern str Key pattern, e.g. cube:abc:*.
Returns:
Type DescriptionList[str] List[str]: Matching keys.
Raises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/report/ports/store/#domain.report.ports.store.ReportStore.set","title":"setasync","text":"set(key: str, value: str) -> None\nStore value under key, overwriting any existing entry.
Parameters:
Name Type Description Defaultkey str Storage key.
requiredvalue str Value to store.
requiredRaises:
Type DescriptionNotImplementedError Base class contract.
"},{"location":"domain/tag/","title":"Tag","text":"Tag domain: the Tag aggregate, Mongo document schema, enrichment adaptor, and CRUD service wiring.
"},{"location":"domain/tag/models/","title":"Models","text":""},{"location":"domain/tag/models/#domain.tag.models","title":"domain.tag.models","text":""},{"location":"domain/tag/models/#domain.tag.models--summary","title":"Summary","text":"Define the Tag aggregate model shared by the service and storage layers.
"},{"location":"domain/tag/models/#domain.tag.models-classes","title":"Classes","text":""},{"location":"domain/tag/models/#domain.tag.models.Tag","title":"Tag","text":" Bases: BaseModel
Tag aggregate: a named classification label, optionally nested.
Attributes:
Name Type Descriptionname str Tag name, e.g. \"food\".
icon str Icon key rendered for the tag.
parent_id Optional[str] ID of the parent tag; None for a root tag.
Port wiring for the tag aggregate: Mongo repository, enrichment adaptor, and CRUD service wiring.
"},{"location":"domain/tag/ports/db/","title":"Db","text":""},{"location":"domain/tag/ports/db/#domain.tag.ports.db","title":"domain.tag.ports.db","text":""},{"location":"domain/tag/ports/db/#domain.tag.ports.db--summary","title":"Summary","text":"Mongo persistence for tags: document schema with an in-memory cache.
"},{"location":"domain/tag/ports/db/#domain.tag.ports.db-classes","title":"Classes","text":""},{"location":"domain/tag/ports/db/#domain.tag.ports.db.TagDocument","title":"TagDocument","text":" Bases: Tag, BaseDocument
Mongo document form of :class:Tag read through an in-memory cache.
create_tag_repo()\nCreate a Mongo-backed tag repository with an in-memory cache.
Returns:
Name Type DescriptionAny Mongo-backed tag repository using an in-memory cache backend.
"},{"location":"domain/tag/ports/enrichment/","title":"Enrichment","text":""},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment","title":"domain.tag.ports.enrichment","text":""},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment--summary","title":"Summary","text":"Tag enrichment port: expose the shared tag enrichment pipeline as an async callable.
"},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment-classes","title":"Classes","text":""},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment.TagEnrichmentAdaptor","title":"TagEnrichmentAdaptor","text":"TagEnrichmentAdaptor(**kwargs)\nAdaptor exposing the tag enrichment pipeline as an async callable.
Initialize the adaptor with the shared tags pipeline.
Parameters:
Name Type Description Default**kwargs dict Ignored; kept for dependency-injection compatibility.
{}"},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment.TagEnrichmentAdaptor-functions","title":"Functions","text":""},{"location":"domain/tag/ports/enrichment/#domain.tag.ports.enrichment.TagEnrichmentAdaptor.__call__","title":"__call__ async","text":"__call__(payload: dict) -> dict\nRun the tag enrichment pipeline on payload.
Defaults the tags key to [\"misc\"] when the pipeline produces nothing.
Parameters:
Name Type Description Defaultpayload dict Enrichment input, e.g. expense text and hints.
requiredReturns:
Name Type Descriptiondict dict Enriched payload whose tags list is always non-empty.
get_tag_enrichment_svc(**kwargs) -> TagEnrichmentAdaptor\nBuild a tag enrichment service adaptor.
Parameters:
Name Type Description Default**kwargs dict Passed through to the adaptor constructor.
{} Returns:
Name Type DescriptionTagEnrichmentAdaptor TagEnrichmentAdaptor Ready-to-use tag enrichment adaptor.
"},{"location":"domain/tag/ports/service/","title":"Service","text":""},{"location":"domain/tag/ports/service/#domain.tag.ports.service","title":"domain.tag.ports.service","text":""},{"location":"domain/tag/ports/service/#domain.tag.ports.service--summary","title":"Summary","text":"CRUD service wiring for the tag aggregate via the hexa container.
"},{"location":"domain/tag/ports/service/#domain.tag.ports.service-classes","title":"Classes","text":""},{"location":"domain/tag/ports/service/#domain.tag.ports.service.TagCrudsService","title":"TagCrudsService","text":" Bases: CrudsServiceAdaptor[Tag, TagDocument]
Tag CRUD service resolving :class:Tag documents from a repo.
Instances are created by :func:get_tag_service. The model and schema class attributes bind the domain model and its document type. An additional lookup helper get_by_names is provided.
async","text":"get_by_names(names: list[str])\nReturn tags whose names match any of the provided values.
Parameters:
Name Type Description Defaultnames list[str] Tag names to look up.
requiredReturns:
Name Type Descriptionlist Matching tag documents.
"},{"location":"domain/tag/ports/service/#domain.tag.ports.service-functions","title":"Functions","text":""},{"location":"domain/tag/ports/service/#domain.tag.ports.service.get_tag_service","title":"get_tag_service","text":"get_tag_service(repo) -> TagCrudsService\nBuild a tag CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed tag repository from :func:create_tag_repo.
Returns:
Name Type DescriptionTagCrudsService TagCrudsService Ready-to-use tag CRUD service.
"},{"location":"domain/upload/","title":"Upload","text":"Upload domain: the UploadResult model, Mongo document schema, and CRUD service wiring.
"},{"location":"domain/upload/models/","title":"Models","text":""},{"location":"domain/upload/models/#domain.upload.models","title":"domain.upload.models","text":""},{"location":"domain/upload/models/#domain.upload.models--summary","title":"Summary","text":"Define the UploadResult model returned after storing an uploaded file.
"},{"location":"domain/upload/models/#domain.upload.models-classes","title":"Classes","text":""},{"location":"domain/upload/models/#domain.upload.models.UploadResult","title":"UploadResult","text":" Bases: BaseModel
Metadata describing a stored file upload.
Attributes:
Name Type Descriptionoriginal_filename str Name of the file as uploaded by the client.
saved_as str Name the file was stored under on disk.
content_type str MIME type of the uploaded file.
url str Public URL serving the stored file.
absolute_path str Absolute filesystem path of the stored file.
"},{"location":"domain/upload/ports/","title":"Ports","text":"Port wiring for uploads: Mongo repository and CRUD service wiring.
"},{"location":"domain/upload/ports/db/","title":"Db","text":""},{"location":"domain/upload/ports/db/#domain.upload.ports.db","title":"domain.upload.ports.db","text":""},{"location":"domain/upload/ports/db/#domain.upload.ports.db--summary","title":"Summary","text":"Mongo persistence for upload results: document schema and repository factory.
"},{"location":"domain/upload/ports/db/#domain.upload.ports.db-classes","title":"Classes","text":""},{"location":"domain/upload/ports/db/#domain.upload.ports.db.UploadResultDocument","title":"UploadResultDocument","text":" Bases: UploadResult, BaseDocument
Mongo document form of :class:UploadResult.
create_upload_repo()\nCreate a Mongo-backed upload result repository.
Returns:
Name Type DescriptionAny Mongo-backed upload result repository.
"},{"location":"domain/upload/ports/service/","title":"Service","text":""},{"location":"domain/upload/ports/service/#domain.upload.ports.service","title":"domain.upload.ports.service","text":""},{"location":"domain/upload/ports/service/#domain.upload.ports.service--summary","title":"Summary","text":"CRUD service wiring for upload results via the hexa container.
"},{"location":"domain/upload/ports/service/#domain.upload.ports.service-classes","title":"Classes","text":""},{"location":"domain/upload/ports/service/#domain.upload.ports.service.UploadCrudsService","title":"UploadCrudsService","text":" Bases: CrudsServiceAdaptor[UploadResult, UploadResultDocument]
Upload result CRUD service resolving :class:UploadResult documents.
Instances are created by :func:get_upload_service. The model and schema class attributes bind the domain model and its document type.
get_upload_service(repo) -> UploadCrudsService\nBuild an upload result CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed upload repository from :func:create_upload_repo.
Returns:
Name Type DescriptionUploadCrudsService UploadCrudsService Ready-to-use upload result CRUD service.
"},{"location":"domain/user/","title":"User","text":"User domain: the User aggregate, Mongo document schema, and CRUD service wiring.
"},{"location":"domain/user/models/","title":"Models","text":""},{"location":"domain/user/models/#domain.user.models","title":"domain.user.models","text":""},{"location":"domain/user/models/#domain.user.models--summary","title":"Summary","text":"Define the User aggregate model shared by the service and storage layers.
"},{"location":"domain/user/models/#domain.user.models-classes","title":"Classes","text":""},{"location":"domain/user/models/#domain.user.models.User","title":"User","text":" Bases: BaseModel
User aggregate: identity information for an account owner.
Attributes:
Name Type Descriptionname str Display name of the user; empty when unknown.
username str Unique username of the user.
email str Email address of the user.
"},{"location":"domain/user/ports/","title":"Ports","text":"Port wiring for the user aggregate: Mongo repository and CRUD service wiring.
"},{"location":"domain/user/ports/db/","title":"Db","text":""},{"location":"domain/user/ports/db/#domain.user.ports.db","title":"domain.user.ports.db","text":""},{"location":"domain/user/ports/db/#domain.user.ports.db--summary","title":"Summary","text":"Mongo persistence for users: document schema and repository factory.
"},{"location":"domain/user/ports/db/#domain.user.ports.db-classes","title":"Classes","text":""},{"location":"domain/user/ports/db/#domain.user.ports.db.UserDocument","title":"UserDocument","text":" Bases: User, BaseDocument
Mongo document form of :class:User.
create_user_repo()\nCreate a Mongo-backed user repository.
Returns:
Name Type DescriptionAny Mongo-backed user repository.
"},{"location":"domain/user/ports/service/","title":"Service","text":""},{"location":"domain/user/ports/service/#domain.user.ports.service","title":"domain.user.ports.service","text":""},{"location":"domain/user/ports/service/#domain.user.ports.service--summary","title":"Summary","text":"CRUD service wiring for the user aggregate via the hexa container.
"},{"location":"domain/user/ports/service/#domain.user.ports.service-classes","title":"Classes","text":""},{"location":"domain/user/ports/service/#domain.user.ports.service.UserCrudsService","title":"UserCrudsService","text":" Bases: CrudsServiceAdaptor[User, UserDocument]
User CRUD service resolving :class:User documents from a repo.
Instances are created by :func:get_user_service. The model and schema class attributes bind the domain model and its document type.
get_user_service(repo) -> UserCrudsService\nBuild a user CRUD service wired to repo.
Parameters:
Name Type Description Defaultrepo Any Mongo-backed user repository from :func:create_user_repo.
Returns:
Name Type DescriptionUserCrudsService UserCrudsService Ready-to-use user CRUD service.
"},{"location":"infra/","title":"Infra","text":"Infrastructure layer for the Expenses Service.
Provide adapters, database repositories, and LLM provider pools that implement the ports declared by the domain layer.
"},{"location":"infra/http_cache/","title":"Http Cache","text":""},{"location":"infra/http_cache/#infra.http_cache","title":"infra.http_cache","text":""},{"location":"infra/http_cache/#infra.http_cache--summary","title":"Summary","text":"Domain-agnostic HTTP response cache.
A thin Redis-backed response cache that wraps route handlers as a decorator.
Examplefrom infra.http_cache import cache_response\n\n@cache_response(ttl=60)\nasync def list_entities(request, skip: int = 0, limit: int = 100):\n ...\nThe cache is independent of the report cache (apicache:* vs report:* key namespaces) and of Mongo's cached repositories \u2014 it operates directly on the endpoint. Cached responses expire via TTL (default settings.cache_ttl). When no http_cache_store is wired on request.app.state.db_resources the decorator is a no-op pass-through, so applying/removing it is safe and trivial.
HttpCacheStore(\n url: str = \"redis://localhost:6379/0\",\n decode_responses: bool = True,\n)\nStore string responses in Redis with TTL under the apicache: key space.
Attributes:
Name Type Description_redis Redis Asynchronous Redis client bound to the configured URL.
Initialize the store with a Redis connection.
Parameters:
Name Type Description Defaulturl str Redis connection URL.
'redis://localhost:6379/0' decode_responses bool Whether Redis returns decoded strings.
True"},{"location":"infra/http_cache/#infra.http_cache.HttpCacheStore-functions","title":"Functions","text":""},{"location":"infra/http_cache/#infra.http_cache.HttpCacheStore.close","title":"close async","text":"close() -> None\nClose the underlying Redis connection.
"},{"location":"infra/http_cache/#infra.http_cache.HttpCacheStore.delete","title":"deleteasync","text":"delete(key: str) -> None\nDelete the value stored at key.
Parameters:
Name Type Description Defaultkey str Cache key to remove.
required"},{"location":"infra/http_cache/#infra.http_cache.HttpCacheStore.generation","title":"generationasync","text":"generation(resource: str) -> str\nReturn the current generation counter for a resource namespace.
Parameters:
Name Type Description Defaultresource str Resource namespace to read.
requiredReturns:
Name Type Descriptionstr str Generation counter, or \"0\" when unset.
async","text":"get(key: str) -> Optional[str]\nRead the value stored at key.
Parameters:
Name Type Description Defaultkey str Cache key to read.
requiredReturns:
Type DescriptionOptional[str] Optional[str]: Cached value, or None when absent.
async","text":"invalidate(*resources: str) -> None\nInvalidate all cached responses for the given resource namespaces.
Parameters:
Name Type Description Default*resources str Resource namespaces to invalidate.
() Notes Bumps each namespace's generation counter so existing entries become unreachable immediately; Redis reclaims them at TTL expiry.
"},{"location":"infra/http_cache/#infra.http_cache.HttpCacheStore.set","title":"setasync","text":"set(key: str, value: str, ttl: int) -> None\nStore value at key with a TTL.
Parameters:
Name Type Description Defaultkey str Cache key to write.
requiredvalue str Serialized value to persist.
requiredttl int Lifetime in seconds.
required"},{"location":"infra/http_cache/#infra.http_cache-functions","title":"Functions","text":""},{"location":"infra/http_cache/#infra.http_cache.cache_response","title":"cache_response","text":"cache_response(ttl: Optional[int] = None) -> Callable\nDecorate a GET-style route handler to cache its JSON response.
Parameters:
Name Type Description Defaultttl Optional[int] Cache lifetime in seconds; defaults to settings.cache_ttl.
None Returns:
Name Type DescriptionCallable Callable Decorator that wraps the route handler.
NotesThe wrapped handler must accept a request: Request parameter (as every openapi_first handler does). Responses that are already a fastapi.Response (for example 204) are returned untouched and never cached. When no http_cache_store is wired on request.app.state.db_resources the decorator passes through to the handler without caching.
Infrastructure adapters for the Expenses Service.
Group concrete adapter implementations for report storage, CRUD services, and in-memory SSE event publication.
"},{"location":"infra/adapters/redis/","title":"Redis","text":""},{"location":"infra/adapters/redis/#infra.adapters.redis","title":"infra.adapters.redis","text":""},{"location":"infra/adapters/redis/#infra.adapters.redis--summary","title":"Summary","text":"Redis-backed implementation of the report store port.
Persist and scan report payloads in Redis under the report:* key space.
RedisStoreAdaptor(\n url: str = \"redis://localhost:6379/0\",\n decode_responses: bool = True,\n)\n Bases: ReportStore
Adapt a Redis client to the report store port.
Attributes:
Name Type Description_redis Redis Asynchronous Redis client bound to the configured URL.
Initialize the adaptor with a Redis connection.
Parameters:
Name Type Description Defaulturl str Redis connection URL.
'redis://localhost:6379/0' decode_responses bool Whether Redis returns decoded strings.
True"},{"location":"infra/adapters/redis/#infra.adapters.redis.RedisStoreAdaptor-functions","title":"Functions","text":""},{"location":"infra/adapters/redis/#infra.adapters.redis.RedisStoreAdaptor.clear","title":"clear async","text":"clear() -> None\nDelete every report key from the store.
NotesScans REPORT_PREFIX and removes all matching keys in one call.
async","text":"close() -> None\nClose the underlying Redis connection.
"},{"location":"infra/adapters/redis/#infra.adapters.redis.RedisStoreAdaptor.delete","title":"deleteasync","text":"delete(key: str) -> None\nDelete the value stored at key.
Parameters:
Name Type Description Defaultkey str Redis key to remove.
required"},{"location":"infra/adapters/redis/#infra.adapters.redis.RedisStoreAdaptor.get","title":"getasync","text":"get(key: str) -> Optional[str]\nRead the value stored at key.
Parameters:
Name Type Description Defaultkey str Redis key to read.
requiredReturns:
Type DescriptionOptional[str] Optional[str]: Stored value, or None when the key is absent.
async","text":"scan(pattern: str) -> List[str]\nList keys matching pattern.
Parameters:
Name Type Description Defaultpattern str Glob-style key pattern.
requiredReturns:
Type DescriptionList[str] List[str]: Matching keys.
"},{"location":"infra/adapters/redis/#infra.adapters.redis.RedisStoreAdaptor.set","title":"setasync","text":"set(key: str, value: str) -> None\nStore value at key.
Parameters:
Name Type Description Defaultkey str Redis key to write.
requiredvalue str Serialized value to persist.
required"},{"location":"infra/adapters/service/","title":"Service","text":""},{"location":"infra/adapters/service/#infra.adapters.service","title":"infra.adapters.service","text":""},{"location":"infra/adapters/service/#infra.adapters.service--summary","title":"Summary","text":"Generic CRUD service adaptor over a Mongo repository.
Bridge pydantic models and mongo-ops documents, exposing create, read, update, patch, delete, and search operations for every domain that needs them.
"},{"location":"infra/adapters/service/#infra.adapters.service-classes","title":"Classes","text":""},{"location":"infra/adapters/service/#infra.adapters.service.CrudsServiceAdaptor","title":"CrudsServiceAdaptor","text":"CrudsServiceAdaptor(*, repo=None)\n Bases: Generic[Model, Schema]
Adapt a generic Mongo repository to a model/schema CRUD service.
Attributes:
Name Type Descriptionrepo BaseRepository Repository backing all CRUD operations.
model Type[Model] Pydantic model type handled by this service.
schema Type[Schema] Document schema type persisted by the repository.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"infra/adapters/service/#infra.adapters.service.CrudsServiceAdaptor-functions","title":"Functions","text":""},{"location":"infra/adapters/service/#infra.adapters.service.CrudsServiceAdaptor.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"infra/adapters/service/#infra.adapters.service.CrudsServiceAdaptor.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"infra/adapters/service/#infra.adapters.service.CrudsServiceAdaptor.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
SSEInMemoryBus \u2014 in-memory event bus for SSE progress events.
Buffer published progress events so they can be replayed per fetch request.
"},{"location":"infra/adapters/sse/#infra.adapters.sse-classes","title":"Classes","text":""},{"location":"infra/adapters/sse/#infra.adapters.sse.SSEInMemoryBus","title":"SSEInMemoryBus","text":"SSEInMemoryBus()\n Bases: Generic[T]
Buffer SSE progress events in memory.
Attributes:
Name Type Description_events List[T] Events published since the last clear.
Initialize an empty event buffer.
"},{"location":"infra/adapters/sse/#infra.adapters.sse.SSEInMemoryBus-functions","title":"Functions","text":""},{"location":"infra/adapters/sse/#infra.adapters.sse.SSEInMemoryBus.clear","title":"clear","text":"clear() -> None\nRemove all buffered events.
"},{"location":"infra/adapters/sse/#infra.adapters.sse.SSEInMemoryBus.get_events","title":"get_events","text":"get_events(fr_id: str) -> List[T]\nReturn buffered events for a fetch request.
Parameters:
Name Type Description Defaultfr_id str Fetch request identifier to filter by.
requiredReturns:
Type DescriptionList[T] List[T]: Events whose fetch_request_id equals fr_id.
async","text":"publish(event: T) -> None\nAppend an event to the buffer.
Parameters:
Name Type Description Defaultevent T Event to append.
required"},{"location":"infra/db/","title":"Db","text":"Database infrastructure for the Expenses Service.
Bundle connection setup and generic repository factories used by the infrastructure adapters.
"},{"location":"infra/db/setup/","title":"Setup","text":""},{"location":"infra/db/setup/#infra.db.setup","title":"infra.db.setup","text":""},{"location":"infra/db/setup/#infra.db.setup--summary","title":"Summary","text":"Database setup \u2014 connection lifecycle only. No domain imports.
Connect and disconnect the shared Mongo connection manager at application startup and shutdown.
"},{"location":"infra/db/setup/#infra.db.setup-functions","title":"Functions","text":""},{"location":"infra/db/setup/#infra.db.setup.setup_database","title":"setup_databaseasync","text":"setup_database(uri: str, db_name: str)\nConnect the shared Mongo connection manager.
Parameters:
Name Type Description Defaulturi str Mongo connection URI.
requireddb_name str Target database name.
required"},{"location":"infra/db/setup/#infra.db.setup.shutdown_database","title":"shutdown_databaseasync","text":"shutdown_database()\nDisconnect the shared Mongo connection manager.
"},{"location":"infra/db/repos/","title":"Repos","text":"Generic database repository factories.
Expose the MongoDB repository factory and a PostgreSQL placeholder used by domain adapters.
"},{"location":"infra/db/repos/mongo/","title":"Mongo","text":""},{"location":"infra/db/repos/mongo/#infra.db.repos.mongo","title":"infra.db.repos.mongo","text":""},{"location":"infra/db/repos/mongo/#infra.db.repos.mongo--summary","title":"Summary","text":"Generic MongoDB CRUD repo \u2014 single implementation for all domains.
Select a concrete mongo-ops repository (base, cached, or populating) from the options supplied to the factory.
"},{"location":"infra/db/repos/pgsql/","title":"Pgsql","text":""},{"location":"infra/db/repos/pgsql/#infra.db.repos.pgsql","title":"infra.db.repos.pgsql","text":""},{"location":"infra/db/repos/pgsql/#infra.db.repos.pgsql--summary","title":"Summary","text":"Generic PostGres CRUD repo \u2014 single implementation for all domains.
Placeholder factory for future PostgreSQL repository support.
"},{"location":"infra/llm/","title":"Llm","text":"LLM infrastructure for the Expenses Service.
Provide HTTP client ports, retry pools, provider configuration, and statement parsing adaptors.
"},{"location":"infra/llm/httpx_client/","title":"Httpx Client","text":""},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client","title":"infra.llm.httpx_client","text":""},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client--summary","title":"Summary","text":"HTTP client ports for OpenAI-compatible chat completion endpoints.
Provide synchronous and asynchronous httpx wrappers that issue chat completion requests with bearer authentication.
"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client-classes","title":"Classes","text":""},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.AsyncClientPort","title":"AsyncClientPort","text":"AsyncClientPort(\n api_key: str = \"\",\n endpoint: str = \"\",\n timeout: float = 60.0,\n)\nAsynchronous httpx client for chat completion APIs.
Attributes:
Name Type Descriptionapi_key str Bearer token used for authentication.
endpoint str Base URL of the completions API.
timeout float Request timeout in seconds.
_http_client AsyncClient Underlying asynchronous HTTP client.
Initialize the asynchronous client.
Parameters:
Name Type Description Defaultapi_key str Bearer token used for authentication.
'' endpoint str Base URL of the completions API.
'' timeout float Request timeout in seconds.
60.0"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.AsyncClientPort-functions","title":"Functions","text":""},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.AsyncClientPort.aclose","title":"aclose async","text":"aclose()\nClose the underlying asynchronous HTTP client.
"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.AsyncClientPort.chat_completion","title":"chat_completionasync","text":"chat_completion(\n model: str,\n messages: list,\n temperature: float = 0.0,\n max_tokens: int = 4096,\n) -> dict\nSend an asynchronous chat completion request.
Parameters:
Name Type Description Defaultmodel str Model identifier to invoke.
requiredmessages list Chat messages in API format.
requiredtemperature float Sampling temperature.
0.0 max_tokens int Maximum tokens to generate.
4096 Returns:
Name Type Descriptiondict dict Decoded JSON response body.
"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.SyncClientPort","title":"SyncClientPort","text":"SyncClientPort(\n api_key: str = \"\",\n endpoint: str = \"\",\n timeout: float = 60.0,\n)\nSynchronous httpx client for chat completion APIs.
Attributes:
Name Type Descriptionapi_key str Bearer token used for authentication.
endpoint str Base URL of the completions API.
timeout float Request timeout in seconds.
_client Client Underlying synchronous HTTP client.
Initialize the synchronous client.
Parameters:
Name Type Description Defaultapi_key str Bearer token used for authentication.
'' endpoint str Base URL of the completions API.
'' timeout float Request timeout in seconds.
60.0"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.SyncClientPort-functions","title":"Functions","text":""},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.SyncClientPort.chat_completion","title":"chat_completion","text":"chat_completion(\n model: str,\n messages: list,\n temperature: float = 0.0,\n max_tokens: int = 4096,\n) -> dict\nSend a chat completion request.
Parameters:
Name Type Description Defaultmodel str Model identifier to invoke.
requiredmessages list Chat messages in API format.
requiredtemperature float Sampling temperature.
0.0 max_tokens int Maximum tokens to generate.
4096 Returns:
Name Type Descriptiondict dict Decoded JSON response body.
"},{"location":"infra/llm/httpx_client/#infra.llm.httpx_client.SyncClientPort.close","title":"close","text":"close()\nClose the underlying HTTP client.
"},{"location":"infra/llm/model/","title":"Model","text":""},{"location":"infra/llm/model/#infra.llm.model","title":"infra.llm.model","text":""},{"location":"infra/llm/model/#infra.llm.model--summary","title":"Summary","text":"Dataclass describing an LLM model and its retry policy.
Carry the model identifier, provider name, and the retry, rate-limit, token, and timeout settings used by the pool retry loop.
"},{"location":"infra/llm/model/#infra.llm.model-classes","title":"Classes","text":""},{"location":"infra/llm/model/#infra.llm.model.ModelPort","title":"ModelPortdataclass","text":"ModelPort(\n name: str,\n provider: str,\n max_retries: int = 3,\n retry_delay: float = 2.0,\n rate_limit_delay: float = 1.0,\n max_tokens: int = 4096,\n timeout: float = 120.0,\n)\nDescribe an LLM model and its request policy.
Attributes:
Name Type Descriptionname str Provider-specific model identifier.
provider str Provider key (for example groq).
max_retries int Number of retry attempts per request.
retry_delay float Seconds to wait between attempts.
rate_limit_delay float Seconds to wait before each call.
max_tokens int Maximum tokens to request from the model.
timeout float Request timeout in seconds.
"},{"location":"infra/llm/pool/","title":"Pool","text":""},{"location":"infra/llm/pool/#infra.llm.pool","title":"infra.llm.pool","text":""},{"location":"infra/llm/pool/#infra.llm.pool--summary","title":"Summary","text":"LLM pool adaptors with retry, rotation, and HTTP error handling.
Rotate through configured model ports, retrying failed chat completions and translating provider errors into RuntimeError failures.
AsyncPoolAdaptor(**kwargs)\nAsynchronous LLM pool with model rotation.
Attributes:
Name Type Descriptionhttpx_client AsyncClientPort Client used for requests.
models list Model ports available for rotation.
Initialize the pool from keyword configuration.
Parameters:
Name Type Description Default**kwargs Configuration; httpx_client and models are consumed, remaining keys become instance attributes.
{}"},{"location":"infra/llm/pool/#infra.llm.pool.AsyncPoolAdaptor-functions","title":"Functions","text":""},{"location":"infra/llm/pool/#infra.llm.pool.AsyncPoolAdaptor.aclose","title":"aclose async","text":"aclose()\nClose the underlying asynchronous HTTP client.
"},{"location":"infra/llm/pool/#infra.llm.pool.AsyncPoolAdaptor.generate","title":"generateasync","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt asynchronously.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/pool/#infra.llm.pool.PoolAdaptor","title":"PoolAdaptor","text":"PoolAdaptor(**kwargs)\nSynchronous LLM pool with model rotation.
Attributes:
Name Type Descriptionhttpx_client SyncClientPort Client used for requests.
models list Model ports available for rotation.
Initialize the pool from keyword configuration.
Parameters:
Name Type Description Default**kwargs Configuration; httpx_client and models are consumed, remaining keys become instance attributes.
{}"},{"location":"infra/llm/pool/#infra.llm.pool.PoolAdaptor-functions","title":"Functions","text":""},{"location":"infra/llm/pool/#infra.llm.pool.PoolAdaptor.close","title":"close","text":"close()\nClose the underlying HTTP client.
"},{"location":"infra/llm/pool/#infra.llm.pool.PoolAdaptor.generate","title":"generate","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/setup/","title":"Setup","text":""},{"location":"infra/llm/setup/#infra.llm.setup","title":"infra.llm.setup","text":""},{"location":"infra/llm/setup/#infra.llm.setup--summary","title":"Summary","text":"LLM pool factories resolved from configuration.
Import and instantiate the provider-specific synchronous or asynchronous pool selected by the LLM_PROVIDER environment variable.
setup_async_pool(provider: str = None) -> AsyncPoolAdaptor\nBuild an asynchronous pool for the selected provider.
Parameters:
Name Type Description Defaultprovider str Provider key; defaults to LLM_PROVIDER or open_router.
None Returns:
Name Type DescriptionAsyncPoolAdaptor AsyncPoolAdaptor Configured asynchronous pool.
"},{"location":"infra/llm/setup/#infra.llm.setup.setup_sync_pool","title":"setup_sync_pool","text":"setup_sync_pool(provider: str = None) -> PoolAdaptor\nBuild a synchronous pool for the selected provider.
Parameters:
Name Type Description Defaultprovider str Provider key; defaults to LLM_PROVIDER or open_router.
None Returns:
Name Type DescriptionPoolAdaptor PoolAdaptor Configured synchronous pool.
"},{"location":"infra/llm/providers/","title":"Providers","text":"LLM provider integrations.
Namespace for provider-specific configuration, model ports, and pool adaptors.
"},{"location":"infra/llm/providers/groq/","title":"Groq","text":"Groq LLM provider integration.
Expose Groq configuration, model ports, and synchronous/asynchronous pools.
"},{"location":"infra/llm/providers/groq/config/","title":"Config","text":""},{"location":"infra/llm/providers/groq/config/#infra.llm.providers.groq.config","title":"infra.llm.providers.groq.config","text":""},{"location":"infra/llm/providers/groq/config/#infra.llm.providers.groq.config--summary","title":"Summary","text":"Groq provider configuration loaded from the environment.
Read the Groq API key and endpoint used by the Groq pool adaptors.
"},{"location":"infra/llm/providers/groq/config/#infra.llm.providers.groq.config-classes","title":"Classes","text":""},{"location":"infra/llm/providers/groq/config/#infra.llm.providers.groq.config.GroqConfig","title":"GroqConfig","text":"GroqConfig()\nHold Groq provider credentials and endpoint.
Attributes:
Name Type Descriptionapi_key str Groq API key from GROQ_API_KEY or LLM_API_KEY.
endpoint str Groq API base URL.
Load Groq configuration from environment variables.
"},{"location":"infra/llm/providers/groq/config/#infra.llm.providers.groq.config.GroqConfig-functions","title":"Functions","text":""},{"location":"infra/llm/providers/groq/models/","title":"Models","text":""},{"location":"infra/llm/providers/groq/models/#infra.llm.providers.groq.models","title":"infra.llm.providers.groq.models","text":""},{"location":"infra/llm/providers/groq/models/#infra.llm.providers.groq.models--summary","title":"Summary","text":"Groq model port definitions.
Expose the default Groq model identifiers used by the Groq pool adaptors.
"},{"location":"infra/llm/providers/groq/models/#infra.llm.providers.groq.models-classes","title":"Classes","text":""},{"location":"infra/llm/providers/groq/models/#infra.llm.providers.groq.models-functions","title":"Functions","text":""},{"location":"infra/llm/providers/groq/models/#infra.llm.providers.groq.models.create_model_ports","title":"create_model_ports","text":"create_model_ports()\nCreate the default Groq model ports.
Returns:
Name Type Descriptionlist Model ports for the supported Groq models.
"},{"location":"infra/llm/providers/groq/pool/","title":"Pool","text":""},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool","title":"infra.llm.providers.groq.pool","text":""},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool--summary","title":"Summary","text":"Groq pool adaptors.
Wire Groq configuration and model ports into the synchronous and asynchronous LLM pool adaptors.
"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool-classes","title":"Classes","text":""},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.AsyncGroqPool","title":"AsyncGroqPool","text":"AsyncGroqPool(**kwargs)\n Bases: AsyncPoolAdaptor
Asynchronous LLM pool backed by Groq.
Initialize the pool with Groq defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.AsyncGroqPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.AsyncGroqPool.aclose","title":"aclose async","text":"aclose()\nClose the underlying asynchronous HTTP client.
"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.AsyncGroqPool.generate","title":"generateasync","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt asynchronously.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.SyncGroqPool","title":"SyncGroqPool","text":"SyncGroqPool(**kwargs)\n Bases: PoolAdaptor
Synchronous LLM pool backed by Groq.
Initialize the pool with Groq defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.SyncGroqPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.SyncGroqPool.close","title":"close","text":"close()\nClose the underlying HTTP client.
"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool.SyncGroqPool.generate","title":"generate","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/groq/pool/#infra.llm.providers.groq.pool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/llama_parser/","title":"Llama Parser","text":"LlamaCloud statement parser integration.
Expose parser configuration, extraction models, and the parser pool adaptor.
"},{"location":"infra/llm/providers/llama_parser/config/","title":"Config","text":""},{"location":"infra/llm/providers/llama_parser/config/#infra.llm.providers.llama_parser.config","title":"infra.llm.providers.llama_parser.config","text":""},{"location":"infra/llm/providers/llama_parser/config/#infra.llm.providers.llama_parser.config--summary","title":"Summary","text":"LlamaCloud parser configuration loaded from the environment.
Read the LlamaCloud API key used by the parser adaptor.
"},{"location":"infra/llm/providers/llama_parser/config/#infra.llm.providers.llama_parser.config-classes","title":"Classes","text":""},{"location":"infra/llm/providers/llama_parser/config/#infra.llm.providers.llama_parser.config.LlamaParserConfig","title":"LlamaParserConfig","text":"LlamaParserConfig()\nHold LlamaCloud parser credentials.
Attributes:
Name Type Descriptionapi_key str LlamaCloud API key from LLAMA_CLOUD_API_KEY.
Load parser configuration from environment variables.
"},{"location":"infra/llm/providers/llama_parser/config/#infra.llm.providers.llama_parser.config.LlamaParserConfig-functions","title":"Functions","text":""},{"location":"infra/llm/providers/llama_parser/models/","title":"Models","text":""},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models","title":"infra.llm.providers.llama_parser.models","text":""},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models--summary","title":"Summary","text":"Pydantic models for statement extraction results.
Define the transaction schema returned by LlamaCloud extraction and the default extraction configuration.
"},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models-classes","title":"Classes","text":""},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models.Direction","title":"Direction","text":" Bases: str, Enum
Transaction direction.
Attributes:
Name Type DescriptionDEBIT str Debit transaction direction.
CREDIT str Credit transaction direction.
"},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models.RawExpense","title":"RawExpense","text":" Bases: BaseModel
A single extracted statement transaction.
Attributes:
Name Type Descriptiondate str Expense date as DD-MM-YYYY.
amount float Transaction amount.
balance float Account balance after transaction.
description str Complete reconstructed transaction description.
raw_lines List[str] Raw OCR/text lines that form this transaction.
direction Direction Either DEBIT or CREDIT.
"},{"location":"infra/llm/providers/llama_parser/models/#infra.llm.providers.llama_parser.models.Statement","title":"Statement","text":" Bases: BaseModel
Extraction result containing parsed transactions.
Attributes:
Name Type Descriptiontransactions List[RawExpense] Extracted transactions.
"},{"location":"infra/llm/providers/llama_parser/pool/","title":"Pool","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool","title":"infra.llm.providers.llama_parser.pool","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool--summary","title":"Summary","text":"LlamaCloud statement parser adaptor.
Upload a statement PDF to LlamaCloud for extraction, or replay a cached CSV, returning normalized transaction dictionaries.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool-classes","title":"Classes","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool","title":"AsyncLlamaParserPool","text":"AsyncLlamaParserPool(**kwargs)\n Bases: LlamaParserAdaptor
LLM parser pool configured from the environment.
Initialize the pool with configuration defaults.
Parameters:
Name Type Description Default**kwargs Overrides passed to the parser adaptor.
{}"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool-attributes","title":"Attributes","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool.client","title":"client property","text":"client: AsyncLlamaCloud\nReturn the lazily initialized LlamaCloud client.
Returns:
Name Type DescriptionAsyncLlamaCloud AsyncLlamaCloud Authenticated LlamaCloud client.
Raises:
Type DescriptionValueError When no API key is configured.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool.aclose","title":"acloseasync","text":"aclose()\nClose the LlamaCloud client if it was created.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.AsyncLlamaParserPool.generate_statement","title":"generate_statementasync","text":"generate_statement(\n filepath: Union[str, os.PathLike],\n cached: Optional[Union[str, os.PathLike]] = None,\n) -> List[dict]\nExtract transactions from a statement PDF.
When cached points to a CSV previously exported by scripts/llama_txns_extractor.py, read it and validate each row into RawExpense models instead of calling LlamaCloud.
Parameters:
Name Type Description Defaultfilepath Union[str, PathLike] Path to the statement PDF.
requiredcached Optional[Union[str, PathLike]] Path to a cached CSV export.
None Returns:
Type DescriptionList[dict] List[dict]: Extracted transaction dictionaries.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor","title":"LlamaParserAdaptor","text":"LlamaParserAdaptor(**kwargs)\nExtract transactions through the LlamaCloud API.
Attributes:
Name Type Descriptionapi_key str LlamaCloud API key.
extract_config dict Extraction configuration payload.
_client Optional[AsyncLlamaCloud] Lazily created API client.
Initialize the parser adaptor.
Parameters:
Name Type Description Default**kwargs Configuration; api_key and extract_config are consumed, remaining keys become instance attributes.
{}"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor-attributes","title":"Attributes","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor.client","title":"client property","text":"client: AsyncLlamaCloud\nReturn the lazily initialized LlamaCloud client.
Returns:
Name Type DescriptionAsyncLlamaCloud AsyncLlamaCloud Authenticated LlamaCloud client.
Raises:
Type DescriptionValueError When no API key is configured.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor-functions","title":"Functions","text":""},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor.aclose","title":"acloseasync","text":"aclose()\nClose the LlamaCloud client if it was created.
"},{"location":"infra/llm/providers/llama_parser/pool/#infra.llm.providers.llama_parser.pool.LlamaParserAdaptor.generate_statement","title":"generate_statementasync","text":"generate_statement(\n filepath: Union[str, os.PathLike],\n cached: Optional[Union[str, os.PathLike]] = None,\n) -> List[dict]\nExtract transactions from a statement PDF.
When cached points to a CSV previously exported by scripts/llama_txns_extractor.py, read it and validate each row into RawExpense models instead of calling LlamaCloud.
Parameters:
Name Type Description Defaultfilepath Union[str, PathLike] Path to the statement PDF.
requiredcached Optional[Union[str, PathLike]] Path to a cached CSV export.
None Returns:
Type DescriptionList[dict] List[dict]: Extracted transaction dictionaries.
"},{"location":"infra/llm/providers/open_ai/","title":"Open Ai","text":"OpenAI LLM provider integration.
Expose OpenAI configuration, model ports, and synchronous/asynchronous pools.
"},{"location":"infra/llm/providers/open_ai/config/","title":"Config","text":""},{"location":"infra/llm/providers/open_ai/config/#infra.llm.providers.open_ai.config","title":"infra.llm.providers.open_ai.config","text":""},{"location":"infra/llm/providers/open_ai/config/#infra.llm.providers.open_ai.config--summary","title":"Summary","text":"OpenAI provider configuration loaded from the environment.
Read the OpenAI API key and endpoint used by the OpenAI pool adaptors.
"},{"location":"infra/llm/providers/open_ai/config/#infra.llm.providers.open_ai.config-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_ai/config/#infra.llm.providers.open_ai.config.OpenAiConfig","title":"OpenAiConfig","text":"OpenAiConfig()\nHold OpenAI provider credentials and endpoint.
Attributes:
Name Type Descriptionapi_key str OpenAI API key from OPENAI_API_KEY.
endpoint str OpenAI API base URL.
Load OpenAI configuration from environment variables.
"},{"location":"infra/llm/providers/open_ai/config/#infra.llm.providers.open_ai.config.OpenAiConfig-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_ai/models/","title":"Models","text":""},{"location":"infra/llm/providers/open_ai/models/#infra.llm.providers.open_ai.models","title":"infra.llm.providers.open_ai.models","text":""},{"location":"infra/llm/providers/open_ai/models/#infra.llm.providers.open_ai.models--summary","title":"Summary","text":"OpenAI model port definitions.
Expose the default OpenAI model identifiers used by the OpenAI pool adaptors.
"},{"location":"infra/llm/providers/open_ai/models/#infra.llm.providers.open_ai.models-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_ai/models/#infra.llm.providers.open_ai.models-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_ai/models/#infra.llm.providers.open_ai.models.create_model_ports","title":"create_model_ports","text":"create_model_ports()\nCreate the default OpenAI model ports.
Returns:
Name Type Descriptionlist Model ports for the supported OpenAI models.
"},{"location":"infra/llm/providers/open_ai/pool/","title":"Pool","text":""},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool","title":"infra.llm.providers.open_ai.pool","text":""},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool--summary","title":"Summary","text":"OpenAI pool adaptors.
Wire OpenAI configuration and model ports into the synchronous and asynchronous LLM pool adaptors.
"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.AsyncOpenAiPool","title":"AsyncOpenAiPool","text":"AsyncOpenAiPool(**kwargs)\n Bases: AsyncPoolAdaptor
Asynchronous LLM pool backed by OpenAI.
Initialize the pool with OpenAI defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.AsyncOpenAiPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.AsyncOpenAiPool.aclose","title":"aclose async","text":"aclose()\nClose the underlying asynchronous HTTP client.
"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.AsyncOpenAiPool.generate","title":"generateasync","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt asynchronously.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.SyncOpenAiPool","title":"SyncOpenAiPool","text":"SyncOpenAiPool(**kwargs)\n Bases: PoolAdaptor
Synchronous LLM pool backed by OpenAI.
Initialize the pool with OpenAI defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.SyncOpenAiPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.SyncOpenAiPool.close","title":"close","text":"close()\nClose the underlying HTTP client.
"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool.SyncOpenAiPool.generate","title":"generate","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/open_ai/pool/#infra.llm.providers.open_ai.pool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_router/","title":"Open Router","text":"OpenRouter LLM provider integration.
Expose OpenRouter configuration, model ports, and synchronous/asynchronous pools.
"},{"location":"infra/llm/providers/open_router/config/","title":"Config","text":""},{"location":"infra/llm/providers/open_router/config/#infra.llm.providers.open_router.config","title":"infra.llm.providers.open_router.config","text":""},{"location":"infra/llm/providers/open_router/config/#infra.llm.providers.open_router.config--summary","title":"Summary","text":"OpenRouter provider configuration loaded from the environment.
Read the OpenRouter API key and endpoint used by the OpenRouter pool adaptors.
"},{"location":"infra/llm/providers/open_router/config/#infra.llm.providers.open_router.config-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_router/config/#infra.llm.providers.open_router.config.OpenRouterConfig","title":"OpenRouterConfig","text":"OpenRouterConfig()\nHold OpenRouter provider credentials and endpoint.
Attributes:
Name Type Descriptionapi_key str OpenRouter API key from OPENROUTER_API_KEY or LLM_API_KEY.
endpoint str OpenRouter API base URL.
Load OpenRouter configuration from environment variables.
"},{"location":"infra/llm/providers/open_router/config/#infra.llm.providers.open_router.config.OpenRouterConfig-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_router/models/","title":"Models","text":""},{"location":"infra/llm/providers/open_router/models/#infra.llm.providers.open_router.models","title":"infra.llm.providers.open_router.models","text":""},{"location":"infra/llm/providers/open_router/models/#infra.llm.providers.open_router.models--summary","title":"Summary","text":"OpenRouter model port definitions.
Expose the default OpenRouter model identifiers used by the OpenRouter pool adaptors.
"},{"location":"infra/llm/providers/open_router/models/#infra.llm.providers.open_router.models-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_router/models/#infra.llm.providers.open_router.models-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_router/models/#infra.llm.providers.open_router.models.create_model_ports","title":"create_model_ports","text":"create_model_ports()\nCreate the default OpenRouter model ports.
Returns:
Name Type Descriptionlist Model ports for the supported OpenRouter models.
"},{"location":"infra/llm/providers/open_router/pool/","title":"Pool","text":""},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool","title":"infra.llm.providers.open_router.pool","text":""},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool--summary","title":"Summary","text":"OpenRouter pool adaptors.
Wire OpenRouter configuration and model ports into the synchronous and asynchronous LLM pool adaptors.
"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool-classes","title":"Classes","text":""},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.AsyncOpenRouterPool","title":"AsyncOpenRouterPool","text":"AsyncOpenRouterPool(**kwargs)\n Bases: AsyncPoolAdaptor
Asynchronous LLM pool backed by OpenRouter.
Initialize the pool with OpenRouter defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.AsyncOpenRouterPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.AsyncOpenRouterPool.aclose","title":"aclose async","text":"aclose()\nClose the underlying asynchronous HTTP client.
"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.AsyncOpenRouterPool.generate","title":"generateasync","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt asynchronously.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.SyncOpenRouterPool","title":"SyncOpenRouterPool","text":"SyncOpenRouterPool(**kwargs)\n Bases: PoolAdaptor
Synchronous LLM pool backed by OpenRouter.
Initialize the pool with OpenRouter defaults.
Parameters:
Name Type Description Default**kwargs Overrides for the client and model ports.
{}"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.SyncOpenRouterPool-functions","title":"Functions","text":""},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.SyncOpenRouterPool.close","title":"close","text":"close()\nClose the underlying HTTP client.
"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool.SyncOpenRouterPool.generate","title":"generate","text":"generate(\n prompt: str,\n system_prompt: Optional[str] = None,\n max_tokens: Optional[int] = None,\n models: Optional[list] = None,\n) -> str\nGenerate text for a prompt.
Parameters:
Name Type Description Defaultprompt str User prompt text.
requiredsystem_prompt Optional[str] Optional system instruction.
None max_tokens Optional[int] Token cap overriding model defaults.
None models Optional[list] Model ports overriding the pool defaults.
None Returns:
Name Type Descriptionstr str Generated content.
"},{"location":"infra/llm/providers/open_router/pool/#infra.llm.providers.open_router.pool-functions","title":"Functions","text":""},{"location":"interfaces/","title":"Interfaces","text":"Thin entry points for the Aetoskia Expenses Service: FastAPI route handlers wired to openapi.yaml operationIds, SSE handlers, and CLI commands. Handlers stay thin and delegate to domain services; business logic lives in the domain layer.
"},{"location":"interfaces/auth/","title":"Auth","text":""},{"location":"interfaces/auth/#interfaces.auth","title":"interfaces.auth","text":""},{"location":"interfaces/auth/#interfaces.auth--summary","title":"Summary","text":"Auth interface: thin FastAPI entry points related to authentication, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/openapi/","title":"Openapi","text":""},{"location":"interfaces/openapi/#interfaces.openapi","title":"interfaces.openapi","text":""},{"location":"interfaces/openapi/#interfaces.openapi--summary","title":"Summary","text":"All handler functions \u2014 names must match openapi.yaml operationId values. The OpenAPI-first router resolves each operation to a handler by name, so this module re-exports every route handler from the subpackages into one flat namespace.
"},{"location":"interfaces/openapi/#interfaces.openapi-classes","title":"Classes","text":""},{"location":"interfaces/openapi/#interfaces.openapi.AccountCrudsService","title":"AccountCrudsService","text":"AccountCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[Account, AccountDocument]
Account CRUD service resolving :class:Account documents from a repo.
Instances are created by :func:get_account_service. The model and schema class attributes bind the domain model and its document type.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.AccountCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.AccountCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.AccountCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.AccountCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
EntityCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[Entity, EntityDocument]
Entity CRUD service resolving :class:Entity documents from a repo.
Instances are created by :func:get_entity_service. The model and schema class attributes bind the domain model and its document type.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.EntityCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.EntityCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.EntityCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.EntityCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
ExpenseCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[Expense, ExpenseDocument]
Expense CRUD service resolving :class:Expense documents from a repo.
Instances are created by :func:get_expense_service. The model and schema class attributes bind the domain model and its document type.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.ExpenseCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.ExpenseCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.ExpenseCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.ExpenseCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
FetchRequestCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[FetchRequest, FetchRequestDocument]
CRUD service for fetch requests with pipeline stage helpers.
Attributes:
Name Type Descriptionmodel FetchRequest Domain model class.
schema FetchRequestDocument Persistence document class.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"save_enrichment(\n id: PyObjectId, enrichment_dicts: list\n) -> None\nPersist the enriched expense dicts on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredenrichment_dicts list Enriched expense dicts.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.save_raw_lines","title":"save_raw_linesasync","text":"save_raw_lines(id: PyObjectId, raw_lines: list) -> None\nPersist the extracted raw lines on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredraw_lines list Raw OCR/text lines.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.save_txn_blocks","title":"save_txn_blocksasync","text":"save_txn_blocks(id: PyObjectId, txn_blocks: dict) -> None\nPersist the extracted transaction blocks on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredtxn_blocks dict Transaction blocks keyed by order id.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.save_txn_dicts","title":"save_txn_dictsasync","text":"save_txn_dicts(\n id: PyObjectId, txn_dicts: list, txn_dicts_count: int\n) -> None\nPersist the parsed transaction dicts and count on the request source.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredtxn_dicts list Raw expense dicts.
requiredtxn_dicts_count int Number of parsed transaction dicts.
requiredReturns:
Name Type DescriptionNone None Nothing.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.search","title":"searchasync","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.FetchRequestCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"update_status(\n id: PyObjectId,\n status: str,\n error_message: Optional[str] = None,\n retry_count: Optional[int] = None,\n) -> bool\nUpdate the request status, optionally carrying failure detail.
Parameters:
Name Type Description Defaultid PyObjectId Fetch request id.
requiredstatus str New status value.
requirederror_message Optional[str] Message recorded when failing.
None retry_count Optional[int] Retry counter recorded when failing.
None Returns:
Name Type Descriptionbool bool True when a document was patched.
Raises:
Type DescriptionValueError If status == \"failed\" and either error_message or retry_count is None.
Bases: BaseModel
Definition of a report snapshot. Bounds the data set; dimensions are sliced at read time.
Attributes:
Name Type Descriptionname str Snapshot name; empty for an auto-generated name.
granularities List[str] Granularities to precompute in the cube.
group_dims List[str] Dimensions to group by, e.g. \"payee\", \"tag\".
flow str Flow filter: inflows, outflows, or both.
accounts Optional[List[str]] Account names to include; all when None.
ignore_self bool Exclude self-transfer tagged expenses.
start_date str Inclusive start boundary, DD-MM-YYYY.
end_date str Inclusive end boundary, DD-MM-YYYY.
min_amount Optional[float] Minimum absolute amount to include.
max_amount Optional[float] Maximum absolute amount to include.
"},{"location":"interfaces/openapi/#interfaces.openapi.ReportService","title":"ReportService","text":"ReportService(\n expense_svc: ExpenseCrudsService,\n tag_svc: TagCrudsService,\n store: ReportStore,\n report_repo=None,\n)\nBuild, persist, and serve precomputed report snapshots.
NotesInstances are created by :func:get_report_service. The service scans expenses in batches, expands tag hierarchies, and persists period series into the configured :class:ReportStore.
Initialize the report service with its dependencies.
Parameters:
Name Type Description Defaultexpense_svc ExpenseCrudsService Expense CRUD service used as the cube source.
requiredtag_svc TagCrudsService Tag CRUD service used to expand tag hierarchies and resolve ignore tags.
requiredstore ReportStore Key-value store for cube period data.
requiredreport_repo Any Report snapshot repository; defaults to :func:create_report_repo when omitted.
None"},{"location":"interfaces/openapi/#interfaces.openapi.ReportService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.ReportService.delete_snapshot","title":"delete_snapshot async","text":"delete_snapshot(report_id: str) -> bool\nDelete a snapshot and all of its cube keys from the store.
Parameters:
Name Type Description Defaultreport_id str Snapshot ID to delete.
requiredReturns:
Name Type Descriptionbool bool True when the snapshot existed and was deleted.
async","text":"fetch_report(\n report_id: str,\n granularities: Optional[List[str]] = None,\n period_ids: Optional[List[str]] = None,\n flow: str = \"outflows\",\n payees: Optional[List[str]] = None,\n tags: Optional[List[str]] = None,\n) -> Optional[Report]\nSlice a stored snapshot into a report API response.
\"*\" in payees or tags expands to every value stored in the cube meta.
Parameters:
Name Type Description Defaultreport_id str Snapshot ID to slice.
requiredgranularities Optional[List[str]] Granularities to include; defaults to the snapshot's own.
None period_ids Optional[List[str]] Period labels to filter to.
None flow str Flow to serve; both includes inflows and outflows.
'outflows' payees Optional[List[str]] Payee filters applied per bucket.
None tags Optional[List[str]] Tag path filters applied per bucket.
None Returns:
Type DescriptionOptional[Report] Optional[Report]: The sliced report view, or None when the snapshot does not exist.
async","text":"generate_snapshot(\n query: ReportQuery,\n) -> ReportSnapshotDocument\nValidate a query and return an existing or newly built snapshot.
If a snapshot with the same canonical signature already exists it is returned directly; otherwise a fresh cube is built and persisted.
Parameters:
Name Type Description Defaultquery ReportQuery Raw snapshot definition.
requiredReturns:
Name Type DescriptionReportSnapshotDocument ReportSnapshotDocument The existing or newly created snapshot.
"},{"location":"interfaces/openapi/#interfaces.openapi.ReportService.list_snapshots","title":"list_snapshotsasync","text":"list_snapshots(\n offset: int = 0, limit: int = DEFAULT_LIMIT\n) -> List[ReportSnapshotDocument]\nList stored snapshots, newest first.
Parameters:
Name Type Description Defaultoffset int Number of snapshots to skip.
0 limit int Maximum number of snapshots to return.
DEFAULT_LIMIT Returns:
Type DescriptionList[ReportSnapshotDocument] List[ReportSnapshotDocument]: Snapshots ordered by creation time, newest first.
"},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService","title":"TagCrudsService","text":"TagCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[Tag, TagDocument]
Tag CRUD service resolving :class:Tag documents from a repo.
Instances are created by :func:get_tag_service. The model and schema class attributes bind the domain model and its document type. An additional lookup helper get_by_names is provided.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
async","text":"get_by_names(names: list[str])\nReturn tags whose names match any of the provided values.
Parameters:
Name Type Description Defaultnames list[str] Tag names to look up.
requiredReturns:
Name Type Descriptionlist Matching tag documents.
"},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService.model_to_dict","title":"model_to_dictstaticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.TagCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
UploadCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[UploadResult, UploadResultDocument]
Upload result CRUD service resolving :class:UploadResult documents.
Instances are created by :func:get_upload_service. The model and schema class attributes bind the domain model and its document type.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.UploadCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.UploadCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.UploadCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.UploadCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
Bases: BaseModel
Metadata describing a stored file upload.
Attributes:
Name Type Descriptionoriginal_filename str Name of the file as uploaded by the client.
saved_as str Name the file was stored under on disk.
content_type str MIME type of the uploaded file.
url str Public URL serving the stored file.
absolute_path str Absolute filesystem path of the stored file.
"},{"location":"interfaces/openapi/#interfaces.openapi.UserCrudsService","title":"UserCrudsService","text":"UserCrudsService(*, repo=None)\n Bases: CrudsServiceAdaptor[User, UserDocument]
User CRUD service resolving :class:User documents from a repo.
Instances are created by :func:get_user_service. The model and schema class attributes bind the domain model and its document type.
Initialize the adaptor with a backing repository.
Parameters:
Name Type Description Defaultrepo BaseRepository Repository used for all operations.
None"},{"location":"interfaces/openapi/#interfaces.openapi.UserCrudsService-functions","title":"Functions","text":""},{"location":"interfaces/openapi/#interfaces.openapi.UserCrudsService.create","title":"create async","text":"create(data: Model | dict) -> Schema\nCreate a document from a model or raw mapping.
Parameters:
Name Type Description Defaultdata Model | dict Model instance or field mapping to persist.
requiredReturns:
Name Type DescriptionSchema Schema Persisted document.
"},{"location":"interfaces/openapi/#interfaces.openapi.UserCrudsService.delete","title":"deleteasync","text":"delete(id: PyObjectId) -> bool\nDelete a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Name Type Descriptionbool bool True when a document was deleted.
staticmethod","text":"model_to_dict(model_obj: Model) -> dict\nSerialize a model into a sparse dictionary.
Parameters:
Name Type Description Defaultmodel_obj Model Model instance to serialize.
requiredReturns:
Name Type Descriptiondict dict Fields that are set and not None.
async","text":"patch(id: PyObjectId, data: dict) -> Schema | None\nPartially update a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata dict Fields to patch.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
async","text":"read(id: PyObjectId) -> Schema | None\nRead a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requiredReturns:
Type DescriptionSchema | None Schema | None: Matching document, or None when absent.
async","text":"search(\n filter: dict | None = None, *args, **kwargs\n) -> list[Schema]\nList documents matching an optional filter.
Parameters:
Name Type Description Defaultfilter dict | None Query filter passed to the repository.
None Returns:
Type Descriptionlist[Schema] list[Schema]: Matching documents.
NotesExtra positional and keyword arguments are forwarded to the repository.
"},{"location":"interfaces/openapi/#interfaces.openapi.UserCrudsService.update","title":"updateasync","text":"update(id: PyObjectId, data: Model | dict) -> Schema | None\nReplace a document by primary key.
Parameters:
Name Type Description Defaultid PyObjectId Document identifier.
requireddata Model | dict Replacement model or field mapping.
requiredReturns:
Type DescriptionSchema | None Schema | None: Updated document, or None when absent.
cache_response(ttl: Optional[int] = None) -> Callable\nDecorate a GET-style route handler to cache its JSON response.
Parameters:
Name Type Description Defaultttl Optional[int] Cache lifetime in seconds; defaults to settings.cache_ttl.
None Returns:
Name Type DescriptionCallable Callable Decorator that wraps the route handler.
NotesThe wrapped handler must accept a request: Request parameter (as every openapi_first handler does). Responses that are already a fastapi.Response (for example 204) are returned untouched and never cached. When no http_cache_store is wired on request.app.state.db_resources the decorator passes through to the handler without caching.
async","text":"create_account(request: Request, body: dict)\nCreate a new account.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Account payload forwarded to the service.
requiredReturns:
Name Type DescriptionAccountDocument The created account.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_entity","title":"create_entityasync","text":"create_entity(request: Request, body: dict)\nCreate a new entity.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Entity payload forwarded to the service.
requiredReturns:
Name Type DescriptionEntityDocument The created entity.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_expense","title":"create_expenseasync","text":"create_expense(request: Request, body: dict)\nCreate a new expense.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Expense payload forwarded to the service.
requiredReturns:
Name Type DescriptionExpenseDocument The created expense.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_fetch_request","title":"create_fetch_requestasync","text":"create_fetch_request(request: Request, body: dict)\nCreate a new fetch request.
A stable fingerprint is derived from the source payload and stored on the document when the payload does not already provide one.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Fetch request payload forwarded to the service.
requiredReturns:
Name Type DescriptionFetchRequestDocument The created fetch request.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_report","title":"create_reportasync","text":"create_report(request: Request, body: dict)\nGenerate a report snapshot from a query definition.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Report query payload; validated into a ReportQuery.
requiredReturns:
Name Type DescriptionReportSnapshotDocument The generated snapshot.
Raises:
Type DescriptionHTTPException 400 when the query payload is invalid.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_tag","title":"create_tagasync","text":"create_tag(request: Request, body: dict)\nCreate a new tag.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Tag payload forwarded to the service.
requiredReturns:
Name Type DescriptionTagDocument The created tag.
"},{"location":"interfaces/openapi/#interfaces.openapi.create_user","title":"create_userasync","text":"create_user(request: Request, body: dict)\nCreate a new user.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict User payload forwarded to the service.
requiredReturns:
Name Type DescriptionUserDocument The created user.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_account","title":"delete_accountasync","text":"delete_account(request: Request, id: str)\nDelete an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_entity","title":"delete_entityasync","text":"delete_entity(request: Request, id: str)\nDelete an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_expense","title":"delete_expenseasync","text":"delete_expense(request: Request, id: str)\nDelete an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_fetch_request","title":"delete_fetch_requestasync","text":"delete_fetch_request(request: Request, id: str)\nDelete a fetch request and its dependent data.
Cascades deletes to related expenses and ambiguities, removes the fetch request, and invalidates the expenses HTTP cache.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_report","title":"delete_reportasync","text":"delete_report(request: Request, id: str)\nDelete a report snapshot by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Report snapshot id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when the snapshot does not exist.
"},{"location":"interfaces/openapi/#interfaces.openapi.delete_tag","title":"delete_tagasync","text":"delete_tag(request: Request, id: str)\nDelete a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_account","title":"get_accountasync","text":"get_account(request: Request, id: str)\nGet an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredReturns:
Name Type DescriptionAccountDocument The matching account.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_current_user","title":"get_current_userasync","text":"get_current_user(request: Request)\nGet the profile of the authenticated user.
Reads the principal from request.state and creates the profile on first access when it does not exist yet.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the authenticated user and app.state.db_resources.
requiredReturns:
Name Type DescriptionUserDocument The current user's profile.
Raises:
Type DescriptionHTTPException 401 when the request is not authenticated.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_entity","title":"get_entityasync","text":"get_entity(request: Request, id: str)\nGet an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredReturns:
Name Type DescriptionEntityDocument The matching entity.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_expense","title":"get_expenseasync","text":"get_expense(request: Request, id: str)\nGet an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredReturns:
Name Type DescriptionExpenseDocument The matching expense.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_fetch_request","title":"get_fetch_requestasync","text":"get_fetch_request(request: Request, id: str)\nGet a fetch request by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type DescriptionFetchRequestDocument The matching fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_report","title":"get_reportasync","text":"get_report(\n request: Request,\n id: str,\n granularity: Optional[List[str]] = Query(None),\n period_ids: Optional[List[str]] = Query(None),\n flow: str = \"outflows\",\n payee: Optional[List[str]] = Query(None),\n tags: Optional[List[str]] = Query(None),\n)\nFetch a report snapshot with optional granularity, flow, and filter overrides.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Report snapshot id.
requiredgranularity Optional[List[str]] Granularities to materialize; empty means the snapshot's default set.
Query(None) period_ids Optional[List[str]] Period labels to constrain output.
Query(None) flow str Flow filter of inflows, outflows, or both. Defaults to outflows.
'outflows' payee Optional[List[str]] Payee names to include.
Query(None) tags Optional[List[str]] Tag paths to include.
Query(None) Returns:
Name Type DescriptionReport The fetched report.
Raises:
Type DescriptionHTTPException 400 when the report arguments are invalid.
HTTPException 404 when the snapshot does not exist.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_tag","title":"get_tagasync","text":"get_tag(request: Request, id: str)\nGet a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredReturns:
Name Type DescriptionTagDocument The matching tag.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_uploaded_file","title":"get_uploaded_fileasync","text":"get_uploaded_file(request: Request, filepath: str)\nServe an uploaded file from disk.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request.
requiredfilepath str Relative path of the file under UPLOAD_DIR.
requiredReturns:
Name Type DescriptionFileResponse The requested file with its original filename.
Raises:
Type DescriptionHTTPException 404 when the file does not exist.
"},{"location":"interfaces/openapi/#interfaces.openapi.get_user","title":"get_userasync","text":"get_user(request: Request, id: str)\nGet a user by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str User id.
requiredReturns:
Name Type DescriptionUserDocument The matching user.
Raises:
Type DescriptionHTTPException 404 when no user matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_accounts","title":"list_accountsasync","text":"list_accounts(\n request: Request, skip: int = 0, limit: int = 100\n)\nList accounts with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of accounts to skip (offset). Defaults to 0.
0 limit int Maximum number of accounts to return. Defaults to 100.
100 Returns:
Type Descriptionlist[AccountDocument]: Matching accounts from AccountCrudsService.search.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_ambiguities","title":"list_ambiguitiesasync","text":"list_ambiguities(request: Request, id: str)\nList pending ambiguities for a fetch request.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type Descriptionlist Pending ambiguity documents from the ambiguity service.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_entities","title":"list_entitiesasync","text":"list_entities(\n request: Request, skip: int = 0, limit: int = 100\n)\nList entities with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of entities to skip (offset). Defaults to 0.
0 limit int Maximum number of entities to return. Defaults to 100.
100 Returns:
Type Descriptionlist[EntityDocument]: Matching entities from EntityCrudsService.search.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_expenses","title":"list_expensesasync","text":"list_expenses(\n request: Request,\n offset: int = 0,\n limit: int = 10,\n start_date: str = \"\",\n end_date: str = \"\",\n)\nList expenses with pagination, excluding self-transfers.
Expenses tagged with a self-transfer tag are filtered out. The start_date and end_date parameters are accepted by the signature but not applied to the underlying search filter.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of expenses to skip (offset). Defaults to 0.
0 limit int Maximum number of expenses to return. Defaults to 10.
10 start_date str Accepted date-range start; not applied to the search.
'' end_date str Accepted date-range end; not applied to the search.
'' Returns:
Type Descriptionlist[ExpenseDocument]: Matching expenses from ExpenseCrudsService.search.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_fetch_requests","title":"list_fetch_requestsasync","text":"list_fetch_requests(\n request: Request, offset: int = 0, limit: int = 100\n)\nList fetch requests with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of fetch requests to skip (offset). Defaults to 0.
0 limit int Maximum number of fetch requests to return. Defaults to 100.
100 Returns:
Type Descriptionlist[FetchRequestDocument]: Matching fetch requests from the service.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_reports","title":"list_reportsasync","text":"list_reports(\n request: Request, offset: int = 0, limit: int = 100\n)\nList report snapshots with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of snapshots to skip (offset). Defaults to 0.
0 limit int Maximum number of snapshots to return. Defaults to 100.
100 Returns:
Type Descriptionlist[ReportSnapshotDocument]: Matching snapshots from the report service.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_tags","title":"list_tagsasync","text":"list_tags(\n request: Request, skip: int = 0, limit: int = 1000\n)\nList tags with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of tags to skip (offset). Defaults to 0.
0 limit int Maximum number of tags to return. Defaults to 1000.
1000 Returns:
Type Descriptionlist[TagDocument]: Matching tags from TagCrudsService.search.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_uploads","title":"list_uploadsasync","text":"list_uploads(request: Request)\nList all upload records.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredReturns:
Type Descriptionlist[UploadDocument]: All uploads from the upload service.
"},{"location":"interfaces/openapi/#interfaces.openapi.list_users","title":"list_usersasync","text":"list_users(\n request: Request, skip: int = 0, limit: int = 100\n)\nList users with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of users to skip (offset). Defaults to 0.
0 limit int Maximum number of users to return. Defaults to 100.
100 Returns:
Type Descriptionlist[UserDocument]: Matching users from UserCrudsService.search.
"},{"location":"interfaces/openapi/#interfaces.openapi.resolve_ambiguity","title":"resolve_ambiguityasync","text":"resolve_ambiguity(request: Request, id: str, body: dict)\nResolve an ambiguity by choosing one of its candidates.
Marks the ambiguity resolved, then requeues the parent fetch request when no pending ambiguities remain and the fetch request is paused.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Ambiguity id.
requiredbody dict Resolution payload; must contain the chosen candidate.
requiredReturns:
Type DescriptionUpdated ambiguity document.
Raises:
Type DescriptionHTTPException 400 when the chosen candidate is missing.
HTTPException 404 when the ambiguity is not found.
"},{"location":"interfaces/openapi/#interfaces.openapi.stream_fetch_events","title":"stream_fetch_eventsasync","text":"stream_fetch_events(request: Request, id: str)\nStream progress events for a fetch request as server-sent events.
If the SSE bus is not configured on app.state.db_resources an empty events list is returned. Otherwise a text/event-stream response is yielded, polling the bus every 500 ms until the client disconnects.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Type DescriptionStreamingResponse | dict: SSE stream, or {\"events\": []} when the bus
is unavailable.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_account","title":"update_accountasync","text":"update_account(request: Request, id: str, body: dict)\nUpdate an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionAccountDocument The updated account.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_current_user","title":"update_current_userasync","text":"update_current_user(request: Request, body: dict)\nUpdate the profile of the authenticated user.
Creates the profile on first access, then applies the update payload.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the authenticated user and app.state.db_resources.
requiredbody dict Fields to update on the current user's profile.
requiredReturns:
Name Type DescriptionUserDocument The updated profile.
Raises:
Type DescriptionHTTPException 401 when the request is not authenticated.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_entity","title":"update_entityasync","text":"update_entity(request: Request, id: str, body: dict)\nUpdate an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionEntityDocument The updated entity.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_expense","title":"update_expenseasync","text":"update_expense(request: Request, id: str, body: dict)\nUpdate an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionExpenseDocument The updated expense.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_fetch_request","title":"update_fetch_requestasync","text":"update_fetch_request(request: Request, id: str, body: dict)\nPatch a fetch request's status and retry bookkeeping.
Delegates to FetchRequestCrudsService.update_status with the status, error_message, and retry_count fields from the payload, then returns the refreshed document.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredbody dict Payload with status, error_message, and retry_count fields.
requiredReturns:
Name Type DescriptionFetchRequestDocument The refreshed fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_fetch_request_put","title":"update_fetch_request_putasync","text":"update_fetch_request_put(\n request: Request, id: str, body: dict\n)\nReplace a fetch request by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredbody dict Full fetch request payload forwarded to the service.
requiredReturns:
Name Type DescriptionFetchRequestDocument The updated fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.update_tag","title":"update_tagasync","text":"update_tag(request: Request, id: str, body: dict)\nUpdate a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionTagDocument The updated tag.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.upload_entity_logo","title":"upload_entity_logoasync","text":"upload_entity_logo(\n request: Request, id: str, file: UploadFile\n)\nUpload a logo for an entity and persist it to the logo directory.
The file contents are hashed to derive a stable filename, written under LOGO_DIR, and the entity's logo field is updated with the served URL.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredfile UploadFile Uploaded logo image.
requiredReturns:
Name Type Descriptiondict A mapping with keys id, url, logo, and status.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/openapi/#interfaces.openapi.upload_file","title":"upload_fileasync","text":"upload_file(request: Request)\nUpload a raw request body as a file.
The filename is parsed from the content-disposition header (defaulting to upload) and combined with a content hash to form the stored filename under UPLOAD_DIR. The resulting UploadResult is persisted via the upload service.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the body, content type, and app.state.db_resources.
requiredReturns:
Name Type DescriptionUploadDocument The created upload record.
"},{"location":"interfaces/account/","title":"Account","text":"Account interface: thin FastAPI route handlers for the account resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/account/routes/","title":"Routes","text":""},{"location":"interfaces/account/routes/#interfaces.account.routes","title":"interfaces.account.routes","text":""},{"location":"interfaces/account/routes/#interfaces.account.routes--summary","title":"Summary","text":"Account REST handlers \u2014 thin API entry points for the account resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to AccountCrudsService via request.app.state.db_resources.
"},{"location":"interfaces/account/routes/#interfaces.account.routes-classes","title":"Classes","text":""},{"location":"interfaces/account/routes/#interfaces.account.routes-functions","title":"Functions","text":""},{"location":"interfaces/account/routes/#interfaces.account.routes.create_account","title":"create_accountasync","text":"create_account(request: Request, body: dict)\nCreate a new account.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Account payload forwarded to the service.
requiredReturns:
Name Type DescriptionAccountDocument The created account.
"},{"location":"interfaces/account/routes/#interfaces.account.routes.delete_account","title":"delete_accountasync","text":"delete_account(request: Request, id: str)\nDelete an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/account/routes/#interfaces.account.routes.get_account","title":"get_accountasync","text":"get_account(request: Request, id: str)\nGet an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredReturns:
Name Type DescriptionAccountDocument The matching account.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/account/routes/#interfaces.account.routes.list_accounts","title":"list_accountsasync","text":"list_accounts(\n request: Request, skip: int = 0, limit: int = 100\n)\nList accounts with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of accounts to skip (offset). Defaults to 0.
0 limit int Maximum number of accounts to return. Defaults to 100.
100 Returns:
Type Descriptionlist[AccountDocument]: Matching accounts from AccountCrudsService.search.
"},{"location":"interfaces/account/routes/#interfaces.account.routes.update_account","title":"update_accountasync","text":"update_account(request: Request, id: str, body: dict)\nUpdate an account by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Account id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionAccountDocument The updated account.
Raises:
Type DescriptionHTTPException 404 when no account matches the id.
"},{"location":"interfaces/ambiguity/","title":"Ambiguity","text":"Ambiguity interface: thin FastAPI route handlers for the ambiguity resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/ambiguity/routes/","title":"Routes","text":""},{"location":"interfaces/ambiguity/routes/#interfaces.ambiguity.routes","title":"interfaces.ambiguity.routes","text":""},{"location":"interfaces/ambiguity/routes/#interfaces.ambiguity.routes--summary","title":"Summary","text":"Ambiguity REST handlers \u2014 thin API entry points for the ambiguity resource, wired to openapi.yaml operationIds by the OpenAPI-first router. Resolution updates the ambiguity and requeues the parent fetch request when no pending ambiguities remain.
"},{"location":"interfaces/ambiguity/routes/#interfaces.ambiguity.routes-functions","title":"Functions","text":""},{"location":"interfaces/ambiguity/routes/#interfaces.ambiguity.routes.resolve_ambiguity","title":"resolve_ambiguityasync","text":"resolve_ambiguity(request: Request, id: str, body: dict)\nResolve an ambiguity by choosing one of its candidates.
Marks the ambiguity resolved, then requeues the parent fetch request when no pending ambiguities remain and the fetch request is paused.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Ambiguity id.
requiredbody dict Resolution payload; must contain the chosen candidate.
requiredReturns:
Type DescriptionUpdated ambiguity document.
Raises:
Type DescriptionHTTPException 400 when the chosen candidate is missing.
HTTPException 404 when the ambiguity is not found.
"},{"location":"interfaces/entity/","title":"Entity","text":"Entity interface: thin FastAPI route handlers for the entity resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/entity/routes/","title":"Routes","text":""},{"location":"interfaces/entity/routes/#interfaces.entity.routes","title":"interfaces.entity.routes","text":""},{"location":"interfaces/entity/routes/#interfaces.entity.routes--summary","title":"Summary","text":"Entity REST handlers \u2014 thin API entry points for the entity resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to EntityCrudsService via request.app.state.db_resources.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes-classes","title":"Classes","text":""},{"location":"interfaces/entity/routes/#interfaces.entity.routes-functions","title":"Functions","text":""},{"location":"interfaces/entity/routes/#interfaces.entity.routes.create_entity","title":"create_entityasync","text":"create_entity(request: Request, body: dict)\nCreate a new entity.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Entity payload forwarded to the service.
requiredReturns:
Name Type DescriptionEntityDocument The created entity.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes.delete_entity","title":"delete_entityasync","text":"delete_entity(request: Request, id: str)\nDelete an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes.get_entity","title":"get_entityasync","text":"get_entity(request: Request, id: str)\nGet an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredReturns:
Name Type DescriptionEntityDocument The matching entity.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes.list_entities","title":"list_entitiesasync","text":"list_entities(\n request: Request, skip: int = 0, limit: int = 100\n)\nList entities with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of entities to skip (offset). Defaults to 0.
0 limit int Maximum number of entities to return. Defaults to 100.
100 Returns:
Type Descriptionlist[EntityDocument]: Matching entities from EntityCrudsService.search.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes.update_entity","title":"update_entityasync","text":"update_entity(request: Request, id: str, body: dict)\nUpdate an entity by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionEntityDocument The updated entity.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/entity/routes/#interfaces.entity.routes.upload_entity_logo","title":"upload_entity_logoasync","text":"upload_entity_logo(\n request: Request, id: str, file: UploadFile\n)\nUpload a logo for an entity and persist it to the logo directory.
The file contents are hashed to derive a stable filename, written under LOGO_DIR, and the entity's logo field is updated with the served URL.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Entity id.
requiredfile UploadFile Uploaded logo image.
requiredReturns:
Name Type Descriptiondict A mapping with keys id, url, logo, and status.
Raises:
Type DescriptionHTTPException 404 when no entity matches the id.
"},{"location":"interfaces/expense/","title":"Expense","text":"Expense interface: thin FastAPI route handlers for the expense resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/expense/routes/","title":"Routes","text":""},{"location":"interfaces/expense/routes/#interfaces.expense.routes","title":"interfaces.expense.routes","text":""},{"location":"interfaces/expense/routes/#interfaces.expense.routes--summary","title":"Summary","text":"Expense REST handlers \u2014 thin API entry points for the expense resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to ExpenseCrudsService via request.app.state.db_resources.
"},{"location":"interfaces/expense/routes/#interfaces.expense.routes-classes","title":"Classes","text":""},{"location":"interfaces/expense/routes/#interfaces.expense.routes-functions","title":"Functions","text":""},{"location":"interfaces/expense/routes/#interfaces.expense.routes.create_expense","title":"create_expenseasync","text":"create_expense(request: Request, body: dict)\nCreate a new expense.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Expense payload forwarded to the service.
requiredReturns:
Name Type DescriptionExpenseDocument The created expense.
"},{"location":"interfaces/expense/routes/#interfaces.expense.routes.delete_expense","title":"delete_expenseasync","text":"delete_expense(request: Request, id: str)\nDelete an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/expense/routes/#interfaces.expense.routes.get_expense","title":"get_expenseasync","text":"get_expense(request: Request, id: str)\nGet an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredReturns:
Name Type DescriptionExpenseDocument The matching expense.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/expense/routes/#interfaces.expense.routes.list_expenses","title":"list_expensesasync","text":"list_expenses(\n request: Request,\n offset: int = 0,\n limit: int = 10,\n start_date: str = \"\",\n end_date: str = \"\",\n)\nList expenses with pagination, excluding self-transfers.
Expenses tagged with a self-transfer tag are filtered out. The start_date and end_date parameters are accepted by the signature but not applied to the underlying search filter.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of expenses to skip (offset). Defaults to 0.
0 limit int Maximum number of expenses to return. Defaults to 10.
10 start_date str Accepted date-range start; not applied to the search.
'' end_date str Accepted date-range end; not applied to the search.
'' Returns:
Type Descriptionlist[ExpenseDocument]: Matching expenses from ExpenseCrudsService.search.
"},{"location":"interfaces/expense/routes/#interfaces.expense.routes.update_expense","title":"update_expenseasync","text":"update_expense(request: Request, id: str, body: dict)\nUpdate an expense by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Expense id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionExpenseDocument The updated expense.
Raises:
Type DescriptionHTTPException 404 when no expense matches the id.
"},{"location":"interfaces/fetch_request/","title":"Fetch Request","text":"Fetch request interface: thin FastAPI route handlers, SSE handlers, and a CLI for the fetch request resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/fetch_request/routes/","title":"Routes","text":""},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes","title":"interfaces.fetch_request.routes","text":""},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes--summary","title":"Summary","text":"Fetch request REST handlers \u2014 thin API entry points for the fetch request resource, wired to openapi.yaml operationIds by the OpenAPI-first router. Deletion cascades to related expenses, ambiguities, and the HTTP cache.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes-classes","title":"Classes","text":""},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes-functions","title":"Functions","text":""},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.create_fetch_request","title":"create_fetch_requestasync","text":"create_fetch_request(request: Request, body: dict)\nCreate a new fetch request.
A stable fingerprint is derived from the source payload and stored on the document when the payload does not already provide one.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Fetch request payload forwarded to the service.
requiredReturns:
Name Type DescriptionFetchRequestDocument The created fetch request.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.delete_fetch_request","title":"delete_fetch_requestasync","text":"delete_fetch_request(request: Request, id: str)\nDelete a fetch request and its dependent data.
Cascades deletes to related expenses and ambiguities, removes the fetch request, and invalidates the expenses HTTP cache.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.get_fetch_request","title":"get_fetch_requestasync","text":"get_fetch_request(request: Request, id: str)\nGet a fetch request by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type DescriptionFetchRequestDocument The matching fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.list_fetch_requests","title":"list_fetch_requestsasync","text":"list_fetch_requests(\n request: Request, offset: int = 0, limit: int = 100\n)\nList fetch requests with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of fetch requests to skip (offset). Defaults to 0.
0 limit int Maximum number of fetch requests to return. Defaults to 100.
100 Returns:
Type Descriptionlist[FetchRequestDocument]: Matching fetch requests from the service.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.update_fetch_request","title":"update_fetch_requestasync","text":"update_fetch_request(request: Request, id: str, body: dict)\nPatch a fetch request's status and retry bookkeeping.
Delegates to FetchRequestCrudsService.update_status with the status, error_message, and retry_count fields from the payload, then returns the refreshed document.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredbody dict Payload with status, error_message, and retry_count fields.
requiredReturns:
Name Type DescriptionFetchRequestDocument The refreshed fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/fetch_request/routes/#interfaces.fetch_request.routes.update_fetch_request_put","title":"update_fetch_request_putasync","text":"update_fetch_request_put(\n request: Request, id: str, body: dict\n)\nReplace a fetch request by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredbody dict Full fetch request payload forwarded to the service.
requiredReturns:
Name Type DescriptionFetchRequestDocument The updated fetch request.
Raises:
Type DescriptionHTTPException 404 when no fetch request matches the id.
"},{"location":"interfaces/fetch_request/sse/","title":"Sse","text":""},{"location":"interfaces/fetch_request/sse/#interfaces.fetch_request.sse","title":"interfaces.fetch_request.sse","text":""},{"location":"interfaces/fetch_request/sse/#interfaces.fetch_request.sse--summary","title":"Summary","text":"Fetch request SSE handlers \u2014 real-time progress events and ambiguity listing for a given fetch request. Events are streamed via an SSE bus; ambiguities are queried directly from the ambiguity service.
"},{"location":"interfaces/fetch_request/sse/#interfaces.fetch_request.sse-functions","title":"Functions","text":""},{"location":"interfaces/fetch_request/sse/#interfaces.fetch_request.sse.list_ambiguities","title":"list_ambiguitiesasync","text":"list_ambiguities(request: Request, id: str)\nList pending ambiguities for a fetch request.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Name Type Descriptionlist Pending ambiguity documents from the ambiguity service.
"},{"location":"interfaces/fetch_request/sse/#interfaces.fetch_request.sse.stream_fetch_events","title":"stream_fetch_eventsasync","text":"stream_fetch_events(request: Request, id: str)\nStream progress events for a fetch request as server-sent events.
If the SSE bus is not configured on app.state.db_resources an empty events list is returned. Otherwise a text/event-stream response is yielded, polling the bus every 500 ms until the client disconnects.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Fetch request id.
requiredReturns:
Type DescriptionStreamingResponse | dict: SSE stream, or {\"events\": []} when the bus
is unavailable.
"},{"location":"interfaces/fetch_request/cli/","title":"Cli","text":"Fetch request CLI package: argparse-driven command entry point (main), subcommand implementations (commands), and the pipeline runner (run).
"},{"location":"interfaces/fetch_request/cli/__main__/","title":"Main","text":""},{"location":"interfaces/fetch_request/cli/__main__/#interfaces.fetch_request.cli.__main__","title":"interfaces.fetch_request.cli.__main__","text":""},{"location":"interfaces/fetch_request/cli/__main__/#interfaces.fetch_request.cli.__main__--summary","title":"Summary","text":"CLI for FetchRequest management \u2014 list, get, create, run, resolve, retry.
Example:
```python\npython -m interfaces.fetch_request.cli list\npython -m interfaces.fetch_request.cli get <id>\npython -m interfaces.fetch_request.cli create-file --account \"ICICI Savings\" --path ./stmt.pdf --start-date 2025-04-01 --end-date 2026-03-31\npython -m interfaces.fetch_request.cli run <id>\npython -m interfaces.fetch_request.cli ambiguities <fr_id>\npython -m interfaces.fetch_request.cli resolve <fr_id>\npython -m interfaces.fetch_request.cli retry <id>\n```\nasync","text":"main()\nRun the FetchRequest CLI: parse arguments, dispatch to a subcommand.
Initializes the application resources before dispatch and shuts them down afterwards.
"},{"location":"interfaces/fetch_request/cli/commands/","title":"Commands","text":""},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands","title":"interfaces.fetch_request.cli.commands","text":""},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands--summary","title":"Summary","text":"Subcommand implementations: list, get, create-file, create-email, ambiguities, resolve, retry. Each cmd_* function receives the parsed argparse namespace and prints its result to stdout.
async","text":"cmd_ambiguities(args)\nList ambiguities for a fetch request, optionally cleaning them.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with fr_id, status, clean, and yes fields.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_create_email","title":"cmd_create_emailasync","text":"cmd_create_email(args)\nCreate an email-based fetch request.
Requires an existing account and user; parses the date range, builds an EmailSource, and persists the created fetch request.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with account, user, from-email, bank, subject, raw-terms, start-date, and end-date fields.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_create_file","title":"cmd_create_fileasync","text":"cmd_create_file(args)\nCreate a file-based fetch request.
Requires an existing account and user; parses the date range, builds a FileSource, and persists the created fetch request.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with account, user, path, bank, start-date, and end-date fields.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_get","title":"cmd_getasync","text":"cmd_get(args)\nShow details of a single fetch request.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with the id field.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_list","title":"cmd_listasync","text":"cmd_list(args)\nList fetch requests, optionally filtered by status and account.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with status, account, and limit fields.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_resolve","title":"cmd_resolveasync","text":"cmd_resolve(args)\nResolve ambiguities, interactively or directly by amount and balance.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with fr_id, ambiguity-id, amount, and balance fields.
required"},{"location":"interfaces/fetch_request/cli/commands/#interfaces.fetch_request.cli.commands.cmd_retry","title":"cmd_retryasync","text":"cmd_retry(args)\nReset a failed or paused fetch request back to pending.
Optionally clears extracted data such as raw_lines and txn_blocks.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with the id and reset-data fields.
required"},{"location":"interfaces/fetch_request/cli/run/","title":"Run","text":""},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run","title":"interfaces.fetch_request.cli.run","text":""},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run--summary","title":"Summary","text":"Pipeline runner subcommand \u2014 drives _extract \u2192 _enrich \u2192 _process_expenses with a --till guard that stops the run after a given stage.
"},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run-classes","title":"Classes","text":""},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run-functions","title":"Functions","text":""},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run.cmd_run","title":"cmd_runasync","text":"cmd_run(args)\nRun the pipeline for a fetch request using parsed CLI arguments.
Parameters:
Name Type Description Defaultargs Parsed argparse namespace with id, till, force, and resume fields.
required"},{"location":"interfaces/fetch_request/cli/run/#interfaces.fetch_request.cli.run.run_pipeline","title":"run_pipelineasync","text":"run_pipeline(\n fr_id: str,\n *,\n till: str = \"expense\",\n force: bool = False,\n resume: bool = False,\n splitter=None\n)\nRun the extraction pipeline for a fetch request.
Fetches the source content, extracts raw expenses, enriches them, and saves them as expenses, stopping between stages when till asks for it.
Parameters:
Name Type Description Defaultfr_id str Fetch request id.
requiredtill str Stop stage: raw, enriched, or expense. Defaults to expense.
'expense' force bool Reset to pending and clear extraction data before running. Defaults to False.
False resume bool Load previously resolved choices before running. Defaults to False.
False splitter Optional custom splitter injected into the extractor.
None"},{"location":"interfaces/report/","title":"Report","text":"Reports interface: thin API entry points for the reports resource.
"},{"location":"interfaces/report/routes/","title":"Routes","text":""},{"location":"interfaces/report/routes/#interfaces.report.routes","title":"interfaces.report.routes","text":""},{"location":"interfaces/report/routes/#interfaces.report.routes--summary","title":"Summary","text":"Report REST handlers \u2014 thin API entry points for the reports resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to ReportService via request.app.state.db_resources and translate domain validation errors into 400 responses.
"},{"location":"interfaces/report/routes/#interfaces.report.routes-classes","title":"Classes","text":""},{"location":"interfaces/report/routes/#interfaces.report.routes-functions","title":"Functions","text":""},{"location":"interfaces/report/routes/#interfaces.report.routes.create_report","title":"create_reportasync","text":"create_report(request: Request, body: dict)\nGenerate a report snapshot from a query definition.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Report query payload; validated into a ReportQuery.
requiredReturns:
Name Type DescriptionReportSnapshotDocument The generated snapshot.
Raises:
Type DescriptionHTTPException 400 when the query payload is invalid.
"},{"location":"interfaces/report/routes/#interfaces.report.routes.delete_report","title":"delete_reportasync","text":"delete_report(request: Request, id: str)\nDelete a report snapshot by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Report snapshot id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when the snapshot does not exist.
"},{"location":"interfaces/report/routes/#interfaces.report.routes.get_report","title":"get_reportasync","text":"get_report(\n request: Request,\n id: str,\n granularity: Optional[List[str]] = Query(None),\n period_ids: Optional[List[str]] = Query(None),\n flow: str = \"outflows\",\n payee: Optional[List[str]] = Query(None),\n tags: Optional[List[str]] = Query(None),\n)\nFetch a report snapshot with optional granularity, flow, and filter overrides.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Report snapshot id.
requiredgranularity Optional[List[str]] Granularities to materialize; empty means the snapshot's default set.
Query(None) period_ids Optional[List[str]] Period labels to constrain output.
Query(None) flow str Flow filter of inflows, outflows, or both. Defaults to outflows.
'outflows' payee Optional[List[str]] Payee names to include.
Query(None) tags Optional[List[str]] Tag paths to include.
Query(None) Returns:
Name Type DescriptionReport The fetched report.
Raises:
Type DescriptionHTTPException 400 when the report arguments are invalid.
HTTPException 404 when the snapshot does not exist.
"},{"location":"interfaces/report/routes/#interfaces.report.routes.list_reports","title":"list_reportsasync","text":"list_reports(\n request: Request, offset: int = 0, limit: int = 100\n)\nList report snapshots with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredoffset int Number of snapshots to skip (offset). Defaults to 0.
0 limit int Maximum number of snapshots to return. Defaults to 100.
100 Returns:
Type Descriptionlist[ReportSnapshotDocument]: Matching snapshots from the report service.
"},{"location":"interfaces/tag/","title":"Tag","text":"Tag interface: thin FastAPI route handlers for the tag resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/tag/routes/","title":"Routes","text":""},{"location":"interfaces/tag/routes/#interfaces.tag.routes","title":"interfaces.tag.routes","text":""},{"location":"interfaces/tag/routes/#interfaces.tag.routes--summary","title":"Summary","text":"Tag REST handlers \u2014 thin API entry points for the tag resource, wired to openapi.yaml operationIds by the OpenAPI-first router. All handlers delegate to TagCrudsService via request.app.state.db_resources.
"},{"location":"interfaces/tag/routes/#interfaces.tag.routes-classes","title":"Classes","text":""},{"location":"interfaces/tag/routes/#interfaces.tag.routes-functions","title":"Functions","text":""},{"location":"interfaces/tag/routes/#interfaces.tag.routes.create_tag","title":"create_tagasync","text":"create_tag(request: Request, body: dict)\nCreate a new tag.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict Tag payload forwarded to the service.
requiredReturns:
Name Type DescriptionTagDocument The created tag.
"},{"location":"interfaces/tag/routes/#interfaces.tag.routes.delete_tag","title":"delete_tagasync","text":"delete_tag(request: Request, id: str)\nDelete a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredReturns:
Name Type DescriptionResponse Empty 204 response on successful delete.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/tag/routes/#interfaces.tag.routes.get_tag","title":"get_tagasync","text":"get_tag(request: Request, id: str)\nGet a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredReturns:
Name Type DescriptionTagDocument The matching tag.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/tag/routes/#interfaces.tag.routes.list_tags","title":"list_tagsasync","text":"list_tags(\n request: Request, skip: int = 0, limit: int = 1000\n)\nList tags with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of tags to skip (offset). Defaults to 0.
0 limit int Maximum number of tags to return. Defaults to 1000.
1000 Returns:
Type Descriptionlist[TagDocument]: Matching tags from TagCrudsService.search.
"},{"location":"interfaces/tag/routes/#interfaces.tag.routes.update_tag","title":"update_tagasync","text":"update_tag(request: Request, id: str, body: dict)\nUpdate a tag by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str Tag id.
requiredbody dict Fields to update, forwarded to the service.
requiredReturns:
Name Type DescriptionTagDocument The updated tag.
Raises:
Type DescriptionHTTPException 404 when no tag matches the id.
"},{"location":"interfaces/upload/","title":"Upload","text":"Upload interface: thin FastAPI route handlers for the upload resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/upload/routes/","title":"Routes","text":""},{"location":"interfaces/upload/routes/#interfaces.upload.routes","title":"interfaces.upload.routes","text":""},{"location":"interfaces/upload/routes/#interfaces.upload.routes--summary","title":"Summary","text":"Upload REST handlers \u2014 thin API entry points for the upload resource, wired to openapi.yaml operationIds by the OpenAPI-first router. Files are persisted under UPLOAD_DIR and a name-hashed copy is registered with the upload service.
"},{"location":"interfaces/upload/routes/#interfaces.upload.routes-classes","title":"Classes","text":""},{"location":"interfaces/upload/routes/#interfaces.upload.routes-functions","title":"Functions","text":""},{"location":"interfaces/upload/routes/#interfaces.upload.routes.get_uploaded_file","title":"get_uploaded_fileasync","text":"get_uploaded_file(request: Request, filepath: str)\nServe an uploaded file from disk.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request.
requiredfilepath str Relative path of the file under UPLOAD_DIR.
requiredReturns:
Name Type DescriptionFileResponse The requested file with its original filename.
Raises:
Type DescriptionHTTPException 404 when the file does not exist.
"},{"location":"interfaces/upload/routes/#interfaces.upload.routes.list_uploads","title":"list_uploadsasync","text":"list_uploads(request: Request)\nList all upload records.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredReturns:
Type Descriptionlist[UploadDocument]: All uploads from the upload service.
"},{"location":"interfaces/upload/routes/#interfaces.upload.routes.upload_file","title":"upload_fileasync","text":"upload_file(request: Request)\nUpload a raw request body as a file.
The filename is parsed from the content-disposition header (defaulting to upload) and combined with a content hash to form the stored filename under UPLOAD_DIR. The resulting UploadResult is persisted via the upload service.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the body, content type, and app.state.db_resources.
requiredReturns:
Name Type DescriptionUploadDocument The created upload record.
"},{"location":"interfaces/user/","title":"User","text":"User interface: thin FastAPI route handlers for the user resource, wired to openapi.yaml operationIds by the OpenAPI-first router.
"},{"location":"interfaces/user/routes/","title":"Routes","text":""},{"location":"interfaces/user/routes/#interfaces.user.routes","title":"interfaces.user.routes","text":""},{"location":"interfaces/user/routes/#interfaces.user.routes--summary","title":"Summary","text":"User REST handlers \u2014 thin API entry points for the user resource, wired to openapi.yaml operationIds by the OpenAPI-first router. Current-user handlers read the authenticated principal from request.state and create the profile on first access.
"},{"location":"interfaces/user/routes/#interfaces.user.routes-classes","title":"Classes","text":""},{"location":"interfaces/user/routes/#interfaces.user.routes-functions","title":"Functions","text":""},{"location":"interfaces/user/routes/#interfaces.user.routes.create_user","title":"create_userasync","text":"create_user(request: Request, body: dict)\nCreate a new user.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredbody dict User payload forwarded to the service.
requiredReturns:
Name Type DescriptionUserDocument The created user.
"},{"location":"interfaces/user/routes/#interfaces.user.routes.get_current_user","title":"get_current_userasync","text":"get_current_user(request: Request)\nGet the profile of the authenticated user.
Reads the principal from request.state and creates the profile on first access when it does not exist yet.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the authenticated user and app.state.db_resources.
requiredReturns:
Name Type DescriptionUserDocument The current user's profile.
Raises:
Type DescriptionHTTPException 401 when the request is not authenticated.
"},{"location":"interfaces/user/routes/#interfaces.user.routes.get_user","title":"get_userasync","text":"get_user(request: Request, id: str)\nGet a user by id.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredid str User id.
requiredReturns:
Name Type DescriptionUserDocument The matching user.
Raises:
Type DescriptionHTTPException 404 when no user matches the id.
"},{"location":"interfaces/user/routes/#interfaces.user.routes.list_users","title":"list_usersasync","text":"list_users(\n request: Request, skip: int = 0, limit: int = 100\n)\nList users with pagination.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries app.state.db_resources.
requiredskip int Number of users to skip (offset). Defaults to 0.
0 limit int Maximum number of users to return. Defaults to 100.
100 Returns:
Type Descriptionlist[UserDocument]: Matching users from UserCrudsService.search.
"},{"location":"interfaces/user/routes/#interfaces.user.routes.update_current_user","title":"update_current_userasync","text":"update_current_user(request: Request, body: dict)\nUpdate the profile of the authenticated user.
Creates the profile on first access, then applies the update payload.
Parameters:
Name Type Description Defaultrequest Request Incoming HTTP request; carries the authenticated user and app.state.db_resources.
requiredbody dict Fields to update on the current user's profile.
requiredReturns:
Name Type DescriptionUserDocument The updated profile.
Raises:
Type DescriptionHTTPException 401 when the request is not authenticated.
"},{"location":"pipelines/","title":"Pipelines","text":"Top-level pipelines package for the khata-app Expenses Service backend.
Pipeline families live in dedicated subpackages. The enrichment family lives under pipelines.enrichment and is documented there; keep this package free of implementation modules.
Enrichment pipelines (entity + tags) as hexa-wired dagpipe graphs.
"},{"location":"pipelines/enrichment/#pipelines.enrichment--notes","title":"Notes","text":"get_entity_pipeline / get_tags_pipeline return memoized, fully assembled roots \u2014 hexa wiring + pattern registry + dagpipe Engine \u2014 matching the OG domain/enrichment adaptors' behaviour.
get_entity_pipeline()\nBuild and memoize the entity enrichment pipeline root.
Returns:
Name Type DescriptionImplEntityPipeline The assembled entity pipeline root.
"},{"location":"pipelines/enrichment/#pipelines.enrichment.get_tags_pipeline","title":"get_tags_pipeline","text":"get_tags_pipeline()\nBuild and memoize the tags enrichment pipeline root.
Returns:
Name Type DescriptionImplTagsPipeline The assembled tags pipeline root.
"},{"location":"pipelines/enrichment/entity/","title":"Entity","text":"Entity enrichment family (hexa-wired dagpipe graph).
"},{"location":"pipelines/enrichment/entity/#pipelines.enrichment.entity--notes","title":"Notes","text":"Houses the abstract contracts (abc.py), the concrete dagpipe stage nodes and root (impl.py) and the runtime resources (resources/) for the entity family.
Abstract contracts for the entity enrichment family (no implementation).
The entity family is the classic dagpipe chain:
normalize \u2192 extract_candidates \u2192 candidate_flags \u2192 amount_flags \u2192\nset_entity \u2192 entity_alias \u2192 fallback\nEach stage port is a dagpipe Node whose resolve yields forked States carrying confidence. EntityPipeline (the hexa root) wires the stage slots and runs the graph through a dagpipe Engine; EntityFinalizePort turns the terminal states into the entity result dict.
Bases: RegistryPort, ABC
candidate.value \u2192 candidate.flags via CANDIDATE_BASED_FLAG_MAPPING.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.CandidateFlagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.CandidateFlagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.CandidateFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.CandidateFlagsPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield forks with candidate.flags updated from the candidate value.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying candidate.
Yields:
Name Type DescriptionState Iterable[State] Forked states with candidate.flags populated.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.CandidateFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort","title":"EntityAliasPort","text":" Bases: RegistryPort, ABC
candidate.value \u2192 entity via ENTITY_ALIAS_REGEX (when name not set).
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the aliased entity fork from the candidate value.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying a candidate value.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states with the aliased entity.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityAliasPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityFinalizePort","title":"EntityFinalizePort","text":" Bases: FinalizePort, ABC
terminal states \u2192 {entity.name, entity.id, entity.type, ...}.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityFinalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityFinalizePort.process","title":"processabstractmethod","text":"process(states: List) -> dict\nBuild the entity result dict from the terminal states.
Parameters:
Name Type Description Defaultstates List Terminal states from the dagpipe graph.
requiredReturns:
Name Type Descriptiondict dict The entity result dict.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityPipeline","title":"EntityPipeline","text":" Bases: ABC
Root \u2014 wires normalize \u2192 \u2026 \u2192 fallback, then runs the dagpipe graph.
Attributes:
Name Type Descriptionnormalize NormalizePort Normalize stage port.
extract_candidates ExtractCandidatesPort Extract-candidates stage port.
candidate_flags CandidateFlagsPort Candidate-flags stage port.
amount_flags AmountFlagsPort Amount-flags stage port.
set_entity SetEntityPort Set-entity stage port.
entity_alias EntityAliasPort Entity-alias stage port.
fallback FallbackPort Fallback stage port.
finalize EntityFinalizePort Terminal finalize port.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityPipeline-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.EntityPipeline.enrich","title":"enrichabstractmethod","text":"enrich(payload: dict) -> dict\nEnrich a raw transaction payload into an entity result.
Parameters:
Name Type Description Defaultpayload dict Raw transaction payload.
requiredReturns:
Name Type Descriptiondict dict The entity result dict.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort","title":"ExtractCandidatesPort","text":" Bases: RegistryPort, ABC
signals \u2192 candidate.value forks (confidence penalties on fallbacks).
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield candidate.value forks, penalizing fallback candidates.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying signals.
Yields:
Name Type DescriptionState Iterable[State] Forked states carrying a candidate.value.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.ExtractCandidatesPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort","title":"FallbackPort","text":" Bases: RegistryPort, ABC
Terminal \u2014 merchant/person fallback or Unknown.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the terminal fallback entity fork.
Parameters:
Name Type Description Defaultstate State Incoming terminal dagpipe state.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states with the fallback entity.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.FallbackPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort","title":"NormalizePort","text":" Bases: RegistryPort, ABC
raw.description \u2192 signals (raw/items/parts), stripping number sequences.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the normalized signals fork of the incoming state.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying raw.description.
Yields:
Name Type DescriptionState Iterable[State] Forked states carrying the normalized signals.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.NormalizePort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort","title":"SetEntityPort","text":" Bases: RegistryPort, ABC
candidate.flags \u2192 entity via FLAGS_BASED_ENTITY_RULES.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the resolved entity fork from candidate flags.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying candidate flags.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states carrying the resolved entity.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/abc/#pipelines.enrichment.entity.abc.SetEntityPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/","title":"Impl","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl","title":"pipelines.enrichment.entity.impl","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl--summary","title":"Summary","text":"Concrete entity-family implementations (dagpipe stage nodes + root).
Stage bodies are ports of domain/enrichment/entity/resolver.py, keeping the exact fork/confidence semantics. The root ImplEntityPipeline.enrich runs the hexa-wired stage graph through a dagpipe Engine (assembled in shared/loader.py) and delegates terminal processing to ImplEntityFinalizePort (port of EntityStatesProcessorAdaptor).
Bases: CandidateFlagsPort
Candidate-flags stage: keyword matches append candidate-based flags.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort.candidate_based_flag_mapping","title":"candidate_based_flag_mappingproperty","text":"candidate_based_flag_mapping\nKeyword \u2192 flag mapping used for candidate flagging.
Returns:
Name Type Descriptiondict The candidate-based flag mapping.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nAppend candidate flags whose keywords appear in the candidate value.
Parameters:
Name Type Description Defaultstate State Incoming state carrying a candidate value and flags.
requiredYields:
Name Type DescriptionState Iterable[State] A fork with updated candidate.flags when flags changed, else the unmodified state.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplCandidateFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort","title":"ImplEntityAliasPort","text":" Bases: EntityAliasPort
Entity-alias stage: resolve the entity from the candidate via aliases.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.default_logo_mapping","title":"default_logo_mappingproperty","text":"default_logo_mapping\nEntity type \u2192 default logo mapping.
Returns:
Name Type Descriptiondict The default logo mapping.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.entity_alias_regex","title":"entity_alias_regexproperty","text":"entity_alias_regex\nAlias regex \u2192 name pairs used for entity resolution.
Returns:
Type DescriptionList[Tuple[re.Pattern, str]]: Compiled (regex, name) pairs.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.entity_type_mapping","title":"entity_type_mappingproperty","text":"entity_type_mapping\nEntity id \u2192 type mapping used for entity resolution.
Returns:
Name Type Descriptiondict The entity type mapping.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nResolve the entity from the candidate value via alias regexes.
Parameters:
Name Type Description Defaultstate State Incoming state carrying a candidate value.
requiredYields:
Name Type DescriptionState Iterable[State] A fork with the aliased entity payload, or the unmodified state when the name is already set or no alias matches.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityAliasPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityFinalizePort","title":"ImplEntityFinalizePort","text":" Bases: EntityFinalizePort
Finalize terminal states into the entity result dict.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityFinalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityFinalizePort.process","title":"process","text":"process(states: List) -> dict\nBuild the entity result dict from the best terminal state.
Parameters:
Name Type Description Defaultstates List Terminal states from the dagpipe graph.
requiredReturns:
Name Type Descriptiondict dict The entity result dict (name, id, type, logo, raw_candidate, candidate flags and tags).
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityPipeline","title":"ImplEntityPipeline","text":" Bases: EntityPipeline
Concrete entity pipeline root wiring the stage ports.
Attributes:
Name Type Descriptionnormalize ImplNormalizePort Normalize stage port.
extract_candidates ImplExtractCandidatesPort Extract-candidates port.
candidate_flags ImplCandidateFlagsPort Candidate-flags port.
amount_flags ImplAmountFlagsPort Amount-flags port.
set_entity ImplSetEntityPort Set-entity port.
entity_alias ImplEntityAliasPort Entity-alias port.
fallback ImplFallbackPort Fallback port.
finalize ImplEntityFinalizePort Terminal finalize port.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityPipeline-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplEntityPipeline.enrich","title":"enrich","text":"enrich(payload: dict) -> dict\nRun the entity graph on a raw payload and finalize the result.
Parameters:
Name Type Description Defaultpayload dict Raw transaction payload.
requiredReturns:
Name Type Descriptiondict dict The entity result dict from the finalize port.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort","title":"ImplExtractCandidatesPort","text":" Bases: ExtractCandidatesPort
Extract-candidates stage: signals \u2192 candidate value forks with penalties.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort.candidate_regex","title":"candidate_regexproperty","text":"candidate_regex\nCandidate extraction regexes from the pattern registry.
Returns:
Type DescriptionList[re.Pattern]: Compiled candidate extraction regexes.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort.negative_candidates","title":"negative_candidatesproperty","text":"negative_candidates\nTokens excluded from candidate extraction.
Returns:
Name Type DescriptionList The registered negative candidate tokens.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nYield candidate-value forks from signals, penalizing fallbacks.
Parameters:
Name Type Description Defaultstate State Incoming state carrying signals.
Yields:
Name Type DescriptionState Iterable[State] Forks carrying candidate.value for each accepted candidate (parts/items fallbacks penalized), or a single penalized fork when nothing matches.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplExtractCandidatesPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort","title":"ImplFallbackPort","text":" Bases: FallbackPort
Terminal fallback stage: candidate merchant/person, else Unknown.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nAssign the terminal fallback entity when none was resolved.
Parameters:
Name Type Description Defaultstate State Incoming terminal state.
requiredYields:
Name Type DescriptionState Iterable[State] A fork carrying the fallback entity (candidate, Unknown, or the already-resolved entity).
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplFallbackPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort","title":"ImplNormalizePort","text":" Bases: NormalizePort
Normalize stage: strip number sequences, then build raw/items/parts signals.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nClean raw.description and yield a single signals fork.
Parameters:
Name Type Description Defaultstate State Incoming state carrying raw.description and the raw.amount/raw.balance values.
Yields:
Name Type DescriptionState Iterable[State] A single fork populating signals.raw, signals.items and signals.parts.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplNormalizePort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort","title":"ImplSetEntityPort","text":" Bases: SetEntityPort
Set-entity stage: resolve the entity from candidate flags via rules.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.default_logo_mapping","title":"default_logo_mappingproperty","text":"default_logo_mapping\nEntity type \u2192 default logo mapping.
Returns:
Name Type Descriptiondict The default logo mapping.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.entity_type_mapping","title":"entity_type_mappingproperty","text":"entity_type_mapping\nEntity id \u2192 type mapping used for entity resolution.
Returns:
Name Type Descriptiondict The entity type mapping.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.flags_based_entity_rules","title":"flags_based_entity_rulesproperty","text":"flags_based_entity_rules\nFlag-matching rules that emit the resolved entity.
Returns:
Type DescriptionList[Dict]: The ordered entity rules.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nResolve the entity from candidate flags using the first matching rule.
Parameters:
Name Type Description Defaultstate State Incoming state carrying candidate flags.
requiredYields:
Name Type DescriptionState Iterable[State] A fork with the resolved entity payload, the unmodified state when an entity name is already set, or a penalized fork when unresolvable.
"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl.ImplSetEntityPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/entity/impl/#pipelines.enrichment.entity.impl-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/","title":"Shared","text":"Shared enrichment core: models, identity, utils, ports, loader, registry.
"},{"location":"pipelines/enrichment/shared/#pipelines.enrichment.shared--notes","title":"Notes","text":"These modules are shared by the entity and tags enrichment families.
Entity identity helpers (port of domain/enrichment/entity/identity.py).
build_entity(\n name: str,\n entity_type: str = \"merchant\",\n entity_logo: str | None = None,\n) -> dict\nBuild the entity payload dict from name, type and logo.
Parameters:
Name Type Description Defaultname str Entity display name.
requiredentity_type str Entity type key, defaults to \"merchant\".
'merchant' entity_logo str | None Logo URL, or None.
None Returns:
Name Type Descriptiondict dict Entity payload with entity.id, entity.name, entity.type and entity.logo keys.
canonicalize_candidate(candidate: str | None) -> str | None\nCanonicalize a candidate value via normalize_key.
Parameters:
Name Type Description Defaultcandidate str | None Raw candidate, or None/empty.
requiredReturns:
Type Descriptionstr | None str | None: The normalized candidate, or None when candidate is empty.
normalize_key(text: str | None) -> str | None\nNormalize a key: NFKC, lowercase and stripped.
Parameters:
Name Type Description Defaulttext str | None Raw key, or None.
requiredReturns:
Type Descriptionstr | None str | None: The normalized key, or None when text is None.
to_entity_id(name: str | None) -> str | None\nBuild the canonical snake-cased entity id from a name.
Parameters:
Name Type Description Defaultname str | None Raw entity name, or None/empty.
requiredReturns:
Type Descriptionstr | None str | None: The snake-cased entity id, or None when name is empty.
Concrete shared enrichment ports.
ImplAmountFlagsPort is the port of domain.enrichment.nodes.AmountBasedFlagNode \u2014 used by both the entity and tags families.
Bases: AmountFlagsPort
Amount-flags stage: map the amount to amount_* candidate flags.
Shared by the entity and tags families; the amount-flag name encodes the comparison (e.g. amount_greater_than_500, amount_within_5_500).
property","text":"amount_based_flag_mapping\nFlag names to evaluate, taken from the registry.
Returns:
Name Type DescriptionList The registered amount-flag names.
"},{"location":"pipelines/enrichment/shared/impl/#pipelines.enrichment.shared.impl.ImplAmountFlagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/shared/impl/#pipelines.enrichment.shared.impl.ImplAmountFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/impl/#pipelines.enrichment.shared.impl.ImplAmountFlagsPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nEvaluate the amount-based flags and append the matches.
Parameters:
Name Type Description Defaultstate State Incoming state carrying raw.amount and candidate.flags.
Yields:
Name Type DescriptionState Iterable[State] A fork with candidate.flags updated when flags were appended, else the unmodified state.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/shared/impl/#pipelines.enrichment.shared.impl.ImplAmountFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/shared/loader/","title":"Loader","text":""},{"location":"pipelines/enrichment/shared/loader/#pipelines.enrichment.shared.loader","title":"pipelines.enrichment.shared.loader","text":""},{"location":"pipelines/enrichment/shared/loader/#pipelines.enrichment.shared.loader--summary","title":"Summary","text":"Assemble a hexa-wired enrichment port tree into a runnable dagpipe graph.
Flow (mirrors domain/enrichment/{entity,tags}/pipeline.py#load, but hexa replaces the class-path import/instantiation and the dagpipe spec is consumed for its schema/graph/per-node config):
hexa.build(root_cls) instantiates and wires every stage port slot.resources/patterns/*.yaml files merge into a PatternRegistry.set_registry + set_config from the family resources/pipeline.yaml.schema: builds a State subclass, graph: builds the Graph, and the Engine is created.enrich().load(root_cls: type, resources_dir: Path)\nBuild the wired root + dagpipe runtime; attach engine/state_cls to root.
Parameters:
Name Type Description Defaultroot_cls type Composition root class to hexa-build.
requiredresources_dir Path Family resources directory containing pipeline.yaml and patterns/.
Returns:
Name Type Descriptionobject The wired root instance with _engine/_state_cls attached.
Raises:
Type DescriptionFileNotFoundError When pipeline.yaml does not exist.
Pattern model family + PatternRegistry (port of domain/enrichment/models.py).
The registry is loaded from the family resources/patterns/*.yaml files and injected into every dagpipe stage node via set_registry.
Bases: BasePattern
Array pattern: a plain list of values.
Attributes:
Name Type Descriptiontype Literal[ARRAY] Fixed discriminator.
array List Plain value list.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.BasePattern","title":"BasePattern","text":" Bases: BaseModel
Base model for all patterns: a discriminated type tag.
Attributes:
Name Type Descriptiontype PatternType Pattern kind discriminator.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.KeywordsPattern","title":"KeywordsPattern","text":" Bases: BasePattern
Keywords pattern: a flat list of keywords.
Attributes:
Name Type Descriptiontype Literal[KEYWORDS] Fixed discriminator.
items List[str] Keyword list.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.MappingPattern","title":"MappingPattern","text":" Bases: BasePattern
Enumerated mapping of token \u2192 value.
Attributes:
Name Type Descriptiontype Literal[MAPPING] Fixed discriminator.
mapping Dict[str, Union[str, MappingValue, List]] Token mapping.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.MappingValue","title":"MappingValue","text":" Bases: BaseModel
Named value inside a mapping pattern.
Attributes:
Name Type Descriptionid str Mapping key id.
name str Display name.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry","title":"PatternRegistry","text":" Bases: BaseModel
Loaded pattern registry injected into dagpipe stage nodes.
Attributes:
Name Type Descriptionversion int Registry schema version.
patterns Dict[str, Pattern] Name \u2192 pattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.array","title":"array","text":"array(name: str) -> List\nReturn the raw array of an ArrayPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Name Type DescriptionList List The array items.
Raises:
Type DescriptionTypeError When the pattern is not an ArrayPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.get","title":"get","text":"get(name: str) -> Pattern\nLook up a pattern by name.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Name Type DescriptionPattern Pattern The stored pattern object.
Raises:
Type DescriptionKeyError When the pattern name is not registered.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.keywords","title":"keywords","text":"keywords(name: str) -> List[str]\nReturn the keyword list of a KeywordsPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionList[str] List[str]: The keyword items.
Raises:
Type DescriptionTypeError When the pattern is not a KeywordsPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.mapping","title":"mapping","text":"mapping(name: str) -> Dict[str, str]\nReturn the token mapping of a MappingPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionDict[str, str] Dict[str, str]: The mapping dict.
Raises:
Type DescriptionTypeError When the pattern is not a MappingPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.regex","title":"regex","text":"regex(name: str) -> re.Pattern\nReturn the compiled regex of a RegexPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionPattern re.Pattern: The compiled regex.
Raises:
Type DescriptionTypeError When the pattern is not a RegexPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.regex_list","title":"regex_list","text":"regex_list(name: str) -> List[re.Pattern]\nReturn the compiled regexes of a RegexListPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionList[Pattern] List[re.Pattern]: The compiled regexes.
Raises:
Type DescriptionTypeError When the pattern is not a RegexListPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.regex_map","title":"regex_map","text":"regex_map(name: str) -> List[Tuple[re.Pattern, str]]\nReturn the compiled (regex, value) pairs of a RegexMapPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionList[Tuple[Pattern, str]] List[Tuple[re.Pattern, str]]: The compiled pairs.
Raises:
Type DescriptionTypeError When the pattern is not a RegexMapPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.rules","title":"rules","text":"rules(name: str) -> List[Dict]\nReturn the rule list of a RulesPattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Type DescriptionList[Dict] List[Dict]: The ordered rules.
Raises:
Type DescriptionTypeError When the pattern is not a RulesPattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternRegistry.template","title":"template","text":"template(name: str) -> str\nReturn the format string of a TemplatePattern.
Parameters:
Name Type Description Defaultname str Pattern name.
requiredReturns:
Name Type Descriptionstr str The template format string.
Raises:
Type DescriptionTypeError When the pattern is not a TemplatePattern.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.PatternType","title":"PatternType","text":" Bases: str, Enum
Supported pattern kinds loaded from the family pattern files.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexListPattern","title":"RegexListPattern","text":" Bases: BasePattern
List-of-regexes pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX_LIST] Fixed discriminator.
patterns List[str] Regex sources.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexListPattern-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexListPattern.compile_all","title":"compile_all","text":"compile_all(flags: int = re.IGNORECASE) -> List[re.Pattern]\nCompile every regex source.
Parameters:
Name Type Description Defaultflags int Compile flags, default re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionList[Pattern] List[re.Pattern]: The compiled regexes.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexMapPattern","title":"RegexMapPattern","text":" Bases: BasePattern
Regex \u2192 value mapping pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX_MAP] Fixed discriminator.
mapping Dict[str, str] Regex source \u2192 value.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexMapPattern-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexMapPattern.compile_all","title":"compile_all","text":"compile_all(\n flags: int = re.IGNORECASE,\n) -> List[Tuple[re.Pattern, str]]\nPre-compile the mapping into (regex, value) pairs.
Parameters:
Name Type Description Defaultflags int Compile flags, default re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionList[Tuple[Pattern, str]] List[Tuple[re.Pattern, str]]: The compiled pairs.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexPattern","title":"RegexPattern","text":" Bases: BasePattern
Single-regex pattern.
Attributes:
Name Type Descriptiontype Literal[REGEX] Fixed discriminator.
pattern str Regex source.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexPattern-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RegexPattern.compile","title":"compile","text":"compile(flags: int = re.IGNORECASE) -> re.Pattern\nCompile the regex pattern.
Parameters:
Name Type Description Defaultflags int Compile flags, default re.IGNORECASE.
IGNORECASE Returns:
Type DescriptionPattern re.Pattern: The compiled regex.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.RulesPattern","title":"RulesPattern","text":" Bases: BasePattern
Rule-set pattern: ordered flag rules with emit payloads.
Attributes:
Name Type Descriptiontype Literal[RULES] Fixed discriminator.
rules List[Dict] Ordered rule dicts.
"},{"location":"pipelines/enrichment/shared/models/#pipelines.enrichment.shared.models.TemplatePattern","title":"TemplatePattern","text":" Bases: BasePattern
String-template pattern.
Attributes:
Name Type Descriptiontype Literal[TEMPLATE] Fixed discriminator.
format str Format/template string.
"},{"location":"pipelines/enrichment/shared/ports/","title":"Ports","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports","title":"pipelines.enrichment.shared.ports","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports--summary","title":"Summary","text":"Shared enrichment port contracts.
Stage ports are dagpipe Nodes: hexa.build() wires their instances on a family root, the shared loader injects the pattern registry + per-node config, and a dagpipe Engine executes them. FinalizePort is the terminal state processor (confidence sort + result dict building).
Bases: RegistryPort, ABC
amount \u2192 amount_* candidate flags (shared by entity and tags families).
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort.amount_based_flag_mapping","title":"amount_based_flag_mappingproperty","text":"amount_based_flag_mapping\nFlag names to evaluate, taken from the registry.
Returns:
Name Type DescriptionList The registered amount-flag names.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the forked states with amount_* flags applied.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying the amount.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states carrying the updated candidate flags.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.AmountFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.FinalizePort","title":"FinalizePort","text":" Bases: ABC
Terminal state processor: confidence sort then build the result dict.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.FinalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.FinalizePort.process","title":"processabstractmethod","text":"process(states: list) -> dict\nBuild the result dict from the terminal states.
Parameters:
Name Type Description Defaultstates list Terminal states from the dagpipe graph.
requiredReturns:
Name Type Descriptiondict dict The generated result dict.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort","title":"RegistryPort","text":" Bases: Node, ABC
dagpipe node with injectable PatternRegistry + per-node config.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield the forked states carrying this stage's output.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states carrying the stage output.
"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/shared/ports/#pipelines.enrichment.shared.ports.RegistryPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/shared/registry/","title":"Registry","text":""},{"location":"pipelines/enrichment/shared/registry/#pipelines.enrichment.shared.registry","title":"pipelines.enrichment.shared.registry","text":""},{"location":"pipelines/enrichment/shared/registry/#pipelines.enrichment.shared.registry--summary","title":"Summary","text":"Registry mapping enrichment family \u2192 composition root.
Enrichment has two families (entity, tags); each has a single default root (no per-bank variants) so the family is the root, living in the family's impl.py. Callers use resolve_enrichment_root instead of hand-rolled maps.
known_enrichment_roots() -> list\nList the registered enrichment family names.
Returns:
Name Type Descriptionlist list The known family names.
"},{"location":"pipelines/enrichment/shared/registry/#pipelines.enrichment.shared.registry.resolve_enrichment_root","title":"resolve_enrichment_root","text":"resolve_enrichment_root(family: str) -> type\nReturn the composition root class for an enrichment family.
Parameters:
Name Type Description Defaultfamily str Enrichment family name (\"entity\" or \"tags\").
requiredReturns:
Name Type Descriptiontype type The composition root class for the family.
Raises:
Type DescriptionValueError When the family has no registered enrichment root.
"},{"location":"pipelines/enrichment/shared/utils/","title":"Utils","text":""},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils","title":"pipelines.enrichment.shared.utils","text":""},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils--summary","title":"Summary","text":"Description/candidate utilities (port of domain/enrichment/entity/utils.py).
extract_candidates(\n description: str,\n candidate_regexes: Iterable[re.Pattern],\n) -> List[str]\nExtract valid payee candidates from a description.
Parameters:
Name Type Description Defaultdescription str Raw description text.
requiredcandidate_regexes Iterable[Pattern] Compiled extraction regexes.
requiredReturns:
Type DescriptionList[str] List[str]: The normalized valid candidates.
"},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils.is_valid_candidate","title":"is_valid_candidate","text":"is_valid_candidate(candidate: str) -> bool\nReturn True when a candidate looks like a plausible payee.
Parameters:
Name Type Description Defaultcandidate str Extracted candidate value.
requiredReturns:
Name Type Descriptionbool bool True when the candidate passes the length/content heuristics.
"},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils.lookup_mapping","title":"lookup_mapping","text":"lookup_mapping(candidate: str, mapping: dict)\nLook up mapping values for a candidate token.
Parameters:
Name Type Description Defaultcandidate str Candidate token.
requiredmapping dict Mapping dict of key \u2192 MappingValue.
requiredReturns:
Name Type Descriptionlist Matching value names, or (None, None) when the candidate is empty.
normalize_description(text: str) -> str\nNormalize a description: separators \u2192 space, lowercase, drop OCR noise.
Parameters:
Name Type Description Defaulttext str Raw description.
requiredReturns:
Name Type Descriptionstr str The normalized lowercase description.
"},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils.normalize_money_str","title":"normalize_money_str","text":"normalize_money_str(x) -> str\nFormat a numeric value as a fixed two-decimal string.
Parameters:
Name Type Description Defaultx float Value coercible to float.
requiredReturns:
Name Type Descriptionstr str The value formatted to exactly two decimals.
"},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils.normalize_person_handle","title":"normalize_person_handle","text":"normalize_person_handle(handle: str) -> str\nNormalize a person/UPI handle into a capitalized display name.
Parameters:
Name Type Description Defaulthandle str Raw handle (may carry a UPI suffix or trailing digits).
requiredReturns:
Name Type Descriptionstr str The cleaned handle, or \"\" when only hex characters remain.
"},{"location":"pipelines/enrichment/shared/utils/#pipelines.enrichment.shared.utils.remove_number_sequence","title":"remove_number_sequence","text":"remove_number_sequence(\n text: str, amt: str, bal: str\n) -> str\nStrip amount/balance digit sequences from a description.
Parameters:
Name Type Description Defaulttext str Description text.
requiredamt str Amount value.
requiredbal str Balance value.
requiredReturns:
Name Type Descriptionstr str The cleaned, whitespace-collapsed description.
"},{"location":"pipelines/enrichment/tags/","title":"Tags","text":"Tags enrichment family (hexa-wired dagpipe graph).
"},{"location":"pipelines/enrichment/tags/#pipelines.enrichment.tags--notes","title":"Notes","text":"Houses the abstract contracts (abc.py), the concrete dagpipe stage nodes and root (impl.py) and the runtime resources (resources/) for the tags family.
Abstract contracts for the tags enrichment family (no implementation).
The tags family chains resolved entities into tags:
amount_flags \u2192 entity_flags \u2192 set_tags\nIt consumes the output of the entity family (entity.name + amount) and emits tags. TagsPipeline is the hexa root; TagsFinalizePort dedupes tags and defaults to [\"misc\"].
Bases: RegistryPort, ABC
entity.name + candidate.flags \u2192 entity_* flags via ENTITY_BASED_FLAG_MAPPING.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield forks with entity_* flags appended from the entity name.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying entity.name.
Yields:
Name Type DescriptionState Iterable[State] Forked states carrying updated candidate flags.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort.set_config","title":"set_config","text":"set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.EntityFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort","title":"SetTagsPort","text":" Bases: RegistryPort, ABC
candidate.flags \u2192 tags via FLAGS_BASED_TAGS_RULES.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort.resolve","title":"resolveabstractmethod","text":"resolve(state: State) -> Iterable[State]\nYield forks with tags populated from candidate flags.
Parameters:
Name Type Description Defaultstate State Incoming dagpipe state carrying candidate flags.
requiredYields:
Name Type DescriptionState Iterable[State] Forked states carrying the emitted tags.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.SetTagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsFinalizePort","title":"TagsFinalizePort","text":" Bases: FinalizePort, ABC
terminal states \u2192 {\"tags\": [...]} (deduped, default [\"misc\"]).
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsFinalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsFinalizePort.process","title":"processabstractmethod","text":"process(states: List) -> dict\nBuild the tags result dict from the terminal states.
Parameters:
Name Type Description Defaultstates List Terminal states from the dagpipe graph.
requiredReturns:
Name Type Descriptiondict dict The tags result dict.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsPipeline","title":"TagsPipeline","text":" Bases: ABC
Root \u2014 wires amount_flags \u2192 entity_flags \u2192 set_tags, then runs the graph.
Attributes:
Name Type Descriptionamount_flags AmountFlagsPort Amount-flags stage port.
entity_flags EntityFlagsPort Entity-flags stage port.
set_tags SetTagsPort Set-tags stage port.
finalize TagsFinalizePort Terminal finalize port.
"},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsPipeline-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/abc/#pipelines.enrichment.tags.abc.TagsPipeline.enrich","title":"enrichabstractmethod","text":"enrich(payload: dict) -> dict\nEnrich an entity payload into a tags result.
Parameters:
Name Type Description Defaultpayload dict Payload carrying entity.name and the amount.
Returns:
Name Type Descriptiondict dict The tags result dict.
"},{"location":"pipelines/enrichment/tags/impl/","title":"Impl","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl","title":"pipelines.enrichment.tags.impl","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl--summary","title":"Summary","text":"Concrete tags-family implementations (dagpipe stage nodes + root).
Stage bodies are ports of domain/enrichment/tags/flags.py. The root ImplTagsPipeline.enrich runs the hexa-wired stage graph through a dagpipe Engine and delegates terminal processing to ImplTagsFinalizePort (port of TagStatesProcessorAdaptor).
Bases: EntityFlagsPort
Entity-flags stage: append entity_* flags from the entity name.
property","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplEntityFlagsPort.entity_based_flag_mapping","title":"entity_based_flag_mappingproperty","text":"entity_based_flag_mapping\nEntity name \u2192 flag mapping used for entity flagging.
Returns:
Name Type Descriptiondict The entity-based flag mapping.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplEntityFlagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplEntityFlagsPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nAppend matching entity_* flags and reset tags.
Parameters:
Name Type Description Defaultstate State Incoming state carrying entity.name and candidate.flags.
Yields:
Name Type DescriptionState Iterable[State] A fork with updated candidate.flags and empty tags, or the unmodified state when no entity name is set.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplEntityFlagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort","title":"ImplSetTagsPort","text":" Bases: SetTagsPort
Set-tags stage: emit tags from the matching flag rules.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort-attributes","title":"Attributes","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort.config","title":"configproperty","text":"config\nPer-node config injected via set_config.
Returns:
Type Descriptiondict | None: The per-node config, or None before injection.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort.flags_based_tags_rules","title":"flags_based_tags_rulesproperty","text":"flags_based_tags_rules\nFlag-matching rules that emit tags.
Returns:
Type DescriptionList[Dict]: The ordered tag rules.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort.resolve","title":"resolve","text":"resolve(state: State) -> Iterable[State]\nAppend tags emitted by the first matching flag rules.
Parameters:
Name Type Description Defaultstate State Incoming state carrying candidate flags and tags.
requiredYields:
Name Type DescriptionState Iterable[State] A fork with tags updated when rules matched, else the unmodified state.
set_config(config)\nInject the per-node config.
Parameters:
Name Type Description Defaultconfig dict Per-node config from the dagpipe spec.
required"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplSetTagsPort.set_registry","title":"set_registry","text":"set_registry(registry)\nInject the merged pattern registry.
Parameters:
Name Type Description Defaultregistry PatternRegistry The merged pattern registry.
required"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplTagsFinalizePort","title":"ImplTagsFinalizePort","text":" Bases: TagsFinalizePort
Finalize terminal states into the tags result dict.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplTagsFinalizePort-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplTagsFinalizePort.process","title":"process","text":"process(states: List) -> dict\nBuild the tags result dict, deduped and order-preserving.
Parameters:
Name Type Description Defaultstates List Terminal states from the dagpipe graph.
requiredReturns:
Name Type Descriptiondict dict {\"tags\": [...]} with unique tags.
Bases: TagsPipeline
Concrete tags pipeline root wiring the stage ports.
Attributes:
Name Type Descriptionamount_flags ImplAmountFlagsPort Amount-flags stage port.
entity_flags ImplEntityFlagsPort Entity-flags stage port.
set_tags ImplSetTagsPort Set-tags stage port.
finalize ImplTagsFinalizePort Terminal finalize port.
"},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplTagsPipeline-functions","title":"Functions","text":""},{"location":"pipelines/enrichment/tags/impl/#pipelines.enrichment.tags.impl.ImplTagsPipeline.enrich","title":"enrich","text":"enrich(payload: dict) -> dict\nRun the tags graph on an entity payload and finalize the result.
Parameters:
Name Type Description Defaultpayload dict Payload carrying entity.name and the amount.
Returns:
Name Type Descriptiondict dict The tags result dict from the finalize port.
"},{"location":"pipelines/extraction/","title":"Extraction","text":"Extraction pipelines, organized per source family.
pipeline \u2192 extraction \u2192 type [pdf,email,csv,xlsx,llama] \u2192 {pipeline.yaml, abc.py, impl.py, banks/}\nShared leaf contracts and cross-family machinery live in shared/; the registry mapping (source_type, bank, pipeline) \u2192 root lives in shared/registry.py.
csv (direct table) extraction family.
"},{"location":"pipelines/extraction/csv/abc/","title":"Abc","text":""},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc","title":"pipelines.extraction.csv.abc","text":""},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc--summary","title":"Summary","text":"Abstract contracts for the csv (direct table) extraction graph.
The csv family is a \"direct table\" pipeline \u2014 no OCR, no buckets, no ambiguity. It shares the tabular core (shared/tabular.py) with xlsx: only the table reader differs (csv rows vs xlsx worksheet rows). Bank-specific readers live under banks/.
Bases: TabularExtractionPipeline
csv-family root \u2014 pins only the reader; chain shared with xlsx.
Slot annotationssource: ExtractionSource ingest, table_reader, txn_dicts, raw_expense
Attributes:
Name Type Descriptionsource ExtractionSource The extraction source descriptor.
table_reader CsvTableReaderPort Csv table reader stage.
"},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc.CsvExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc.CsvExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc.CsvTableReaderPort","title":"CsvTableReaderPort","text":" Bases: TableReaderPort
content \u2192 list of typed records read from a csv statement file.
"},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc.CsvTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/abc/#pipelines.extraction.csv.abc.CsvTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from a csv statement file.
Parameters:
Name Type Description Defaultcontent Materialized content (bytes, Content, dict, or str).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/csv/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/csv/impl/#pipelines.extraction.csv.impl","title":"pipelines.extraction.csv.impl","text":""},{"location":"pipelines/extraction/csv/impl/#pipelines.extraction.csv.impl--summary","title":"Summary","text":"Concrete csv-family implementations.
ImplCsvTableReaderPort reads csv rows with the omniread csv parser and runs them through the shared TableParserMixin (header location / aliases / typed conversion) to emit typed records. The chain (records \u2192 balance-adjusted txn dicts \u2192 raw expenses) is the shared tabular core.
Bases: CsvExtractionPipeline
Concrete csv graph root.
Attributes:
Name Type Descriptioningest ImplIngestPort Ingest stage.
table_reader ImplCsvTableReaderPort Csv table reader stage.
txn_dicts ImplTabularTxnDictsPort Shared tabular txn-dicts stage.
raw_expense ImplRawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/csv/impl/#pipelines.extraction.csv.impl.ImplCsvExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/impl/#pipelines.extraction.csv.impl.ImplCsvExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/csv/impl/#pipelines.extraction.csv.impl.ImplCsvTableReaderPort","title":"ImplCsvTableReaderPort","text":" Bases: TableParserMixin, CsvTableReaderPort
Concrete csv reader \u2014 omniread csv parser + shared TableParserMixin.
read(content) -> List[dict]\nRead typed records from csv content.
Parameters:
Name Type Description Defaultcontent Materialized content (Content, bytes, or dict).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/csv/banks/","title":"Banks","text":"csv family \u2014 bank-specific ports and pipeline roots.
"},{"location":"pipelines/extraction/csv/banks/axis/","title":"Axis","text":""},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis","title":"pipelines.extraction.csv.banks.axis","text":""},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis--summary","title":"Summary","text":"Axis bank-specific port implementations (csv table path).
Faithful port of domain/extraction/banks/axis/csv.py:
TableParserMixin (icici-style header/alias logic),column_aliases with the Axis DR/CR inversion \u2014 credits (salary, refunds, interest) arrive under DR with the balance rising and spends under CR with it falling (verified by balance-chain replay).AxisCsvExtractionPipeline pins the reader; ordering/balance policy stays in the shared tabular txn_dicts stage.
Bases: ImplCsvExtractionPipeline
Axis csv graph root \u2014 pins the Axis reader.
Attributes:
Name Type Descriptiontable_reader AxisCsvTableReaderPort Axis csv reader stage.
"},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis.AxisCsvExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis.AxisCsvExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis.AxisCsvTableReaderPort","title":"AxisCsvTableReaderPort","text":" Bases: ImplCsvTableReaderPort
Axis csv reader \u2014 DR/CR inverted column aliases.
Attributes:
Name Type Descriptioncolumn_aliases Dict[str, List[str]] Axis DR/CR-inverted aliases.
required_columns tuple Required columns for header matching.
"},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis.AxisCsvTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/banks/axis/#pipelines.extraction.csv.banks.axis.AxisCsvTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from csv content.
Parameters:
Name Type Description Defaultcontent Materialized content (Content, bytes, or dict).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/csv/banks/icici/","title":"Icici","text":""},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici","title":"pipelines.extraction.csv.banks.icici","text":""},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici--summary","title":"Summary","text":"Icici bank-specific port implementations (csv table path).
Faithful port of domain/extraction/banks/icici/csv.py: shares all table logic with xlsx via the shared TableParserMixin (default icici aliases).
IciciCsvExtractionPipeline pins the reader; ordering/balance policy stays in the shared tabular txn_dicts stage.
Bases: ImplCsvExtractionPipeline
Icici csv graph root \u2014 pins the Icici reader.
Attributes:
Name Type Descriptiontable_reader IciciCsvTableReaderPort Icici csv reader stage.
"},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici.IciciCsvExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici.IciciCsvExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici.IciciCsvTableReaderPort","title":"IciciCsvTableReaderPort","text":" Bases: ImplCsvTableReaderPort
Icici csv reader \u2014 inherits the default (icici) column aliases.
"},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici.IciciCsvTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/csv/banks/icici/#pipelines.extraction.csv.banks.icici.IciciCsvTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from csv content.
Parameters:
Name Type Description Defaultcontent Materialized content (Content, bytes, or dict).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/email/","title":"Email","text":"email (message) extraction family.
"},{"location":"pipelines/extraction/email/abc/","title":"Abc","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc","title":"pipelines.extraction.email.abc","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc--summary","title":"Summary","text":"Abstract contracts for the email (message) extraction graph (no implementation).
Email is NOT the OCR text chain. A message is self-contained \u2014 one HTML email maps to one transaction, so the chain is deliberately slim:
ingest \u2192 message_reader \u2192 message_parser \u2192 raw_expense\nrun lives in the concrete impl).No bucket finding, splitting, or ambiguity resolution happens here.
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc-classes","title":"Classes","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.EmailExtractionPipeline","title":"EmailExtractionPipeline","text":" Bases: ABC
Root \u2014 wires ingest \u2192 message_reader \u2192 message_parser \u2192 raw_expense.
Attributes:
Name Type Descriptionsource ExtractionSource The extraction source descriptor.
pipeline str Pipeline tag; defaults to \"heuristic\".
ingest IngestPort Ingest stage.
message_reader MessageReaderPort Message-reading stage.
message_parser MessageParserPort Message-parsing stage.
raw_expense RawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.EmailExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.EmailExtractionPipeline.run","title":"runabstractmethod","text":"run(source) -> List[Any]\nRun the email extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageParserPort","title":"MessageParserPort","text":" Bases: ABC
message text \u2192 one txn dict (date/particulars/amount/balance/direction).
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageParserPort.parse","title":"parseabstractmethod","text":"parse(message: str) -> Dict[str, Any]\nParse one message into a txn dict.
Parameters:
Name Type Description Defaultmessage str Flattened message text.
requiredReturns:
Type DescriptionDict[str, Any] Dict[str, Any]: Txn dict with date/particulars/amount/balance/
Dict[str, Any] direction keys.
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageReaderPort","title":"MessageReaderPort","text":" Bases: ABC
content \u2192 list of flattened message texts.
"},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/abc/#pipelines.extraction.email.abc.MessageReaderPort.extract","title":"extractabstractmethod","text":"extract(content) -> List[str]\nFlatten content into message texts.
Parameters:
Name Type Description Defaultcontent Content (list, bytes, dict, or a single source).
requiredReturns:
Type DescriptionList[str] List[str]: Flattened message texts.
"},{"location":"pipelines/extraction/email/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl","title":"pipelines.extraction.email.impl","text":""},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl--summary","title":"Summary","text":"Concrete email-family implementations.
Faithful port of the OG email adaptors (domain/extraction/banks/{axis,icici}/email.py): a BeautifulSoup flatten of each HTML message into one text blob, then a bank-specific regex parse into a single transaction. ImplMessageReaderPort is shared; ImplMessageParserPort carries the shared description-slicing helper and the per-bank modules subclass it with their own regex/date rules.
Bases: EmailExtractionPipeline
Concrete email graph root.
Attributes:
Name Type Descriptionpipeline str Pipeline tag (\"heuristic\").
ingest ImplIngestPort Ingest stage.
message_reader ImplMessageReaderPort Message-reading stage.
message_parser ImplMessageParserPort Message-parsing stage.
raw_expense ImplRawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplEmailExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplEmailExtractionPipeline.run","title":"run","text":"run(source)\nRun the email extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplMessageParserPort","title":"ImplMessageParserPort","text":" Bases: MessageParserPort
Base email parser: shared description-slicing; banks implement parse.
Attributes:
Name Type Descriptiondescription_starts List[str] Markers where descriptions begin.
description_ends List[str] Markers where descriptions end.
"},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplMessageParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplMessageParserPort.parse","title":"parse","text":"parse(message: str)\nParse one message into a txn dict.
Parameters:
Name Type Description Defaultmessage str Flattened message text.
requiredRaises:
Type DescriptionNotImplementedError Always; subclasses must implement parse.
Bases: MessageReaderPort
Concrete message reader \u2014 HTML flattens each message to text.
"},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplMessageReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/impl/#pipelines.extraction.email.impl.ImplMessageReaderPort.extract","title":"extract","text":"extract(content) -> List[str]\nFlatten each message source into text.
Parameters:
Name Type Description Defaultcontent Content, list/tuple of sources, or a single source.
requiredReturns:
Type DescriptionList[str] List[str]: Flattened message texts.
"},{"location":"pipelines/extraction/email/banks/","title":"Banks","text":"email family \u2014 bank-specific ports and pipeline roots.
"},{"location":"pipelines/extraction/email/banks/axis/","title":"Axis","text":""},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis","title":"pipelines.extraction.email.banks.axis","text":""},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis--summary","title":"Summary","text":"Axis bank-specific port implementations (email message path).
Faithful port of domain/extraction/banks/axis/email.py (AxisTransactionParserAdaptor.parse): INR amount, debited/credited direction, DD-MM-YYYY timestamped date, and a description sliced between Axis Bank Credit Card Transaction: and the trailing spam markers.
Bases: ImplEmailExtractionPipeline
Axis email graph root \u2014 pins the Axis message parser.
Attributes:
Name Type Descriptionmessage_parser AxisMessageParserPort Axis message parser.
"},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis.AxisEmailExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis.AxisEmailExtractionPipeline.run","title":"run","text":"run(source)\nRun the email extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis.AxisMessageParserPort","title":"AxisMessageParserPort","text":" Bases: ImplMessageParserPort
Axis email parser \u2014 INR amount, debited/credited, timestamped date.
Attributes:
Name Type Descriptiondescription_starts List[str] Axis description start markers.
description_ends List[str] Axis description end markers.
"},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis.AxisMessageParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/banks/axis/#pipelines.extraction.email.banks.axis.AxisMessageParserPort.parse","title":"parse","text":"parse(message: str)\nParse an Axis message into one txn dict.
Parameters:
Name Type Description Defaultmessage str Flattened message text.
requiredReturns:
Type DescriptionTxn dict with txn_date, particulars, amount, balance, direction.
Raises:
Type DescriptionValueError When the amount or transaction date is not found.
"},{"location":"pipelines/extraction/email/banks/icici/","title":"Icici","text":""},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici","title":"pipelines.extraction.email.banks.icici","text":""},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici--summary","title":"Summary","text":"Icici bank-specific port implementations (email message path).
Faithful port of domain/extraction/banks/icici/email.py (IciciTransactionParserAdaptor.parse): INR amount, credited/refund/ reversal direction, on <Mon DD, YYYY> at <HH:MM:SS> date formatting to DD-MM-YYYY, and a description sliced between Info: and the available credit-limit footer.
Bases: ImplEmailExtractionPipeline
Icici email graph root \u2014 pins the Icici message parser.
Attributes:
Name Type Descriptionmessage_parser IciciMessageParserPort Icici message parser.
"},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici.IciciEmailExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici.IciciEmailExtractionPipeline.run","title":"run","text":"run(source)\nRun the email extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici.IciciMessageParserPort","title":"IciciMessageParserPort","text":" Bases: ImplMessageParserPort
Icici email parser \u2014 credited/refund/reversal direction, DD-MM-YYYY.
Attributes:
Name Type Descriptiondescription_starts List[str] Icici description start markers.
description_ends List[str] Icici description end markers.
"},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici.IciciMessageParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/email/banks/icici/#pipelines.extraction.email.banks.icici.IciciMessageParserPort.parse","title":"parse","text":"parse(message: str)\nParse an Icici message into one txn dict.
Parameters:
Name Type Description Defaultmessage str Flattened message text.
requiredReturns:
Type DescriptionTxn dict with txn_date, particulars, amount, balance, direction.
Raises:
Type DescriptionValueError When the amount or transaction date is not found.
"},{"location":"pipelines/extraction/llama/","title":"Llama","text":"Llama (structured-objects) extraction family.
"},{"location":"pipelines/extraction/llama/abc/","title":"Abc","text":""},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc","title":"pipelines.extraction.llama.abc","text":""},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc--summary","title":"Summary","text":"Abstract contracts for the llama (structured-objects) extraction graph.
The llama family is \"tabular-like\" but the front stage differs: instead of reading table rows it starts from a LIST OF ALREADY-STRUCTURED OBJECTS (one per transaction \u2014 what LlamaCloud returns, or the cached fixture CSV standing in for it). The downstream stages reuse the shared core:
LlamaObjectsReaderPort : list of objects -> filtered records (drops B/F marker rows + pre-marker header rows, port of OG BucketFinderAdaptor.filter_txn_rows).LlamaExtractionPipeline: root matching the tabular run-driver shape, but routed through objects_reader instead of table_reader. It reuses ImplIngestPort (list pass-through), ObjectsTxnDictsPort (stated balances trusted) and ImplRawExpensePort.Bank-specific wiring lives under banks/.
Bases: ABC
Root \u2014 objects chain: ingest \u2192 objects_reader \u2192 txn_dicts \u2192 raw_expense.
Slot annotationssource: ExtractionSource ingest: IngestPort objects_reader: LlamaObjectsReaderPort txn_dicts: ObjectsTxnDictsPort raw_expense: RawExpensePort
Attributes:
Name Type Descriptionsource ExtractionSource The extraction source descriptor.
pipeline str Pipeline tag (\"llama\").
ingest IngestPort Ingest stage.
objects_reader LlamaObjectsReaderPort Objects-reading stage.
txn_dicts ObjectsTxnDictsPort Objects-to-txn-dicts stage.
raw_expense RawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc.LlamaExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc.LlamaExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the llama objects extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc.LlamaObjectsReaderPort","title":"LlamaObjectsReaderPort","text":" Bases: ABC
list of structured objects \u2192 list of filtered records (in order).
"},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc.LlamaObjectsReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/abc/#pipelines.extraction.llama.abc.LlamaObjectsReaderPort.read","title":"readabstractmethod","text":"read(objects) -> List[Dict[str, Any]]\nRead structured objects, dropping marker and header rows.
Parameters:
Name Type Description Defaultobjects List of structured statement objects.
requiredReturns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: Filtered records in order.
"},{"location":"pipelines/extraction/llama/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl","title":"pipelines.extraction.llama.impl","text":""},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl--summary","title":"Summary","text":"Concrete llama-family implementations.
ImplLlamaObjectsReaderPort receives the list of already-structured statement objects (the equivalent of the LlamaCloud extract result) and applies the row-level bucket filter \u2014 B/F marker rows and any rows before the first marker are dropped, mirroring OG domain.extraction.adaptors.txn_blocks.BucketFinderAdaptor.filter_txn_rows. The downstream chain (objects \u2192 txn dicts \u2192 raw expenses) is the shared core: ImplTxnDictsObjectsPort (stated balances trusted) + ImplRawExpensePort.
Bases: LlamaExtractionPipeline
Concrete llama graph root.
Attributes:
Name Type Descriptioningest ImplIngestPort Ingest stage.
objects_reader ImplLlamaObjectsReaderPort Objects-reading stage.
txn_dicts ImplObjectsTxnDictsPort Objects-to-txn-dicts stage.
raw_expense ImplRawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the llama objects extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaObjectsReaderPort","title":"ImplLlamaObjectsReaderPort","text":" Bases: LlamaObjectsReaderPort
Drop B/F marker rows + pre-marker header rows from a statement list.
Mirrors the OG bucket finder contract exactly: markers are B/F / BIF / B|F matched against each object's description (upper-cased). With limit_first only the first (primary) bucket is kept (default False, like the OG lama service; the icici bank module overrides it to True to match the icici OG CONFIG). Statements without a marker row pass through.
Attributes:
Name Type Descriptionbf_markers tuple Marker tokens identifying bucket boundaries.
limit_first bool Keep only the first bucket.
"},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaObjectsReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaObjectsReaderPort.filter_objects","title":"filter_objects","text":"filter_objects(\n objects: List[Any], *, limit_first: bool = False\n) -> List[dict]\nFilter objects to rows between balance-forward marker rows.
Parameters:
Name Type Description Defaultobjects List[Any] Structured statement objects.
requiredlimit_first bool Keep only the first bucket. Defaults to False.
False Returns:
Type DescriptionList[dict] List[dict]: Records between (and after) marker rows.
"},{"location":"pipelines/extraction/llama/impl/#pipelines.extraction.llama.impl.ImplLlamaObjectsReaderPort.read","title":"read","text":"read(objects) -> List[dict]\nRead structured objects, applying the row-level bucket filter.
Parameters:
Name Type Description Defaultobjects List of structured statement objects.
requiredReturns:
Type DescriptionList[dict] List[dict]: Filtered records in order.
"},{"location":"pipelines/extraction/llama/banks/","title":"Banks","text":"Llama-family bank-specific wiring.
"},{"location":"pipelines/extraction/llama/banks/icici/","title":"Icici","text":""},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici","title":"pipelines.extraction.llama.banks.icici","text":""},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici--summary","title":"Summary","text":"Icici bank-specific port implementations (llama objects path).
The llama objects are already normalized per-transaction (date / amount / balance / description / direction), so there is no bank-specific column logic. IciciLlamaObjectsReaderPort mirrors the icici OG bank CONFIG {\"limit_first\": True} (keeps only the primary account bucket), matching the 223-txn llama run stored in the DB. IciciLlamaExtractionPipeline pins the reader; the shared objects policy (stated balances trusted) is identical across banks.
Bases: ImplLlamaExtractionPipeline
Icici llama graph root \u2014 pins the Icici objects reader.
Attributes:
Name Type Descriptionobjects_reader IciciLlamaObjectsReaderPort Icici objects reader.
"},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the llama objects extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaObjectsReaderPort","title":"IciciLlamaObjectsReaderPort","text":" Bases: ImplLlamaObjectsReaderPort
Icici llama objects reader \u2014 primary bucket only (OG icici CONFIG).
Attributes:
Name Type Descriptionlimit_first bool Whether to keep only the primary bucket.
"},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaObjectsReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaObjectsReaderPort.filter_objects","title":"filter_objects","text":"filter_objects(\n objects: List[Any], *, limit_first: bool = False\n) -> List[dict]\nFilter objects to rows between balance-forward marker rows.
Parameters:
Name Type Description Defaultobjects List[Any] Structured statement objects.
requiredlimit_first bool Keep only the first bucket. Defaults to False.
False Returns:
Type DescriptionList[dict] List[dict]: Records between (and after) marker rows.
"},{"location":"pipelines/extraction/llama/banks/icici/#pipelines.extraction.llama.banks.icici.IciciLlamaObjectsReaderPort.read","title":"read","text":"read(objects) -> List[dict]\nRead structured objects, applying the row-level bucket filter.
Parameters:
Name Type Description Defaultobjects List of structured statement objects.
requiredReturns:
Type DescriptionList[dict] List[dict]: Filtered records in order.
"},{"location":"pipelines/extraction/pdf/","title":"Pdf","text":"pdf (OCR text) extraction family.
"},{"location":"pipelines/extraction/pdf/abc/","title":"Abc","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc","title":"pipelines.extraction.pdf.abc","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc--summary","title":"Summary","text":"Abstract contracts for the pdf (OCR text) extraction graph (no implementation).
The pdf family is the classic heuristic text chain:
ingest \u2192 raw_lines \u2192 txn_blocks \u2192 txn_dicts \u2192 raw_expense\nNon-PDF families (email / csv / xlsx) do NOT extend this root \u2014 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.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc-classes","title":"Classes","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.BucketFinderPort","title":"BucketFinderPort","text":" Bases: ABC
Divide raw_lines into account buckets at B/F markers.
Attributes:
Name Type Descriptionnumber NumberPort Number extraction leaf.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.BucketFinderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.BucketFinderPort.get_opening_balance_buckets","title":"get_opening_balance_bucketsabstractmethod","text":"get_opening_balance_buckets(\n lines: List[str],\n *,\n limit_first: bool = False,\n line_offset: int = 0\n) -> List[tuple]\nDivide raw lines into account buckets at B/F markers.
Parameters:
Name Type Description Defaultlines List[str] Raw text lines.
requiredlimit_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 DescriptionList[tuple] List[tuple]: (start, end, opening_balance) bucket triples.
Bases: ABC
Root \u2014 wires ingest \u2192 raw_lines \u2192 txn_blocks \u2192 txn_dicts \u2192 raw_expenses.
Attributes:
Name Type Descriptionsource 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.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.PDFExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.PDFExtractionPipeline.run","title":"runabstractmethod","text":"run(source) -> List[Any]\nRun the pdf extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.RawLinesPort","title":"RawLinesPort","text":" Bases: ABC
content \u2192 list of raw text lines.
Attributes:
Name Type Descriptioncovert_to_image bool Whether to binarize pages via image conversion.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.RawLinesPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.RawLinesPort.extract","title":"extractabstractmethod","text":"extract(content) -> List[str]\nExtract raw OCR text lines from content.
Parameters:
Name Type Description Defaultcontent Materialized content payload.
requiredReturns:
Type DescriptionList[str] List[str]: Raw text lines.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.SplitterPort","title":"SplitterPort","text":" Bases: ABC
Split bucket line-groups into transaction blocks.
Attributes:
Name Type Descriptionnumber NumberPort Number extraction leaf.
date DatePort Date parsing leaf.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.SplitterPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.SplitterPort.split_blocks","title":"split_blocksabstractmethod","text":"split_blocks(\n lines: List[str],\n *,\n has_header: bool = False,\n min_numbers: int = 3,\n detect_date_ranges: bool = False\n) -> List[str]\nSplit bucket line-groups into transaction blocks.
Parameters:
Name Type Description Defaultlines List[str] Lines belonging to one account bucket.
requiredhas_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 DescriptionList[str] List[str]: Transaction block texts.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TransactionParserPort","title":"TransactionParserPort","text":" Bases: ABC
Parse one transaction block into a structured dict.
Attributes:
Name Type Descriptionmin_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.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TransactionParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TransactionParserPort.parse","title":"parseabstractmethod","text":"parse(\n txn_text: str, prev_date_str, prev_balance: float\n) -> Dict[str, Any]\nParse one transaction block into a structured dict.
Parameters:
Name Type Description Defaulttxn_text str Transaction block text.
requiredprev_date_str Previous transaction date string.
requiredprev_balance float Running balance from the previous transaction.
requiredReturns:
Type DescriptionDict[str, Any] Dict[str, Any]: Parsed transaction dict.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnBlocksPort","title":"TxnBlocksPort","text":" Bases: ABC
raw_lines \u2192 txn_blocks (opening_balance \u2192 list[block strings]).
Attributes:
Name Type Descriptionhas_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.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnBlocksPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnBlocksPort.extract","title":"extractabstractmethod","text":"extract(raw_lines: List[str]) -> Dict[float, List[str]]\nExtract txn blocks keyed by opening balance.
Parameters:
Name Type Description Defaultraw_lines List[str] Raw OCR text lines.
requiredReturns:
Type DescriptionDict[float, List[str]] Dict[float, List[str]]: Opening balance \u2192 block texts.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnDictsPort","title":"TxnDictsPort","text":" Bases: ABC
txn_blocks \u2192 list of structured txn dicts.
Attributes:
Name Type Descriptionmin_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.
"},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/abc/#pipelines.extraction.pdf.abc.TxnDictsPort.extract","title":"extractabstractmethod","text":"extract(txn_blocks: Dict[float, List[str]]) -> Any\nExtract structured txn dicts from txn blocks.
Parameters:
Name Type Description Defaulttxn_blocks Dict[float, List[str]] Opening balance \u2192 block texts.
requiredReturns:
Name Type DescriptionAny Any List of txn dicts.
"},{"location":"pipelines/extraction/pdf/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl","title":"pipelines.extraction.pdf.impl","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl--summary","title":"Summary","text":"Concrete pdf-family implementations.
The pdf family is the OCR text chain; each concrete class REDECLARES its port slots with CONCRETE types \u2014 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:
ImplAmbiguityPort(\n fetch_request_id: str = \"\",\n pause_on_ambiguity: bool = True,\n resolved_choices: Optional[dict] = None,\n resolver: Optional[Callable] = None,\n)\n Bases: AmbiguityPort, AmbiguityHandler
Concrete ambiguity leaf \u2014 delegates to AmbiguityHandler.
Initialize the ambiguity handler.
Parameters:
Name Type Description Defaultfetch_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"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmbiguityPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmbiguityPort.resolve_ambiguity","title":"resolve_ambiguity","text":"resolve_ambiguity(\n line,\n ocr_amount,\n ocr_balance,\n prev_balance,\n candidates=None,\n)\nResolve ambiguity via AmbiguityHandler.resolve_ambiguity.
Parameters:
Name Type Description Defaultline Raw transaction line.
requiredocr_amount OCR amount.
requiredocr_balance OCR balance.
requiredprev_balance Previous transaction balance.
requiredcandidates Candidate (amount, balance) pairs; default set().
None Returns:
Type DescriptionSet with the chosen pair, or None.
Bases: AmountBalancePort
Concrete amount/balance leaf \u2014 resolves via ResolutionContext.
Attributes:
Name Type Descriptionnumber ImplNumberPort Number extraction leaf.
ambiguity ImplAmbiguityPort Ambiguity resolution leaf.
handler Optional[AmbiguityHandler] Optional override handler.
trust_fallback Optional[str] Fallback policy.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmountBalancePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmountBalancePort.adjust_balance","title":"adjust_balance","text":"adjust_balance(balance: float, line: str) -> float\nAdjust an OCR balance (no-op base).
Parameters:
Name Type Description Defaultbalance float OCR balance.
requiredline str Transaction line.
requiredReturns:
Name Type Descriptionfloat float The balance, unmodified.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmountBalancePort.missing_number_candidates","title":"missing_number_candidates","text":"missing_number_candidates(ctx)\nProvide candidates for one-number lines (no-op base).
Parameters:
Name Type Description Defaultctx The active ResolutionContext.
Returns:
Type DescriptionNone.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplAmountBalancePort.resolve","title":"resolve","text":"resolve(amount, balance, prev_balance, line, numbers=None)\nResolve (amount, balance) via ResolutionContext.
Parameters:
Name Type Description Defaultamount OCR amount.
requiredbalance OCR balance (adjusted first).
requiredprev_balance Previous transaction balance.
requiredline Raw transaction line.
requirednumbers Extracted numbers; default None.
None Returns:
Type Description(signed amount, resolved balance) tuple.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplBucketFinderPort","title":"ImplBucketFinderPort","text":" Bases: BucketFinderPort
Concrete bucket finder \u2014 splits raw lines at B/F and opening markers.
Attributes:
Name Type Descriptionnumber ImplNumberPort Number extraction leaf.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplBucketFinderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplBucketFinderPort.get_opening_balance_buckets","title":"get_opening_balance_buckets","text":"get_opening_balance_buckets(\n lines, *, limit_first=False, line_offset=0\n)\nDivide raw lines into opening-balance buckets.
Parameters:
Name Type Description Defaultlines Raw text lines.
requiredlimit_first Keep only the first bucket.
False line_offset Offset added to starting indices.
0 Returns:
Type DescriptionList of (start, end, opening_balance) triples.
Bases: DatePort
Concrete date leaf: parse, split, reconcile, and reorder dates.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDatePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDatePort.get_dates","title":"get_dates","text":"get_dates(line: str) -> Optional[Tuple[str, str]]\nExtract the leading date and text tail from a line.
Parameters:
Name Type Description Defaultline str Text line.
requiredReturns:
Type DescriptionOptional[Tuple[str, str]] Optional[Tuple[str, str]]: (date_str, date_tail) or None.
parse_date(date_str: str) -> datetime.date\nParse DD-MM-YYYY (or DD/MM/YYYY) into a date.
Parameters:
Name Type Description Defaultdate_str str Date string.
requiredReturns:
Type Descriptiondate datetime.date: The parsed date.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDatePort.reconcile_date","title":"reconcile_date","text":"reconcile_date(\n date_str: str, prev_date_str: Optional[str]\n) -> str\nReconcile an OCR date against the previous transaction date.
Parameters:
Name Type Description Defaultdate_str str OCR date string.
requiredprev_date_str Optional[str] Previous transaction date string.
requiredReturns:
Name Type Descriptionstr str Reconciliated date as DD-MM-YYYY.
reconcile_date_full(\n date_str: str, prev: datetime.date\n) -> Optional[str]\nReconcile a date string against a full reference date.
Parameters:
Name Type Description Defaultdate_str str OCR date string.
requiredprev date Previous transaction date.
requiredReturns:
Type DescriptionOptional[str] Optional[str]: Reconciliated DD-MM-YYYY string or None.
reconcile_date_partial(\n date_str: str, prev: datetime.date\n) -> Optional[str]\nReconcile a partial MM-YYYY date against a reference date.
Parameters:
Name Type Description Defaultdate_str str Partial OCR date string.
requiredprev date Previous transaction date.
requiredReturns:
Type DescriptionOptional[str] Optional[str]: Reconciliated DD-MM-YYYY string or None.
reorder_lines_by_date(txn_lines: List[str]) -> List[str]\nMove the dated line to the front of a transaction block.
Parameters:
Name Type Description Defaulttxn_lines List[str] Transaction block lines.
requiredReturns:
Type DescriptionList[str] List[str]: Reordered lines.
Raises:
Type DescriptionValueError When no dated line is present in the block.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDatePort.split_line_by_date","title":"split_line_by_date","text":"split_line_by_date(line: str) -> List[str]\nSplit a merged line into segments at date boundaries.
Parameters:
Name Type Description Defaultline str Possibly merged OCR line.
requiredReturns:
Type DescriptionList[str] List[str]: Line segments split at date boundaries.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDescPort","title":"ImplDescPort","text":" Bases: DescPort
Concrete description leaf \u2014 slices at the first starter marker.
Attributes:
Name Type Descriptionstarters Optional[List[str]] Description starter markers.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDescPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDescPort.extract_description","title":"extract_description","text":"extract_description(description: str) -> str\nExtract and clean the transaction description.
Parameters:
Name Type Description Defaultdescription str Raw description text.
requiredReturns:
Name Type Descriptionstr str Cleaned description.
Raises:
Type DescriptionNotImplementedError When no starters are configured.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplDescPort.fix_ocr","title":"fix_ocr","text":"fix_ocr(text: str) -> str\nFix OCR artifacts in the description text (no-op base).
Parameters:
Name Type Description Defaulttext str Text to fix.
requiredReturns:
Name Type Descriptionstr str Fixed text.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplNumberPort","title":"ImplNumberPort","text":" Bases: NumberPort
Concrete number leaf \u2014 prefers trailing decimals, else the last numbers.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplNumberPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplNumberPort.get_numbers","title":"get_numbers","text":"get_numbers(line: str) -> List[float]\nExtract monetary numbers, preferring trailing decimals.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionList[float] List[float]: Cleaned monetary numbers.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplNumberPort.get_opening_balance","title":"get_opening_balance","text":"get_opening_balance(line: str) -> Optional[float]\nReturn the last number as the opening balance.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionOptional[float] Optional[float]: The last number, else None.
Bases: PDFExtractionPipeline
Concrete pdf graph root.
Attributes:
Name Type Descriptionpipeline 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.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplPDFExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplPDFExtractionPipeline.run","title":"run","text":"run(source)\nRun the pdf extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplRawLinesPort","title":"ImplRawLinesPort","text":" Bases: RawLinesPort
Concrete raw-lines leaf \u2014 OCRs PDF bytes into text lines.
Attributes:
Name Type Descriptioncovert_to_image bool Binarize pages via image conversion.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplRawLinesPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplRawLinesPort.extract","title":"extract","text":"extract(content)\nExtract raw OCR text lines from content.
Parameters:
Name Type Description Defaultcontent PDF bytes, Content, or dict payload.
requiredReturns:
Type DescriptionList of raw text lines.
Raises:
Type DescriptionTypeError When content is not PDF bytes or Content with .raw.
Bases: SplitterPort
Concrete splitter \u2014 splits bucket lines into transaction blocks.
Attributes:
Name Type Descriptionnumber ImplNumberPort Number extraction leaf.
date ImplDatePort Date parsing leaf.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplSplitterPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplSplitterPort.split_blocks","title":"split_blocks","text":"split_blocks(\n lines,\n *,\n has_header=False,\n min_numbers=3,\n detect_date_ranges=False\n)\nSplit bucket lines into transaction blocks.
Parameters:
Name Type Description Defaultlines Bucket lines.
requiredhas_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 DescriptionList of transaction block texts.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTransactionParserPort","title":"ImplTransactionParserPort","text":" Bases: TransactionParserPort
Concrete transaction parser \u2014 one block to one txn dict.
Attributes:
Name Type Descriptionnumber ImplNumberPort Number extraction leaf.
date ImplDatePort Date parsing leaf.
desc ImplDescPort Description extraction leaf.
amount_balance ImplAmountBalancePort Amount/balance resolution leaf.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTransactionParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTransactionParserPort.parse","title":"parse","text":"parse(txn_text, prev_date_str, prev_balance)\nParse a transaction block into a txn dict.
Parameters:
Name Type Description Defaulttxn_text Transaction block text.
requiredprev_date_str Previous transaction date string.
requiredprev_balance Running balance from the previous transaction.
requiredReturns:
Type DescriptionTxn dict, or None when the block has no usable date/numbers.
Bases: TxnBlocksPort
Concrete txn-blocks stage \u2014 buckets plus per-bucket splitting.
Attributes:
Name Type Descriptionbucket_finder ImplBucketFinderPort Bucket-finding leaf.
splitter ImplSplitterPort Block-splitting leaf.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTxnBlocksPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTxnBlocksPort.extract","title":"extract","text":"extract(raw_lines)\nExtract txn blocks keyed by opening balance.
Parameters:
Name Type Description Defaultraw_lines Raw OCR text lines.
requiredReturns:
Type DescriptionDict[float, List[str]]: Opening balance \u2192 block texts.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTxnDictsPort","title":"ImplTxnDictsPort","text":" Bases: TxnDictsPort
Concrete txn-dicts stage \u2014 parses blocks in balance-chained order.
Attributes:
Name Type Descriptionparser ImplTransactionParserPort Transaction parsing leaf.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ImplTxnDictsPort.extract","title":"extract","text":"extract(txn_blocks)\nExtract balance-chained txn dicts from blocks.
Parameters:
Name Type Description Defaulttxn_blocks Opening balance \u2192 block texts.
requiredReturns:
Type DescriptionList of txn dicts.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.clean_num","title":"clean_num","text":"clean_num(s: str) -> float\nPort of domain.extraction.ports.pdf.clean_num.
Parameters:
Name Type Description Defaults str Numeric string to clean.
requiredReturns:
Name Type Descriptionfloat float Parsed numeric value; 0.0 when the string has no digits.
normalize(text: str) -> str\nNormalize OCR text: fix artifacts, strip separators, drop commas.
Parameters:
Name Type Description Defaulttext str Raw OCR text.
requiredReturns:
Name Type Descriptionstr str Normalized text.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.ocr_all_pages","title":"ocr_all_pages","text":"ocr_all_pages(\n pdf_bytes: bytes, covert_to_image: bool = None\n) -> list\nRun OCR over every PDF page, returning per-page text.
Parameters:
Name Type Description Defaultpdf_bytes bytes PDF file bytes.
requiredcovert_to_image bool Binarize pages through image conversion.
None Returns:
Name Type Descriptionlist list One OCR text string per page.
Raises:
Type DescriptionImportError When pytesseract/Pillow are unavailable.
"},{"location":"pipelines/extraction/pdf/impl/#pipelines.extraction.pdf.impl.rasterize_pdf","title":"rasterize_pdf","text":"rasterize_pdf(\n pdf_bytes: bytes, out_dir: str, dpi: int = 300\n) -> list\nRasterize PDF bytes into JPEG page images via pdftoppm.
Parameters:
Name Type Description Defaultpdf_bytes bytes PDF file bytes.
requiredout_dir str Directory to write the PDF and page images.
requireddpi int Render resolution. Defaults to 300.
300 Returns:
Name Type Descriptionlist list Sorted list of generated JPEG page paths.
"},{"location":"pipelines/extraction/pdf/llm/","title":"Llm","text":""},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm","title":"pipelines.extraction.pdf.llm","text":""},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm--summary","title":"Summary","text":"LLM splitter variant of the pdf family (impl-layer, bank-agnostic).
LLMSplitterPort is a faithful port of TransactionSplitterLLMAdaptor (domain/extraction/adaptors/txn_blocks.py) using SyncOpenRouterPool. It swaps into the pdf chain exactly where ImplSplitterPort sits, so the rest of the tree (raw_lines \u2192 txn_blocks \u2192 txn_dicts \u2192 raw_expense) is unchanged.
LLMPdfExtractionPipeline re-pins only the txn_blocks.splitter slot.
Bases: ImplPDFExtractionPipeline
PDF root with the LLM splitter swapped into the txn-blocks stage.
Attributes:
Name Type Descriptiontxn_blocks LLMTxnBlocksPort Txn-blocks stage with LLM splitter.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMPdfExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMPdfExtractionPipeline.run","title":"run","text":"run(source)\nRun the pdf extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMSplitterPort","title":"LLMSplitterPort","text":"LLMSplitterPort(pool=None, **kwargs)\n Bases: SplitterPort
LLM-backed splitter that groups lines into transactions via prompts.
Attributes:
Name Type DescriptionDATE_RE Pattern[str] Compiled regex matching leading DD-MM-YYYY dates.
number ImplNumberPort Number extraction leaf.
date ImplDatePort Date parsing leaf.
GROUP_PROMPT str Prompt grouping indices into transactions.
RESOLVE_PROMPT str Prompt resolving cross-batch conflicts.
MAX_CONFLICT_LOOPS int Max conflict resolution loops.
BATCH_MERGE int Date lines per batch.
Initialize the splitter with an LLM pool.
Parameters:
Name Type Description Defaultpool LLM pool; defaults to a new SyncOpenRouterPool.
None **kwargs Passed through to the base class.
{}"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMSplitterPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMSplitterPort.clean_raw_lines","title":"clean_raw_lines staticmethod","text":"clean_raw_lines(raw_lines: List[str]) -> List[str]\nClean raw lines: strip trailing noise and drop Page lines.
Parameters:
Name Type Description Defaultraw_lines List[str] Raw OCR lines.
requiredReturns:
Type DescriptionList[str] List[str]: Cleaned lines.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMSplitterPort.split_blocks","title":"split_blocks","text":"split_blocks(\n lines,\n *,\n has_header=False,\n min_numbers=3,\n detect_date_ranges=False\n)\nGroup lines into transaction blocks via the LLM.
Parameters:
Name Type Description Defaultlines Raw OCR lines.
requiredhas_header Whether a header precedes the rows.
False min_numbers Minimum numbers for a block.
3 detect_date_ranges Detect date-range lines.
False Returns:
Type DescriptionList of transaction block texts.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMSplitterPort.strip_headers","title":"strip_headersstaticmethod","text":"strip_headers(raw_lines: List[str]) -> List[str]\nDrop header lines preceding the first date line.
Parameters:
Name Type Description Defaultraw_lines List[str] Raw OCR lines.
requiredReturns:
Type DescriptionList[str] List[str]: Lines with headers removed.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMTxnBlocksPort","title":"LLMTxnBlocksPort","text":" Bases: ImplTxnBlocksPort
Txn-blocks stage re-pinning the splitter to the LLM variant.
Attributes:
Name Type Descriptionsplitter LLMSplitterPort LLM-backed splitter.
"},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMTxnBlocksPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/llm/#pipelines.extraction.pdf.llm.LLMTxnBlocksPort.extract","title":"extract","text":"extract(raw_lines)\nExtract txn blocks keyed by opening balance.
Parameters:
Name Type Description Defaultraw_lines Raw OCR text lines.
requiredReturns:
Type DescriptionDict[float, List[str]]: Opening balance \u2192 block texts.
"},{"location":"pipelines/extraction/pdf/banks/","title":"Banks","text":"pdf family \u2014 bank-specific ports and pipeline roots.
"},{"location":"pipelines/extraction/pdf/banks/axis/","title":"Axis","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis","title":"pipelines.extraction.pdf.banks.axis","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis--summary","title":"Summary","text":"Axis bank-specific port implementations (pdf statement path).
Banks EXTEND the concrete Impl* classes \u2014 they never reinvent the ABC contracts. Each Axis* class overrides only the behavior that DIFFERS from the common Impl*; anything shared is inherited. The pipeline root AxisPdfExtractionPipeline pins only the stage slots that differ.
Bases: ImplAmountBalancePort
Axis amount/balance leaf \u2014 pins the Axis number leaf.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisAmountBalancePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisAmountBalancePort.adjust_balance","title":"adjust_balance","text":"adjust_balance(balance: float, line: str) -> float\nAdjust an OCR balance (no-op base).
Parameters:
Name Type Description Defaultbalance float OCR balance.
requiredline str Transaction line.
requiredReturns:
Name Type Descriptionfloat float The balance, unmodified.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisAmountBalancePort.missing_number_candidates","title":"missing_number_candidates","text":"missing_number_candidates(ctx)\nProvide candidates for one-number lines (no-op base).
Parameters:
Name Type Description Defaultctx The active ResolutionContext.
Returns:
Type DescriptionNone.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisAmountBalancePort.resolve","title":"resolve","text":"resolve(amount, balance, prev_balance, line, numbers=None)\nResolve (amount, balance) via ResolutionContext.
Parameters:
Name Type Description Defaultamount OCR amount.
requiredbalance OCR balance (adjusted first).
requiredprev_balance Previous transaction balance.
requiredline Raw transaction line.
requirednumbers Extracted numbers; default None.
None Returns:
Type Description(signed amount, resolved balance) tuple.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisBucketFinderPort","title":"AxisBucketFinderPort","text":" Bases: ImplBucketFinderPort
Axis bucket finder \u2014 pins the Axis number leaf.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisBucketFinderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisBucketFinderPort.get_opening_balance_buckets","title":"get_opening_balance_buckets","text":"get_opening_balance_buckets(\n lines, *, limit_first=False, line_offset=0\n)\nDivide raw lines into opening-balance buckets.
Parameters:
Name Type Description Defaultlines Raw text lines.
requiredlimit_first Keep only the first bucket.
False line_offset Offset added to starting indices.
0 Returns:
Type DescriptionList of (start, end, opening_balance) triples.
Bases: ImplDescPort
Axis description leaf \u2014 slices at UPI/IMPS/NEFT/ACH/2A markers.
Attributes:
Name Type Descriptionstarters List[str] Description starter markers.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisDescPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisDescPort.extract_description","title":"extract_description","text":"extract_description(description: str) -> str\nExtract and clean the transaction description.
Parameters:
Name Type Description Defaultdescription str Raw description text.
requiredReturns:
Name Type Descriptionstr str Cleaned description.
Raises:
Type DescriptionNotImplementedError When no starters are configured.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisDescPort.fix_ocr","title":"fix_ocr","text":"fix_ocr(text: str) -> str\nFix OCR artifacts in the description text (no-op base).
Parameters:
Name Type Description Defaulttext str Text to fix.
requiredReturns:
Name Type Descriptionstr str Fixed text.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisNumberPort","title":"AxisNumberPort","text":" Bases: ImplNumberPort
Axis number leaf \u2014 returns every number in the line.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisNumberPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisNumberPort.get_numbers","title":"get_numbers","text":"get_numbers(line: str) -> List[float]\nExtract every cleaned number from the line.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionList[float] List[float]: All cleaned numbers in the line.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisNumberPort.get_opening_balance","title":"get_opening_balance","text":"get_opening_balance(line: str) -> Optional[float]\nReturn the last number as the opening balance.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionOptional[float] Optional[float]: The last number, else None.
Bases: ImplPDFExtractionPipeline
Axis pdf graph root \u2014 pins the Axis txn-blocks and txn-dicts stages.
Attributes:
Name Type Descriptiontxn_blocks AxisTxnBlocksPort Axis txn-blocks stage.
txn_dicts AxisTxnDictsPort Axis txn-dicts stage.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisPdfExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisPdfExtractionPipeline.run","title":"run","text":"run(source)\nRun the pdf extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisSplitterPort","title":"AxisSplitterPort","text":" Bases: ImplSplitterPort
Axis splitter \u2014 pins the Axis number leaf.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisSplitterPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisSplitterPort.split_blocks","title":"split_blocks","text":"split_blocks(\n lines,\n *,\n has_header=False,\n min_numbers=3,\n detect_date_ranges=False\n)\nSplit bucket lines into transaction blocks.
Parameters:
Name Type Description Defaultlines Bucket lines.
requiredhas_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 DescriptionList of transaction block texts.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTransactionParserPort","title":"AxisTransactionParserPort","text":" Bases: ImplTransactionParserPort
Axis transaction parser \u2014 pins Axis-stage leaves and min_numbers=2.
Attributes:
Name Type Descriptionnumber AxisNumberPort Axis number leaf.
desc AxisDescPort Axis description leaf.
amount_balance AxisAmountBalancePort Axis amount/balance leaf.
min_numbers int Minimum numbers for a block.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTransactionParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTransactionParserPort.parse","title":"parse","text":"parse(txn_text, prev_date_str, prev_balance)\nParse a transaction block into a txn dict.
Parameters:
Name Type Description Defaulttxn_text Transaction block text.
requiredprev_date_str Previous transaction date string.
requiredprev_balance Running balance from the previous transaction.
requiredReturns:
Type DescriptionTxn dict, or None when the block has no usable date/numbers.
Bases: ImplTxnBlocksPort
Axis txn-blocks stage \u2014 header-scanning, date-range, min_numbers=2.
Attributes:
Name Type Descriptionbucket_finder AxisBucketFinderPort Axis bucket finder.
splitter AxisSplitterPort Axis splitter.
has_header bool Header scan enabled.
min_numbers int Minimum numbers for a block.
detect_date_ranges bool Date-range detection enabled.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTxnBlocksPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTxnBlocksPort.extract","title":"extract","text":"extract(raw_lines)\nExtract txn blocks keyed by opening balance.
Parameters:
Name Type Description Defaultraw_lines Raw OCR text lines.
requiredReturns:
Type DescriptionDict[float, List[str]]: Opening balance \u2192 block texts.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTxnDictsPort","title":"AxisTxnDictsPort","text":" Bases: ImplTxnDictsPort
Axis txn-dicts stage \u2014 pins the Axis transaction parser.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis.AxisTxnDictsPort.extract","title":"extract","text":"extract(txn_blocks)\nExtract balance-chained txn dicts from blocks.
Parameters:
Name Type Description Defaulttxn_blocks Opening balance \u2192 block texts.
requiredReturns:
Type DescriptionList of txn dicts.
"},{"location":"pipelines/extraction/pdf/banks/axis/#pipelines.extraction.pdf.banks.axis-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/","title":"Icici","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici","title":"pipelines.extraction.pdf.banks.icici","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici--summary","title":"Summary","text":"Icici bank-specific port implementations (pdf statement path).
Banks EXTEND the concrete Impl* classes \u2014 they never reinvent the ABC contracts. Each Icici* class overrides only the behavior that DIFFERS from the common Impl*; anything shared is inherited.
Derived from the real domain/extraction/banks/icici/pdf.py:
Bases: ImplAmountBalancePort
Icici amount/balance leaf \u2014 negates bracketed OCR balances.
Attributes:
Name Type Descriptionnumber IciciNumberPort Icici number leaf.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciAmountBalancePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciAmountBalancePort.adjust_balance","title":"adjust_balance","text":"adjust_balance(balance: float, line: str) -> float\nNegate a balance flagged as negative by OCR brackets.
Parameters:
Name Type Description Defaultbalance float OCR balance.
requiredline str Transaction line.
requiredReturns:
Name Type Descriptionfloat float Negated balance when a bracket marker is present, else the
float balance unchanged.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciAmountBalancePort.missing_number_candidates","title":"missing_number_candidates","text":"missing_number_candidates(ctx)\nProvide one-number candidates: the number as amount or as balance.
Parameters:
Name Type Description Defaultctx The active ResolutionContext.
Returns:
Type DescriptionSet of (amount, balance) candidate pairs.
resolve(amount, balance, prev_balance, line, numbers=None)\nResolve (amount, balance) via ResolutionContext.
Parameters:
Name Type Description Defaultamount OCR amount.
requiredbalance OCR balance (adjusted first).
requiredprev_balance Previous transaction balance.
requiredline Raw transaction line.
requirednumbers Extracted numbers; default None.
None Returns:
Type Description(signed amount, resolved balance) tuple.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciBucketFinderPort","title":"IciciBucketFinderPort","text":" Bases: ImplBucketFinderPort
Icici bucket finder \u2014 pins the Icici number leaf.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciBucketFinderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciBucketFinderPort.get_opening_balance_buckets","title":"get_opening_balance_buckets","text":"get_opening_balance_buckets(\n lines, *, limit_first=False, line_offset=0\n)\nDivide raw lines into opening-balance buckets.
Parameters:
Name Type Description Defaultlines Raw text lines.
requiredlimit_first Keep only the first bucket.
False line_offset Offset added to starting indices.
0 Returns:
Type DescriptionList of (start, end, opening_balance) triples.
Bases: ImplDescPort
Icici description leaf \u2014 slices at Icici markers and fixes OCR typos.
Attributes:
Name Type Descriptionstarters Optional[List[str]] Description starter markers.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciDescPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciDescPort.extract_description","title":"extract_description","text":"extract_description(description: str) -> str\nExtract and clean the transaction description.
Parameters:
Name Type Description Defaultdescription str Raw description text.
requiredReturns:
Name Type Descriptionstr str Cleaned description.
Raises:
Type DescriptionNotImplementedError When no starters are configured.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciDescPort.fix_ocr","title":"fix_ocr","text":"fix_ocr(text: str) -> str\nFix common Icici OCR typos in the description text.
Parameters:
Name Type Description Defaulttext str Text to fix.
requiredReturns:
Name Type Descriptionstr str Text with OCR replacements applied.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciNumberPort","title":"IciciNumberPort","text":" Bases: ImplNumberPort
Icici number leaf \u2014 prefers the last two decimal numbers.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciNumberPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciNumberPort.get_numbers","title":"get_numbers","text":"get_numbers(line: str) -> List[float]\nExtract monetary numbers, preferring trailing decimals.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionList[float] List[float]: Cleaned monetary numbers.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciNumberPort.get_opening_balance","title":"get_opening_balance","text":"get_opening_balance(line: str) -> Optional[float]\nReturn the last number as the opening balance.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionOptional[float] Optional[float]: The last number, else None.
Bases: ImplPDFExtractionPipeline
Icici pdf graph root \u2014 pins raw-lines, txn-blocks, and txn-dicts stages.
Attributes:
Name Type Descriptionraw_lines IciciRawLinesPort Icici raw-lines stage.
txn_blocks IciciTxnBlocksPort Icici txn-blocks stage.
txn_dicts IciciTxnDictsPort Icici txn-dicts stage.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciPdfExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciPdfExtractionPipeline.run","title":"run","text":"run(source)\nRun the pdf extraction chain end-to-end.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList of raw expense records.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciRawLinesPort","title":"IciciRawLinesPort","text":" Bases: ImplRawLinesPort
Icici raw-lines leaf \u2014 binarized OCR.
Attributes:
Name Type Descriptioncovert_to_image bool Binarize pages via image conversion.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciRawLinesPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciRawLinesPort.extract","title":"extract","text":"extract(content)\nExtract raw OCR text lines from content.
Parameters:
Name Type Description Defaultcontent PDF bytes, Content, or dict payload.
requiredReturns:
Type DescriptionList of raw text lines.
Raises:
Type DescriptionTypeError When content is not PDF bytes or Content with .raw.
Bases: ImplSplitterPort
Icici splitter \u2014 pins the Icici number leaf.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciSplitterPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciSplitterPort.split_blocks","title":"split_blocks","text":"split_blocks(\n lines,\n *,\n has_header=False,\n min_numbers=3,\n detect_date_ranges=False\n)\nSplit bucket lines into transaction blocks.
Parameters:
Name Type Description Defaultlines Bucket lines.
requiredhas_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 DescriptionList of transaction block texts.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTransactionParserPort","title":"IciciTransactionParserPort","text":" Bases: ImplTransactionParserPort
Icici transaction parser \u2014 pins Icici-stage leaves and indices.
Attributes:
Name Type Descriptionnumber IciciNumberPort Icici number leaf.
desc IciciDescPort Icici description leaf.
amount_balance IciciAmountBalancePort Icici amount/balance leaf.
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.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTransactionParserPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTransactionParserPort.parse","title":"parse","text":"parse(txn_text, prev_date_str, prev_balance)\nParse a transaction block into a txn dict.
Parameters:
Name Type Description Defaulttxn_text Transaction block text.
requiredprev_date_str Previous transaction date string.
requiredprev_balance Running balance from the previous transaction.
requiredReturns:
Type DescriptionTxn dict, or None when the block has no usable date/numbers.
Bases: ImplTxnBlocksPort
Icici txn-blocks stage \u2014 min_numbers=2, first bucket only.
Attributes:
Name Type Descriptionbucket_finder IciciBucketFinderPort Icici bucket finder.
splitter IciciSplitterPort Icici splitter.
min_numbers int Minimum numbers for a block.
limit_first bool Keep only the first bucket.
line_offset int Offset added to starting indices.
detect_date_ranges bool Date-range detection enabled.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTxnBlocksPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTxnBlocksPort.extract","title":"extract","text":"extract(raw_lines)\nExtract txn blocks keyed by opening balance.
Parameters:
Name Type Description Defaultraw_lines Raw OCR text lines.
requiredReturns:
Type DescriptionDict[float, List[str]]: Opening balance \u2192 block texts.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTxnDictsPort","title":"IciciTxnDictsPort","text":" Bases: ImplTxnDictsPort
Icici txn-dicts stage \u2014 pins the Icici transaction parser.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici.IciciTxnDictsPort.extract","title":"extract","text":"extract(txn_blocks)\nExtract balance-chained txn dicts from blocks.
Parameters:
Name Type Description Defaulttxn_blocks Opening balance \u2192 block texts.
requiredReturns:
Type DescriptionList of txn dicts.
"},{"location":"pipelines/extraction/pdf/banks/icici/#pipelines.extraction.pdf.banks.icici-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/","title":"Shared","text":"Shared leaf contracts + cross-family machinery.
"},{"location":"pipelines/extraction/shared/ambiguity/","title":"Ambiguity","text":""},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity","title":"pipelines.extraction.shared.ambiguity","text":""},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity--summary","title":"Summary","text":"Ambiguity resolution \u2014 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.
AmbiguityHandler(\n fetch_request_id: str = \"\",\n pause_on_ambiguity: bool = True,\n resolved_choices: Optional[dict] = None,\n resolver: Optional[Callable] = None,\n)\nThree-mode ambiguity dispatcher: resolved_choices -> resolver -> pause -> CLI.
Attributes:
Name Type Descriptionfetch_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 Defaultfetch_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"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.AmbiguityHandler-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.AmbiguityHandler.resolve_ambiguity","title":"resolve_ambiguity","text":"resolve_ambiguity(\n line, ocr_amount, ocr_balance, prev_balance, candidates\n)\nResolve 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 Type Description Defaultline Raw transaction line being resolved.
requiredocr_amount OCR-extracted amount.
requiredocr_balance OCR-extracted balance.
requiredprev_balance Running balance from the previous transaction.
requiredcandidates Collection of candidate (amount, balance) pairs.
requiredReturns:
Type DescriptionSet of a single (amount, balance) pair, or None when no valid
interpretation exists.
Raises:
Type DescriptionPauseForResolution When multiple interpretations remain and pause_on_ambiguity is enabled.
AmbiguousCandidateFound(candidates: set)\n Bases: ValueError
Raised when candidate generation produces multiple valid interpretations.
Attributes:
Name Type Descriptioncandidates set Ambiguous candidate (amount, balance) pairs.
"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.AmountBalanceNotFound","title":"AmountBalanceNotFound","text":" Bases: ValueError
Raised when no valid amount/balance interpretation can be found.
"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.PauseForResolution","title":"PauseForResolution","text":"PauseForResolution(\n line,\n ocr_amount,\n ocr_balance,\n prev_balance,\n candidates,\n fetch_request_id: str = \"\",\n)\n Bases: Exception
Signal that ambiguous candidates need human resolution.
Attributes:
Name Type Descriptionline 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.
"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.ResolutionContext","title":"ResolutionContext","text":"ResolutionContext(\n amount,\n balance,\n prev_balance,\n line,\n numbers,\n handler=None,\n trust_fallback=None,\n missing_number_candidates=None,\n)\nResolves amount/balance pairs, generating candidates when direct validation fails.
Attributes:
Name Type Descriptionamount 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 Type Description Defaultamount OCR-extracted transaction amount.
requiredbalance OCR-extracted closing balance.
requiredprev_balance Running balance from the previous transaction.
requiredline Raw transaction line being resolved.
requirednumbers Extracted numbers from the transaction line.
requiredhandler 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"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.ResolutionContext-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.ResolutionContext.resolve","title":"resolve","text":"resolve()\nResolve 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 DescriptionTwo-tuple of signed amount and validated balance.
Raises:
Type DescriptionAmountBalanceNotFound When no candidate interpretation reconciles with the running balance.
"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.clean_num","title":"clean_num","text":"clean_num(s: str) -> float\nConvert 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 Defaults str Numeric string to clean.
requiredReturns:
Name Type Descriptionfloat float Parsed numeric value; 0.0 when the string has no digits.
get_numbers(text: str) -> List[float]\nExtract monetary numbers from OCR/text lines.
Parameters:
Name Type Description Defaulttext str Text line to scan.
requiredReturns:
Type DescriptionList[float] List[float]: Cleaned numeric values found in the text.
"},{"location":"pipelines/extraction/shared/ambiguity/#pipelines.extraction.shared.ambiguity.validate_signs","title":"validate_signs","text":"validate_signs(\n amount, balance, prev_balance, tolerance=1.0\n)\nValidate a (amount, balance) interpretation against the running balance.
Parameters:
Name Type Description Defaultamount OCR-extracted transaction amount.
requiredbalance OCR-extracted closing balance.
requiredprev_balance Running balance from the previous transaction.
requiredtolerance float Allowed rounding difference. Defaults to 1.0.
1.0 Returns:
Type DescriptionTwo-tuple of signed amount and validated balance, or (None, None)
when no sign combination reconciles with the running balance.
"},{"location":"pipelines/extraction/shared/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl","title":"pipelines.extraction.shared.impl","text":""},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl--summary","title":"Summary","text":"Shared concrete implementations used by every extraction family.
Only genuinely family-agnostic ports live here:
ImplIngestPort : bytes/dict/Content/list/str -> content payload. This is what families receive as their first stage output.ImplRawExpensePort : txn_dicts -> list[RawExpense] (terminal).Every other implementation is homed in the family it belongs to (pdf/impl.py, email/impl.py, csv/impl.py, xlsx/impl.py).
Bases: IngestPort
Materialize an ExtractionSource into a concrete content payload.
Attributes:
Name Type Descriptionsource_type str Source-type tag declared by the concrete root.
"},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl.ImplIngestPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl.ImplIngestPort.materialize","title":"materialize","text":"materialize(source)\nConvert a raw source into a concrete content payload.
Parameters:
Name Type Description Defaultsource Raw source (with raw, bytes, dict, list, or str).
Returns:
Type DescriptionConcrete payload: the source itself, {\"raw\": bytes}, a dict, a
list, or {\"content\": str} depending on the source shape.
Bases: RawExpensePort
Build raw expense records from txn dicts (terminal stage).
"},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl.ImplRawExpensePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/impl/#pipelines.extraction.shared.impl.ImplRawExpensePort.build","title":"build","text":"build(txn_dicts)\nMap structured txn dicts onto the raw-expense shape.
Parameters:
Name Type Description Defaulttxn_dicts List of structured transaction dicts.
requiredReturns:
Type DescriptionList of raw expense dicts keyed by date, amount, balance,
description, and direction.
"},{"location":"pipelines/extraction/shared/ports/","title":"Ports","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports","title":"pipelines.extraction.shared.ports","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports--summary","title":"Summary","text":"Shared leaf contracts for every extraction family (no implementation).
These ports are genuinely common across the pdf / email / csv / xlsx families:
Concrete implementations (re)declare the same slots with CONCRETE types in the per-family impl.py modules and in the per-bank modules; hexa.build() reads the merged MRO annotations and wires everything.
Bases: ABC
Resolve ambiguous amount/balance interpretations.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.AmbiguityPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.AmbiguityPort.resolve_ambiguity","title":"resolve_ambiguityabstractmethod","text":"resolve_ambiguity(\n line: str,\n ocr_amount: float,\n ocr_balance: float,\n prev_balance: float,\n) -> Any\nResolve ambiguous amount/balance interpretations.
Parameters:
Name Type Description Defaultline str Raw transaction line.
requiredocr_amount float OCR-extracted amount.
requiredocr_balance float OCR-extracted balance.
requiredprev_balance float Running balance from the previous transaction.
requiredReturns:
Name Type DescriptionAny Any Resolution result (concrete per implementation).
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.AmountBalancePort","title":"AmountBalancePort","text":" Bases: ABC
Validate + resolve a txn amount against the running balance.
Attributes:
Name Type Descriptiontrust_fallback Optional[str] Fallback policy (\"amount\" or \"balance\").
number NumberPort Number extraction leaf.
ambiguity AmbiguityPort Ambiguity resolution leaf.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.AmountBalancePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.AmountBalancePort.resolve","title":"resolveabstractmethod","text":"resolve(\n amount: float,\n balance: float,\n prev_balance: float,\n line: str,\n numbers: Optional[List[float]] = None,\n) -> Tuple[float, float]\nValidate and resolve a transaction amount against the balance.
Parameters:
Name Type Description Defaultamount float OCR-extracted amount.
requiredbalance float OCR-extracted balance.
requiredprev_balance float Running balance from the previous transaction.
requiredline str Raw transaction line.
requirednumbers Optional[List[float]] Extracted numbers; default None.
None Returns:
Type DescriptionTuple[float, float] Tuple[float, float]: (signed amount, resolved balance).
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DatePort","title":"DatePort","text":" Bases: ABC
Detect, parse and reconcile transaction dates.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DatePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DatePort.get_dates","title":"get_datesabstractmethod","text":"get_dates(line: str) -> Optional[Tuple[str, str]]\nExtract the leading date and the remaining line tail.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionOptional[Tuple[str, str]] Optional[Tuple[str, str]]: (date_str, date_tail) when a date
Optional[Tuple[str, str]] leads the line, else None.
abstractmethod","text":"parse_date(date_str: str) -> datetime.date\nParse a date string into a date.
Parameters:
Name Type Description Defaultdate_str str Date string, commonly DD-MM-YYYY.
Returns:
Type Descriptiondate datetime.date: The parsed date.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DatePort.reconcile_date","title":"reconcile_dateabstractmethod","text":"reconcile_date(\n date_str: str, prev_date_str: Optional[str]\n) -> str\nReconcile an OCR date against the previous transaction date.
Parameters:
Name Type Description Defaultdate_str str OCR-extracted date string.
requiredprev_date_str Optional[str] Previous transaction date string.
requiredReturns:
Name Type Descriptionstr str Reconciliated date as DD-MM-YYYY.
abstractmethod","text":"reorder_lines_by_date(txn_lines: List[str]) -> List[str]\nReorder block lines so the dated line leads.
Parameters:
Name Type Description Defaulttxn_lines List[str] Transaction block lines.
requiredReturns:
Type DescriptionList[str] List[str]: Lines with the dated line moved to the front.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DatePort.split_line_by_date","title":"split_line_by_dateabstractmethod","text":"split_line_by_date(line: str) -> List[str]\nSplit a line into segments at date boundaries.
Parameters:
Name Type Description Defaultline str Text line (possibly two transactions merged).
requiredReturns:
Type DescriptionList[str] List[str]: Line segments split at date boundaries.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DescPort","title":"DescPort","text":" Bases: ABC
Extract a clean transaction description.
Attributes:
Name Type Descriptionstarters List[str] Description starter markers to slice at.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DescPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.DescPort.extract_description","title":"extract_descriptionabstractmethod","text":"extract_description(description: str) -> str\nExtract and clean the transaction description.
Parameters:
Name Type Description Defaultdescription str Raw description text.
requiredReturns:
Name Type Descriptionstr str Cleaned description.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.ExtractionSource","title":"ExtractionSourcedataclass","text":"ExtractionSource(\n source_type: str,\n bank: str,\n pipeline: str,\n path: Optional[str],\n trust_fallback: Optional[str],\n)\nNested attribute struct describing where to pull content from.
Attributes:
Name Type Descriptionsource_type str Source family tag (pdf, email, csv, xlsx, llama).
bank str Bank tag (axis, icici).
pipeline str Pipeline tag (heuristic, llm, tabular).
path Optional[str] Path to the source content, when applicable.
trust_fallback Optional[str] Fallback policy for amount/balance trust.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.IngestPort","title":"IngestPort","text":" Bases: ABC
Turn an ExtractionSource into a concrete content payload.
Attributes:
Name Type Descriptionsource_type str Source-type tag declared by the concrete root.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.IngestPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.IngestPort.materialize","title":"materializeabstractmethod","text":"materialize(source) -> Any\nConvert a raw source into a concrete content payload.
Parameters:
Name Type Description Defaultsource Raw source (via ExtractionSource) to materialize.
Returns:
Name Type DescriptionAny Any Concrete payload (bytes, Content, dict, list, or str).
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.NumberPort","title":"NumberPort","text":" Bases: ABC
Extract monetary numbers from OCR/text lines.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.NumberPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.NumberPort.get_numbers","title":"get_numbersabstractmethod","text":"get_numbers(line: str) -> List[float]\nExtract monetary numbers from a line.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionList[float] List[float]: Cleaned monetary numbers found in the line.
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.NumberPort.get_opening_balance","title":"get_opening_balanceabstractmethod","text":"get_opening_balance(line: str) -> Optional[float]\nExtract the opening balance from a line.
Parameters:
Name Type Description Defaultline str Text line to scan.
requiredReturns:
Type DescriptionOptional[float] Optional[float]: The opening balance when found, else None.
Bases: ABC
txn_dicts \u2192 list[RawExpense], balance-chained (terminal).
"},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.RawExpensePort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/ports/#pipelines.extraction.shared.ports.RawExpensePort.build","title":"buildabstractmethod","text":"build(txn_dicts) -> List[Any]\nBuild raw expenses from txn dicts (terminal stage).
Parameters:
Name Type Description Defaulttxn_dicts List of structured transaction dicts.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/shared/registry/","title":"Registry","text":""},{"location":"pipelines/extraction/shared/registry/#pipelines.extraction.shared.registry","title":"pipelines.extraction.shared.registry","text":""},{"location":"pipelines/extraction/shared/registry/#pipelines.extraction.shared.registry--summary","title":"Summary","text":"Registry mapping (source_type, bank, pipeline) \u2192 composition root.
Each family's banks/ module defines its concrete root (e.g. AxisPdfExtractionPipeline); this module is the single lookup used by callers (the fetch-request scripts) instead of hand-rolled _BANK_TO_ROOT maps.
known_roots() -> list\nList every registered (source_type, bank, pipeline) triple.
Returns:
Name Type Descriptionlist list List of (source_type, bank, pipeline) tuples.
resolve_root(\n source_type: str, bank: str, pipeline: str = \"heuristic\"\n) -> type\nReturn the composition root class for (source_type, bank, pipeline).
Parameters:
Name Type Description Defaultsource_type str Source family (pdf, email, csv, xlsx, llama).
requiredbank str Bank tag (axis, icici).
requiredpipeline str Pipeline tag; defaults to \"heuristic\".
'heuristic' Returns:
Name Type Descriptiontype type The composition root class for the triple.
Raises:
Type DescriptionValueError When no root is registered for the triple.
"},{"location":"pipelines/extraction/shared/tabular/","title":"Tabular","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular","title":"pipelines.extraction.shared.tabular","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular--summary","title":"Summary","text":"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 \u2014 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 \u2014 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). Bases: ObjectsTxnDictsPort
build(objects)\nBuild txn dicts from already-structured objects (impl).
Parameters:
Name Type Description Defaultobjects Structured statement objects.
requiredReturns:
Type DescriptionList of txn dicts.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.ImplTabularTxnDictsPort","title":"ImplTabularTxnDictsPort","text":" Bases: TabularTxnDictsPort
build(records)\nBuild balance-chained txn dicts from typed records (impl).
Parameters:
Name Type Description Defaultrecords Typed table records.
requiredReturns:
Type DescriptionList of txn dicts.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.ObjectsTxnDictsPort","title":"ObjectsTxnDictsPort","text":" Bases: ABC
already-structured objects \u2192 list of txn dicts (stated balances trusted).
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.ObjectsTxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.ObjectsTxnDictsPort.build","title":"buildabstractmethod","text":"build(\n objects: List[Dict[str, Any]],\n) -> List[Dict[str, Any]]\nBuild txn dicts from already-structured objects.
Parameters:
Name Type Description Defaultobjects List[Dict[str, Any]] Structured statement objects.
requiredReturns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: Txn dicts.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TableParserMixin","title":"TableParserMixin","text":"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 Descriptioncolumn_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.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TableReaderPort","title":"TableReaderPort","text":" Bases: ABC
content \u2192 list of typed table records (in sheet/file order).
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TableReaderPort.read","title":"readabstractmethod","text":"read(content) -> List[Dict[str, Any]]\nRead typed table records from content.
Parameters:
Name Type Description Defaultcontent Materialized content payload.
requiredReturns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: Typed table records in source order.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularExtractionPipeline","title":"TabularExtractionPipeline","text":" Bases: ABC
Root \u2014 direct-table chain: ingest \u2192 table_reader \u2192 txn_dicts \u2192 raw_expense.
Attributes:
Name Type Descriptionsource 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.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularTxnDictsPort","title":"TabularTxnDictsPort","text":" Bases: ABC
records \u2192 list of txn dicts, balance-chained (terminal rules live here).
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularTxnDictsPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.TabularTxnDictsPort.build","title":"buildabstractmethod","text":"build(\n records: List[Dict[str, Any]],\n) -> List[Dict[str, Any]]\nBuild balance-chained txn dicts from typed records.
Parameters:
Name Type Description Defaultrecords List[Dict[str, Any]] Typed table records.
requiredReturns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: Txn dicts.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular-functions","title":"Functions","text":""},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.adjust_balances","title":"adjust_balances","text":"adjust_balances(\n records: List[Dict[str, Any]],\n) -> List[Dict[str, Any]]\nWalk 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 Defaultrecords List[Dict[str, Any]] Records in table order to chain.
requiredReturns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: The same records with corrected balances.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.objects_to_txn_dict","title":"objects_to_txn_dict","text":"objects_to_txn_dict(obj: Dict[str, Any]) -> Dict[str, Any]\nMap 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 \u2014 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 Defaultobj Dict[str, Any] Structured statement object.
requiredReturns:
Type DescriptionDict[str, Any] Dict[str, Any]: Txn dict with txn_date, particulars, amount, balance,
Dict[str, Any] and direction keys.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.signed_amount","title":"signed_amount","text":"signed_amount(record: Dict[str, Any]) -> float\nCompute the signed amount from deposit minus withdrawal.
Parameters:
Name Type Description Defaultrecord Dict[str, Any] Typed table record.
requiredReturns:
Name Type Descriptionfloat float Deposit minus withdrawal, rounded to 2 places.
"},{"location":"pipelines/extraction/shared/tabular/#pipelines.extraction.shared.tabular.tabular_to_txn_dict","title":"tabular_to_txn_dict","text":"tabular_to_txn_dict(\n record: Dict[str, Any],\n) -> Dict[str, Any]\nMap a typed table record onto the standard txn-dict shape.
Parameters:
Name Type Description Defaultrecord Dict[str, Any] Typed, balance-chained table record.
requiredReturns:
Type DescriptionDict[str, Any] Dict[str, Any]: Txn dict with txn_date, particulars, amount, balance,
Dict[str, Any] and direction keys.
"},{"location":"pipelines/extraction/xlsx/","title":"Xlsx","text":"xlsx (direct table) extraction family.
"},{"location":"pipelines/extraction/xlsx/abc/","title":"Abc","text":""},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc","title":"pipelines.extraction.xlsx.abc","text":""},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc--summary","title":"Summary","text":"Abstract contracts for the xlsx (direct table) extraction graph.
The xlsx family is a \"direct table\" pipeline \u2014 no OCR, no buckets, no ambiguity. It shares the tabular core (shared/tabular.py) with csv: only the table reader differs (xlsx worksheet rows vs csv rows). Bank-specific readers live under banks/.
Bases: TabularExtractionPipeline
xlsx-family root \u2014 pins only the reader; chain shared with csv.
Slot annotationssource: ExtractionSource ingest, table_reader, txn_dicts, raw_expense
Attributes:
Name Type Descriptionsource ExtractionSource The extraction source descriptor.
table_reader XlsxTableReaderPort Xlsx table reader stage.
"},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc.XlsxExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc.XlsxExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc.XlsxTableReaderPort","title":"XlsxTableReaderPort","text":" Bases: TableReaderPort
content \u2192 list of typed records read from an xlsx statement sheet.
"},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc.XlsxTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/abc/#pipelines.extraction.xlsx.abc.XlsxTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from an xlsx statement sheet.
Parameters:
Name Type Description Defaultcontent Materialized content (bytes, Content, dict, or str).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/xlsx/impl/","title":"Impl","text":""},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl","title":"pipelines.extraction.xlsx.impl","text":""},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl--summary","title":"Summary","text":"Concrete xlsx-family implementations.
ImplXlsxTableReaderPort reads typed worksheet rows (via the omniread xlsx parser's workbook) and runs them through the shared TableParserMixin to emit typed records. The chain (records \u2192 balance-adjusted txn dicts \u2192 raw expenses) is the shared tabular core.
Bases: XlsxExtractionPipeline
Concrete xlsx graph root.
Attributes:
Name Type Descriptioningest ImplIngestPort Ingest stage.
table_reader ImplXlsxTableReaderPort Xlsx table reader stage.
txn_dicts ImplTabularTxnDictsPort Shared tabular txn-dicts stage.
raw_expense ImplRawExpensePort Terminal raw-expense stage.
"},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl.ImplXlsxExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl.ImplXlsxExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl.ImplXlsxTableReaderPort","title":"ImplXlsxTableReaderPort","text":" Bases: TableParserMixin, XlsxTableReaderPort
Concrete xlsx reader \u2014 omniread xlsx parser + shared TableParserMixin.
Attributes:
Name Type Descriptionmax_header_scan int Max rows scanned for the header row.
"},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl.ImplXlsxTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/impl/#pipelines.extraction.xlsx.impl.ImplXlsxTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from xlsx content.
Parameters:
Name Type Description Defaultcontent Materialized content (Content, bytes, or dict).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"},{"location":"pipelines/extraction/xlsx/banks/","title":"Banks","text":"xlsx family \u2014 bank-specific ports and pipeline roots.
"},{"location":"pipelines/extraction/xlsx/banks/icici/","title":"Icici","text":""},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici","title":"pipelines.extraction.xlsx.banks.icici","text":""},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici--summary","title":"Summary","text":"Icici bank-specific port implementations (xlsx table path).
Faithful port of domain/extraction/banks/icici/xlsx.py: the xlsx reader uses the shared TableParserMixin (default icici aliases) over typed worksheet rows. Ordering/balance policy stays in the shared tabular txn_dicts stage.
Bases: ImplXlsxExtractionPipeline
Icici xlsx graph root \u2014 pins the Icici reader.
Attributes:
Name Type Descriptiontable_reader IciciXlsxTableReaderPort Icici xlsx reader stage.
"},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici.IciciXlsxExtractionPipeline-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici.IciciXlsxExtractionPipeline.run","title":"run","text":"run(source) -> List[Any]\nRun the direct-table extraction chain.
Parameters:
Name Type Description Defaultsource Raw extraction source.
requiredReturns:
Type DescriptionList[Any] List[Any]: Raw expense records.
"},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici.IciciXlsxTableReaderPort","title":"IciciXlsxTableReaderPort","text":" Bases: ImplXlsxTableReaderPort
Icici xlsx reader \u2014 inherits the default (icici) column aliases.
"},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici.IciciXlsxTableReaderPort-functions","title":"Functions","text":""},{"location":"pipelines/extraction/xlsx/banks/icici/#pipelines.extraction.xlsx.banks.icici.IciciXlsxTableReaderPort.read","title":"read","text":"read(content) -> List[dict]\nRead typed records from xlsx content.
Parameters:
Name Type Description Defaultcontent Materialized content (Content, bytes, or dict).
requiredReturns:
Type DescriptionList[dict] List[dict]: Typed table records.
"}]}