twitch-byte-bot / README.md
JuanCS-Dev's picture
fix: Mah blinks when unseen
26d9a59 verified
|
Raw History Blame Contribute Delete
5.95 kB
---
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_