# ICSS (ListeningMind)

> ICSS (Intent-Conditioned Silicon Sampling) samples synthetic respondents from intent states observed in search behavior (CEP, nano intent, KBF, constraint, avoidance, consideration, journey stage) instead of demographics, and runs surveys, FGDs and 1:1 chats with them. Marketers and researchers use it to test hypotheses before real fieldwork. Data comes from ListeningMind search data (DaaS, SERP) plus stored CEP Finder and Intent KG runs, for Korea, Japan and the US. It also includes a distinctive brand asset (DBA) recognition test.

Korean: 검색 의도로 조건화한 합성 소비자 패널로 설문·FGD를 돌려 보는 앱 · Japanese: 検索意図で条件づけた合成消費者パネルで調査・FGDを行うアプリ

## Use it as an agent
- [MCP server](https://daas-icss.listeningmind.ai/mcp): Streamable HTTP, JSON-RPC. 31 app tools plus app_guide, result store tools (results_sync, results_list, results_get, results_compare, results_export) and settings sweeps (plan_batch, batch_status)
- WebMCP: every page of this app registers the same tools in `document.modelContext` for a browser agent; calls that spend credits ask the person on the page
- [OpenAPI](https://daas-icss.listeningmind.ai/.well-known/openapi.json): the same tools as a REST contract (operationId = tool name)
- [agents.md](https://daas-icss.listeningmind.ai/agents.md): step-by-step guide · [API catalog](https://daas-icss.listeningmind.ai/.well-known/api-catalog) · [MCP server card](https://daas-icss.listeningmind.ai/.well-known/mcp/server-card.json)
- Every page answers `Accept: text/markdown` with a markdown version
- Tools of kind run or delete spend credits or delete data: over MCP the call returns confirm_url for a person, then call confirmation_status
- Accounts: reading results and history is open. Starting a run or changing data needs a ListeningMind member: the person approving confirm_url signs in or [signs up](https://daas-icss.listeningmind.ai/_lm/auth/signup); other changes over MCP need the member's agent key (LM-User-Key header, created at https://daas-icss.listeningmind.ai/_lm/account)

## What you give and what you get
- Inputs: Brand or category keyword(s), market (kr/jp/us); optional: 2-5 comparison brands, panel conditions (market distribution or one cluster, size), survey questions. For the asset test: target brand, aliases, competitors, masked asset descriptions or images.
- Outputs: Search data summary (demand, gender/age, journeys, clusters), CEP state distribution with evidence labels, grounding pack with sufficiency verdict, synthetic panel roster (7-element state vectors), survey result distributions and open-answer themes, FGD transcript and summary, a saved story (#run=ID), per-asset fame and uniqueness quadrant.
- Cost: Topic analysis, comparison and SERP collection use the Data API and are cached 12 h on the server (exact credits are not reported by the app). Reusing stored CEP and KG runs costs 0 credits. A new CEP build costs about 30k-40k (standard) or a measured 66k-133k (deep) credits; a KG build 38k-46k. Surveys and FGDs make one LLM call per respondent batch (Gemini 2.5 Flash by default). The asset test uses LLM calls only (assets x models x repeats).

## How a result is made (in order)
1. `get_config`: Check that the LLM and data back-ends are on.
2. `analyze_topic`: Get search-behavior data for each keyword; merge several keywords yourself.
3. `find_cep_run`: Look for a stored CEP Finder run for the topic (free).
4. `get_cep_states`: Load that run as the intent-state distribution P(IntentState).
5. `start_cep_build`: Only if none exists, start a new CEP analysis (spends credits, needs confirmation).
6. `get_cep_job`: Poll until done, then load the result with get_cep_states.
7. `get_grounding_pack`: Check for a stored grounding pack.
8. `build_grounding_pack`: If missing, build one from stored runs only (0 credits).
9. `get_grounding_job`: Poll the grounding job until done.
10. `get_evidence`: Get the CEP and KG evidence summary for persona grounding.
11. `probe_ai_overview`: Probe AI Overviews to fill category-specific avoidance and criteria.
12. `get_cluster_serp`: For a custom panel on one cluster, collect that cluster's SERP evidence.
13. `get_keyword_info`: Add gender/age and volume for the chosen keywords.
14. `ask_llm`: Generate question ideas, survey batches, FGD turns and summaries with state-first persona prompts.
15. `save_run`: Save the snapshot on the server so it opens at #run=ID.
16. `list_runs`: Find saved stories to reopen.

Run stages reported by the app: start → cep → kg → related → assemble

## Method (how the analysis works)
1. Pull search-behavior data per keyword (demand, gender and age, journeys, clusters, SERP) and compare brands side by side if given.
2. Load a stored CEP Finder run as the intent-state distribution P(IntentState), building a new one only when none exists.
3. Ground personas with the CEP Finder and Intent KG evidence summary and probe AI Overviews for category-specific avoidance and criteria.
4. Sample a synthetic panel from intent states (CEP, nano intent, KBF, constraint, avoidance, consideration, journey) instead of demographics.
5. Run surveys, FGDs or 1:1 chats with state-first persona prompts, aggregate the answers and save the story.

## Reading the result
- results holds the answer distribution per question and the open-answer themes; respondents and panel_size tell how many synthetic answers they rest on.
- The panel roster shows each respondent's 7-element state vector, so you can trace an answer back to a CEP and its constraints.
- cepStates and the grounding pack's sufficiency verdict show how well the panel is grounded in search evidence.
- In the asset test, each asset gets fame, uniqueness and a quadrant.
- Synthetic and AI answers are not consumer responses; treat them as hypotheses to calibrate with a real panel.

## Requests this app answers well
- Run a price sensitivity survey on a 300-person synthetic panel of sunscreen buyers split by search intent
- Run a 6-person FGD on protein drinks in Japan and summarize why people hesitate to buy
- Test whether AI can name our brand from a masked description of our pack
- Before real research, check which of these 3 concept lines a panel prefers, as a hypothesis

## Continue in another app
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt) (MCP `https://daas-prompt.listeningmind.ai/mcp`): When the panel shows which situations and criteria drive choice and you want to see whether AI answers recommend the brand there. Carry: The keyword, own brand and comparison brands, and the CEPs and KBF that mattered in the answers.

## Using the screens (browser agents)
- `describe_screen`: menus, tabs, fields and buttons of the current screen, and what the page is for
- `go_to`: open a menu or page of this app by its label or path
- `fill_field`: type a value into a field by its label (never presses run; runs go through the run tools, which ask the person)
- `read_this_page`: the text and ids of what the person is looking at

## Tools
- `get_config` (read, GET /api/config): Returns which back-ends are switched on: llm (bool), provider, chain, model, daas (bool), maistro (bool). Call first; if llm is false the survey, FGD and question generation cannot run.
- `analyze_topic` (run, POST /api/analyze): Pulls the full search-behavior analysis for one keyword (demand, gender/age audience, search journeys, behavior clusters, SERP) from the maistro-lmpipe analyze service. This is the first data step of the app; the UI calls it once per keyword and merges the results in the browser. Cached on the server for 12 hours. Returns the raw analysis JSON.
- `get_keyword_info` (run, POST /api/daas/keyword_info): Calls the ListeningMind keyword_info endpoint through the app proxy: monthly volume, trend, competition, CPC, gender/age demography and intents for a list of keywords. The UI uses it to add demography and volume to the chosen cluster keywords. Cached 12 hours.
- `get_evidence` (read, POST /api/evidence): Looks up existing CEP Finder runs and Intent KG runs that match the topic and returns a short evidence summary (top CEPs with keywords, KBF, constraints, brands; KG nodes such as KBF, CEP, heuristics, pitfalls). Reads stored runs only, never builds. Returns {topic, locale, cep, kg, cep_error, kg_error}.
- `compare_brands` (run, POST /api/compare): Runs the maistro-lmpipe compare analysis for 2 to 5 brands or items in one market (search demand, audience and intent side by side). The UI starts it when the user enters comparison items. Cached 12 hours.
- `get_category_journey` (run, POST /api/cdj): Calls the maistro-lmpipe category scope analysis that the UI uses as the substrate for the 5-stage consumer decision journey (CDJ) view. Returns the top_n category keywords with stage signals. Cached 12 hours.
- `get_analysis_prompt` (read, GET /api/prompts/{prompt_id}): Fetches a purpose-specific analysis prompt template from maistro-lmpipe (first 4,000 chars of analysis_prompt). The UI uses it to build insight prompts. Returns {id, analysis_prompt, version}.
- `probe_ai_overview` (run, POST /api/aio-probe): Collects Google AI Overview and People Also Ask text for the keyword plus probe queries such as 'keyword + downsides / side effects / caveats' in the market language. The UI uses it to fill category-specific avoidance and decision criteria in the intent state vector. Returns {keyword, gl, queries, aio:[{text, from}], paa:[{q, from}]}.
- `get_cluster_serp` (run, POST /api/cluster-serp): For up to 6 keywords of the chosen search cluster, collects AI Overview text, People Also Ask, people-also-search-for and top organic titles, merged and de-duplicated. The UI uses it when a custom panel is built from one cluster. Returns {aio, paa, pasf, organic, per_keyword, n_keywords}.
- `find_cep_run` (read, POST /api/cep/find): Searches the CEP Finder run history for a run that matches the topic in the same market (prefers deep over standard over quick, and the market language). Free. Returns {found, run, candidates:[{run_id, topic, keyword, gl, depth, score}]}.
- `get_cep_states` (read, POST /api/cep/states): Converts a CEP Finder run (cep_map) into the ICSS intent-state distribution: per CEP weight, volume, nano intents, KBF, constraints, avoidances, alternatives, thresholds, brands, journey, demography with evidence labels. This is P(IntentState) used to sample the synthetic panel. Free.
- `start_cep_build` (run, POST /api/cep/build): Starts a new CEP Finder analysis for the keyword when no stored run exists. Returns {job_id}; poll get_cep_job, then call get_cep_states with the finished run_id. Spends Data API credits.
- `get_cep_job` (read, GET /api/cep/job/{job_id}): Returns the CEP Finder job state: status, progress [{pct, msg, stage}] and run_id when finished. Repeat until status is done, completed or error.
- `get_grounding_pack` (read, GET /api/icss/grounding): Reads the stored deep-grounding pack for a topic and market (CEP map states, related CEP runs, KG nodes and sentences with evidence grades, sufficiency verdict, credits). Returns {found:false} when none exists. Use full=1 for the whole pack as the UI does.
- `list_grounding_packs` (read, GET /api/icss/grounding/list): Lists all stored grounding packs: {items:[{topic, gl, built_at, sufficiency, stats, credits}]}.
- `build_grounding_pack` (action, POST /api/icss/ground): Builds and saves a grounding pack from existing CEP Finder and Intent KG runs for the topic and related topics, without starting any new build (0 credits). Returns {job_id}; poll get_grounding_job.
- `build_grounding_pack_new` (run, POST /api/icss/ground): Same as build_grounding_pack but also starts a new CEP Finder build (cep_build) and/or a new Intent KG build (kg_build) when stored runs are missing. Requires confirm_credits=true, which this tool sends. Returns {job_id}; poll get_grounding_job.
- `get_grounding_job` (read, GET /api/icss/ground/job/{job_id}): Returns the grounding job: status (running, done, error), stage (start, cep, kg, related, assemble), steps log, and a pack summary when done. Repeat until done or error, then call get_grounding_pack with full=1.
- `ask_llm` (run, POST /api/llm): Sends one prompt to the server LLM chain (Gemini first, then OpenAI on failure; 75 s limit per provider) and returns {text, provider}. The UI builds every synthetic-respondent prompt in the browser (state-first persona: CEP, nano intent, KBF, constraint, avoidance, consideration, journey, then demography as reference) and calls this for question suggestions, survey batches, open-answer theming, FGD turns and summaries. An agent must build those prompts itself.
- `save_run` (action, PUT /api/runs/{run_id}): Saves a full session snapshot (data, panel, questions, results, FGD log, chats) on the server so it opens at /#run=<id> on any PC. The UI does this automatically after a survey finishes. The id must match run_<letters/digits/_ 6-64>. Body limit 25 MB. Returns {ok, id, bytes}.
- `list_runs` (read, GET /api/runs): Lists stories saved on the server, newest first: {runs:[{id, q, locale, label, n, mode, at, panelMeta, hasResults, fgdN, chatN, bytes}], total}.
- `get_run` (read, GET /api/runs/{run_id}): Returns the full saved snapshot of a story (cur, panel, questions, results, fgd, chatLogs, gateLog, dba).
- `delete_run` (delete, DELETE /api/runs/{run_id}): Moves a saved story to the server trash; it disappears from every PC's archive. Returns {ok, id}.
- `check_asset_masking` (run, POST /api/dba/mask-check): Brand asset test (DBA) step 1: checks that each asset description contains no target or competitor brand name and, for images, transcribes visible text with a vision model to detect brand names. Returns {assets:[{id, img}], checks:[{id, ok, textLeaks, imageText, imageLeaks, note}]}. Uploaded data-URL images are stored and replaced by /api/dba/img paths.
- `start_dba_ai_test` (run, POST /api/dba/ai-test): Brand asset test, AI-response mode: asks Gemini and OpenAI directly (no persona) 'which brand is this?' for every masked asset, reps times per model, then scores fame and uniqueness on first-mentioned brand and saves the test. This is a GEO metric, not consumer response. Returns {job}; poll get_dba_job.
- `get_dba_job` (read, GET /api/dba/job/{job_id}): Returns {id, status (running, done, error), done, total, error, testId} and, when done, the full scored test. Repeat until done or error.
- `ask_dba_llm` (run, POST /api/dba/ask): One vision-capable LLM call used by the synthetic-panel asset test: the UI sends a batch prompt built from ICSS personas plus up to 4 images and parses brand answers. Returns {text, provider, model}.
- `score_dba_synthetic` (action, POST /api/dba/score): Scores synthetic-panel answers (fame, uniqueness, quadrant, baseline) and saves the test. Send the same test fields plus responses collected with ask_dba_llm. Returns {test}.
- `list_dba_tests` (read, GET /api/dba/tests): Lists saved brand-asset tests with per-asset fame, uniqueness and quadrant. Filter by brand (exact name or alias), locale and kind. Returns {tests, total, providers}.
- `get_dba_test` (read, GET /api/dba/tests/{test_id}): Returns one saved test in full: brand, assets, responses, per-asset results, baseline, disclaimer.
- `get_dba_image` (read, GET /api/dba/img/{name}): Downloads a stored stimulus image referenced by a test asset (img field /api/dba/img/<name>).

## Pages
- [ICSS synthetic panel](https://daas-icss.listeningmind.ai/): Data lookup, panel building, survey, FGD, archive and asset test are all on this one page.
- [Reliability evaluation](https://daas-icss.listeningmind.ai/docs/reliability.html): Validation of synthetic results against real panel data.

## Limits
- Markets: kr, jp, us only. Panel sampling (state vectors, individual-difference axes), survey prompt construction, aggregation, the hallucination gate and CSV/Excel export run in browser code; the HTTP API provides data and a raw LLM call. To reproduce a UI result an agent must write the state-first prompts itself and call ask_llm. Results are kept in browser localStorage and on the server (/api/runs); the UI uploads automatically after a survey, an agent must call save_run itself. Synthetic and AI answers are not consumer responses and need calibration with a real panel. Builds spend credits; call them only after human confirmation.

## The ListeningMind apps (same account, same tools, call any of them)
Each app has `/mcp`, `/llms.txt`, `/agents.md` and WebMCP on its pages. `family_apps` and `recommend_app` return this list with addresses.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt): Diagnoses whether a product detail page can be cited by AI answers and used by shopping agents (MCP `https://daas-aco.listeningmind.ai/mcp`)
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt): Measures whether AI agents can get real tasks done on a website (MCP `https://daas-aoo.listeningmind.ai/mcp`)
- [Brand Finder](https://daas-brand.listeningmind.ai/llms.txt): Which brands lead search by generation or field, and what their brand assets are (MCP `https://daas-brand.listeningmind.ai/mcp`)
- [Brand Naming Agent](https://daas-naming.listeningmind.ai/llms.txt): Creates and checks brand name candidates grounded in search data (MCP `https://daas-naming.listeningmind.ai/mcp`)
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt): Turns a brand website into the entities, wiki pages and evidence AI assistants read (MCP `https://daas-wiki.listeningmind.ai/mcp`)
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt): In which situations do people start looking for this category (category entry point map) (MCP `https://daas-cep.listeningmind.ai/mcp`)
- [Creative Finder](https://daas-creative.listeningmind.ai/llms.txt): Finds purchase situations (CEP) in search data and drafts a creative, an image and a video for each (MCP `https://daas-creative.listeningmind.ai/mcp`)
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt): What category demand looks like in the next 3-6 months and when to launch or campaign (MCP `https://daas-forecast.listeningmind.ai/mcp`)
- [Funnel Leak Finder](https://daas-funnel.listeningmind.ai/llms.txt): Where category search journeys leak to competitors (MCP `https://daas-funnel.listeningmind.ai/mcp`)
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt): Checks whether a web page is ready to be read and cited by search engines and AI answer engines (MCP `https://daas-geo.listeningmind.ai/mcp`)
- [Intent KG](https://daas-intent.listeningmind.ai/llms.txt): What people look for about a topic, why, and how they choose (Intent Knowledge Graph) (MCP `https://daas-intent.listeningmind.ai/mcp`)
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt): Finds what consumers ask AI and builds managed brand prompts with AI visibility (MCP `https://daas-prompt.listeningmind.ai/mcp`)
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt): What is rising in search for a gender and age segment right now (MCP `https://daas-pulse.listeningmind.ai/mcp`)
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt): Which Smart Store products to grow, and how to rewrite their titles and detail pages in searchers' words (MCP `https://daas-store.listeningmind.ai/mcp`)
- [Taste Finder](https://daas-taste.listeningmind.ai/llms.txt): In what sensory and emotional words do people choose this (consumer taste report from search data) (MCP `https://daas-taste.listeningmind.ai/mcp`)
- [ListeningMind Data API](https://daas.listeningmind.ai/llms.txt): the search data behind every app (MCP `https://daas.listeningmind.ai/mcp`) · [glossary](https://daas.listeningmind.ai/en/glossary) · [all apps](https://daas.listeningmind.ai/en/apps)

## Optional
- ListeningMind data and other apps: https://www.listeningmind.com · contact m-support@listeningmind.com