Repos

repos

Repository pattern for mirumoji's database entities

Additional Information

• Each repository wraps an AsyncSession and exposes typed async operations that return Pydantic DTOs

• Mutating operations stage changes on the session and flush to populate server-side defaults (ids, timestamps)

• The surrounding UnitOfWork owns the commit/rollback boundary

• Failures raise domain exceptions (RecordNotFoundError, DatabaseError) that the server maps to HTTP responses

ClipRepository

Data access for Clip records

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

add(profile_id, file_id, start_time, end_time, llm_breakdown_response) async

Adds a clip record

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
file_id	UUID	Source file id	required
start_time	float	Clip start time in seconds	required
end_time	float	Clip end time in seconds	required
llm_breakdown_response	dict	Serialized breakdown payload	required

Returns:

Type	Description
ClipDTO	The created ClipDTO

Raises:

Type	Description
DatabaseError	If the insert fails

delete(clip_id) async

Deletes a clip record

Parameters:

Name	Type	Description	Default
clip_id	UUID	The clip id	required

Raises:

Type	Description
RecordNotFoundError	If the clip does not exist
DatabaseError	If the deletion fails

get(clip_id) async

Fetches a clip by id

Parameters:

Name	Type	Description	Default
clip_id	UUID	The clip id	required

Returns:

Type	Description
ClipDTO	The matching ClipDTO

Raises:

Type	Description
RecordNotFoundError	If the clip does not exist
DatabaseError	If the lookup fails

list_for_profile(profile_id, load_file=False) async

Lists all clips belonging to a profile

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
load_file	bool	Eagerly load the related file	False

Returns:

Type	Description
list[ClipDTO]	A list of ClipDTO, newest first

Raises:

Type	Description
DatabaseError	If the query fails

FileRepository

Data access for File records

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

add(profile_id, name, path, type=None, folder=None) async

Adds a file record

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
name	str	Base file name	required
path	str	Media-relative path to the file	required
type	str | None	Optional file-type tag	None
folder	str | None	Optional group label for files uploaded together	None

Returns:

Type	Description
FileDTO	The created FileDTO

Raises:

Type	Description
DatabaseError	If the insert fails

delete(file_id) async

Deletes a file record

Parameters:

Name	Type	Description	Default
file_id	UUID	The file id	required

Raises:

Type	Description
RecordNotFoundError	If the file does not exist
DatabaseError	If the deletion fails

get(file_id) async

Fetches a file by id

Parameters:

Name	Type	Description	Default
file_id	UUID	The file id	required

Returns:

Type	Description
FileDTO	The matching FileDTO

Raises:

Type	Description
RecordNotFoundError	If the file does not exist
DatabaseError	If the lookup fails

list_for_profile(profile_id) async

Lists all files belonging to a profile

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required

Returns:

Type	Description
list[FileDTO]	A list of FileDTO, newest first

Raises:

Type	Description
DatabaseError	If the query fails

JobRepository

Data access for Job records

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

add(profile_id, type, params, parent_id=None, total=1) async

Adds a queued job record

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
type	str	Operation type	required
params	dict	Submitted parameters (file references, options)	required
parent_id	UUID | None	Parent batch job id, if any	None
total	int	Number of work items (1 for a single job)	1

Returns:

Type	Description
JobDTO	The created JobDTO

Raises:

Type	Description
DatabaseError	If the insert fails

delete(job_id) async

Deletes a job (cascading to its children)

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required

Raises:

Type	Description
RecordNotFoundError	If the job does not exist
DatabaseError	If the deletion fails

find_referencing_file(profile_id, file_id) async

Finds the profile's top-level jobs that use or produced a file

A matching child resolves to its batch parent, so deleting the returned ids removes whole batches (children cascade via the parent FK)

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
file_id	UUID	The file id	required

Returns:

Type	Description
set[UUID]	The top-level job ids that reference the file

Raises:

Type	Description
DatabaseError	If the query fails

find_referencing_transcript(profile_id, transcript_id) async

Finds the profile's top-level jobs that produced a transcript

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
transcript_id	UUID	The transcript id	required

Returns:

Type	Description
set[UUID]	The top-level job ids that reference the transcript

Raises:

Type	Description
DatabaseError	If the query fails

get(job_id) async

Fetches a job by id

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required

Returns:

Type	Description
JobDTO	The matching JobDTO

Raises:

Type	Description
RecordNotFoundError	If the job does not exist
DatabaseError	If the lookup fails

list_children(parent_id) async

Lists the child jobs of a batch parent

Parameters:

Name	Type	Description	Default
parent_id	UUID	The parent job id	required

Returns:

Type	Description
list[JobDTO]	A list of child JobDTO, oldest first

Raises:

Type	Description
DatabaseError	If the query fails

list_for_profile(profile_id, active_only=False) async

