Buzz Score Arti Ingegration

Buzz Score Integration

Status: Design, pending tech-lead sign-off

Created: 2026-08-18

Last Updated: 2026-08-18

Related Work: Buzz Score epic brief v1.1 AC5 - genesis-web docs/architecture/buzz-score-architecture.md

What this covers

Arti’s side of the Buzz Score. genesis-web computes the score; this service explains it.

Thin by design. SMART_ROLLUP.md and SERVICE_AUTHENTICATION.md already carry the shared background for both repos, and this document only adds what is specific to Buzz Score.

What this service does not do

It does not compute any part of the score.

This service has direct Mongo access, but only for its own concerns: LangGraph checkpoints, memory extraction, credits, and Idea Center boards. Every piece of product data it uses arrives over HTTP from genesis-web through app/utils/api_client.py. There are no models for badges, levels, or metrics anywhere in this repo, and there should not be.

Score data reaches Arti one of two ways, matching the two existing patterns:

Pattern	Path	Existing example
Pushed with the page	`moduleContext.data` on a rollup request	`smartRollupBuzzFactoryService` today
Pulled on demand	`APIClient._make_request` with the user’s JWT	`app/agents/questionnaire/tools.py`

text

  SEAM 1   page open, pushed
  ---------------------------
  artist opens Buzz Factory
        |
        v
  genesis-web   smartRollupBuzzFactoryService builds moduleContext
        |       (level + badges + questionnaire + buzz_score block)
        v
  POST /api/v1/agent/chat/stream   { generateInitialRollup: true, moduleContext }
        |
        v
  genesis-train  generate_initial_rollup_stream() -> buzz_score branch -> LLM
        |
        v
  SSE deltas ---> genesis-web ---> browser        Arti speaks first, no user message


  SEAM 2   conversation, pulled
  -----------------------------
  "why is my buzz score 62?"
        |
        v
  genesis-train  chat graph -> BUZZ_TOOLS
        |        APIClient._make_request, user JWT from state["token"]
        v
  GET /api/v1/buzz-factory/v2/buzz-score ---> genesis-web reads latest snapshot
        |
        v  lean JSON
  LLM narrates the breakdown ---> browser

The two seams differ in who starts the conversation and in how the data travels, but both read the same snapshot. Neither recomputes anything. Seam 1 gets the score handed to it as page context; seam 2 fetches it because the artist asked a question that the page context may not be open to answer.

Seam 1: the page-open rollup

When an artist opens the Buzz Factory page, genesis-web gathers the module data and POSTs to /api/v1/agent/chat/stream with generateInitialRollup: true. Arti speaks first, with no user message.

What arrives

genesis-web extends services/agent/smartRollupBuzzFactoryService.js so the existing buzz_factory ModuleContext carries a score block alongside level, badges, and questionnaire:

python

data["buzz_score"] = {
  "composite":  {"value": 65.8, "band": "building", "status": "live"},
  "slices": {
    "intention": {"value": 72.0, "status": "live",   "subSignals": {...}},
    "action":    {"value": 85.1, "status": "live",   "subSignals": {...}},
    "resonance": {"value": 41.2, "status": "live",   "subSignals": {...}},
  },
  "overTargetRatio": {"content": 0, "release": 0},
  "trend": {"deltaVsLastWeek": +3.1, "configVersionStable": True},
  "configVersion": 3,
}

Every sub-signal is {"value": number|null, "reason": str|null, "weight": float}. The full contract, including the reason vocabulary, lives in genesis-web’s docs/architecture/buzz-score-contract.md.

Changes needed here

A buzz_score branch in generate_initial_rollup_stream() in app/api/routers/chat_api.py, or an extension of the existing buzz_factory branch. Note the voice constraint below before reusing that branch’s prompt.
An onboarding string in get_onboarding_message() for the pre-activation case, where the composite is not yet live.
A typed formatter in app/services/user_data_insights/data_formatter_service.py. Today buzz_factory has no formatter, so follow-up turns fall through to _format_generic_for_analysis(), which JSON-dumps the payload against a 2000-token budget and truncates. A score breakdown truncated mid-structure produces confident nonsense, so this is worth doing rather than deferring.

