Publish to Hugging Face

The huggingface/ directory holds everything needed to publish vaak artefacts to the Hugging Face Hub:

huggingface/
  space/            Gradio app that wraps vaak for a hosted demo
  model_card/       README.md template for fine-tuned checkpoints
  publish.py        Uploads a model, a Space, or both

Prerequisites

pip install "vaak[whisper]" huggingface_hub gradio
huggingface-cli login

The token needs write access.

Publish a model

After fine-tuning with --merge, train/out/ holds the adapter (whisper-small-hi-lora) and the merged full model (whisper-small-hi-merged).

python huggingface/publish.py --adapter --merged --namespace <your-user>

The script:

1. Creates the repos if they do not exist (<your-user>/vaak-whisper-small-hi-lora and <your-user>/vaak-whisper-small-hi by default; override with --adapter-id and --merged-id).
2. Renders huggingface/model_card/README.md, filling in the base model, training data, hardware and the before/after WER and CER from train/out/eval.json. Placeholders that cannot be filled are printed so you can edit them by hand before publishing.
3. Uploads the weights, tokenizer, feature extractor and card.

The card template states that the model is a LoRA fine-tune of an upstream checkpoint and links to the upstream licence. Keep that; it is required by the Whisper licence terms and it is honest. Use --dry-run to see the rendered card and the planned actions without uploading.

Load it back:

vaak transcribe clip.mp3 --model hf-whisper:<your-user>/vaak-whisper-small-hi --language hi

Publish the demo Space

The Space in huggingface/space/ is a Gradio app with a file upload, a microphone input and a language dropdown. It calls faster-whisper directly (Whisper small, int8) so the free CPU tier builds in a minute without pulling the whole vaak package.

python huggingface/publish.py --space --namespace <your-user>

• The Space id defaults to <your-user>/vaak-demo; override with --space-id.
• Set VAAK_WHISPER_SIZE (tiny, base, small, medium, large-v3-turbo) and VAAK_COMPUTE_TYPE in the Space settings to change the model without editing code.
• huggingface/space/requirements.txt pins only gradio and faster-whisper. GPU tiers cost money per hour while the Space is awake, so set it to sleep after inactivity.

Publish everything

python huggingface/publish.py --all --namespace <your-user>

Checklist

• Model card says which upstream model and licence it derives from
• Benchmark rows in the card come from a bench/results/*.json file, not typed by hand
• Space model fits the chosen hardware
• Space is set to sleep after inactivity if it runs on paid hardware