Lists a profile's top-level jobs (batch children are excluded)

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
active_only	bool	Restrict to queued / running jobs	False

Returns:

Type	Description
list[JobDTO]	A list of top-level JobDTO, newest first

Raises:

Type	Description
DatabaseError	If the query fails

list_unfinished() async

Lists every queued / running job across all profiles

Used on startup to reconcile jobs left over from a previous run (the in-process queue does not survive a restart)

Returns:

Type	Description
list[JobDTO]	A list of unfinished JobDTO

Raises:

Type	Description
DatabaseError	If the query fails

update(job_id, *, status=None, progress=None, completed=None, result=None, error=None, error_code=None, error_details=None) async

Applies a partial update to a job (a None argument leaves the field unchanged)

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required
status	str | None	New status	None
progress	float | None	New progress fraction	None
completed	int | None	New completed-item count	None
result	dict | None	Produced references	None
error	str | None	Failure message	None
error_code	str | None	Stable error code	None
error_details	dict | None	Structured error context	None

Returns:

Type	Description
JobDTO	The updated JobDTO

Raises:

Type	Description
RecordNotFoundError	If the job does not exist
DatabaseError	If the update fails

LlmTemplateRepository

Data access for a profile's unique LlmTemplate

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

delete(profile_id) async

Deletes a profile's template

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required

Raises:

Type	Description
RecordNotFoundError	If the profile has no template
DatabaseError	If the deletion fails

get_for_profile(profile_id) async

Fetches the template for a profile, if any

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required

Returns:

Type	Description
LlmTemplateDTO | None	The LlmTemplateDTO, or None when the profile has no template

Raises:

Type	Description
DatabaseError	If the lookup fails

upsert(profile_id, sys_msg, prompt, model, srt_sys_msg='', srt_model='') async

Creates or updates the unique template for a profile

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
sys_msg	str	System message	required
prompt	str	Prompt template	required
model	str	Model selector in provider:model form	required
srt_sys_msg	str	Subtitle-fix system message (empty = default)	''
srt_model	str	Subtitle-fix model override (empty = use model)	''

Returns:

Type	Description
LlmTemplateDTO	The created or updated LlmTemplateDTO

Raises:

Type	Description
DatabaseError	If the operation fails

ProfileRepository

Data access for Profile records

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

delete(profile_id) async

Deletes a profile and cascades to its related records

Parameters:

Name	Type	Description	Default
profile_id	str	The profile id	required

Raises:

Type	Description
RecordNotFoundError	If the profile does not exist
DatabaseError	If the deletion fails

ensure(profile_id) async

Returns a profile, creating it if it doesn't exist

Parameters:

Name	Type	Description	Default
profile_id	str	The profile id	required

Returns:

Type	Description
ProfileDTO	The existing or newly-created ProfileDTO

Raises:

Type	Description
DatabaseError	If the operation fails

exists(profile_id) async

Checks whether a profile exists

Parameters:

Name	Type	Description	Default
profile_id	str	The profile id	required

Returns:

Type	Description
bool	True if the profile exists

Raises:

Type	Description
DatabaseError	If the lookup fails

get(profile_id) async

Fetches a profile by id

Parameters:

Name	Type	Description	Default
profile_id	str	The profile id	required

Returns:

Type	Description
ProfileDTO	The matching ProfileDTO

Raises:

Type	Description
RecordNotFoundError	If the profile does not exist
DatabaseError	If the lookup fails

TranscriptRepository

Data access for Transcript records

Attributes:

Name	Type	Description
session	AsyncSession	The active asynchronous database session

add(profile_id, file_id, text, llm_explanation=None) async

Adds a transcript record

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
file_id	UUID	Source file id	required
text	str	The transcription text	required
llm_explanation	str | None	Optional saved explanation	None

Returns:

Type	Description
TranscriptDTO	The created TranscriptDTO

Raises:

Type	Description
DatabaseError	If the insert fails

delete(transcript_id) async

Deletes a transcript record

Parameters:

Name	Type	Description	Default
transcript_id	UUID	The transcript id	required

Raises:

Type	Description
RecordNotFoundError	If the transcript does not exist
DatabaseError	If the deletion fails

get(transcript_id) async

Fetches a transcript by id

Parameters:

Name	Type	Description	Default
transcript_id	UUID	The transcript id	required

Returns:

Type	Description
TranscriptDTO	The matching TranscriptDTO

Raises:

Type	Description
RecordNotFoundError	If the transcript does not exist
DatabaseError	If the lookup fails

list_for_profile(profile_id, load_file=False) async

Lists all transcripts belonging to a profile

Parameters:

Name	Type	Description	Default
profile_id	str	Owning profile id	required
load_file	bool	Eagerly load the related file	False

Returns:

Type	Description
list[TranscriptDTO]	A list of TranscriptDTO, newest first

Raises:

Type	Description
DatabaseError	If the query fails