Spaces:
Sleeping
Sleeping
|
Download README.md from JuanCS-Dev/twitch-byte-bot: direct link, hf CLI and curl.
- Browser
- Download file 5.95 kB
-
https://huggingface.co/spaces/JuanCS-Dev/twitch-byte-bot/resolve/main/README.md
- Command line
-
hf download hf://spaces/JuanCS-Dev/twitch-byte-bot/README.md
-
curl -L -o README.md https://huggingface.co/spaces/JuanCS-Dev/twitch-byte-bot/resolve/main/README.md
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_ | |