| # Build Small Hackathon — DOX |
|
|
| ## Purpose |
|
|
| Three Gradio apps targeting all tracks + maximum badges + sponsor prizes. Hack window: June 5–15, 2026. |
|
|
| ## Ownership |
|
|
| - **Name:** Build Small Hackathon 2026 — Team nbiish |
| - **Version:** 0.7.0 — Cedar-Copper Edition (Context-Aware LLM) |
| - **Operator:** nbiish |
|
|
| ## Local Contracts |
|
|
| ### Aesthetic |
|
|
| Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar → copper → sun-amber → birch-cream), biophilic motifs, sky-to-water gradient banners. Shared CSS variables live in `shared/cedar_copper_tokens.py`. |
|
|
| ### Rules — Naming & Comments |
|
|
| - Descriptive project names: CritterCalm, FocusFriend, TinyBard |
| - Docstrings on all public functions. Comments on non-obvious logic. |
|
|
| ### Rules — Always |
|
|
| - Models ≤ 32B total params per project |
| - Gradio app hosted as HF Space |
| - Local-first (no cloud APIs = Off the Grid badge) |
| - GGUF quantized models for local inference |
| - Python 3.10+ with pinned requirements |
| - Cedar-copper aesthetic consistency across all UIs (palette tokens in `shared/cedar_copper_tokens.py`) |
|
|
| ### Rules — Never |
|
|
| - Cloud API calls in production path |
| - Hardcoded secrets or API keys |
| - Models > 32B params |
| - Default Gradio look without customization attempt |
|
|
| ### Rules — If |
|
|
| - Custom frontend feasible → use `mount_gradio_app` for Off-Brand badge |
| - Model ≤ 4B → tag Tiny Titan eligible |
| - Using llama.cpp runtime → tag Llama Champion |
| - Fine-tuning done → publish model to HF Hub |
|
|
| ## Work Guidance |
|
|
| ### Gradio 6.0 + MCP Server |
|
|
| - `gradio.Server` is **NOT** in Gradio 6.0 stable. Use `mount_gradio_app(fastapi_app, blocks, path="/gradio")` instead. |
| - MCP server mode: `demo.launch(mcp_server=True)` or `GRADIO_MCP_SERVER=true` env var. |
| - Custom frontends: Serve static HTML/CSS/JS via FastAPI, mount Gradio at `/gradio` for API + MCP. |
| - `@gradio/client` CDN: `https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js` (ES module, use `type="module"`). |
| - Theme parameters: `css`, `head`, `theme` moved from `gr.Blocks(...)` to `app.launch(...)` in Gradio 6.0. |
| - Chatbot API: Gradio 6.0 requires `{"role": "user|assistant", "content": "..."}` dicts (not tuples). |
|
|
| ### HF Agents CLI |
|
|
| - `hf` CLI is installed (v1.18.0). See `skill://hf-cli` for full command reference. |
| - Install expert skills: `hf skills add --global` or `hf skills add --claude --global`. |
| - Spaces managed via: `hf repos create <name> --type space --space-sdk gradio --public`. |
| - Deploy: `git remote add hf https://huggingface.co/spaces/<user>/<space>` then `git push hf main`. |
| - HF README metadata: `colorTo` must be one of `[red, yellow, green, blue, indigo, purple, pink, gray]` (no `emerald`/`amber`). |
| - HF README metadata: `emoji` must match `/\p{Extended_Pictographic}/u` — only the standard emoji block is allowed. Use a real emoji. |
|
|
| ### Inference Architecture (v0.7+) |
|
|
| - **All LLM inference** via the **Hugging Face Inference API** (serverless). No local GGUF, no `llama-cpp-python` compile step. |
| - Shared module: `shared/inference_client.py` provides `cooldown_status()`, `cooldown_active()`, `generate()`, `chat_messages()`, and `force_clear_cooldown()`. |
| - **TinyBard model:** `meta-llama/Llama-3.2-1B-Instruct` via `featherless-ai` provider (only provider supporting this model). |
| - **Other projects:** `Qwen/Qwen2.5-1.5B-Instruct` (free tier, fast, well-suited to chat). Override via `INFERENCE_MODEL`. |
| - Per-project model override: `TINYBARD_MODEL`, `FOCUSFRIEND_MODEL`, `CRITTERCALM_MODEL`. |
| - **Provider override:** `INFERENCE_PROVIDER` (default: `featherless-ai` for TinyBard, auto for others). |
| - **Cooldowns** enforce a per-project minimum gap between inference calls (protects HF/Modal credit budget): |
| - `tinybard`: 6s |
| - `focusfriend`: 10s |
| - `crittercalm`: 12s |
| - Override via `TINYBARD_COOLDOWN_SECONDS`, etc., or global `INFERENCE_COOLDOWN_SECONDS`. |
| - **force_clear_cooldown()**: Clears cooldown before each function call — prevents cooldown from blocking story generation after choices. |
| - **Always-fallback:** every LLM call falls back to procedural / template output if inference fails or is in cooldown. No LLM call ever blocks the UX. |
| - HF Spaces are the dev/test environment — iterate live at `huggingface.co/spaces/nbiish/{tinybard,focusfriend,crittercalm}` rather than localhost. |
|
|
| ### Local Test Environment |
|
|
| - Python: miniconda3 (Python 3.12) |
| - Gradio: 6.0.0 |
| - `huggingface_hub` (for Inference API client) |
| - Inference is serverless — no local model files needed unless you opt in to local mode |
|
|
| ### Local Servers (optional) |
|
|
| - TinyBard: http://localhost:7861/ — FastAPI + Gradio Blocks — nbiish/tinybard |
| - FocusFriend: http://localhost:7862/ — Gradio 6.0 — nbiish/focusfriend |
| - CritterCalm: http://localhost:7863/ — Gradio 6.0 — nbiish/crittercalm |
|
|
| ### Short-term Goals |
|
|
| - Record demo videos (2-3 min each) — show unique story generation, verb-based choices, context-aware narrative |
| - Post to social media |
| - Write Field Notes blog posts (3 — one per project) |
| - Share agent traces for Sharing is Caring badge |
| - Polish UIs for demo appeal |
| - Test CritterCalm voice cloning end-to-end |
| - Test FocusFriend all 4 modes (Chat, Focus, Breathe, Meditate) with real model |
|
|
| ## Verification |
|
|
| - All 3 apps deployed to HF Spaces and accessible |
| - Cooldown system active in `shared/inference_client.py` |
| - Cedar-copper aesthetic consistent across all UIs |
| - No hardcoded secrets; no cloud API calls in production path |
|
|
| ### 1. CritterCalm (Backyard AI) |
|
|
| - **Status:** Code complete. Deployed. HF Inference API + cooldowns wired for script generation. OmniVoice voice cloning still requires local install. |
| - **Stack:** OmniVoice (0.6B, local optional) + Kokoro TTS (82M, local optional) + Qwen2.5-7B (default) via HF Inference API |
| - **Badges:** Off the Grid, Well-Tuned (TBD), Field Notes, Off-Brand |
| - **GitHub:** github.com/nbiish/crittercalm |
| - **HF Space:** huggingface.co/spaces/nbiish/crittercalm |
| - **Standalone repo:** /Volumes/1tb-sandisk/code-external/crittercalm-repo |
|
|
| ### 2. FocusFriend (Thousand Token Wood) |
|
|
| - **Status:** Code complete. Deployed. HF Inference API + cooldowns wired. Gradio 6 Chatbot dict-format fixed. |
| - **Stack:** Qwen2.5-7B (default) via HF Inference API |
| - **Badges:** Off-Brand (sun-amber custom theme), Field Notes, Cooldowns badge |
| - **GitHub:** github.com/nbiish/focusfriend |
| - **HF Space:** huggingface.co/spaces/nbiish/focusfriend |
| - **Standalone repo:** /Volumes/1tb-sandisk/code-external/focusfriend-repo |
|
|
| ### 3. TinyBard (Thousand Token Wood + Tiny Titan + Llama Champion) |
|
|
| - **Status:** COMPLETE. Deployed. Context-aware LLM generation verified live. |
| - **Concept:** ≤4B LLM generates unique interactive text adventures in a CRT terminal aesthetic. Nanaboozhoo trickster narrator. |
| - **Stack:** Llama-3.2-1B-Instruct via HF Inference API (featherless-ai provider) + procedural fallback engine |
| - **Features Implemented:** |
| - **Context-aware story generation**: Last 3 story steps feed into next generation for narrative continuity |
| - **Verb-based action choices**: Always 3 action-oriented choices (not descriptive noun phrases) |
| - **LLM-rated health decisions**: LLM evaluates risk (-15/0/+10), falls back to random.choice |
| - **Player choice integration**: Selected choice text feeds into next story + health evaluation |
| - **Robust choice parsing**: 3 strategies (pipe, newline, comma) + bare-line format + fallback padding |
| - **Always returns 3 choices**: `_parse_choices` pads with procedural fallbacks if LLM returns <3 |
| - **Unique every time**: Temperature 0.6, max_new_tokens 150 — never repeats |
| - **Nanaboozhoo narrator**: Trickster/transformer voice in all LLM prompts |
| - **Game loop verified**: Start → LLM story → select choice → Make Choice → LLM advances story → 3 new choices |
| - **HF Space:** https://nbiish-tinybard.hf.space (RUNNING, SHA: 94d7081) |
| - **Provider:** featherless-ai (only provider supporting Llama-3.2-1B-Instruct) |
| - **Environment Variables:** INFERENCE_MODEL=meta-llama/Llama-3.2-1B-Instruct, INFERENCE_PROVIDER=featherless-ai |
|
|
| ## TODO |
|
|
| ### In Progress |
|
|
| - [ ] Test CritterCalm voice cloning pipeline end-to-end |
| - [ ] Test FocusFriend all 4 modes (Chat, Focus, Breathe, Meditate) with real model |
| - [ ] Record demo videos (2-3 min each) |
| - [ ] Post to social media |
| - [ ] Write Field Notes blog posts (3 — one per project) |
| - [ ] Share agent traces to HF Hub (Sharing is Caring badge) |
|
|
| ### Completed |
|
|
| - [x] CritterCalm v1 code complete (11 files) — Cedar-copper UI |
| - [x] FocusFriend v1 code complete (16 files) — Cedar-copper UI + Gradio 6 dict Chatbot |
| - [x] TinyBard v1 code complete (8 files) — LLM + procedural fallback, CRT UI, clean FastAPI JSON |
| - [x] GitHub repos created (nbiish/crittercalm, nbiish/focusfriend, nbiish/tinybard) |
| - [x] HF Spaces created and deployed (all 3) |
| - [x] Monorepo structure with projects/ directory + shared/ aesthetic module |
| - [x] INTELLIGENCE.md — full hackathon landscape analysis |
| - [x] SUBMISSION_DRAFTS.md — social posts + Field Notes drafts |
| - [x] HF CLI installed + skills configured |
| - [x] llama-cpp-python installed — for reference; v0.5+ uses HF Inference API |
| - [x] Local verification: all 3 apps run on ports 7861/7862/7863 |
| - [x] TinyBard end-to-end game loop verified (start → choose → next scene) |
| - [x] FocusFriend chat verified (user message → Pip reply) |
| - [x] CritterCalm UI navigation verified (all 3 tabs render) |
| - [x] **v0.5: HF Inference API wired into all 3 apps** (no local GGUF, no build step) |
| - [x] **v0.5: Cooldown system** in `shared/inference_client.py` to protect HF/Modal credit budget |
| - [x] **v0.5: TinyBard local test** — procedural fallback works when no HF_TOKEN; cooldown UI shows in footer |
| - [x] **v0.6: TinyBard context-aware generation** — last 3 story steps feed into next generation |
| - [x] **v0.6: Verb-based action choices** — always 3 action-oriented choices (not descriptive noun phrases) |
| - [x] **v0.6: LLM-rated health decisions** — LLM evaluates risk (-15/0/+10) |
| - [x] **v0.6: Player choice integration** — selected choice text feeds into next story + health evaluation |
| - [x] **v0.6: Robust choice parsing** — 3 strategies (pipe, newline, comma) + bare-line format + fallback padding |
| - [x] **v0.6: Nanaboozhoo narrator** — trickster/transformer voice in all LLM prompts |
| - [x] **v0.6: featherless-ai provider** — only provider supporting Llama-3.2-1B-Instruct |
| - [x] **v0.7: Game loop verified live** — Start → LLM story → select choice → Make Choice → LLM advances story → 3 new choices |
| - [x] **v0.7: Git workflow** — worktree isolation, develop→main merge, HF Space deployment |
| - [x] **v0.7: Stale worktrees/branches cleaned up** — all merged branches deleted |
|
|
| ## Anishinaabe Solarpunk Aesthetic |
|
|
| All three apps share a unified visual language rooted in Anishinaabe culture. |
|
|
| ### Visual Identity |
|
|
| - **Palette:** sky-to-sunrise — water-blue (`#1B4965`) → cedar-bark (`#3D2A2A`) → copper (`#8B3A1F`) → sun-amber (`#F2A93B`) → birch-cream (`#F5F1E8`) |
| - **Syllabics:** Canadian Aboriginal ᐴ / ᔔ used as section framings |
| - **Symbols:** sun · clover · florette · circuit diamonds |
| - **Typography:** EB Garamond serif headers + Inter sans + JetBrains Mono for terminal/UI |
| - **CRT Terminal:** Scanline effects, phosphor glow, monospace terminal for TinyBard |
|
|
| ### Cultural Elements |
|
|
| - **Nanaboozhoo narrator**: Trickster/transformer voice in all TinyBard LLM prompts |
| - **Anishinaabemowin labels**: NOOSISKAAZOWIN (Health), DIBIK (Step), AADIZOOKAAN (Story), INAABANDA'IWIN (Choose) |
| - **Biophilic motifs**: Cedar bark textures, birch cream backgrounds, water-blue accents |
| - **Solarpunk optimism**: Technology in harmony with nature, not against it |
|
|
| ### Implementation |
|
|
| - **Tokens module:** `shared/cedar_copper_tokens.py` — CSS variables, color palette, typography |
| - **TinyBard CRT:** Custom CSS with scanline animation, phosphor glow, terminal green accents |
| - **Shared across apps**: Consistent section framings, button styles, card layouts |
|
|
| ## Reference |
|
|
| - CritterCalm: projects/crittercalm/ + github.com/nbiish/crittercalm |
| - FocusFriend: projects/focusfriend/ + github.com/nbiish/focusfriend |
| - TinyBard: projects/tinybard/ + github.com/nbiish/tinybard |
| - Aesthetic module: shared/cedar_copper_tokens.py |
| - Inference client: shared/inference_client.py |
| - ML Intern: github.com/huggingface/ml-intern |
| - HF Agents CLI: huggingface.co/docs/hub/en/agents-cli |
| - Gradio MCP: gradio.app/guides/model-context-protocol |
| - TinyBard HF Space: https://nbiish-tinybard.hf.space |
| - TinyBard App: projects/tinybard/app.py (FastAPI + Gradio + game logic) |
| - TinyBard Key Functions: `_run_turn`, `_llm_health_delta`, `generate_llm_story`, `generate_llm_choices`, `_parse_messages`, `_parse_choices`, `_fallback_choices` |
| - TinyBard Provider: featherless-ai (only provider supporting Llama-3.2-1B-Instruct) |
| - TinyBard Working URL: https://router.huggingface.co/featherless-ai/v1/chat/completions |
|
|
| ## Child DOX Index |
|
|
| - `projects/llms.txt` — Three hackathon Gradio apps (CritterCalm, FocusFriend, TinyBard) |
| - `projects/crittercalm/llms.txt` — Backyard AI pet calming app |
| - `projects/focusfriend/llms.txt` — Focus and mindfulness companion |
| - `projects/tinybard/llms.txt` — Interactive text adventure generator |
| - `shared/llms.txt` — Shared inference client and cedar-copper aesthetic tokens |
|
|
