Utilities

anki_utils

This module defines the AnkiExporter class for creating an Anki deck from the user's saved clips using genanki

Attributes:

Name	Type	Description
LOGGER	Logger	Module's logger.
VIDEO_CSS	str	Pre-defined CSS of the cards
CARD_TEMPLATE	list	Pre-defined template of the cards for genanki
MODEL_FIELDS	list	Pre-defined card model fields.
MODEL_NAME	str	Pre-defined standard deck name.

AnkiExporter

Exports saved clips as an Anki Deck.

Parameters:

Name	Type	Description	Default
model_name	str	Model name for genanki	MODEL_NAME
deck_name	str	Deck name for genanki	MODEL_NAME + ' Deck'
model_fields	list	Model fields for genanki	MODEL_FIELDS
css	str	Card CSS for genanki	VIDEO_CSS
card_template	list	Card template for genanki.	CARD_TEMPLATE

add_card(clip_path, word, meanings, sentence, explanation, tags=None)

Add one card to the deck, clip_path will be bundled as media.

Parameters:

Name	Type	Description	Default
clip_path	str	Path to the clip	required
word	str	Card word	required
meanings	str	Word meanings in string form.	required
sentence	str	Sentence the word came from.	required
explanation	str	GPT explanation of the sentence.	required
tags	list	Optional card tags.	None

export(output_path)

Write .apkg (deck + all media) to output_path.

Parameters:

Name	Type	Description	Default
output_path	str	Path to save the Anki Deck.	required

id_from_string(s) staticmethod

Create a unique anki deck ID from string

Parameters:

Name	Type	Description	Default
s	str	String to create ID from	required

Returns:

Name	Type	Description
int	int	ID generated using hashlib.

env_utils

This module defines helper functions for environment management.

Attributes:

Name	Type	Description
LOGGER	Logger	Module's logger.

check_env(expected, input, dotenv_path=None)

Check if environment variables are available.

Parameters:

Name	Type	Description	Default
expected	list	List of expected environment variables.	required
input	dict	Dictionary with custom valued variables which don't need to be present in environment	required
dotenv_path	str	Optional custom path to look for .env file.	None

Raises:

Type	Description
ValueError	If a variable cannot be found.

Returns:

Name	Type	Description
dict	Dict	Dictionary with all checked variables.

using_modal()

Checks if MODAL_TOKEN_ID and MODAL_TOKEN_SECRET variables are present in the environment

Returns:

Name	Type	Description
bool	bool	True if variables are present, false otherwise.

logging_utils

This module defines a helper function for configuring the backend's logging.

TqdmStreamHandler

Bases: StreamHandler

Handler for displaying tqdm progress bars with python logging

setup_logging()

Configure the root logger to include custom formatting and handlers

srt_utils

This module defines helper functions for SRT manipulation.

Attributes:

Name	Type	Description
LOGGER	Logger	Logger's Module

format_time(seconds)

Format seconds into SRT timestamp format.

Parameters:

Name	Type	Description	Default
seconds	float	The time to format in seconds.	required

Returns:

Name	Type	Description
str	str	Formatted time in the format HH:MM:SS,mmm.

generate_srt(result, srt_path)

Generate an SRT file from Whisper transcription result.

Parameters:

Name	Type	Description	Default
result	dict	The result object from FasterWhisper's transcribe function.	required
srt_path	str	Path to save the SRT file.	required

Returns:

Name	Type	Description
str	str	The Path where the file was saved from srt_path

system_info_utils

This module defines helper functions for colleting information about the system running the program.

get_system_info()

Collects basic information about the system running the program.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dict with information about the system.

gpu_available()

Check if there's a GPU available in the machine running the program.

Returns:

Type	Description
Dict[str, Union[bool, str]]	Dict[str, Union[bool, str]: Dict with keys "available" and "name".

stream_utils

This module defines helper functions for handling streaming responses for fastapi's endpoints.

Attributes:

Name	Type	Description
LOGGER	Logger	Module's logger object.

sse_gen(version, system_message, prompt)

Stream reply from a GptModel object OpenAI API call.

Parameters:

Name	Type	Description	Default
version	str	The OpenAI GPT model version to use.	required
system_message	str	The system message to use for the model.	required
prompt	str	User prompt for the model.	required

Yields:

Name	Type	Description
str	str	The text chunks from the reply.

stream_response_with_task(path, task_func, filename, media_type=None, keepalive_interval=20.0)

Streams a long‐running task’s output file over HTTP without timing out by running task_func in a background thread while yielding a space every keepalive_interval seconds to keep proxies alive.

Parameters:

Name	Type	Description	Default
path	Path	The path to the function's resulting file.	required
task_func	Callable[[], None]	The function which generates the file.	required
filename	str	Filename to pass to response header.	required
media_type	str	Optional media type to pass to response header.	None
keepalive_interval	float	Interval between spaces yielded in seconds.	20.0

Returns:

Name	Type	Description
StreamingReponse	StreamingResponse	Once the task is done, streams the file at path in 8k chunks.

file_utils

This module provides helper functions for file operations and a class for handling file operations within the media_files directory

MediaFileHandler

Handles file and path manipulations within the media_files directory.

Attributes:

Name	Type	Description
project_root	Path	The root directory of the project.
base_path	Path	The absolute local path to media_files.
temp_path	Path	The absolute local path to 'media_files/temp'.
profiles_path	Path	The absolute local path to 'media_files/profiles'
modal_media_path	Path	The relative path to 'media_files' in Modal

clean_temp(check=False) async

Tries to delete all files in temp folder and recreate it

Parameters:

Name	Type	Description	Default
check	bool	If True raise errors if directory couldn't be deleted, otherwise skip. Defaults to False	False

Raises:

Type	Description
OSError	If check=True and there's an error deleting the directory

copy_file(src, dest_relative) async

Copies a file to a destination relative to the media base.

Parameters:

Name	Type	Description	Default
src	Union[str, Path]	The absolute source path of the file to copy.	required
dest_relative	Union[str, Path]	The destination path, relative to the media directory.	required

Returns:

Name	Type	Description
Path	Path	The absolute path to the new file.

delete_dir(dir_path_relative) async

Deletes a directory located relative to the media base.

Parameters:

Name	Type	Description	Default
dir_path_relative	Union[str, Path]	The path of the directory to delete, relative to the media directory.	required

Raises:

Type	Description
OSError	If the directory cannot be deleted.

delete_file(file_path_relative, check=False) async

Deletes a single file located relative to the media base.

Parameters:

Name	Type	Description	Default
file_path_relative	Union[str, Path]	The path of the file to delete, relative to the media directory.	required
check	bool	If True, raise error on failure, otherwise skip. Defaults to False	False

Raises: OSError: If the file cannot be deleted and check=True

get_modal_path(local_path)

Converts an absolute local path to a Modal-compatible relative path.

Parameters:

Name	Type	Description	Default
local_path	Union[str, Path]	An absolute local path.	required

Returns:

Name	Type	Description
Path	Path	A path relative to the project root, suitable for Modal.

get_profile_dir(profile_id, subfolder)

Gets or creates a profile-specific subdirectory.

Parameters:

Name	Type	Description	Default
profile_id	str	The ID of the profile.	required
subfolder	str	The name of the subfolder within the profile directory.	required

Returns:

Name	Type	Description
Path	Path	The absolute path to the profile-specific subdirectory.

get_relative_path(full_path)

Resolves a path relative to the media directory.

Parameters:

Name	Type	Description	Default
full_path	Union[str, Path]	An absolute path to a file or directory.	required

Returns:

Name	Type	Description
Path	Path	The path relative to the media directory.

get_temp_dir(name)

Creates and returns a path to a named directory inside temp.

Parameters:

Name	Type	Description	Default
name	str	The name of the temporary directory.	required

Returns:

Name	Type	Description
Path	Path	The absolute path to the created temporary directory.

move_file(src, dest_relative) async

Moves a file from a source path to a destination relative to the media base.

Parameters:

Name	Type	Description	Default
src	Union[str, Path]	The absolute source path of the file to move.	required
dest_relative	Union[str, Path]	The destination path, relative to the media directory.	required

Returns:

Name	Type	Description
Path	Path	The absolute path to the moved file.

write_file(file_path_relative, content) async

Writes text content to a file, creating directories if necessary.

Parameters:

Name	Type	Description	Default
file_path_relative	Union[str, Path]	The path of the file to write to, relative to the media directory.	required
content	str	The string content to write to the file.	required

Returns:

Name	Type	Description
Path	Path	The absolute path to the written file.

Raises:

Type	Description
IOError	If there is an error writing the file.

get_stream_file(request, upload_id=Header(..., alias='X-Upload-ID'), file_name=Header(..., alias='X-File-Name')) async

Endpoint dependency to save a streamed file to local storage

Parameters:

Name	Type	Description	Default
request	Request	FastAPI Request object.	required
upload_id	str	Header sent from frontend with upload id	Header(..., alias='X-Upload-ID')
file_name	str	Header sent from frontend with file name	Header(..., alias='X-File-Name')

Returns:

Name	Type	Description
Path	Path	Path where the file was saved

Raises:

Type	Description
HTTPException	If upload fails or headers are not present

save_upload_file(request, dest, tqdm_description=None) async

Saves a FastAPI.Request.stream by reading and writing streamed chunks to dest and displaying a TQDM progress bar in logging.

Parameters:

Name	Type	Description	Default
request	UploadFile	FastAPI Request object.	required
dest	Path	The path where the file will be saved.	required
tqdm_description	str	Description of the progress bar in logging. Defaults to None	None

Raises:

Type	Description
Exception	If the upload fails for any reason.

constants

This module defines constant and environemnt variables that are used throughout the application for consistency.