Structural note. The rollup ladder in chat_api.py is roughly 500 lines of inline prompt strings inside one function. Adding a branch follows precedent but deepens that hotspot, and app.api.routers.chat_api is in the mypy ignore_errors baseline so a new file there gets no type checking. Extracting per-module prompt builders into app/services/user_data_insights/ matches how every other domain in this repo is organised and would give the new code full checking. Worth raising at breakdown; not a blocker.

Seam 2: the on-demand tool

For “why is my buzz score 62” asked in normal conversation.

A BUZZ_TOOLS module following the app/agents/questionnaire/tools.py template, which is both the cleanest example in the repo and already Buzz-Factory-adjacent:

module docstring saying when Arti should reach for it
private _lean_* helpers that shrink the payload before it reaches the model
@tool async def with a docstring full of example user phrasings
token = state["token"], then APIClient._make_request("GET", "/buzz-factory/v2/buzz-score", token=token)
json.dumps(...) on success, json.dumps({"error": ...}) on failure
logger.info("🔧 TOOL: ...")
trailing BUZZ_TOOLS = [...]

Register it in CHAT_TOOLS (app/agents/chat/tools.py) and announce it in both catalogues in app/services/ai/prompt_service.py: get_tool_index_context() (the lean one, gated by LEAN_CHAT_CONTEXT) and get_full_tool_capabilities_context(). Both already carry a Buzz Factory line listing the questionnaire tools; extend it rather than adding a new section.

Authentication

Unchanged from SERVICE_AUTHENTICATION.md. Two schemes over the same Authorization: Bearer header:

Caller	Token	Notes
Agent tools acting for an artist	The user’s JWT from `state["token"]`	The user id in this service is the email address, taken from the `emailAddress` claim.
Service-to-service reads	`Bearer service:<SERVICE_AUTH_TOKEN>`	`get_flexible_auth()` returns `user_id == "service_user"`. Bypasses the credit check.

The score endpoint is a per-artist read, so the on-demand tool uses the user’s JWT. It sits behind isLogged on the genesis-web side and is additionally feature-flagged, so the tool must handle a 403 as “not available for this artist yet” rather than as an error.

Voice

The existing buzz_factory rollup prompt cannot be reused as-is.

Its response structure opens with “Celebration”, asks for “genuine enthusiasm”, instructs the model to “make them feel proud”, and closes on “be celebratory of what they’ve accomplished”. That is correct for a gamification hub built on badges and levels.

The Buzz Score is a different instrument and commits to the opposite register:

The score’s stated commitments	What that rules out
“A falling score is a diagnosis, not a scolding”	Framing a drop as a failure, or as motivation
“We don’t hand out participation points”	Celebrating movement that did not happen
A dash means “we can’t see this yet”, never “you have no resonance”	Reading a `null` as a deficiency
The coach can say do less of one thing	Advice that only ever adds work
“If your action is high and the market is quiet, the honest message is keep going, let’s talk strategy, never post more”	Prescribing more output when Action is already at the ceiling

The last row is the whole point of the feature. An artist doing everything right into a quiet market is the case the score exists to describe, and telling that artist to post more is the specific failure it was built to prevent.

Two prompt rules follow directly from the contract:

overTargetRatio above zero means say less, not more. Nine posts against a maximum of seven bought nothing. Arti should say so.
A dash and a zero are different sentences. reason: "platform_disconnected" is “we can’t see TikTok”. A genuine 0 is “this is flat”. Never collapse them.

Testing

app/tests/unit/, following test_buzz_factory_rollup.py. That file’s shape is worth copying: it asserts on the onboarding strings directly, and hand-builds moduleContext dicts to document the contract genesis-web produces, naming the producing service in a comment.

Use unittest.mock.patch and AsyncMock on APIClient._make_request for the tool, and monkeypatch.setenv for env, per test_brand_hub_client.py.

conftest.py already provides test_user_context, which carries buzzProgress.

Cases worth having:

a live score with all three slices renders every slice
a dash renders as “cannot see” language, not as a zero
pre-activation renders Intention and Action while the composite stays absent
overTargetRatio above zero produces do-less guidance
a 403 from the endpoint degrades gracefully