# Intent KG (ListeningMind)

> Give a topic and it builds a graph of intent elements (entry situations, choice criteria, brands, pitfalls, thresholds and more) and their relations, with evidence grades, from ListeningMind search data (related searches, clusters, search journeys, SERPs and AI Overviews). Used by marketers, product planners and AI agents that need grounded answers. Stored graphs are reused at 0 credits through the v1 and v2 APIs and 21 export formats. Markets: Korea, Japan, US.

Korean: 한 토픽에 대해 사람들이 무엇을 왜 찾고 어떻게 고르는가(인텐트 지식 그래프) · Japanese: あるトピックについて人が何を、なぜ探し、どう選ぶか(インテント知識グラフ)

## Use it as an agent
- [MCP server](https://daas-intent.listeningmind.ai/mcp): Streamable HTTP, JSON-RPC. 50 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-intent.listeningmind.ai/.well-known/openapi.json): the same tools as a REST contract (operationId = tool name)
- [agents.md](https://daas-intent.listeningmind.ai/agents.md): step-by-step guide · [API catalog](https://daas-intent.listeningmind.ai/.well-known/api-catalog) · [MCP server card](https://daas-intent.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-intent.listeningmind.ai/_lm/auth/signup); other changes over MCP need the member's agent key (LM-User-Key header, created at https://daas-intent.listeningmind.ai/_lm/account)

## What you give and what you get
- Inputs: Topic (required), market (kr/jp/us). Optional: chosen meaning (sense_id) and seeds, seed plan id, scale (standard/extended), parent run for a child topic, force a new snapshot.
- Outputs: Graph with nodes, relations, evidence grades, limits and readiness (graph, tree, map and data tabs), search journey analysis, decision and question packs, node dossier (MD/HTML/PDF), 21 exports (JSON, Agent Pack, Claims, JSON-LD, RDF family, GraphML, Neo4j, CSV, XLSX and more), single-file HTML bundle.
- Cost: One standard build costs about 35,000-37,000 Data API credits (median of 49 recent standard runs about 37,000) plus LLM calls and takes 2-6 minutes (up to about 9). Extended costs more; a child run reusing parent clusters costs about 14,000 less. A standard run of the same topic and market within about 20 hours is reused at 0 credits. Meaning resolution is one LLM call; a seed plan is up to about 3,000 credits. Reading stored runs, exports, v1 and v2 cost 0 credits.

## How a result is made (in order)
1. `lookup_topic`: Use an existing graph at 0 credits if one matches.
2. `check_launch`: Before building, check existing runs, parent reuse and the credit estimate.
3. `resolve_topic`: Resolve the meaning; if ambiguous, let the person pick a candidate.
4. `start_build`: Build the graph after the person confirms (spends credits).
5. `get_job`: Read progress until status is done.
6. `get_ontology_digest`: Read the result digest.
7. `get_decision_pack`: See what can be claimed under the evidence rules.
8. `get_question_pack`: Split one real customer question into answerable parts and missing evidence.
9. `get_dossier_md`: Get a readable dossier.
10. `export_run`: Export in the needed format.
11. `compare_runs`: Compare with an earlier run of the same topic.
12. `plan_rerun`: For a new snapshot, check conditions and cost first.
13. `rerun_build`: Re-run with the same conditions after confirmation.

Run stages reported by the app: resolve → discover → serp → gate → ontology → done → error

## Method (how the analysis works)
1. Resolve what the topic means first; if it is ambiguous, a person picks a meaning candidate and its seeds.
2. Collect related searches, clusters and search journeys for the topic.
3. Collect SERPs and AI Overviews.
4. Run a readiness gate and collect more widely when the data is thin.
5. Extract typed nodes (entry situations, choice criteria, brands, pitfalls, thresholds and more) and their relations with evidence grades.
6. Store the graph so lookups, decision and question packs and exports reuse it at 0 credits.

## Reading the result
- readiness.status and ontology.limits tell how complete the graph is and what it cannot support.
- The digest from lookup_topic or get_ontology_digest groups CEPs, KBFs, brands, pitfalls, conventions, heuristics, thresholds and alternatives by type; get_schema explains each type.
- Evidence grades on nodes and relations decide what can be claimed; get_decision_pack applies them and returns a gate verdict.
- get_question_pack splits one customer question into answerable conditions, weak ones and missing evidence.
- stats.finder_credits and stats.serp_credits record the build cost; journeys and clusters show how much evidence was collected.

## Requests this app answers well
- Summarize, with evidence, what people check and what they watch out for when choosing an e-bike
- If a customer asks 'recommend a gentle sunscreen for sensitive skin', split what we can answer with evidence from what is missing
- Compare the robot vacuum graph from three months ago with now and tell me which choice criteria changed
- If there is an air fryer topic graph for the US, export it as JSON-LD

## Continue in another app
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt) (MCP `https://daas-wiki.listeningmind.ai/mcp`): When a brand site in the same category needs wiki pages and an action plan tied to demand. Carry: The run (run_id, or topic and gl); Brand Wiki imports its decision layer as demand data and its knowledge layer as category context at 0 credits.
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt) (MCP `https://daas-icss.listeningmind.ai/mcp`): When you want to run a survey or FGD with a synthetic panel grounded on this topic. Carry: The topic and market; ICSS get_evidence and its grounding pack read stored Intent KG runs without new builds.

