Openapi

interfaces.openapi

Summary

All handler functions — 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.

Classes

AccountCrudsService

AccountCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[Account, AccountDocument]

Account CRUD service resolving :class:Account documents from a repo.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

EntityCrudsService

EntityCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[Entity, EntityDocument]

Entity CRUD service resolving :class:Entity documents from a repo.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

ExpenseCrudsService

ExpenseCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[Expense, ExpenseDocument]

Expense CRUD service resolving :class:Expense documents from a repo.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

FetchRequestCrudsService

FetchRequestCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[FetchRequest, FetchRequestDocument]

CRUD service for fetch requests with pipeline stage helpers.

Attributes:

Name	Type	Description
model	FetchRequest	Domain model class.
schema	FetchRequestDocument	Persistence document class.

Initialize the adaptor with a backing repository.

Parameters:

Name	Type	Description	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

save_enrichment async

save_enrichment(
    id: PyObjectId, enrichment_dicts: list
) -> None

Persist the enriched expense dicts on the request source.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Fetch request id.	required
enrichment_dicts	list	Enriched expense dicts.	required

Returns:

Name	Type	Description
None	None	Nothing.

save_raw_lines async

save_raw_lines(id: PyObjectId, raw_lines: list) -> None

Persist the extracted raw lines on the request source.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Fetch request id.	required
raw_lines	list	Raw OCR/text lines.	required

Returns:

Name	Type	Description
None	None	Nothing.

save_txn_blocks async

save_txn_blocks(id: PyObjectId, txn_blocks: dict) -> None

Persist the extracted transaction blocks on the request source.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Fetch request id.	required
txn_blocks	dict	Transaction blocks keyed by order id.	required

Returns:

Name	Type	Description
None	None	Nothing.

save_txn_dicts async

save_txn_dicts(
    id: PyObjectId, txn_dicts: list, txn_dicts_count: int
) -> None

Persist the parsed transaction dicts and count on the request source.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Fetch request id.	required
txn_dicts	list	Raw expense dicts.	required
txn_dicts_count	int	Number of parsed transaction dicts.	required

Returns:

Name	Type	Description
None	None	Nothing.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

update_status async

update_status(
    id: PyObjectId,
    status: str,
    error_message: Optional[str] = None,
    retry_count: Optional[int] = None,
) -> bool

Update the request status, optionally carrying failure detail.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Fetch request id.	required
status	str	New status value.	required
error_message	Optional[str]	Message recorded when failing.	None
retry_count	Optional[int]	Retry counter recorded when failing.	None

Returns:

Name	Type	Description
bool	bool	True when a document was patched.

Raises:

Type	Description
ValueError	If status == "failed" and either error_message or retry_count is None.

ReportQuery

Bases: BaseModel

Definition of a report snapshot. Bounds the data set; dimensions are sliced at read time.

Attributes:

Name	Type	Description
name	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.

ReportService

ReportService(
    expense_svc: ExpenseCrudsService,
    tag_svc: TagCrudsService,
    store: ReportStore,
    report_repo=None,
)

Build, persist, and serve precomputed report snapshots.

Notes

Instances 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	Default
expense_svc	ExpenseCrudsService	Expense CRUD service used as the cube source.	required
tag_svc	TagCrudsService	Tag CRUD service used to expand tag hierarchies and resolve ignore tags.	required
store	ReportStore	Key-value store for cube period data.	required
report_repo	Any	Report snapshot repository; defaults to :func:create_report_repo when omitted.	None

Functions

delete_snapshot async

delete_snapshot(report_id: str) -> bool

Delete a snapshot and all of its cube keys from the store.

Parameters:

Name	Type	Description	Default
report_id	str	Snapshot ID to delete.	required

Returns:

Name	Type	Description
bool	bool	True when the snapshot existed and was deleted.

fetch_report async

fetch_report(
    report_id: str,
    granularities: Optional[List[str]] = None,
    period_ids: Optional[List[str]] = None,
    flow: str = "outflows",
    payees: Optional[List[str]] = None,
    tags: Optional[List[str]] = None,
) -> Optional[Report]

Slice 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	Default
report_id	str	Snapshot ID to slice.	required
granularities	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	Description
Optional[Report]	Optional[Report]: The sliced report view, or None when the snapshot does not exist.

generate_snapshot async

generate_snapshot(
    query: ReportQuery,
) -> ReportSnapshotDocument

Validate 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	Default
query	ReportQuery	Raw snapshot definition.	required

Returns:

Name	Type	Description
ReportSnapshotDocument	ReportSnapshotDocument	The existing or newly created snapshot.

