Models

models

Defines the database models and data transfer objects

Defines the schema for the miurmoji database and pydantic DTOs for all tables. DTOs share a common base pydantic model to handle instantiation directly from ORM objects without running into async lazy-loading errors

Base

Bases: DeclarativeBase

Base class for all SQLAlchemy declarative models

Inherits from SQLAlchemy's DeclarativeBase to provide a unified metadata registry for the mirumoji's ORM models

Clip

Bases: Base

SQLAlchemy model representing a clip tied to a profile and a file

Attributes:

Name	Type	Description
id	UUID	Clip identifier (primary key)
profile_id	str	Owning profile id (foreign key, cascade delete)
profile	Profile	The owning profile relationship
file_id	UUID	Source file id (foreign key, cascade delete)
file	File	The source file relationship
start_time	float	Clip start time in seconds
end_time	float	Clip end time in seconds
llm_breakdown_response	dict	Serialized breakdown payload
created_at	datetime	UTC creation timestamp

ClipDTO

Bases: SafeORMModel

Represents a single profile clip reference saved in the mirumoji database

Attributes:

Name	Type	Description
id	UUID	Clip identifier
profile_id	str	Owning profile id
profile	ProfileDTO | None	Owning profile, when loaded
file_id	UUID	Source file id
file	FileDTO | None	Source file, when loaded
start_time	float	Clip start time in seconds
end_time	float	Clip end time in seconds
llm_breakdown_response	dict	Serialized breakdown payload
created_at	datetime	UTC creation timestamp

File

Bases: Base

SQLAlchemy model representing a single file tied to a profile

Attributes:

