Skip to content

Local Models

Download the files of a local model once, pinned to their SHA-256, then build a provider config by the model's name with no network. Narrative guide: Local Models.

Listing, downloading and locating

list_local_models

list_local_models(kind=None)

The known local models; kind keeps those for one provider config.

kind is one of :data:KINDS: "sherpa-onnx-stt", "sherpa-onnx-tts", "sherpa-onnx-vad", "sherpa-onnx-denoiser" or "smart-turn".

Raises:

Type Description
ValueError

kind is not one of them.

download_local_model

download_local_model(model, models_dir=None)

Download a model's files unless they are already there; return its directory.

Blocking: it is a setup step (python -m roomkit.local_models download, a Dockerfile, a deploy script), not something to call from an event loop. Every file is checked against its pinned SHA-256, and the directory only ever appears complete.

Raises:

Type Description
ModelDownloadError

A file could not be fetched or did not match.

local_model_dir

local_model_dir(model, models_dir=None)

The directory of a downloaded model. Never touches the network.

Raises:

Type Description
ModelNotDownloadedError

The model is not downloaded, or an older version of its files is.

is_downloaded

is_downloaded(model, models_dir=None)

Whether the model's current files are in the models directory.

find_local_model

find_local_model(name, *, kind=None)

The local model called name; kind also requires its provider config.

Raises:

Type Description
ValueError

No model has that name, or it is for another provider config. The message lists the names that would fit.

default_models_dir

default_models_dir()

$ROOMKIT_MODELS_DIR, else $XDG_CACHE_HOME/roomkit/models.

local_model_config

local_model_config(name, *, kind, models_dir=None)

The config fields of a downloaded model: its settings, its file paths and, for a TTS model with named voices, voice_names.

What a provider config's from_local_model() builds itself from.

Configs built by name

FromLocalModel

Mixin for a provider config that a local model can fill in.

The config class names the kind of model it takes in local_model_kind.

from_local_model classmethod

from_local_model(name, *, models_dir=None, **overrides)

The config for a downloaded local model, by the model's name.

Reads no network. Download the model once beforehand with python -m roomkit.local_models download <name>.

Parameters:

Name Type Description Default
name str

The model (python -m roomkit.local_models list names them).

required
models_dir str | Path | None

Where models live; default $ROOMKIT_MODELS_DIR, else ~/.cache/roomkit/models.

None
**overrides Any

Any other field of the config (provider="cuda", num_threads=4); it wins over the model's own settings.

{}

Raises:

Type Description
ModelNotDownloadedError

The model is not downloaded; the message names the command that downloads it.

ValueError

No model has that name, or it is for another config.

Models

LocalModel dataclass

LocalModel(name, kind, description, size_mb, files, paths, settings=dict(), voices=())

A model RoomKit can download once and then run with no network.

Attributes:

Name Type Description
name str

The name the model is downloaded and configured by.

kind str

The provider config it is for ("sherpa-onnx-stt", "sherpa-onnx-tts", "sherpa-onnx-vad", "sherpa-onnx-denoiser", "smart-turn").

description str

One line: what the model does, its language and size.

size_mb int

Download size in megabytes, rounded.

files tuple[ModelFile, ...]

The files to download, each pinned to its SHA-256.

paths dict[str, str]

Config field -> path of the file inside the model's directory. A comma joins several paths for one field (a multi-lang Kokoro's lexicons).

settings dict[str, Any]

Other config fields this model needs (a mode, a model type, its sample rate).

voices tuple[str, ...]

Speaker names, in speaker-id order, for a TTS model with several voices.

ModelFile dataclass

ModelFile(url, sha256)

One file of a local model, pinned to its content.

Attributes:

Name Type Description
url str

Where the file is downloaded from; https:// only. A file whose name ends in .tar.bz2, .tar.gz, .tar.xz or .zip is extracted into the model's directory.

sha256 str

The file's SHA-256, lowercase hex. A download that does not match it is refused.

name property

name

The file's name, the last segment of its URL.

is_archive property

is_archive

Whether the file is extracted rather than kept as is.

Errors

ModelNotDownloadedError

Bases: FileNotFoundError

A local model was asked for and is not in the models directory.

ModelDownloadError

Bases: RuntimeError

A model file could not be fetched, or did not match its pinned SHA-256.