list_snapshots async

list_snapshots(
    offset: int = 0, limit: int = DEFAULT_LIMIT
) -> List[ReportSnapshotDocument]

List stored snapshots, newest first.

Parameters:

Name	Type	Description	Default
offset	int	Number of snapshots to skip.	0
limit	int	Maximum number of snapshots to return.	DEFAULT_LIMIT

Returns:

Type	Description
List[ReportSnapshotDocument]	List[ReportSnapshotDocument]: Snapshots ordered by creation time, newest first.

TagCrudsService

TagCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[Tag, TagDocument]

Tag CRUD service resolving :class:Tag documents from a repo.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

get_by_names async

get_by_names(names: list[str])

Return tags whose names match any of the provided values.

Parameters:

Name	Type	Description	Default
names	list[str]	Tag names to look up.	required

Returns:

Name	Type	Description
list		Matching tag documents.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

UploadCrudsService

UploadCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[UploadResult, UploadResultDocument]

Upload result CRUD service resolving :class:UploadResult documents.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

UploadResult

Bases: BaseModel

Metadata describing a stored file upload.

Attributes:

Name	Type	Description
original_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.

UserCrudsService

UserCrudsService(*, repo=None)

Bases: CrudsServiceAdaptor[User, UserDocument]

User CRUD service resolving :class:User documents from a repo.

Notes

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	Default
repo	BaseRepository	Repository used for all operations.	None

Functions

create async

create(data: Model | dict) -> Schema

Create a document from a model or raw mapping.

Parameters:

Name	Type	Description	Default
data	Model | dict	Model instance or field mapping to persist.	required

Returns:

Name	Type	Description
Schema	Schema	Persisted document.

delete async

delete(id: PyObjectId) -> bool

Delete a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Name	Type	Description
bool	bool	True when a document was deleted.

model_to_dict staticmethod

model_to_dict(model_obj: Model) -> dict

Serialize a model into a sparse dictionary.

Parameters:

Name	Type	Description	Default
model_obj	Model	Model instance to serialize.	required

Returns:

Name	Type	Description
dict	dict	Fields that are set and not None.

patch async

patch(id: PyObjectId, data: dict) -> Schema | None

Partially update a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	dict	Fields to patch.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

read async

read(id: PyObjectId) -> Schema | None

Read a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required

Returns:

Type	Description
Schema | None	Schema | None: Matching document, or None when absent.

search async

search(
    filter: dict | None = None, *args, **kwargs
) -> list[Schema]

List documents matching an optional filter.

Parameters:

Name	Type	Description	Default
filter	dict | None	Query filter passed to the repository.	None

Returns:

Type	Description
list[Schema]	list[Schema]: Matching documents.

Notes

Extra positional and keyword arguments are forwarded to the repository.

update async

update(id: PyObjectId, data: Model | dict) -> Schema | None

Replace a document by primary key.

Parameters:

Name	Type	Description	Default
id	PyObjectId	Document identifier.	required
data	Model | dict	Replacement model or field mapping.	required

Returns:

Type	Description
Schema | None	Schema | None: Updated document, or None when absent.

Functions

cache_response

cache_response(ttl: Optional[int] = None) -> Callable

Decorate a GET-style route handler to cache its JSON response.

Parameters:

Name	Type	Description	Default
ttl	Optional[int]	Cache lifetime in seconds; defaults to settings.cache_ttl.	None

Returns:

Name	Type	Description
Callable	Callable	Decorator that wraps the route handler.

Notes

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

create_account async

create_account(request: Request, body: dict)

Create a new account.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Account payload forwarded to the service.	required

Returns:

Name	Type	Description
AccountDocument		The created account.

create_entity async

create_entity(request: Request, body: dict)

Create a new entity.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Entity payload forwarded to the service.	required

Returns:

Name	Type	Description
EntityDocument		The created entity.

create_expense async

create_expense(request: Request, body: dict)

Create a new expense.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Expense payload forwarded to the service.	required

Returns:

Name	Type	Description
ExpenseDocument		The created expense.

create_fetch_request async

create_fetch_request(request: Request, body: dict)

Create 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Fetch request payload forwarded to the service.	required

Returns:

Name	Type	Description
FetchRequestDocument		The created fetch request.

create_report async

create_report(request: Request, body: dict)

Generate a report snapshot from a query definition.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Report query payload; validated into a ReportQuery.	required

Returns:

Name	Type	Description
ReportSnapshotDocument		The generated snapshot.

Raises:

Type	Description
HTTPException	400 when the query payload is invalid.

create_tag async

create_tag(request: Request, body: dict)

