--- title: Byte Bot sdk: docker app_port: 7860 emoji: πŸ€– colorFrom: purple colorTo: blue --- # πŸ€– BYTE AI β€” Agentic Stream Co-Producer (2026) ## An autonomous AI co-streamer & operations runtime for Twitch Byte is an **autonomous agent runtime** that watches, narrates, moderates, and grows Twitch channels. It runs on a **provider-neutral LLM layer** (default **Google Gemini**, OpenAI-compatible, switchable to Nebius) with an optional **multi-tenant Supabase** persistence layer. Byte spans the full loop: it *perceives* the stream (chat + vision), *reasons* about it, *acts* through a governed control plane, and *reports* on it β€” while a reactive mascot duo (**Byte** + **Mah**) gives the operator a glanceable read of system state. --- ## ⚑ Stats (source of truth: the code, today) | | | |---|---| | **Backend** | 95 Python modules Β· **1092 tests** (4 skipped), hermetic & green Β· ~85% coverage | | **Frontend** | 62 vanilla-JS modules Β· **177 node tests** Β· 9 dashboard partials Β· zero frameworks | | **Surface** | 37 `/api/*` endpoints Β· 2 dashboards (`/` ops, `/studio` streamer PWA) | | **Inference** | provider-neutral OpenAI-compatible client Β· default **Gemini** (`LLM_PROVIDER`) | | **Voice** | provider-neutral TTS (`TTS_PROVIDER`: ElevenLabs / Cartesia) | | **Persistence** | optional multi-tenant Supabase (PostgREST + pgvector); degrades to stateless | | **Quality** | Ruff + Black + Pyright via pre-commit Β· dashboard parity gate Β· scientific test suite | --- ## 🧠 Capabilities (catalogued by domain) ### 1. Perception β€” Byte sees & hears the stream - **Vision runtime** β€” ingests stream/screen frames; LLM-grounded scene understanding. - **IRC stack** β€” full async Twitch chat (connection, protocol, handlers, state, management). - **EventSub runtime** β€” Twitch event subscriptions (follows, raids, redemptions, etc.). - **Sentiment engine** β€” live hype-vs-boredom read of chat. - **Scene runtime** β€” scene/segment awareness and metadata. ### 2. Cognition β€” the agent brain - **Provider-neutral inference** β€” Gemini default; OpenAI-compatible; one switch (`LLM_PROVIDER`). - **Prompt flow & runtime** β€” structured prompt orchestration with grounding. - **Byte semantics** β€” layered semantic understanding (quality, reply, current-events). - **Semantic memory** β€” pgvector-backed long-term memory (multi-tenant). - **Web search grounding** β€” live web grounding for factual replies. ### 3. Voice & Co-Commentary β€” Byte talks back - **Voice runtime** β€” provider-neutral TTS (ElevenLabs / Cartesia). - **Commentary runtime** β€” autonomous, context-aware commentary on the stream. - **HUD runtime** β€” on-stream overlay feed for messages and Byte reactions. - **Recap engine** β€” mid-stream and segment recaps. ### 4. Engagement & Growth - **Channel Points runtime** β€” custom reward handling. - **Regulars runtime** β€” recognises and rewards returning viewers. - **Highlight runtime** β€” autonomous highlight/clip-candidate detection. - **Clips pipeline** β€” real Twitch clip jobs with thumbnails + live polling status. - **Braille / ASCII art runtime** β€” 2Γ—4 Braille-matrix art rendered cleanly in chat. ### 5. Intelligence & Reporting - **Coaching + churn risk** β€” viewer-churn assessment and actionable coaching. - **Stream health score** β€” composite live-health signal. - **Observability stack** β€” analytics, history, snapshots, state recorders (full pipeline). - **Post-stream report** β€” automated end-of-stream analytical report. - **Revenue attribution** β€” attributes outcomes to actions/segments. ### 6. Autonomy & Governance (the control plane) - **Control plane** β€” governed autonomous actions with an approval/risk queue. - **Autonomy logic & runtime** β€” health/sentiment/goal-driven autonomous decisions. - **Ops playbooks** β€” codified operational responses. - **Access control** β€” admin-token gated dashboard + actions. - **Heartbeat & status runtime** β€” liveness and status-line truth. ### 7. Persistence β€” multi-tenant, optional - Supabase repositories for channel config/identity, persona profiles, semantic memory, observability history, post-stream reports, revenue attribution, webhooks, agent notes. - **Graceful degradation:** absent Supabase β†’ fully stateless operation. ### 8. Operator experience β€” two dashboards + a reactive mascot duo - **`/` Ops dashboard** β€” cyber-tactical control surface (channels, autonomy queue, observability, clips, HUD) with a live SSE snapshot stream. - **`/studio` Streamer PWA** β€” light, "wow-but-fast" panel for the streamer. - **Byte πŸ€– + Mah πŸ’—** β€” reactive SVG mascots that read system & stream state (not a timeline), with honest "unseen" states when a signal isn't present yet. --- ## πŸš€ Quick Start For detailed instructions, see the [**Operations Guide**](docs/OPERATIONS_GUIDE.md). ### Prerequisites - Python 3.11+ - A Gemini API key (or any OpenAI-compatible provider via `LLM_PROVIDER`) - Twitch Client ID & Secret (+ user/refresh tokens) - *(optional)* Supabase project (PostgreSQL + pgvector) for stateful multi-tenant mode ### Installation ```bash git clone https://github.com/JuanCS-Dev/twitch-byte-bot.git cd twitch-byte-bot pip install -r bot/requirements.txt cp .env.example .env # fill your keys ``` ### Running ```bash python -m bot.main # starts the agent + dashboard server (port 7860) ``` --- ## πŸ›  Tech Stack - **Backend:** Python 3.11 (AsyncIO), OpenAI-compatible SDK, Croniter, Pillow. - **Frontend:** HTML5, CSS custom properties, vanilla JS (no frameworks), PWA + SSE. - **Inference:** provider-neutral β€” **Gemini** (default) / Nebius. - **Voice:** provider-neutral TTS β€” ElevenLabs / Cartesia. - **Storage:** Supabase (PostgREST + pgvector), optional. - **Quality:** Ruff, Black, Pyright, pre-commit, hermetic scientific test suite. --- _Developed by Juan Carlos β€” VΓ‰RTICE Core Analytics Γ— BYTE AI_