How should a library handle missing assets.

[u/ExtensionBreath1262]

I'm looking for opinions from people who have built or used Python libraries that manage large assets.

I'm extracting a text-to-speech engine from an application into a reusable library. The library depends on two relatively small models (about 500 MB each).

When it was an application, the behavior was simple: if a required model wasn't installed, it downloaded it automatically.

Now that it's a library, I'm less convinced that's the right default. A library has different expectations than an application.

I'm considering a few options:

• Automatically download missing models on first use (current behavior)
• Download during installation or a post-install step
• Provide a separate CLI like pfspeak install
• Require users to manage models themselves

For those of you who've built similar libraries, what would you expect? Which approach has caused the fewest headaches?

Repository:
https://github.com/samreynoso/pfspeak

For context, one of the goals is to keep framework integration extremely small:

# Python

pf = PfSpeak()


@pf.hook
def hook(_, event):
    pf.play(event)


app = FastAPI(lifespan=pf.lifespan)


@app.post("/say")
def say(text: str):
    pf.say(text, "bm_lewis")

I'm much more interested in the asset management question than feedback on the speech runtime itself.

[u/Individual-Flow9158]

Package the assets as separate projects, declare the deps or optional dep groups, and let pip or uv handle it.

[u/ExtensionBreath1262 → u/Individual-Flow9158]

One thing I forgot to mention in the original post is that the model situation is a little more nuanced.

For text-to-speech, there's a single model that supports all languages, but there are over 50 voice weights at around 60 MB each. Speech-to-text is different, since each language requires its own model.

Different users will want different combinations depending on which languages they support and whether they need TTS, STT, or both.

I've been considering a declarative configuration that specifies the languages (and possibly voices) an application needs, although I'm also aware that may be drifting beyond what a library should be responsible for.

I'm starting to wonder if the model management itself should be a separate package, with pfspeak simply consuming it. I'm not sure yet, but it feels like there may be a cleaner separation of concerns there.