Create a new tag.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	Tag payload forwarded to the service.	required

Returns:

Name	Type	Description
TagDocument		The created tag.

create_user async

create_user(request: Request, body: dict)

Create a new user.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
body	dict	User payload forwarded to the service.	required

Returns:

Name	Type	Description
UserDocument		The created user.

delete_account async

delete_account(request: Request, id: str)

Delete an account by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Account id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when no account matches the id.

delete_entity async

delete_entity(request: Request, id: str)

Delete an entity by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Entity id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when no entity matches the id.

delete_expense async

delete_expense(request: Request, id: str)

Delete an expense by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Expense id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when no expense matches the id.

delete_fetch_request async

delete_fetch_request(request: Request, id: str)

Delete 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when no fetch request matches the id.

delete_report async

delete_report(request: Request, id: str)

Delete a report snapshot by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Report snapshot id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when the snapshot does not exist.

delete_tag async

delete_tag(request: Request, id: str)

Delete a tag by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Tag id.	required

Returns:

Name	Type	Description
Response		Empty 204 response on successful delete.

Raises:

Type	Description
HTTPException	404 when no tag matches the id.

get_account async

get_account(request: Request, id: str)

Get an account by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Account id.	required

Returns:

Name	Type	Description
AccountDocument		The matching account.

Raises:

Type	Description
HTTPException	404 when no account matches the id.

get_current_user async

get_current_user(request: Request)

Get 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	Default
request	Request	Incoming HTTP request; carries the authenticated user and app.state.db_resources.	required

Returns:

Name	Type	Description
UserDocument		The current user's profile.

Raises:

Type	Description
HTTPException	401 when the request is not authenticated.

get_entity async

get_entity(request: Request, id: str)

Get an entity by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Entity id.	required

Returns:

Name	Type	Description
EntityDocument		The matching entity.

Raises:

Type	Description
HTTPException	404 when no entity matches the id.

get_expense async

get_expense(request: Request, id: str)

Get an expense by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Expense id.	required

Returns:

Name	Type	Description
ExpenseDocument		The matching expense.

Raises:

Type	Description
HTTPException	404 when no expense matches the id.

get_fetch_request async

get_fetch_request(request: Request, id: str)

Get a fetch request by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required

Returns:

Name	Type	Description
FetchRequestDocument		The matching fetch request.

Raises:

Type	Description
HTTPException	404 when no fetch request matches the id.

get_report async

get_report(
    request: Request,
    id: str,
    granularity: Optional[List[str]] = Query(None),
    period_ids: Optional[List[str]] = Query(None),
    flow: str = "outflows",
    payee: Optional[List[str]] = Query(None),
    tags: Optional[List[str]] = Query(None),
)

Fetch a report snapshot with optional granularity, flow, and filter overrides.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Report snapshot id.	required
granularity	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	Description
Report		The fetched report.

Raises:

Type	Description
HTTPException	400 when the report arguments are invalid.
HTTPException	404 when the snapshot does not exist.

get_tag async

get_tag(request: Request, id: str)

Get a tag by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Tag id.	required

Returns:

Name	Type	Description
TagDocument		The matching tag.

Raises:

Type	Description
HTTPException	404 when no tag matches the id.

get_uploaded_file async

get_uploaded_file(request: Request, filepath: str)

Serve an uploaded file from disk.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request.	required
filepath	str	Relative path of the file under UPLOAD_DIR.	required

Returns:

Name	Type	Description
FileResponse		The requested file with its original filename.

Raises:

Type	Description
HTTPException	404 when the file does not exist.

get_user async

get_user(request: Request, id: str)

Get a user by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	User id.	required

Returns:

Name	Type	Description
UserDocument		The matching user.

Raises:

Type	Description
HTTPException	404 when no user matches the id.

list_accounts async

list_accounts(
    request: Request, skip: int = 0, limit: int = 100
)

List accounts with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
skip	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	Description
	list[AccountDocument]: Matching accounts from AccountCrudsService.search.

list_ambiguities async

list_ambiguities(request: Request, id: str)

List pending ambiguities for a fetch request.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required

Returns:

Name	Type	Description
list		Pending ambiguity documents from the ambiguity service.

list_entities async

list_entities(
    request: Request, skip: int = 0, limit: int = 100
)

List entities with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
skip	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	Description
	list[EntityDocument]: Matching entities from EntityCrudsService.search.

list_expenses async

list_expenses(
    request: Request,
    offset: int = 0,
    limit: int = 10,
    start_date: str = "",
    end_date: str = "",
)

List 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
offset	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	Description
	list[ExpenseDocument]: Matching expenses from ExpenseCrudsService.search.

