Understand Kam chat request and response cycles.

Kam chat is not only a text box. The product works when the user-visible prompt, the hidden React Native request context, the backend read path, and the rendered chat turn all agree.

This page is the copy/paste contract for users and agents. Use it when you want to write a prompt, build a fixture, review /llms.txt, or test whether a response is honest about sources.

First principles

1. A request has two parts: the prompt the user sees and the request context the React Native chat screen attaches before sending.
2. The prompt should name the scope before asking for interpretation. Scope can be a sport, team, date, slate, book, source, saved read, game, watchlist, or workspace.
3. The suffix should tell Kam how to handle priors, missing data, stale data, and blocked sources.
4. The request context should lock the product lane when the UI already knows it. Important fields include sportFocus, dataSource, responseView, timeScope, bookmakerSelection, and useCase.
5. The answer must separate the active response scope from adjacent data availability. A FanDuel board can say Polymarket is available without silently turning the response into a full cross-market comparison.
6. Missing data is a valid answer. Kam should say what is missing instead of filling the gap from priors.
7. A useful answer ends with a current read, source state, caveat, and one next action.

Prompt shape

Use this shape for prompt chips, fixtures, demo chat JSON, or manual requests:

Scope prefix: sport, team, date, saved read, source, or workspace.
Ask the exact research question.
Tell Kam how to handle priors, missing data, stale data, or blocked sources.

The tested React Native quick prompts use this grounding suffix for market-data prompts:

Use only app APIs and tool results already in this chat.
Do not answer from priors.
If the data is missing, say "No data available."

That suffix is part of the product contract. It tells Kam to answer from app APIs, tool results, source receipts, and read models instead of using general model memory.

Visible prompt plus request context

The user sees a short prompt. The chat screen can attach context that makes the backend route deterministic.

Example for a quick MLB odds request:

prompt:
  Show me MLB odds

requestContextOverrides:
  surface: summary_ask
  analysisTier: fast
  serverManagedRouting: true
  answerSurface: chat
  sportFocus: baseball_mlb
  dataSource: sportsbooks
  responseView: odds_board
  timeScope: today
  bookmakerSelection: best_available
  useCase: daily_odds_board_summary
  dailyOddsBoardReadModelRequired: true
  platformPanelContext.dataPlane:
    materialized_daily_odds_board_view

Agents should read this as:

Do not invent a general MLB answer.
Load the materialized MLB daily odds board.
Render an odds_board answer in chat.
Report source coverage honestly.
If adjacent Polymarket coverage is available, say so.
Do not render a full cross-market table unless the user asked for it.

React Native context fields

These are the fields agents should understand when reading a Kam chat request.

surface

Where the request came from. Common example: summary_ask.

Use it to preserve intent from quick prompts, platform panels, game detail, or workspace handoffs.

analysisTier

Expected depth and latency. Common examples: fast for quick board reads, deeper tiers for richer analysis.

Use it to avoid turning a quick board prompt into an expensive research run.

serverManagedRouting

Whether the backend should choose the exact route while preserving UI intent.

Use it when the frontend knows this is a product lane but the backend should pick the final read path.

answerSurface

Where the answer will render. Common example: chat.

Use it to shape the final response for the chat thread instead of a standalone report.

sportFocus

The bounded sport key. Examples: baseball_mlb, basketball_nba, americanfootball_nfl, icehockey_nhl.

Use it to keep source reads from drifting into the wrong sport.

dataSource

The requested source family. Values are sportsbooks, polymarket, or both.

Use it to decide whether the request is a sportsbook read, a prediction-market read, or a cross-market read.

responseView

The UI/result shape. Examples: odds_board, all_games, quick_read, market_alignment, futures, platform_detail.

Use it to keep the response format aligned with the chat screen.

timeScope

The selected time window. Examples: today, tomorrow, this_week, or a pinnedDate.

Use it to prevent hidden date drift.

bookmakerSelection

The selected book scope. Examples: best_available, all_books, fanduel.

Use it to decide whether the response should lead with one book, compare books, or report that a named book is unavailable.

preferredSportsbooks

The ordered sportsbook preference list. Example: ["fanduel"].

