DEVELOPER.md

Developer Guide

This documents how local development differs from running on the Hugging Face Space, since a few things (persistent storage, secrets) work differently in each environment.

Provider API tokens (BYOK)

• Every provider is bring-your-own-key: each user pastes their own API key(s) into the UI. Keys are persisted in the browser's localStorage and sent to the server only transiently, as part of each generation request - they are never read from the server environment and never written to disk by this app.
• Each ModelProvider in providers.py declares its own api_token_env (just a label identifying which key it needs, e.g. FAL_KEY or REPLICATE_API_TOKEN - not an actual env var read at runtime). app.py derives one key input field per distinct api_token_env automatically (TOKEN_ENVS in app.py), so adding a new provider with a new api_token_env adds its input field with no other UI changes needed. Providers that share an api_token_env (e.g. the two fal.ai providers both use FAL_KEY) share one input field.
• .env / load_dotenv() still exist for non-provider local config (e.g. LOG_LEVEL), but no longer carry provider API keys.
• Some providers need more than just a key - e.g. Azure resources are deployed per-user, so Sora-2-on-Azure also needs the user's own resource endpoint URL. Declare these via ModelProvider.extra_config_envs (a tuple of label names, analogous to api_token_env); app.py derives one plain (non-password) text input per distinct name automatically (EXTRA_CONFIG_ENVS), rendered in the same BYOK section and persisted the same way. Read a value back inside a provider's call function with provider.extra_config("NAME").

Persistent storage (/data)

• On the Space: /data is the mounted persistent storage directory (if enabled for the Space). Runs (input image + per-provider output videos + runs.json history index) are written there and survive restarts.
• Locally: /data is normally not writable/creatable on a developer machine (e.g. macOS blocks writing to /data at the OS level). runs.ensure_data_dirs() detects this and falls back to a ./data directory next to the project files instead. This fallback dir is gitignored.
• You don't need to do anything to trigger the fallback - it happens automatically the first time ensure_data_dirs() fails to create /data.

Running locally

pip install -r requirements.txt
python app.py

Then open the printed local URL (e.g. http://127.0.0.1:7860).

Adding a new model provider

Add a ModelProvider(...) entry to PROVIDERS in providers.py. Reuse fal_queue_call if the new model is also on fal.ai, replicate_call if it's on Replicate, veo_call if it's a Veo model on the Gemini API, or write a new call function matching the signature (provider, image_path) -> bytes for providers with a different API contract (see generic_sync_call and polling_call for templates of direct-response vs. job-polling contracts). No subclassing is needed - the call field is what makes this duck-typed. Give the provider an api_token_env label (new or reused) - the UI picks up a BYOK input field for it automatically. If the provider needs more than a key (e.g. a per-resource endpoint URL), also set extra_config_envs - see sora-2-azure for an example.