Name	Type	Description
id	UUID	File identifier (primary key)
profile_id	str	Owning profile id (foreign key, cascade delete)
profile	Profile	The owning profile relationship
name	str	Base file name
path	str	Media-relative path to the file
type	str | None	Optional file-type tag
folder	str | None	Optional group label for files uploaded together (e.g. a picked directory's name), used to group the file list
created_at	datetime	UTC creation timestamp

FileDTO

Bases: SafeORMModel

Represents a single profile file reference stored in the mirumoji database

Attributes:

Name	Type	Description
id	UUID	File identifier
profile_id	str	Owning profile id
profile	ProfileDTO | None	Owning profile, when loaded
name	str	Base file name
path	str	Media-relative path to the file
type	str | None	Optional file-type tag
folder	str | None	Optional group label for files uploaded together
created_at	datetime	UTC creation timestamp

Job

Bases: Base

SQLAlchemy model representing a long-running processing job

Mirumoji Server Jobs

• A job runs one operation (transcription, SRT generation, conversion, or LLM SRT-fixing) server-side using an existing profile file, so that the client can submit it and track it across navigation

• A batch is a parent job with one child job per file (parent_id), and the parent aggregates total / completed

Attributes:

Name	Type	Description
id	UUID	Job identifier (primary key)
profile_id	str	Owning profile id (foreign key, cascade delete)
profile	Profile	The owning profile relationship
parent_id	UUID | None	Parent batch job id, when this is a child
type	str	Operation type (e.g. transcribe, generate_srt, convert, fix_srt, or a batch_* variant)
status	str	queued, running, succeeded, failed, or cancelled
progress	float	Progress fraction in [0, 1]
total	int	Number of work items (1 for a single job, N for a batch)
completed	int	Number of finished work items
params	dict	Submitted parameters (file references, options)
result	dict | None	Produced references (file / transcript / SRT ids) or None until finished
error	str | None	Failure message when status is failed
error_code	str | None	Stable error code on failure (the domain exception's code, or ServerError for an unexpected failure)
error_details	dict | None	Optional structured error context
created_at	datetime	UTC creation timestamp
updated_at	datetime	UTC last-update timestamp

JobDTO

Bases: SafeORMModel

Represents a single processing job stored in the mirumoji database

Attributes:

Name	Type	Description
id	UUID	Job identifier
profile_id	str	Owning profile id
profile	ProfileDTO | None	Owning profile, when loaded
parent_id	UUID | None	Parent batch job id, when this is a child
type	str	Operation type
status	str	queued, running, succeeded, failed, or cancelled
progress	float	Progress fraction in [0, 1]
total	int	Number of work items
completed	int	Number of finished work items
params	dict	Submitted parameters
result	dict | None	Produced references, or None until finished
error	str | None	Failure message when status is failed
error_code	str | None	Stable error code on failure
error_details	dict | None	Optional structured error context
created_at	datetime	UTC creation timestamp
updated_at	datetime	UTC last-update timestamp

LlmTemplate

Bases: Base

SQLAlchemy model representing a profile's unique LLM template

Attributes:

Name	Type	Description
id	UUID	Template identifier (primary key)
profile_id	str	Owning profile id (foreign key, unique, cascade delete)
profile	Profile	The owning profile relationship
sys_msg	str	System message
prompt	str	Prompt template
model	str	Model selector in provider:model form
srt_sys_msg	str	Subtitle-fix system message (empty = default)
srt_model	str	Subtitle-fix model override (empty = use model)

LlmTemplateDTO

Bases: SafeORMModel

Represents a profile's LLM template stored in the mirumoji database

Attributes:

Name	Type	Description
id	UUID	Template identifier
profile_id	str	Owning profile id
profile	ProfileDTO | None	Owning profile, when loaded
sys_msg	str	System message
prompt	str	Prompt template
model	str	Model selector in provider:model form
srt_sys_msg	str	Subtitle-fix system message (empty = default)
srt_model	str	Subtitle-fix model override (empty = use model)

Profile

Bases: Base

SQLAlchemy model representing a mirumoji profile

Attributes:

Name	Type	Description
id	str	Client-supplied profile identifier (primary key)
created_at	datetime	UTC creation timestamp

ProfileDTO

Bases: SafeORMModel

Represents a single profile stored in the mirumoji database

Attributes:

Name	Type	Description
id	str	Profile identifier
created_at	datetime	UTC creation timestamp

SafeORMModel

Bases: BaseModel

Pydantic base for ORM-backed DTOs that tolerates unloaded relationships

Validates directly from SQLAlchemy instances (from_attributes), but first replaces any relationship field that wasn't eagerly loaded with None instead of triggering a lazy load, which would fail under async

check_sqlalchemy_state(data) classmethod

Builds a validation-safe mapping from a SQLAlchemy instance

Maps unloaded relationship fields to None so that validation never triggers an async-unsafe lazy load. Inputs that aren't SQLAlchemy instances are returned unchanged

Parameters:

Name	Type	Description	Default
data	Any	The value being validated (ORM instance or mapping)	required

Returns:

Type	Description
Any	A mapping safe for Pydantic validation, or data unchanged when it isn't a SQLAlchemy instance

Transcript

Bases: Base

SQLAlchemy model representing a transcript tied to a profile and a file

Attributes:

Name	Type	Description
id	UUID	Transcript identifier (primary key)
profile_id	str	Owning profile id (foreign key, cascade delete)
profile	Profile	The owning profile relationship
file_id	UUID	Source file id (foreign key, cascade delete)
file	File	The source file relationship
text	str	The transcription text
llm_explanation	str | None	Optional saved LLM explanation
created_at	datetime	UTC creation timestamp

TranscriptDTO

Bases: SafeORMModel

Represents a single profile transcript stored in the mirumoji database

Attributes:

Name	Type	Description
id	UUID	Transcript identifier
profile_id	str	Owning profile id
profile	ProfileDTO | None	Owning profile, when loaded
file_id	UUID	Source file id
file	FileDTO | None	Source file, when loaded
text	str	The transcription text
llm_explanation	str | None	Optional saved LLM explanation
created_at	datetime	UTC creation timestamp

get_now_utc()

Generates the current datetime in UTC

Returns:

Type	Description
datetime	The current UTC time