Envfile

envfile

Defines functions to read, edit, and write a .env configuration file for an end-user

The .env file is stored in the application's data directory in the user's machine and is used to start the Mirumoji Docker Compose application with the configuration that was selected by the user via the launcher. It is also used to perist that information for future runs

delete_value(path, key)

Removes a single key from the .env file, preserving the others

Parameters:

Name	Type	Description	Default
path	Path	The .env file to update	required
key	str	The variable name to remove	required

Returns:

Type	Description
bool	True when the key was present and removed, False otherwise

host_config(env)

Resolves the Modal-host reservations (CPU, memory, concurrency) with their managed-config defaults

Every defaulted MODAL_HOST_VARS entry is included so each sizing key is always present in the deploy

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The resolved managed configuration values	required

Returns:

Type	Description
dict[str, str]	Each defaulted host sizing variable and its value

import_file(source, target)

Merges an external .env file into the managed config file

Reads the managed target, overrides its values with the values present in source (keys absent from source are kept), and writes the merged result back to target

Parameters:

Name	Type	Description	Default
source	Path	The external .env file to import	required
target	Path	The managed config file to overwrite	required

Returns:

Type	Description
dict[str, str]	The merged values now persisted in target

Raises:

Type	Description
EnvConfigError	If source does not exist or cannot be read

missing_required(specs, values)

Returns the required environment variables that still have no value set

Checks the EnvVar.required attribute to check if the environment variable is required and appends it to a list if it doesn't contain a value in values

Parameters:

Name	Type	Description	Default
specs	Iterable[EnvVar]	The environment variables to check	required
values	Mapping[str, str]	The currently resolved values	required

Returns:

Type	Description
list[EnvVar]	The required environment variables with no non-empty values

overlay_environ(values, names)

Merges the environment variables stored in values with the ones set in the current proccess' context (accessed via os.environ) if they're listed in names

For each named variable not already set in values, adds a non-empty value from os.environ if present. The values in values take precedence when a named variable is present both in values and os.environ. Empty string values are considered as not set

Example

values = {"VAR_0": "0", "VAR_1": "V1A", "VAR_2": "V2"}
names = ["VAR_1", "VAR_2", "VAR_3"]

# os.environ = {"VAR_1": "V1B", "VAR_3": "V3"}

merged = overlay_environ(values, names)
print(merged)

# {"VAR_0": "0", "VAR_1": "V1A", "VAR_2": "V2", "VAR_3": "V3"}

Parameters:

Name	Type	Description	Default
values	Mapping[str, str]	The values read from the .env file	required
names	Iterable[str]	The variable names to consider	required

Returns:

Type	Description
dict[str, str]	A new dict combining the file values and any environment fallbacks

read(path)

Reads a .env file into a dict, ignoring blank/unset entries

Parameters:

Name	Type	Description	Default
path	Path	The .env file path	required

Returns:

Type	Description
dict[str, str]	The parsed key/value pairs, or an empty dict when the file is absent

read_deployment(env)

Parses the persisted deployment choice from the resolved values of a managed config file

Missing or unrecognised values return None so that callers can fall back to a flag or a built-in default

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The resolved environment values	required

Returns:

Type	Description
tuple[Backend | None, ImageSource | None]	The persisted (backend, source), each None when absent/invalid

resolve_backend(flag, env_path)

Resolves which transcription backend to use

Order of Precedence

• The explicit flag override, when provided

• The persisted MIRUMOJI_TRANSCRIBE_BACKEND

• The default (MODAL)

Parameters:

Name	Type	Description	Default
flag	Backend | None	An explicit backend override, or None to fall back to the config	required
env_path	Path	The managed config file to fall back to	required

Returns:

Type	Description
Backend	The backend to use

resolve_host_nonpreemptible(env_path, flag=None)

Reports whether the CPU host runs on non-preemptible capacity

Order of Precedence

• The explicit flag override, when provided

• The persisted MIRUMOJI_HOST_NONPREEMPTIBLE, overlaid with the process environment

• The default (False)

Parameters:

Name	Type	Description	Default
env_path	Path	The managed config file to read	required
flag	bool | None	An explicit override, or None to resolve from the config	None

Returns:

Type	Description
bool	True when the CPU host should run on non-preemptible capacity

resolve_host_on_gpu(env_path, flag=None)

Reports whether the host runs on a GPU instead of offloading to the worker

Order of Precedence

• The explicit flag override, when provided

• The persisted MIRUMOJI_HOST_ON_GPU, overlaid with the process environment

• The default (False)

A CPU host (the toggle unset or 0) offloads transcription to the separate worker, so this returns False

Parameters:

Name	Type	Description	Default
env_path	Path	The managed config file to read	required
flag	bool | None	An explicit override, or None to resolve from the config	None

Returns:

Type	Description
bool	True when the host should run on a GPU with the in-process backend

resolve_image_version(env_path, flag=None)

Resolves the published image version the launcher pulls and composes with

Order of Precedence

The value is considered in the following order

• The explicit flag override, when provided

• The persisted MIRUMOJI_IMAGE_VERSION, overlaid with the process environment

• The installed package version

Parameters:

Name	Type	Description	Default
env_path	Path	The managed config file to read	required
flag	str | None	An explicit version override, or None to fall back to the config	None

Returns:

Type	Description
str	The version that fills the {version} in the image references

resolve_managed_config(env_path)

Resolves the managed config, overlaying it with the process environment

Reads the managed .env, overlays the process environment (see overlay_environ), and keeps only the non-empty managed config keys

Usage

Both the CLI and the GUI build the configuration injected into a Modal-hosted container (and the Modal credentials the deploy authenticates with) from this, so they always agree

Parameters:

Name	Type	Description	Default
env_path	Path	The managed config file to read	required

Returns:

Type	Description
dict[str, str]	The resolved non-empty managed configuration values

resolve_source(flag, env_path)

Resolves which image source to use

Order of Precedence

• The explicit flag override, when provided

• The persisted MIRUMOJI_IMAGE_SOURCE

• The default (PULL)

Parameters:

Name	Type	Description	Default
flag	bool | None	True to build, False to pull, or None to fall back to the config	required
env_path	Path	The managed config file to fall back to	required

Returns:

Type	Description
ImageSource	The image source to use

set_value(path, key, value)

Upserts a single key into the .env file, preserving the others

Parameters:

Name	Type	Description	Default
path	Path	The .env file to update	required
key	str	The variable name to set	required
value	str	The value to write	required

write(path, values)

Writes resolved values to a .env file, skipping blanks

Parameters:

Name	Type	Description	Default
path	Path	The .env file path to write to	required
values	Mapping[str, str]	The values to persist	required