Spaces:
Sleeping
Sleeping
| title: ᐴ TinyBard ᔔ | |
| emoji: ☀️ | |
| colorFrom: blue | |
| colorTo: yellow | |
| sdk: gradio | |
| sdk_version: 6.0.0 | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| tags: | |
| - text-adventure | |
| - interactive-fiction | |
| - thousand-token-wood | |
| - build-small-hackathon | |
| - tiny-titan | |
| - off-brand | |
| - mcp-server | |
| - anishinaabe | |
| - solarpunk | |
| - inference-api | |
| - cooldowns | |
| # ◈──◆──◇ ᐴ TINYBARD ᔔ AADIZOOKAAN-AKINOOMAAGEWIN / STORY-TELLING ENGINE ◇──◆──◈ | |
| > **A small LLM fires five-minute interactive text adventures in a cedar-and-copper CRT terminal.** | |
| > | |
| > ᐴ The land remembers the stories. ᔔ ☼ ☘ ≈ | |
| TinyBard uses FastAPI + `mount_gradio_app` (Gradio 6.0) with a fully custom HTML/CSS/JS frontend, **MCP server mode** enabled, and an **HF Inference API** backend. Every adventure is procedurally generated — rooms, NPCs, items, and branching narratives on the fly. | |
| ## ◆ GASHKITOONAN / CAPABILITIES ◈ | |
| - **◇ Dynamic Adventures ◇** — LLM generates unique story beats for every playthrough | |
| - **◇ Three Aadizookaanan / Genres ◇** — Aadizookaan (Fantasy), Ish piming (Sci-Fi), Mashkodewaazibi (Cyberpunk) | |
| - **◇ Misko-Aki / CRT Terminal ◇** — Cedar-copper cabinet, sun-amber phosphor, frost-on-glass scanlines | |
| - **◇ MCP Kinoomaagewinan / Tools ◇** — `start_game` and `make_choice` exposed as MCP tools | |
| - **◇ Giiwenaabik / Inference API ◇** — Serverless HF Inference API; no local GGUF, no build step | |
| - **◇ Asabiikesiwin / Cooldown ◇** — 6s default between inference calls to protect your credit budget | |
| - **◇ Bmaad-ziibi / Procedural Fallback ◇** — Full engine works without the LLM | |
| - **◇ Anishinaabe-Solarpunk ◇** — Sky-to-sunrise palette, syllabic framings, biophilic motifs | |
| ## ☼ NITAM-AABAJICHIGANAN / PREREQUISITES ◈ | |
| - Python 3.10+ | |
| - A Hugging Face token (for the Inference API; many small models work anonymously) | |
| - ~100MB disk, ~256MB RAM — the model is serverless, not local | |
| ## ◇ AABAJITOOWINAN / INSTALLATION ◈ | |
| ```bash | |
| git clone https://github.com/nbiish/tinybard.git | |
| cd tinybard | |
| pip install -r requirements.txt | |
| # Optional: pick a model (default: Qwen/Qwen2.5-1.5B-Instruct — small + fast + free) | |
| export INFERENCE_MODEL="Qwen/Qwen2.5-1.5B-Instruct" | |
| # Or for the originally-intended VibeThinker 1.5B: | |
| # export INFERENCE_MODEL="mradermacher/VibeThinker-1.5B-GGUF" | |
| # Optional: set the HF token (anonymous works for many models) | |
| export HF_TOKEN="hf_..." | |
| # Optional: tune the cooldown | |
| export TINYBARD_COOLDOWN_SECONDS=6 | |
| python app.py | |
| ``` | |
| Then open <http://localhost:7860/>. | |
| ## ◈ WAABANDA'IWEWIN / EXAMPLES ◇ | |
| ```text | |
| ╭─────────────────────────────────────╮ | |
| │ ᐴ AADIZOOKAAN / FANTASY ᔔ │ | |
| ╰─────────────────────────────────────╯ | |
| You stand before the gates of the Whisperwood. The ancient trees | |
| hum with a faint violet energy... | |
| [ Take the golden key ] [ Drink the mossy vial ] [ Press forward ] | |
| ``` | |
| ## ☼ NAANAAGADAWENINDIZOWIN / VERIFICATION ◈ | |
| ```bash | |
| curl -X POST http://localhost:7860/api/game/start \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"genre": "fantasy"}' | |
| ``` | |
| Returns clean JSON: `{"story", "choices", "health", "step", "game_over", "history"}`. | |
| ```bash | |
| curl http://localhost:7860/api/model_status | |
| ``` | |
| Returns: `{"model": "...", "cooldown": {"active": bool, "remaining_seconds": float, "window_seconds": float}}`. | |
| ## ◈ MODEL ◇ | |
| | Model (default) | Size | Purpose | License | | |
| |---|---|---|---| | |
| | Qwen2.5-1.5B-Instruct | 1.5B | Interactive story generation | Apache 2.0 | | |
| | VibeThinker 1.5B | 1.5B | Alternative — also tiny | Apache 2.0 | | |
| Override `INFERENCE_MODEL` to any model that supports `chat_completion` on the HF Inference API. The 1.5B defaults fit the **Tiny Titan** badge. | |
| ## ◇ MCP KINOOMAAGEWINAN / TOOLS ◈ | |
| TinyBard runs with `mcp_server=True`, exposing these tools (also available as FastAPI endpoints): | |
| - **`/api/game/start`** (POST `{"genre": "fantasy|scifi|cyberpunk"}`) — Start an adventure | |
| - **`/api/game/choice`** (POST `{choice, genre, step, health, history}`) — Submit a player choice | |
| - **`/api/model_status`** (GET) — Check the inference model + cooldown state | |
| Connect from any MCP client (Claude Desktop, Cursor, etc.) to the SSE endpoint at `/gradio/gradio_api/mcp/`. | |
| ## ◇ GIIZHIITAA / BADGE TARGETS ◇ | |
| - **◆ Tiny Titan** — Model ≤ 1.5B (well under 4B limit) | |
| - **◆ Off-Brand** — Fully custom FastAPI+Gradio frontend | |
| - **◆ Field Notes** — Blog post about tiny model interactive fiction | |
| ## ☼ GANAWENDAAGWAD / SECURITY ◈ | |
| PQC standard for any future API keys via the `pqc-secrets` skill (ML-KEM-768 + AES-256-GCM). At present, only the HF token is in flight (read from env var, never written to disk). | |
| ## ◇ AABAAJICHIGANAN / COOLDOWNS ◈ | |
| The `shared/inference_client.py` module enforces per-project cooldowns. Cooldown protects your HF/Modal credit budget from runaway re-rolls. Defaults: | |
| - `tinybard`: 6s | |
| - `focusfriend`: 10s | |
| - `crittercalm`: 12s | |
| Override per project via Space env vars (`TINYBARD_COOLDOWN_SECONDS`, etc.). | |
| --- | |
| ◈──◆──◇ ☼ TinyBard v1.1 · Cedar Edition · Anishinaabe Solarpunk · Inference API ◇──◆──◈ | |