list_fetch_requests async

list_fetch_requests(
    request: Request, offset: int = 0, limit: int = 100
)

List fetch requests with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
offset	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	Description
	list[FetchRequestDocument]: Matching fetch requests from the service.

list_reports async

list_reports(
    request: Request, offset: int = 0, limit: int = 100
)

List report snapshots with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
offset	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	Description
	list[ReportSnapshotDocument]: Matching snapshots from the report service.

list_tags async

list_tags(
    request: Request, skip: int = 0, limit: int = 1000
)

List tags with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
skip	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	Description
	list[TagDocument]: Matching tags from TagCrudsService.search.

list_uploads async

list_uploads(request: Request)

List all upload records.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required

Returns:

Type	Description
	list[UploadDocument]: All uploads from the upload service.

list_users async

list_users(
    request: Request, skip: int = 0, limit: int = 100
)

List users with pagination.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
skip	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	Description
	list[UserDocument]: Matching users from UserCrudsService.search.

resolve_ambiguity async

resolve_ambiguity(request: Request, id: str, body: dict)

Resolve 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Ambiguity id.	required
body	dict	Resolution payload; must contain the chosen candidate.	required

Returns:

Type	Description
	Updated ambiguity document.

Raises:

Type	Description
HTTPException	400 when the chosen candidate is missing.
HTTPException	404 when the ambiguity is not found.

stream_fetch_events async

stream_fetch_events(request: Request, id: str)

Stream 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required

Returns:

Type	Description
	StreamingResponse | dict: SSE stream, or {"events": []} when the bus
	is unavailable.

update_account async

update_account(request: Request, id: str, body: dict)

Update an account by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Account id.	required
body	dict	Fields to update, forwarded to the service.	required

Returns:

Name	Type	Description
AccountDocument		The updated account.

Raises:

Type	Description
HTTPException	404 when no account matches the id.

update_current_user async

update_current_user(request: Request, body: dict)

Update the profile of the authenticated user.

Creates the profile on first access, then applies the update payload.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries the authenticated user and app.state.db_resources.	required
body	dict	Fields to update on the current user's profile.	required

Returns:

Name	Type	Description
UserDocument		The updated profile.

Raises:

Type	Description
HTTPException	401 when the request is not authenticated.

update_entity async

update_entity(request: Request, id: str, body: dict)

Update an entity by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Entity id.	required
body	dict	Fields to update, forwarded to the service.	required

Returns:

Name	Type	Description
EntityDocument		The updated entity.

Raises:

Type	Description
HTTPException	404 when no entity matches the id.

update_expense async

update_expense(request: Request, id: str, body: dict)

Update an expense by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Expense id.	required
body	dict	Fields to update, forwarded to the service.	required

Returns:

Name	Type	Description
ExpenseDocument		The updated expense.

Raises:

Type	Description
HTTPException	404 when no expense matches the id.

update_fetch_request async

update_fetch_request(request: Request, id: str, body: dict)

Patch 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required
body	dict	Payload with status, error_message, and retry_count fields.	required

Returns:

Name	Type	Description
FetchRequestDocument		The refreshed fetch request.

Raises:

Type	Description
HTTPException	404 when no fetch request matches the id.

update_fetch_request_put async

update_fetch_request_put(
    request: Request, id: str, body: dict
)

Replace a fetch request by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Fetch request id.	required
body	dict	Full fetch request payload forwarded to the service.	required

Returns:

Name	Type	Description
FetchRequestDocument		The updated fetch request.

Raises:

Type	Description
HTTPException	404 when no fetch request matches the id.

update_tag async

update_tag(request: Request, id: str, body: dict)

Update a tag by id.

Parameters:

Name	Type	Description	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Tag id.	required
body	dict	Fields to update, forwarded to the service.	required

Returns:

Name	Type	Description
TagDocument		The updated tag.

Raises:

Type	Description
HTTPException	404 when no tag matches the id.

upload_entity_logo async

upload_entity_logo(
    request: Request, id: str, file: UploadFile
)

Upload 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	Default
request	Request	Incoming HTTP request; carries app.state.db_resources.	required
id	str	Entity id.	required
file	UploadFile	Uploaded logo image.	required

Returns:

Name	Type	Description
dict		A mapping with keys id, url, logo, and status.

Raises:

Type	Description
HTTPException	404 when no entity matches the id.

upload_file async

upload_file(request: Request)

Upload 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	Default
request	Request	Incoming HTTP request; carries the body, content type, and app.state.db_resources.	required

Returns:

Name	Type	Description
UploadDocument		The created upload record.