PolyLab Docs | AI Chat

What Ask PolyLab does

Ask PolyLab is a chat drawer inside the scanner. It does not trade, place orders, or decide what a user should buy. Its job is narrower: answer PolyLab product questions, translate a natural-language request into a scanner setup, show a market preview when filters are relevant, and prepare safe user actions for explicit confirmation when needed.

The useful mental model is:

User asks a PolyLab question or requests a market universe.
Backend maps the request to either an informational answer or structured filters and optional actions.
Backend runs a preview query only when filters or actions need market results.
User reviews the response.
User can apply filters immediately, open a preview market, or confirm account-level actions such as watches.

User flow

Opening the chat

The chat is available from the scanner toolbar as Ask PolyLab. It requires a signed-in user. If the user is not signed in, the frontend opens the login modal instead of sending a chat request.

Sending a message

When the user sends a message, the frontend posts to POST /api/agent/chat with:

the message text
the current signed-in user_id
the recent chat history
the current scanner view and filters
a small set of currently visible market ids
the Supabase bearer token in the Authorization header

The endpoint verifies the Supabase session before doing any planning. If the token is missing or the user id does not match, the request is rejected.

Receiving a response

The response can include:

reply: short assistant text shown in the drawer
filters: sanitized scanner filter state
agent_constraints: extra constraints used by the preview, such as smart-money percentage
preview: up to 8 matching market outcomes plus the full preview count
suggested_actions: safe UI actions or a confirmation summary
action_token: a signed token for actions that require confirmation
blocked_actions: requests the backend refused, such as trading
knowledge_sources and agent_metadata: diagnostics for planner source, fallback, and context

For product questions such as "what is PolyLab?", "how does Smart Money work?", or "why can data differ from live Polymarket?", the response can be answer-only. In that case the backend returns no actions and an empty preview instead of showing unrelated market matches.

Backend planning flow

Context first

Before planning, the backend builds context from two sources:

current tag stats from the market database
the agent knowledge pack under docs/agent
generated public documentation pages under frontend_deploy/docs

Those knowledge chunks tell the agent how PolyLab filters work, how to treat categories and tags, how Smart Money percentages map to counts, which actions are allowed, how the product works, and where the current data limitations are.

Planner selection

The planner is selected from environment configuration:

If OpenAI planner support is configured, the backend asks the LLM for a structured plan.
If the LLM provider is disabled, unavailable, times out, or returns invalid output, the backend falls back to the rule-based planner.

The fallback planner still returns the same shape: filters, constraints, actions, blocked actions, and a short reply.

Backend is the authority

The model is not trusted to write directly. After a plan comes back, the backend:

sanitizes filter values
post-processes category searches into tags when possible
validates every action against an allowlist
rejects trading/order action types
runs the market preview itself
signs confirmable actions only after validation

Filters, tags, and search

The most important rule is that broad topics should use tags, while specific wording should use search.

User intent	Better mapping	Why
"football markets with smart money over 75"	`includedTags` such as `Soccer` or `FIFA World Cup`, `search = ""`, smart-money threshold	Football is a category/topic. Tag matching gives the backend the right market universe.
"weather markets ending today"	Weather tag, `include_expired = false`, expiry window ending at the current UTC day boundary	Weather is a broad topic and today is a time filter.
"Biden market"	`search = "Biden"`	This is specific wording that should be matched against market text.
"crypto politics markets"	`includedTags = ["Crypto", "Politics"]`, `search = ""`	Multiple broad topics should not be concatenated into full text.
"tight spread liquid markets"	`max_spread` and `min_liquidity`	These are numeric scanner filters, not text search terms.

This is why a phrase like soccer football in the search box is not a good result. The scanner search behaves like text matching over market wording. For category alternatives, the agent should use includedTags and leave search empty when suitable tags exist.

Smart Money mapping

Smart Money in PolyLab is based on sampled holder rows and wallet PnL sign. A percentage request is converted to a count threshold against the sampled holder set.

Request	Internal interpretation
`smart money 70%+`	`smart_money_min_win_pct = 70`, count threshold around 14 out of 20
`sm nad 75`	`smart_money_min_win_pct = 75`, count threshold around 15 out of 20
`smart money over 80`	`smart_money_min_win_pct = 80`, count threshold around 16 out of 20

The preview still comes from the backend query. The chat response should be read as research filtering, not investment advice.

Applying filters

Apply filters is a client-side action. It does not change the user account and does not require confirmation.

When applied, the frontend:

switches the app into workspace mode
resets any active saved preset selection
applies the returned filter state
updates URL parameters
fetches the matching market rows
shows a short "Filters applied" feedback message

On mobile, applying filters also closes the chat, closes the mobile filters sheet, and scrolls to the market results.

Preview markets

The response preview is intentionally small. It returns a useful sample of matching market outcomes plus a count. Clicking a preview market opens that market in the scanner when it is already loaded. If it is not currently loaded, the frontend first applies the agent filters and then lets the refreshed result set represent the requested universe.

Confirmed actions

Some actions affect user-owned data and require explicit confirmation.

Action family	Confirmation required	Notes
Set scanner filters	No	Pure client UI state.
Switch scanner view	No	Pure client UI state.
Open market detail	No	Pure client UI state.
Create, update, or delete watches	Yes	Backend signs an action token and executes only after confirmation.
Create, update, or delete saved presets	Yes	User-owned data.
Update notification settings	Yes	User-owned notification configuration.
Mark alert read	Yes	User-owned alert state.
Buy, sell, trade, place order, cancel order	Blocked	Trading and order actions are outside the agent boundary.

Confirmable actions are signed with a short-lived backend token. The confirm endpoint verifies the token signature, expiry, action payloads, and user id before executing anything.

Example requests

Find a smart-money category

find football markets with smart money over 75

Expected behavior: use football-related tags, set a smart-money threshold, show preview markets, and offer Apply filters.

Find expiring weather markets

show weather markets ending today with liquidity

Expected behavior: use the Weather tag, exclude expired outcomes, set an expiry window for today, and prefer liquidity filtering if the request asks for it.

Prepare watches

watch the matching markets

Expected behavior: prepare watch actions for the preview or selected markets, then require explicit confirmation before creating any watches.

Trading request

buy the best one

Expected behavior: block the trading action and redirect the user toward research/filtering. The agent cannot place or prepare orders.

Current limitations

The chat is an early beta feature.
The planner can fall back to rule-based behavior when LLM planning is unavailable.
The preview is snapshot-based, not a live order book.
Search is still text matching; broad categories should be tags.
Smart Money is a holder/PnL context signal, not a prediction model.
The agent can prepare account actions only through the confirmation flow.

AI Chat