I'm extracting a text-to-speech engine from an application into a reusable Python library. It depends on large model files—currently roughly 500 MB each, with additional voice and language models planned. In the original application, missing models were downloaded automatically on first use, but that behavior feels less appropriate for a library, especially in servers, containers, and offline environments.
Possible approaches include downloading models on first use, installing them through an optional package extra or post-install step, providing a separate command such as `pfspeak install`, requiring users to manage model files themselves, or exposing a configurable model-provider interface.
The goal is to keep normal framework integration simple, while still allowing users to choose model locations, control downloads and updates, support different language and voice combinations, and avoid unexpected network requests or hundreds of megabytes being pulled into a deployment. What design has worked best for libraries with similar large assets?
4 Answers
Treat the models as a separate dependency rather than silently downloading them as part of normal library usage. A good default is to look for models in a predictable location and raise a clear error if they are missing. Then provide a CLI for downloading or updating them, plus an optional install extra for users who want a bundled setup. Since the assets are large, users should be told about disk usage, licensing, and exactly what will be installed.
Optional dependency groups can work for small, fixed assets, but they may become awkward here. One TTS model can have dozens of voice weights, while speech recognition may need a separate model for every language, so users will want different combinations. Packaging every possible asset through the installer could make installations unnecessarily large.
I’d keep the core package lightweight, expose a separate asset-management tool or package, and let users declare which languages and voices they need. The runtime library can then accept a model directory, a manifest, or a provider and avoid making assumptions about how those files arrived there.
Make asset handling configurable through a public model-provider interface. The default provider could use local files and optionally support automatic downloads, but users should also be able to supply explicit paths or their own provider. This matters especially for containers and servers, where downloading 500 MB during startup is undesirable and model updates may need to be managed separately.
A practical precedence order could be explicit constructor arguments, project configuration, user-level configuration, environment-variable overrides, and finally a documented default directory. For example, `PfSpeak(models="auto")` could opt into downloads, while plain `PfSpeak()` only searches known locations and fails without network access. Explicit mappings could also allow each model to be assigned its own path.
That matches the direction I’m considering. The model provider or installation policy needs to be exposed through the public configuration instead of remaining an internal abstraction. A layered configuration system should also leave room for multilingual TTS and STT model combinations later.
Avoid automatic downloads by default. Libraries are often imported in environments with restricted network access, unexpected latency is hard to debug, and a background download can cause permissions or reproducibility problems. Automatic downloading can still be an explicit mode for convenient local experimentation, while production users get deterministic paths and an informative missing-model error.
That separation is increasingly appealing. The library could focus on consuming models, while another package handles downloading, updating, configuring, and discovering them.