Run any Skill in Manus with one click

heater-appb-bubba-ai

Stars2

Forks0

UpdatedJuly 6, 2026 at 19:01

Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

hicklax13

hicklax13/HEATER_v1.0.0

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	heater-appb-bubba-ai
description	Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.

Bubba (AI Assistant) — streaming, metering, and the byte-identical drain

Bubba is read-only on the league — it recommends, never writes. Its explainer tools are additive and registry-first (src/ai/tools.py over CONSTANTS_REGISTRY); never give it a mutating tool without an explicit owner decision.

The one inviolable seam

src/ai/providers.py is shared with the live Streamlit app. _chat_events() (providers.py:46-166) is the streaming generator; chat() (169-200) is a thin DRAIN over it that must return the byte-identical pre-streaming dict. Frozen-reference guard: tests/api/test_ai_providers_streaming.py:79 test_chat_is_a_drain_returning_todays_exact_dict — if your change makes it fail, the live Streamlit app just changed; redesign additively.

Failure story: litellm.stream_chunk_builder returns None on an empty stream — undiscovered, None.choices would have crashed the LIVE app's chat() hot path via the shared drain. Guarded at providers.py:95-103 (graceful done). When touching the stream loop, preserve that guard and the terminal-done contract.

Money flow (metering & caps)

ChatService.send (api/services/chat_service.py): key check → cap check → call → meter BEFORE persist (~line 162) so history failures can't skip billing. send_stream meters server-side before emitting the terminal done frame — a tail-disconnect still bills. Mid-stream partial-token metering was a documented under-count until P5 added it (litellm constraint: Py<3.14 for ≥1.83.8; CI runs 3.12).
Caps: src/ai/budget.is_over_cap(user_id, on_own_key, cap_usd=None) (budget.py:72-76) — the cap_usd override is the tier hook; own-key users are exempt. api/gating.py::get_managed_ai_cap resolves tier→cap, returns None while billing dormant (= admin default) and NEVER raises (store failure → bounded, logged over-grant). Over-cap streaming error carries code:"over_cap" → frontend OverCapNudge (Bubba.tsx ~841). Chat identity offset: chat_user_id = 1_000_000_000 + AppUser.id.
Keys: src/ai/keys.py — per-provider env HEATER_AI_ADMIN_KEY_<PROVIDER> (keys.py:27-33); resolution user-own-key → admin key → None (124-142); Fernet key HEATER_AI_KEY (falls back to HEATER_RELAY_KEY). Key VALUES never in git.

Message construction

ChatService._build_user_content (chat_service.py:60-89): with NO tag/image/page-context it returns the bare message string — that exact byte-identity is what keeps the equivalence test green; attachments produce the OpenAI multimodal parts list; page_context folds a data-json block into the user turn. Vision-incapable model + image → graceful error frame, never a 500.

Frontend composer (web/src/components/bubba/)

SSE reader bubba.sendStream handles text_delta / tool_started / tool_result / done / error (Bubba.tsx:380-436). Errors surface as an in-chat frame — the stream endpoint never 500s mid-stream.
Page context auto-attach: usePageData publishes {pageId, data} to BubbaContext; Bubba serializes to a 16 KB UTF-8-byte cap, code-point-safe (Bubba.tsx:57). Wiring a page through usePageData gives Bubba context for free.
Tag flow: capture-phase click reads data-bubba-tag off PlayerLink (intercepts before PlayerDialog); data-bubba-panel excludes Bubba itself from snapshots; snapshots of cross-origin headshots render blank (documented html-to-image caveat, keyed on source==="snapshot").
Message queue drains only after a CLEAN turn; an errored turn pauses the queue with a hint.
PDFs attach as EXTRACTED TEXT (pdfjs, dynamic import, 12 KB cap) — works on every model; not raw-PDF passthrough.

When NOT to apply

Model/pricing questions → the claude-api skill. Adding a normal (non-chat) endpoint → heater-appb-endpoint-slice. Tier design changes (new tiers, cap amounts) are owner decisions.

More from this repository

same repository

heater-appb-architecture

hicklax13/HEATER_v1.0.0

Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.

2026-07-062

heater-appb-auth-billing

hicklax13/HEATER_v1.0.0

Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.

2026-07-062

heater-appb-calibration-backtest

hicklax13/HEATER_v1.0.0

Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.

2026-07-062

heater-appb-contracts-openapi

hicklax13/HEATER_v1.0.0

Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.

2026-07-062

heater-appb-debugging

hicklax13/HEATER_v1.0.0

Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.

2026-07-062

heater-appb-deploy-ops

hicklax13/HEATER_v1.0.0

Use when deploying HEATER App B, changing Railway or Vercel env vars/service config, diagnosing live 502s/timeouts/blank data after deploy, operating the Yahoo-token or Statcast relays, or driving Railway/Vercel headlessly from a terminal.

2026-07-062

name	heater-appb-bubba-ai
description	Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.

Bubba (AI Assistant) — streaming, metering, and the byte-identical drain

The one inviolable seam

Money flow (metering & caps)

ChatService.send (api/services/chat_service.py): key check → cap check → call → meter BEFORE persist (~line 162) so history failures can't skip billing. send_stream meters server-side before emitting the terminal done frame — a tail-disconnect still bills. Mid-stream partial-token metering was a documented under-count until P5 added it (litellm constraint: Py<3.14 for ≥1.83.8; CI runs 3.12).
Caps: src/ai/budget.is_over_cap(user_id, on_own_key, cap_usd=None) (budget.py:72-76) — the cap_usd override is the tier hook; own-key users are exempt. api/gating.py::get_managed_ai_cap resolves tier→cap, returns None while billing dormant (= admin default) and NEVER raises (store failure → bounded, logged over-grant). Over-cap streaming error carries code:"over_cap" → frontend OverCapNudge (Bubba.tsx ~841). Chat identity offset: chat_user_id = 1_000_000_000 + AppUser.id.
Keys: src/ai/keys.py — per-provider env HEATER_AI_ADMIN_KEY_<PROVIDER> (keys.py:27-33); resolution user-own-key → admin key → None (124-142); Fernet key HEATER_AI_KEY (falls back to HEATER_RELAY_KEY). Key VALUES never in git.

Message construction

Frontend composer (web/src/components/bubba/)

SSE reader bubba.sendStream handles text_delta / tool_started / tool_result / done / error (Bubba.tsx:380-436). Errors surface as an in-chat frame — the stream endpoint never 500s mid-stream.
Page context auto-attach: usePageData publishes {pageId, data} to BubbaContext; Bubba serializes to a 16 KB UTF-8-byte cap, code-point-safe (Bubba.tsx:57). Wiring a page through usePageData gives Bubba context for free.
Tag flow: capture-phase click reads data-bubba-tag off PlayerLink (intercepts before PlayerDialog); data-bubba-panel excludes Bubba itself from snapshots; snapshots of cross-origin headshots render blank (documented html-to-image caveat, keyed on source==="snapshot").
Message queue drains only after a CLEAN turn; an errored turn pauses the queue with a hint.
PDFs attach as EXTRACTED TEXT (pdfjs, dynamic import, 12 KB cap) — works on every model; not raw-PDF passthrough.

When NOT to apply

Model/pricing questions → the claude-api skill. Adding a normal (non-chat) endpoint → heater-appb-endpoint-slice. Tier design changes (new tiers, cap amounts) are owner decisions.