## 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
- `lookup_topic` (read, GET /api/v1/lookup): Main agent entry point: matches a topic to the best stored finished run and returns its digest (sense, readiness, CEPs, KBFs, brands, pitfalls, conventions, heuristics, thresholds, alternatives, journey summary, limits, link to the page). Never builds. If nothing matches it returns match=false with reason no_matching_run; then use check_launch and start_build.
- `lookup_or_build_topic` (run, GET /api/v1/lookup): Same as lookup_topic, but when no stored run matches it starts a build (joins a running build of the same topic if one exists). With wait=0 it returns job_id at once; with wait up to 600 seconds it waits and returns the digest if the build finishes. Spends about 35,000-37,000 Data API credits when a build starts; ask the person first. The server may disable builds through this API (reason build_disabled).
- `check_launch` (read, GET /api/launch_check): Before building a topic, returns finished runs of the same topic and market (up to 5, reuse them instead of rebuilding), whether a parent run's clusters can be reused for a cheaper child run, a scope verdict for the child topic, and credit estimates for a child run and a standalone standard run. Starts nothing.
- `resolve_topic` (run, POST /api/resolve): Stage 0: decides what the topic word means before collecting data. Returns query, ambiguous (true when several meanings are plausible) and candidates, each with id, label and seeds. If ambiguous, let the person pick a candidate, then pass sense_id, seeds and the whole result as resolution to start_build. Results are cached per topic and market for 15 minutes. One LLM call, no Data API credits.
- `create_seed_plan` (run, POST /api/seed_plan): Optional alternative to resolve_topic: widens the input into real nearby search terms using cheap lookups (two related-keyword lists plus keyword info) and proposes seeds and a journey allocation with a cost estimate. Does not build. Returns a plan with id, seeds, allocation and credits; pass the id as seed_plan_id (optionally with edited seeds) to start_build.
- `get_seed_plan` (read, GET /api/seed_plan/{plan_id}): Returns a saved seed plan by id (topic, gl, seeds, allocation, credit estimate).
- `start_build` (run, POST /api/build): Builds an Intent Knowledge Graph for a topic: resolves the meaning, collects related searches, clusters, search journeys and SERPs/AI Overviews, then extracts typed nodes (CEP, KBF, brands, pitfalls, thresholds and more) and relations with evidence grades. Returns job_id. If the same topic and market is already building it returns that job with joined=true; if a standard run of the same topic finished within about 20 hours it returns that run with reused=true at 0 credits (set force=true for a new snapshot). Ask the person before calling.
- `get_job` (read, GET /api/jobs/{run_id}): Returns a build's status (queued, running, done, error), progress log entries (stage, pct, msg, extra), error, duration, config, sense, seeds, stats and readiness. Repeat until status is done or error, then read the graph with get_result, get_tree or get_ontology_digest.
- `get_result` (read, GET /api/jobs/{run_id}/result): Returns the pipeline result of a run: ontology (nodes, edges, limits, readiness, spec check, journey verdicts), keywords, sense, seeds and stats. slim=1 drops the bulky serp, clusters, journeys and keyword detail; use it unless you need raw evidence.
- `get_ontology_digest` (read, GET /api/v1/ontology/{run_id}): Returns a specific run in the stable v1 format. view=digest gives the same digest as lookup_topic (grouped nodes, relations, readiness, limits, journey summary); view=full returns the whole ontology graph.
- `get_tree` (read, GET /api/jobs/{run_id}/tree): Returns the graph as a hierarchy rooted at the topic (the tree tab of the page).
- `get_journeys` (read, GET /api/jobs/{run_id}/journeys): Returns the search journey analysis computed from the run's stored path_finder data: where searches flow before and after the topic, alternatives weighed, and verifiability.
- `get_decision_pack` (read, GET /api/v2/decision-packs/{run_id}): Returns a decision evidence pack for a finished run: nodes and edges with evidence, a gate verdict, limits, sources and verification tasks, shaped for a purpose. Use it when an agent must decide what it can safely claim. 404 if the run does not exist, 409 if not completed, 410 if archived.
- `get_question_pack` (read, GET /api/v2/question-packs/{run_id}): For one real customer question, splits what the run can answer: conditions it can answer, weak ones, missing product evidence and content to improve. Give conditions explicitly when possible; otherwise they are split from the question and the gate may say NO_CONDITIONS.
- `get_dossier_md` (read, GET /api/jobs/{run_id}/dossier.md): Returns a readable dossier of the run in Markdown: each tree node explained with evidence, journeys and approved concepts. Best text version of a run page for an agent.
- `get_dossier_html` (read, GET /api/jobs/{run_id}/dossier.html): Returns the same dossier as an HTML page. By default it is laid out for printing; print=1 gives the screen layout.
- `download_dossier_pdf` (read, GET /api/jobs/{run_id}/dossier.pdf): Renders the dossier to PDF with headless Chromium and returns the file. Can take up to a few minutes for large runs.
- `export_run` (read, GET /api/jobs/{run_id}/export.{fmt}): Downloads the run's graph in one of 21 formats: json (full original), agentpack (compact conclusions, evidence and limits for agents), claims (JSONL claims with sources), jsonld, ttl, rdfxml, nt, trig, nq, owl, skos, tbox (schema), shacl (shapes), graphml, gexf, dot, neo4j (zip of CSVs), csv (triples), xlsx, md (mindmap), bundle (zip).
- `get_export_audit` (read, GET /api/jobs/{run_id}/export_audit): For each export format, measures what is kept or lost (labels, definitions, quotes, volumes, sources, edges) by checking the actual exported files. Use it to pick a format.
- `download_bundle` (read, GET /api/jobs/{run_id}/bundle.html): Returns one self-contained HTML file with all tabs and data of the run that opens in a browser without the server (read-only). Use it to share a run outside the internal network.
- `get_run_health` (read, GET /api/jobs/{run_id}/health): Scores where in the pipeline this run became thin (per-node checks and first attribution), using thresholds the pipeline already uses.
- `get_shacl_report` (read, GET /api/jobs/{run_id}/shacl): Validates the run's data graph against the SHACL shape graph (pyshacl, no inference) and returns the conformance result, violations and links to the shapes file.
- `get_shacl_spec` (read, GET /api/schema/spec.shacl.ttl): Returns the SHACL shapes (Turtle) that define valid relations, evidence and entailment rules for all runs.
- `get_schema` (read, GET /api/v1/schema): Describes the vocabulary: node types and layers, relations and their signatures, evidence grades, adjudication rules and fingerprints. Read it once to understand node types before using the graph.
- `preview_conform` (read, POST /api/jobs/{run_id}/conform): Dry run: shows which relations in a stored run would be rewritten by the current conformance rules (off-spec count before and after, list of changes). Saves nothing.
- `apply_conform` (action, POST /api/jobs/{run_id}/conform): Applies the current conformance rules to a stored run and saves it; each changed relation keeps its original direction and name in provenance and a note is added to limits. No credits. Requires write access.
- `explain_highlight` (run, POST /api/explain): Asks the model to explain one highlight of the graph using only the facts you send (why it matters, structure, market, marketing and product implications, caveat). The model may not add numbers or brands not in facts. Results are cached per run, title and facts.
- `list_reviews` (read, GET /api/reviews): With run_id: nodes of that run that need human review, with features, predicted approval and any AI suggestion. Without run_id: all review decisions so far and stats.
- `ai_suggest_reviews` (run, POST /api/reviews/ai_suggest): Runs AI suggestions (approved, rejected, needs_edit) for all review items of a run, in batches of 25 per LLM call. Suggestions are advisory and shown next to items in list_reviews. Requires write access.
- `set_review` (action, POST /api/reviews): Saves a human review decision for one node key. Requires write access; the reviewer is recorded from the token or network plus the optional name.
- `list_concepts` (read, GET /api/concepts): Lists concept candidates for a topic (nodes reproduced across runs of the same topic) and their approval status.
- `set_concept` (action, POST /api/concepts): Approves (verify) a reproduced node as a stable concept with an id, or retires an approved concept. Only keys listed by list_concepts can be verified. Requires write access.
- `get_run_concepts` (read, GET /api/jobs/{run_id}/concepts): Returns which nodes of this run map to approved concepts ({node_id: concept_id, label, version, due}).
- `get_consensus` (read, GET /api/consensus): Overlays recent runs of the same topic and returns how often each node and relation appears and how stable it is; nodes reproduced in at least k of n runs are marked entailed.
- `list_topics` (read, GET /api/topics): Lists topics that have finished runs, to choose topics for a combined graph.
- `get_related_topics` (read, GET /api/topics/related): Returns other topics that share identity keys with this topic, with the shared concepts as evidence.
- `search_nodes` (read, GET /api/xindex): Searches nodes across all runs by text (cross-run index), optionally filtered by node type.
- `list_contradictions` (read, GET /api/xindex/contradictions): Lists pairs of claims from different runs with similar content but different numbers.
- `list_runs` (read, GET /api/runs): Lists saved runs newest first (id, topic, gl, status, created, finished, duration, counts, config) plus store stats. Use topic to filter.
- `list_runs_v1` (read, GET /api/v1/runs): Light v1 list of runs (run_id, topic, gl, status, created, node and edge counts, readiness) for agents checking which topics already exist.
- `get_run` (read, GET /api/runs/{run_id}): Returns the full record of one run: metadata, config snapshot, execution log and result. Large; prefer get_result with slim=1 or get_ontology_digest.
- `get_report_robots` (read, GET /api/runs/{run_id}/robots): Returns whether search engines may index this run's report pages (robots index or noindex). Read only; no credits.
- `compare_runs` (read, GET /api/compare): Compares two runs of the same topic (e.g. 3 months apart): added, removed and changed nodes and relations, with a noise floor from repeated runs. Warns if topics or markets differ.
- `compare_runs_v1` (read, GET /api/v1/compare): Stable v1 version of compare_runs for agents: matches nodes by key, then by evidence keywords; no noise floor.
- `plan_rerun` (read, POST /api/runs/{run_id}/rerun): Dry run of rerun_build: returns the inherited conditions (topic, gl, sense, seeds, scale, overrides, parent run), the config items that changed since then, the credit estimate and budget. Starts nothing.
- `rerun_build` (run, POST /api/runs/{run_id}/rerun): Builds a new snapshot of a finished run with the same inputs (topic, gl, sense, seeds, scale, parent). Joins a running build of the same topic if any. Returns the plan plus job_id; poll get_job. Ask the person first.
- `delete_run` (delete, DELETE /api/runs/{run_id}): Deletes a run from the store. Requires write access. Returns {deleted, by}.
- `delete_review` (delete, DELETE /api/reviews/{key}): Deletes one stored review decision by key. Changes shared data.
- `clear_pins` (delete, DELETE /api/pins): Removes pinned items. Changes shared data.
- `reindex_runs` (action, POST /api/runs/reindex): Rebuilds the run index from stored files. Changes shared data; no credits.

## Pages
- [Intent KG home](https://daas-intent.listeningmind.ai/): Main screen: topic input and build, run history, combined graph and guide tabs.

## Limits
- Markets: kr, jp, us only. A build of a topic and market already in progress is joined instead of duplicated, and a standard run within about 20 hours is reused (use force for a new snapshot). Builds are rate-limited per caller (default 10 per hour) and reserve credit budget before starting. Scale deep is not open. Do not use the SSE stream; call get_job repeatedly. The store keeps 200 runs; older runs keep their link but lose their body (v2 then returns 410).
- Auth: Reads need no credentials on the internal network. Builds, re-runs, seed plans, deletes, reviews, concepts, explain, AI review and apply_conform need X-Onto-Token: <IKG key> or Authorization: Bearer <IKG key> unless the caller comes from a trusted network.

## 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`)
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt): Synthetic consumer panel conditioned on search intent, for surveys and FGDs (MCP `https://daas-icss.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