Use it for ordering and defaults. Do not use it to hide books that the user explicitly requested.

useCase

The product job. Examples: daily_odds_board_summary, schedule_count, scores_context, market_shape, futures.

Use it as the main intent label for tests, fixtures, and /llms.txt.

platformPanelContext.dataPlane

The durable read path that should support the answer. Examples: materialized_daily_odds_board_view, materialized_cross_market_delta_view, historical_frozen_facts.

Use it to verify whether the answer is backed by the correct data lane.

gameHandoff

The selected game context from game detail or platform panel. It can carry matchup, selected book, hot-read keys, source mode, snapshot age, and visible surface.

Use it when the user asks a follow-up from a specific game.

workspaceId

The saved workspace context.

Use it for watchlists, saved reads, artifacts, and follow-up memory.

promptRouteId

The backend prompt route chosen by the request context attachment.

Use it for debugging, receipts, retries, and regression tests.

What happens after send

The React Native chat thread is built from turn items. A good fixture or backend response should make these states possible.

1. userMessage: the exact visible prompt.
2. agentProgress: route and source lifecycle labels, such as Choosing route, Reading sources, Preparing structured response, and Writing answer.
3. readModel: the durable read model or blocked state.
4. toolCall: the app API, source, or tool read used to load the data.
5. structuredResponse: typed UI output, such as a games table, odds board, chart packet, or action card.
6. agentMessage: the final human-readable answer. Streaming deltas update this item.
7. reasoning: optional trace-style notes when enabled.
8. artifact: saved table, chart, board, watch item, or report.
9. receipt: source receipts, freshness state, workflow receipt, and next transition.
10. decision: route, blocked-state, approval, or next-action decision.

For source reads, the lifecycle should move through tooling and drafting states. The mobile screen has tested labels for Reading board and Preparing structured response, so docs, fixtures, and demos should use the same mental model.

Good response shape

A good answer has four visible parts:

Current read:
  What Kam can say right now.

Source state:
  Which board, book, schedule, score, prediction market,
  saved read, fixture, or read model was used.

Caveat:
  What is stale, thin, missing, delayed, blocked, inferred,
  or outside the active response scope.

Next action:
  Track, open game detail, compare books, refresh, save,
  wait, review, or pass.

Do not hide source state. Do not turn a caveat into confidence. Do not show a pick when the user asked for source truth.

Generic board versus cross-market request

This distinction matters for MLB odds and Polymarket.

Generic board request

Scope: MLB today. Source: market-price data.
Show me MLB odds
Use only app APIs and tool results already in this chat.
Do not answer from priors.
If the data is missing, say "No data available."

Expected context:

useCase: daily_odds_board_summary
responseView: odds_board
dataSource: sportsbooks
platformPanelContext.dataPlane:
  materialized_daily_odds_board_view

Good response language:

Sportsbook odds: FanDuel loaded for 15/15 games.
Polymarket: 15/15 matched games available.
Cross-market comparison:
  available when requested with Polymarket or all-sources scope.

Bad response language:

Polymarket: 0/15 games loaded.
Cross-market comparison:
  not allowed without Polymarket coverage.

The bad response is wrong when the durable cross-market projection already has matched Polymarket rows. The generic board should stay a FanDuel board, but it should report available adjacent Polymarket coverage honestly.

Explicit cross-market request

Scope: MLB today.
Source: sportsbooks and prediction markets.
Show all MLB books and Polymarket.
Find the biggest deltas and chart them.
If Polymarket data is missing, say "Cross-market status: Incomplete"
and explain why alignment is blocked.

Expected context:

useCase: market_shape
responseView: market_alignment
dataSource: both
bookmakerSelection: all_books
platformPanelContext.dataPlane:
  materialized_cross_market_delta_view

Good response language:

Cross-market status: ready.
Sportsbook rows: loaded.
Prediction-market rows: loaded.
Joined comparison rows: ready.
Chart status: ready.

Blocked response language:

Cross-market status: Incomplete.
Sportsbook rows are available.
Polymarket rows are missing or not joined.
No delta table was rendered.
Next action: refresh or wait for the cross-market projection.

Copy/paste examples

Show the current MLB board

Expected lane: daily_odds_board_summary

