# 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