Spaces:
Sleeping
Sleeping
| # Byte Documentation (Complete Guide) | |
| Related docs: | |
| - [Documentation index](INDEX.md) | |
| - [Project README](../README.md) | |
| - [Executable implementation plan](IMPLEMENTATION_PLAN_EXECUTAVEL_PARIDADE_AGENT_DASHBOARD.md) | |
| - [GitHub visual assets guide](GITHUB_VISUAL_ASSETS_2026.md) | |
| ## 1. Product Summary | |
| Byte is a Twitch AI chat agent that runs on Gemini 3 Flash (Vertex AI) and is deployable on Cloud Run. | |
| Main goals: | |
| - Real-time chat assistance for live streams. | |
| - Short, direct, readable responses for chat flow. | |
| - Better factual reliability for current-events and technical prompts. | |
| - Production deployment path with observability and cost tracking. | |
| ## 2. Core Capabilities | |
| - Trigger-based natural chat responses via `byte`, `@byte`, or `!byte`. | |
| - Built-in short help/status flows. | |
| - Movie fact-sheet handling with context carryover. | |
| - Current-events prompt enrichment with verification instructions. | |
| - Serious/technical mode with strict 1-message contract (max 4 lines). | |
| - Automatic live context updates from trusted YouTube/X links. | |
| - Token refresh flow for IRC mode when refresh credentials are configured. | |
| - Real-time observability dashboard, control plane, autonomy controls, and risk queue. | |
| ## 3. Architecture | |
| ### Runtime Components | |
| - `bot/main.py`: Twitch integration, mode routing, health endpoint, token handling. | |
| - `bot/logic.py`: LLM orchestration, prompt construction, response limits, live context memory. | |
| - `bot/prompt_flow.py` + `bot/prompt_runtime.py`: runtime prompt pipeline and quality gates. | |
| - `bot/control_plane.py`: runtime config, goal scheduler state, budget windows, risk queue. | |
| - `bot/autonomy_runtime.py`: heartbeat loop, autonomous goal execution, anti-spam budget enforcement. | |
| - `bot/dashboard_server.py`: dashboard assets + admin APIs (`observability`, `channel-control`, `control-plane`, `action-queue`, `autonomy/tick`). | |
| - `bot/observability_state.py` + `bot/observability_snapshot.py`: telemetry aggregation and metrics snapshot. | |
| - `dashboard/`: modular static UI (`index.html`, `main.js`, `features/*`, `styles/*`). | |
| ### Infrastructure Components | |
| - Twitch chat transport: | |
| - `irc` mode: direct IRC socket mode (demo-friendly). | |
| - `eventsub` mode: official cloud chatbot path. | |
| - Gemini model provider: Vertex AI (`gemini-3-flash-preview`, `global`). | |
| - Secret store: Google Secret Manager. | |
| - Runtime host: Cloud Run. | |
| ## 4. Operating Modes | |
| ### Mode A: `TWITCH_CHAT_MODE=irc` | |
| Use this when you need quick demo behavior without streamer authorization. | |
| - Byte account joins target channel as viewer. | |
| - Byte reads chat and sends responses. | |
| - Required credentials are user-based (`TWITCH_USER_TOKEN`, optionally refresh token). | |
| ### Mode B: `TWITCH_CHAT_MODE=eventsub` | |
| Use this for official cloud chatbot architecture. | |
| - Requires app credentials and EventSub subscription flow. | |
| - In third-party channels, broadcaster authorization is required (`channel:bot`). | |
| ## 5. Environment Variables | |
| ### Required in All Modes | |
| - `GOOGLE_CLOUD_PROJECT`: GCP project ID. | |
| - `TWITCH_CHAT_MODE`: `irc` or `eventsub`. | |
| - `BYTE_TRIGGER`: chat trigger token (default: `byte`). | |
| ### EventSub Mode (`TWITCH_CHAT_MODE=eventsub`) | |
| - `TWITCH_CLIENT_ID` | |
| - `TWITCH_BOT_ID` | |
| - `TWITCH_CHANNEL_ID` | |
| - Secret in Secret Manager: `twitch-client-secret` | |
| ### IRC Mode (`TWITCH_CHAT_MODE=irc`) | |
| - `TWITCH_BOT_LOGIN` | |
| - `TWITCH_CHANNEL_LOGIN` | |
| - `TWITCH_CHANNEL_LOGINS` (optional, comma-separated, overrides single-channel login) | |
| - `TWITCH_USER_TOKEN` | |
| - Optional but recommended: | |
| - `TWITCH_REFRESH_TOKEN` | |
| - `TWITCH_CLIENT_ID` | |
| - `TWITCH_CLIENT_SECRET` or `TWITCH_CLIENT_SECRET_SECRET_NAME` | |
| - `TWITCH_TOKEN_REFRESH_MARGIN_SECONDS` | |
| ### Optional Runtime Tuning | |
| - `TWITCH_IRC_HOST` (default: `irc.chat.twitch.tv`) | |
| - `TWITCH_IRC_PORT` (default: `6697`) | |
| - `TWITCH_IRC_TLS` (default: `true`) | |
| - `AUTO_SCENE_CACHE_TTL_SECONDS` | |
| - `AUTO_SCENE_METADATA_TIMEOUT_SECONDS` | |
| - `AUTO_SCENE_REQUIRE_METADATA` | |
| ## 6. Twitch Setup (2026) | |
| ### 6.1 Create Twitch App | |
| Open: `https://dev.twitch.tv/console/apps/create` | |
| Use: | |
| - Name: `Byte Agent` | |
| - Redirect URL: `http://localhost:3000/callback` | |
| - Category: `Chat Bot` | |
| Collect: | |
| - `TWITCH_CLIENT_ID` | |
| - `TWITCH_CLIENT_SECRET` | |
| ### 6.2 Generate User Token for IRC Mode | |
| ```bash | |
| twitch token --user-token --dcf \ | |
| --client-id "$TWITCH_CLIENT_ID" \ | |
| --secret "$TWITCH_CLIENT_SECRET" \ | |
| --scopes "chat:read chat:edit" | |
| ``` | |
| Store: | |
| - Access token -> `TWITCH_USER_TOKEN` | |
| - Refresh token -> `TWITCH_REFRESH_TOKEN` (recommended) | |
| ## 7. Local Run | |
| ```bash | |
| pip install -r bot/requirements.txt | |
| python bot/main.py | |
| ``` | |
| Expected behavior: | |
| - Health server on `0.0.0.0:$PORT` (default `8080`). | |
| - Twitch connection starts based on selected mode. | |
| ### 7.1 Runtime HTTP Endpoints | |
| - `GET /`, `GET /health`, `GET /healthz` (and trailing slash variants): returns `AGENT_ONLINE`. | |
| - `GET /api/observability`: returns a live JSON snapshot for metrics and context. | |
| - `POST /api/channel-control`: `list|join|part` in IRC, mode-aware guard in EventSub. | |
| - `GET|PUT /api/control-plane`: runtime autonomy/scheduler/budget configuration. | |
| - `GET /api/action-queue`: pending/approved/rejected/ignored risk actions. | |
| - `POST /api/action-queue/<action_id>/decision`: approve/reject with audit note. | |
| - `POST /api/autonomy/tick`: manual autonomy cycle for ops/debug. | |
| - `GET /dashboard`: serves the real-time web dashboard. | |
| ## 8. Cloud Run Deployment | |
| ### 8.1 Recommended Path | |
| Use the deployment helper: | |
| ```bash | |
| ./deploy.sh | |
| ``` | |
| Deployment defaults in `deploy.sh`: | |
| - Region: `us-central1` | |
| - Service name: `byte-bot` | |
| - CPU: `1` | |
| - Memory: `512Mi` | |
| - Min instances: `1` | |
| - Max instances: `1` | |
| - Timeout: `3600s` | |
| - Concurrency: `200` | |
| ### 8.2 Important Notes | |
| - The script enables required APIs automatically. | |
| - For `eventsub`, the script expects `twitch-client-secret` in Secret Manager. | |
| - For `irc` + refresh, set `TWITCH_CLIENT_ID` and provide client secret (inline or Secret Manager). | |
| ## 9. Chat Behavior Contract | |
| ### 9.1 Reply Length | |
| - Default max lines: `4`. | |
| - Default max length: bounded to fit chat safely. | |
| - Serious technical prompts are forced to exactly one message (no split marker). | |
| ### 9.2 Built-in Trigger Intents | |
| - Help intent. | |
| - Intro intent (`byte introduce yourself` style trigger). | |
| - Status intent. | |
| - Movie fact-sheet intent. | |
| - General question intent with LLM response. | |
| ### 9.3 Reliability Rules | |
| The prompt pipeline adds extra instructions when needed: | |
| - Current-events: ask for verifiable and recent facts. | |
| - Direct questions: force immediate first-line answer. | |
| - Follow-up prompts: resolve pronouns from recent chat context. | |
| - Serious technical prompts: prioritize stronger evidence and practical framing. | |
| ## 10. Moderation and Auto-Context | |
| Byte can automatically update scene context from messages posted by trusted curators. | |
| Trusted curators: | |
| - Channel owner (`TWITCH_OWNER_ID`) | |
| - Moderators | |
| Supported sources: | |
| - YouTube links | |
| - X/Twitter links | |
| Safety controls: | |
| - Unsafe term filter. | |
| - Blocked-domain filter. | |
| - Optional metadata requirement before context update. | |
| ## 11. Token Refresh Automation | |
| In IRC mode, automatic token refresh is active when all values exist: | |
| - `TWITCH_REFRESH_TOKEN` | |
| - `TWITCH_CLIENT_ID` | |
| - `TWITCH_CLIENT_SECRET` (or Secret Manager-backed secret) | |
| Flow: | |
| - Validate access token. | |
| - Refresh if invalid or close to expiration. | |
| - Retry connection with refreshed token. | |
| ## 12. Cost Tracking and Monthly Projection | |
| Script: `scripts/estimate_monthly_cost.sh` | |
| What it does: | |
| - Reads Cloud Monitoring usage for Cloud Run + Gemini tokens. | |
| - Pulls live SKU prices from your billing account. | |
| - Computes interval cost and run-rate monthly estimate. | |
| Example: | |
| ```bash | |
| CLOUD_RUN_SERVICE=byte-bot \ | |
| REGION=us-central1 \ | |
| GEMINI_MODEL_FILTER=gemini-3-flash-preview \ | |
| ./scripts/estimate_monthly_cost.sh | |
| ``` | |
| End-of-day snapshot: | |
| ```bash | |
| START_TIME="$(date -u +%Y-%m-%dT00:00:00Z)" \ | |
| END_TIME="$(date -u +%Y-%m-%dT23:59:59Z)" \ | |
| CLOUD_RUN_SERVICE=byte-bot \ | |
| REGION=us-central1 \ | |
| GEMINI_MODEL_FILTER=gemini-3-flash-preview \ | |
| ./scripts/estimate_monthly_cost.sh | |
| ``` | |
| ## 13. Testing and Validation | |
| Run unit tests: | |
| ```bash | |
| python -m unittest discover -s bot/tests | |
| ``` | |
| Focused checks: | |
| ```bash | |
| python -m unittest bot.tests.test_logic | |
| python -m unittest bot.tests.test_scientific | |
| ``` | |
| ## 14. Troubleshooting | |
| ### Byte does not answer in chat | |
| - Confirm `TWITCH_CHAT_MODE`. | |
| - Confirm trigger message starts with `byte`, `@byte`, or `!byte`. | |
| - Confirm tokens are valid and bot login/channel login are lowercase. | |
| ### `invalid client` during auth | |
| - Confirm app `Client ID` is correct. | |
| - Confirm redirect URI exactly matches app settings. | |
| - Confirm you are authorizing the correct app. | |
| ### `invalid scope requested` | |
| - For IRC user token, use `chat:read chat:edit`. | |
| - For EventSub official path, use chat bot scopes (`user:read:chat`, `user:write:chat`, `user:bot`) plus broadcaster scope (`channel:bot`) when required. | |
| ### How to test Byte in multiple channels without redeploy | |
| - Keep IRC mode enabled. | |
| - Seed channels with `TWITCH_CHANNEL_LOGINS=channel_a,channel_b` (optional). | |
| - While Byte is online, owner can manage channels from chat: | |
| - `byte canais` (or `byte channels`) | |
| - `byte join <channel_login>` | |
| - `byte part <channel_login>` | |
| - Byte answers in the same channel where it was triggered. | |
| ### Bot disconnects after token expiry | |
| - Configure refresh variables and client secret source. | |
| - Keep `TWITCH_TOKEN_REFRESH_MARGIN_SECONDS` at a safe value (default `300`). | |
| ## 15. Security Checklist | |
| - Never commit secrets (`.env`, OAuth tokens, client secrets). | |
| - Use Secret Manager for `TWITCH_CLIENT_SECRET` in production. | |
| - Restrict IAM roles to minimum required permissions. | |
| - Review staged files before every push. | |
| ## 16. Launch Checklist (Before Posting on X) | |
| 1. Confirm banner and visual assets exist in `assets/`. | |
| 2. Run tests: `python -m unittest discover -s bot/tests`. | |
| 3. Validate live chat behavior (`byte help`, `byte status`, free-form question). | |
| 4. Run cost script and capture current monthly estimate. | |
| 5. Verify README links in `docs/INDEX.md` all resolve correctly. | |