Expected view: odds_board

Expected data plane: materialized_daily_odds_board_view

Scope: MLB today. Source: market-price data.
Show me MLB odds
Use only app APIs and tool results already in this chat.
Do not answer from priors.
If the data is missing, say "No data available."

Expected response:

Current read:
  MLB odds overview for the active date.

Source state:
  FanDuel or selected sportsbook loaded for the board.
  Adjacent Polymarket coverage reported if matched rows exist.

Caveat:
  Other books or full cross-market comparison are not active
  unless requested.

Next action:
  Open game detail, compare with Polymarket, save the board,
  wait, or pass.

Ask for a bounded schedule answer

Expected lane: schedule_count

Expected view: all_games

Scope: Yankees, June.
How many Yankees games are in June?
If schedule data is incomplete, say what is missing before answering.

Expected response:

Current read:
  Count of Yankees games in the bounded June window.

Source state:
  Schedule source, date range, and team normalization.

Caveat:
  Missing schedule rows or inferred year must be named.

Next action:
  Show the full list, filter home games, save, or review.

Compare sportsbooks and prediction markets

Expected lane: market_shape

Expected view: market_alignment

Expected data plane: materialized_cross_market_delta_view

Scope: current slate.
Source: market prices and prediction markets.
Where do sportsbooks and Polymarket disagree?
If Polymarket data is missing, say "Cross-market status: Incomplete"
and explain why alignment is blocked.

Expected response:

Current read:
  Biggest disagreements only when joined rows exist.

Source state:
  Sportsbook state and prediction-market state are separate.

Caveat:
  Liquidity, missing markets, unmatched teams, stale rows,
  or projection not ready.

Next action:
  Open delta chart, inspect one game, refresh, save, or pass.

Review saved reads before acting

Expected lane: market_shape

Expected view: quick_read

Scope: my watchlist today.
Source: saved reads plus current market data.
What changed on my watchlist?
Use only app APIs and tool results already in this chat.
Do not answer from priors.
If the data is missing, say "No data available."

Expected response:

Current read:
  The saved read with the most meaningful movement.

Source state:
  Watchlist item, saved read timestamp, current market state.

Caveat:
  Stale saved read, unavailable market, or no meaningful movement.

Next action:
  Open, refresh, save an updated read, wait, or pass.

Resolve a recent game result

Expected lane: scores_context

Expected view: quick_read

Scope: Lakers recent games.
Did the Lakers game finish?
If the score source is not final, say the game is not confirmed final.

Expected response:

Current read:
  Final, live, scheduled, postponed, or unavailable.

Source state:
  Teams, date, score source, and status.

Caveat:
  If final status is not confirmed, say that directly.

Next action:
  Open game detail, refresh score, review saved read, or wait.

Ask for current futures context

Expected lane: futures

Expected view: futures

Scope: NBA championship futures.
Who is favored to win the NBA championship?
Separate available prices from interpretation and label stale futures data.

Expected response:

Current read:
  Current favorite or no-data state.

Source state:
  Futures market, book, price, and freshness.

Caveat:
  Futures can be stale, thin, or book-specific.

Next action:
  Compare books, inspect movement, save the read, or wait.

Agent checklist

Before answering, agents should check:

1. What did the user actually ask for?
2. What did React Native attach in ChatMacroRequestContext?
3. Which useCase and responseView should own the answer?
4. Which data plane or read model backs the answer?
5. Is the source fresh, stale, thin, missing, blocked, or outside scope?
6. Should the response render structured UI, plain text, an artifact, a receipt, or a blocked state?
7. What is the one next action that helps the user continue?

Static demo versus live product

The public AI button on kam-ai.com is a static product preview. It can use fixture JSON to show the request and response shape without a live backend call.

The live React Native workspace must attach source receipts and read-model state before making claims. If the live product cannot prove the current source state, it should say what is missing.

For agents, /llms.txt mirrors this contract in a copyable format. Use the docs page for human detail, and use /llms.txt when an agent needs the compact product rules.

For structured agent discovery, use the public semantic interface and data availability vocabulary. Those pages explain the capability IDs, response states, receipt types, and typed next actions that back this request cycle.