README.md

metadata

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.

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

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

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