{"id":47892500,"url":"https://github.com/cipher982/spoc-shot","last_synced_at":"2026-04-04T03:10:47.599Z","repository":{"id":298699644,"uuid":"1000774363","full_name":"cipher982/spoc-shot","owner":"cipher982","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-28T18:53:06.000Z","size":655,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T09:44:56.027Z","etag":null,"topics":["ai","generative-ai","llm","webllm"],"latest_commit_sha":null,"homepage":"https://drose.io/storyteller/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipher982.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-12T09:51:41.000Z","updated_at":"2025-12-28T18:53:09.000Z","dependencies_parsed_at":"2025-06-12T12:27:43.950Z","dependency_job_id":"66ebfc81-ec7e-4b50-8106-a7e4985b12e2","html_url":"https://github.com/cipher982/spoc-shot","commit_stats":null,"previous_names":["cipher982/spoc-shot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cipher982/spoc-shot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Fspoc-shot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Fspoc-shot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Fspoc-shot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Fspoc-shot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipher982","download_url":"https://codeload.github.com/cipher982/spoc-shot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipher982%2Fspoc-shot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31386001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"online","status_checked_at":"2026-04-04T02:00:07.569Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","generative-ai","llm","webllm"],"created_at":"2026-04-04T03:10:47.024Z","updated_at":"2026-04-04T03:10:47.593Z","avatar_url":"https://github.com/cipher982.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Storyteller's Quill\n\nAn interactive AI storytelling experience with real-time token probability visualization. Watch the model \"think\" as it writes, seeing the confidence and alternative choices for each word.\n\n**Live Demo:** https://drose.io/storyteller/\n\n---\n\n## Features\n\n- **Interactive Story Generation** — Type a topic and watch the AI craft a story in real-time\n- **Token Probability Visualization** — See model confidence with color-coded uncertainty indicators\n- **Alternative Token Explorer** — Hover over any word to see what other tokens the model considered\n- **Click-to-Retry** — Don't like a word? Click it to regenerate from that point with a different choice\n- **Beautiful Old-Book Aesthetic** — Parchment textures, ink colors, and serif typography\n- **Fully Client-Side** — Model runs in your browser via WebLLM (no data sent to servers)\n\n---\n\n## Requirements\n\n- Python ≥ 3.12\n- `uv` package manager\n- A modern browser with **WebGPU** support (Chrome 113+, Edge 113+, Firefox 121+)\n\n\u003e The server only serves static files; all inference happens client-side in your browser.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install dependencies\nmake install\n\n# 2. Start development server\nmake dev\n\n# 3. Open browser\nopen http://127.0.0.1:8004\n```\n\nOr use the config helper:\n\n```bash\n./config.sh init      # Create .env from template\n./config.sh dev       # Configure for development\nmake dev              # Start server\n```\n\n---\n\n## Make Targets\n\n```text\nmake help        # Show all available commands\nmake install     # Install Python dependencies (uv sync)\nmake dev         # Start development server with hot-reload\nmake test        # Run test suite\nmake docker      # Build and run in Docker (development)\nmake docker-prod # Build and run in Docker (production, detached)\nmake stop        # Stop the development server\nmake clean       # Remove cache files and prune Docker\n```\n\n---\n\n## Configuration\n\nKey environment variables (see `.env.example`):\n\n| Variable       | Default   | Description                          |\n|----------------|-----------|--------------------------------------|\n| `HOST`         | `0.0.0.0` | Server bind address                  |\n| `PORT`         | `8004`    | HTTP port                            |\n| `RELOAD`       | `true`    | Enable uvicorn auto-reload           |\n| `WEBLLM_MODE`  | `webllm`  | Inference mode (webllm/server/hybrid)|\n\n---\n\n## How It Works\n\n1. **WebLLM** loads a quantized LLM (Llama/Qwen) directly in your browser using WebGPU\n2. As the model generates tokens, it streams both the token and its **logprobs** (log probabilities)\n3. The UI visualizes confidence levels:\n   - **High confidence** (\u003e90%) — Solid ink color\n   - **Medium confidence** (70-90%) — Slightly faded\n   - **Low confidence** (\u003c70%) — Golden/uncertain appearance with decorative underline\n4. Hovering reveals the top-5 alternative tokens the model considered\n5. Clicking a token lets you \"rewind\" and try a different path\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                      Browser                             │\n│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │\n│  │  logit-viz  │───▶│   WebLLM    │───▶│   WebGPU    │  │\n│  │    (.js)    │◀───│  Manager    │◀───│   (GPU)     │  │\n│  └─────────────┘    └─────────────┘    └─────────────┘  │\n└─────────────────────────────────────────────────────────┘\n              │\n              ▼ (static files only)\n┌─────────────────────────────────────────────────────────┐\n│                    FastAPI Server                        │\n│         Serves HTML/JS/CSS • Health checks              │\n└─────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Testing\n\n```bash\nmake test\n```\n\nThe test suite includes:\n- **Basic tests** — UI elements, parameter controls, accessibility\n- **E2E tests** — Full user interactions via Playwright\n- **Mock infrastructure** — GPU-free testing with simulated WebLLM responses\n\nSee `tests/README.md` for details on the testing strategy.\n\n---\n\n## Deployment\n\nDeployed via **Coolify** on clifford at `https://drose.io/storyteller/`\n\nThe Docker container:\n- Builds with `uv` for fast dependency installation\n- Runs uvicorn on port 8000 internally\n- Caddy reverse proxy handles `/storyteller` path routing\n\n---\n\n## History\n\nThis project evolved from **SPOC-Shot**, an agent comparison demo. In November 2025, it was reimagined as **The Storyteller's Quill** — focusing on the creative and educational aspects of watching an LLM generate text token-by-token.\n\nThe original agent comparison code has been archived. See `CODE_REVIEW_SUMMARY.md` for details on the migration.\n\n---\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipher982%2Fspoc-shot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipher982%2Fspoc-shot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipher982%2Fspoc-shot/lists"}