Run a swarm prediction — graph build, persona generation, multi-agent simulation, report.

IMPORTANT: Enrich the prompt before calling. The engine extracts named entities to create personas. Add specific people, companies, organizations, and opposing viewpoints. Show the enriched prompt to the user for confirmation first.

If the user provides a document (PDF, MD, TXT), call upload_document first and pass the returned document_id.

Returns immediately with simulation_id. Call simulation_status to wait for completion — each call blocks up to 50s for the next state change, so you only need a few. When status returns state=COMPLETED, the full report is included inline.

Check the progress of a running or completed simulation. Long-polls by default — blocks up to 50s waiting for a state change (phase transition, new round, new actions, completion). When state=COMPLETED, includes the full prediction report inline.

Lifecycle: CREATED → GRAPH_BUILDING → GENERATING_PROFILES → READY → SIMULATING → COMPLETED/FAILED/CANCELLED/INTERRUPTED.

Generate and retrieve the prediction report for a completed simulation. If the report hasn't been generated yet, triggers generation (may take 1-3 minutes). Returns a detailed markdown analysis ready to display as an artifact in the side panel. Pass force_regenerate=true to rebuild an already-cached report.

Chat with a specific simulated agent to understand their perspective, reasoning, and predicted behavior. The agent responds in character based on their persona and simulation experience.

List past simulation runs with their status and metadata.

Search past simulations by topic, project name, or simulation ID.

Upload a document for use in simulations. LIMITS: Max 10MB, PDF/MD/TXT only. The server extracts text server-side (PyMuPDF for PDFs). Returns a document_id to pass to create_simulation. NOTE: Only works with local file paths (stdio transport). For remote/hosted mode, the client skill uploads via HTTP instead.

Access simulation data: agent profiles, configuration, action logs, social media posts, round-by-round timeline, per-agent activity stats, and interview history. Paginated — use offset to get more results when has_more is true.

Stop a running simulation. SIGTERMs the subprocess immediately and marks the simulation as stopped. Partial action log is preserved — you can still call get_report or simulation_data on a cancelled simulation for whatever data was produced before cancellation. Use this when a simulation is taking too long, was started by mistake, or is producing bad output you want to abort.