HACKATHON-CONTEXT.md

# Build Small Hackathon — Full Context (Hugging Face × Gradio)

> Verified from the official field guide + live org scan. Shared reference for this project.
> **No deadlines/timelines recorded here by design** — sequence work by dependency, not calendar.

## The premise
A return to **small, local, tinkerable** open-weight models — everything **under 32B parameters**,
running on hardware you own. "Less API bill, more workshop."

## Two tracks (equal prize pools, pick one per app)
- **🏡 Backyard AI (practical):** *"Practical, problem-solving apps built to improve daily life — for you or someone close to you. Useful things that run on hardware you own."* (storybook generator, study tutor, receipt/bill parser, on-device doc assistant)
- **🍄 An Adventure in Thousand Token Wood (whimsical):** *"Whimsical, delightful, AI-native apps that push the boundaries of fun."* AI must be **load-bearing**, not a build helper. (interactive games, entertainment tools, desktop pet, text-adventure DM)

## Entry criteria
- **REQ-01 — Under 32B:** every model your project depends on must be <32B **total** params (not just active). Combine several freely; each must individually stay under the cap.
- **REQ-02 — Ship a Gradio app** in the official `build-small-hackathon` HF org (Docker fine if the interface is a Gradio Space).
- **REQ-03 — Record a demo video** showing the app working (judges fall back to it if GPU/API limits block a live run — treat it as the primary judged artifact).
- **REQ-04 — Post on social**, link it from the README.
- **REQ-05 — GPU limit:** submit as many apps as you like; if relying on free ZeroGPU, max 10 ZeroGPU apps/user (Modal credits or consumer HW otherwise).
- **REQ-06 — Tag your README** frontmatter for the tracks + badges you want considered, plus a short write-up of the idea & tech. (No single canonical tag spelling is enforced; the wild uses several variants — include both hyphen and space forms.)

## Prize table — $48k cash + 20k Modal credits + 2× RTX 5080 + ChatGPT Pro (29 ways to win)
### General track prizes — awarded PER TRACK (Backyard **and** Wood each):
| Place | Prize |
|---|---|
| 1st | $4,000 |
| 2nd | $2,500 |
| 3rd | $1,500 |
| 4th | $1,000 |
| Community Choice (by likes) | $2,000 |

### Sponsor prizes (own criteria):
- **⚙️ Best Use of Modal** — **1st 10,000 / 2nd 7,000 / 3rd 3,000 CREDITS** ($20k total). *"Use Modal for the development or runtime of your app, and note it in your Space README. Judged on best use of the platform. Inference, fine-tuning, batch jobs and sandboxes all count."*
- **🧠 Best MiniCPM Build (OpenBMB)** — **$2,500 / $1,500 / $1,000 PER TRACK** ($5k per track, $10k total). Build with MiniCPM models; Vision (MiniCPM-V) & omni (MiniCPM-o) variants qualify.
- **💻 Best Use of Codex (OpenAI)** — $5,000 / $3,000 / $1,000 ($10k). Requires **Codex-attributed commits** in the connected repo/Space.
- **🟩 Nemotron Hardware Prize (NVIDIA)** — **2× RTX 5080**: one "best space" (NVIDIA-judged on merit), one "community engagement" (likes). Build with Nemotron models.

### Bonus badges:
- **Off Brand $1,500** — best custom UI beyond default Gradio (*"gr.Server is your friend"*).
- **Tiny Titan $1,500** — best app on a genuinely tiny model; **ALL models ≤4B**.
- **Best Demo $1,000** — best full package: app + demo video + social post.
- **Best Agent $1,000** — best agentic app (multi-step tool use + planning, <32B).
- **Bonus Quest Champion $2,000** — most bonus criteria met across the board.
- **Judges' Wildcard $1,000** — amazing but fits no category (every submission auto-entered; no action).

### Rules that matter
- **Awards stack** — one app can win a track placement + sponsor prizes + bonus badges simultaneously.
- **Multiple submissions allowed**, each judged independently.
- Sponsor models must form a **core part of the experience** (you may also use other providers' models under the cap).
- Some prizes require running locally to be eligible; hosted sponsor APIs exist for dev.

## Sponsor models & platforms (verified)
- **OpenBMB / MiniCPM** (free hosted API + local via llama.cpp/transformers):
  - `MiniCPM-V-4.6` (1.3B) — vision/OCR/document understanding. Class `AutoModelForImageTextToText` + `AutoProcessor`; `transformers[torch]>=5.7` (+ `av` for video, avoids torchcodec/CUDA issues). Starter Space to fork: `openbmb/MiniCPM-V-4.6-Demo` (gr.Server).
  - `MiniCPM-o-4_5` (9.4B) — full-duplex omni (voice/vision/language in, speech out). `AutoModel` + `trust_remote_code`; `model.chat(msgs=..., use_tts_template=, enable_thinking=, generate_audio=)` — content as a list, **no tokenizer arg**.
  - `MiniCPM5-1B` (1.08B, llama arch) — text gen, tool-calling, on-device. `AutoModelForCausalLM`.
  - `MiniCPM4.1-8B` — text reasoning.
  - `VoxCPM2` (2B) — TTS, 48kHz, **PyTorch ≥2.5.0**. Voice Design `(description)text` (no ref); Controllable Cloning `generate(text="(style)text", reference_wav_path=...)`; Ultimate Cloning adds `prompt_wav_path`+`prompt_text`. Style varies run-to-run (gen 1–3×).
- **NVIDIA / Nemotron 3** family: Nano (30B MoE reasoning), Nano-4B (edge), Nano-Omni (multimodal), **ASR** (`nemotron-speech-streaming-en-0.6b` [kit-recommended] or `nemotron-3.5-asr-streaming-0.6b` [multilingual]), **Parse** (`NVIDIA-Nemotron-Parse-v1.2`, sub-1B doc extraction: tables/math/handwriting/figures/layout), Embed-VL.
- **Modal** (serverless GPU): inference, **fine-tuning** (`hp_sweep_gpt`: 8 SLMs in parallel; `fine-tuning-embeddings`; Ramp case study — parallel fine-tune, 79% cost cut), **batch** (`spawn_map`, 1M jobs/1 line, scale-to-zero), **sandboxes** (run untrusted/LLM-generated code — flagship pattern: `examples/agent`, `safe_code_execution`; the GRPO example notes the *Best Use of Modal prize "showcased sandboxes for securely evaluating model-generated code"*). Memory snapshots, Volumes, scheduled jobs.
- **Black Forest Labs** FLUX.2 Klein (4B/9B image); **JetBrains** Mellum 2 (12B MoE code); **Cohere** Transcribe (ASR) + Tiny Aya.

## Submission process
Join the org → upload the Gradio Space → record a demo video (host on YouTube/Space/public) → one social post → update README with links + frontmatter tags + a short write-up. Submit when ready.

## This portfolio's Modal strategy (context for both apps)
Two apps, both engineered to be **1st-caliber for Best Use of Modal**, on **different flagship axes** so they don't cannibalize the single top slot:
- **WitnessBox** — Axis A: **Sandbox runs model-generated code** (the pattern Modal's prize "showcased").
- **Tiny Foundry** — Axis B: **massive elastic parallel scale** (dozens of GPU containers at once; Modal Batch's core identity).
Goal: maximize P(winning 1st) + a real shot at a **1st + 2nd sweep**. Awards stack, so each also pursues OpenBMB / Tiny Titan / Well-Tuned / track placements as secondary.