### General Setup and Run

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Basic commands to copy the environment file, set up all necessary components, and start the development server.

```bash
cp .env.example .env
npm run setup:all
npm run dev
```

--------------------------------

### Start Neo4j Service

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Installs Neo4j using Homebrew and starts the service. For Linux, use the appropriate package manager command.

```bash
brew install neo4j && brew services start neo4j
```

--------------------------------

### Manual Local Ollama Setup

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Steps to manually set up Neo4j and Ollama locally, including starting services and pulling models.

```bash
# 1. Start Neo4j (macOS; for Linux: sudo apt install neo4j)
brew install neo4j && brew services start neo4j

# 2. Start Ollama & pull models
ollama serve &
ollama pull qwen2.5:32b
ollama pull nomic-embed-text
```

--------------------------------

### Common Preparation for Cloud API Installation

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Installs Neo4j locally and copies the environment file. Use 'sudo apt install neo4j' on Linux.

```bash
# Common prep for all three flavours
brew install neo4j       # macOS  (Linux: sudo apt install neo4j)
cp .env.example .env
```

--------------------------------

### Clone MiroShark and Install Dependencies

Source: https://github.com/aaronjmars/miroshark/blob/main/README.md

Clone the MiroShark repository, copy the example environment file, and paste your OpenRouter API key. The launcher will then check dependencies, start Neo4j, install frontend and backend, and serve the application.

```bash
git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
# Paste your OpenRouter key into the LLM_API_KEY / SMART_API_KEY /
# NER_API_KEY / OPENAI_API_KEY / EMBEDDING_API_KEY slots (same key,
# 5 places). Default lineup is Mimo V2 Flash + Gemini 3 Flash.
./miroshark
```

--------------------------------

### Copy Environment Example

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Copy the example environment file to .env to configure your local development settings.

```bash
cp .env.example .env
```

--------------------------------

### Clone MiroShark and Configure Environment

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Clones the MiroShark repository and copies the example environment file. This is the first step for the local quick start launcher.

```bash
git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
```

--------------------------------

### Full .env Reference Example

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/CONFIGURATION.md

A comprehensive list of all configurable environment variables for MiroShark, covering LLM, Smart model, Wonderwall, NER, Neo4j, Embeddings, Reranker, and more. Uncomment and modify variables as needed for your setup.

```bash
# ─── LLM (default — profiles, sim config, memory compaction) ───
LLM_PROVIDER=openai                # "openai" (default) or "claude-code"
LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL_NAME=qwen2.5:32b

# ─── Smart model (reports, ontology, graph reasoning — #1 quality lever) ───
# SMART_PROVIDER=openai
# SMART_MODEL_NAME=google/gemini-3-flash-preview          # Cloud preset

# ─── Wonderwall (agent sim loop — #1 cost driver, use cheapest viable) ───
# WONDERWALL_MODEL_NAME=xiaomi/mimo-v2-flash
# Optional: route Wonderwall to a custom OpenAI-compatible endpoint
# (self-hosted vLLM, Modal, custom fine-tune…). Both fields are
# optional — leaving either blank inherits LLM_BASE_URL / LLM_API_KEY.
# WONDERWALL_BASE_URL=https://your-endpoint.example.com/v1
# WONDERWALL_API_KEY=not-checked

# ─── NER (entity extraction — needs reliable JSON, no hidden CoT) ───
# NER_MODEL_NAME=google/gemini-3-flash-preview

# ─── Disable chain-of-thought on reasoning-capable OpenRouter models ───
# ~3x lower latency on Qwen3-Flash / Gemini-3-Flash. Flip to false
# per-deployment if a slot needs CoT.
LLM_DISABLE_REASONING=true

# ─── Claude Code mode (only when LLM_PROVIDER=claude-code) ───
# CLAUDE_CODE_MODEL=claude-sonnet-4-20250514

# ─── Neo4j ───
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=miroshark

# ─── Embeddings ───
EMBEDDING_PROVIDER=ollama          # "ollama" or "openai"
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_BASE_URL=http://localhost:11434
EMBEDDING_DIMENSIONS=768

# ─── Reranker (BGE cross-encoder, ~1GB one-time download) ───
RERANKER_ENABLED=true
RERANKER_MODEL=BAAI/bge-reranker-v2-m3
RERANKER_CANDIDATES=30             # pool size before rerank

# ─── Graph-traversal retrieval (Zep/Graphiti-style BFS from seed entities) ───
GRAPH_SEARCH_ENABLED=true
GRAPH_SEARCH_HOPS=1                # 1 or 2
GRAPH_SEARCH_SEEDS=5               # seed entities per query

# ─── Entity resolution (fuzzy + vector + optional LLM reflection) ───
ENTITY_RESOLUTION_ENABLED=true
ENTITY_RESOLUTION_USE_LLM=true

# ─── Automatic contradiction detection ───
CONTRADICTION_DETECTION_ENABLED=true

# ─── Community clustering (Leiden + LLM summaries) ───
COMMUNITY_MIN_SIZE=3
COMMUNITY_MAX_COUNT=30

# ─── Reasoning trace persistence (:Report subgraph with full ReACT decisions) ───
REASONING_TRACE_ENABLED=true

# ─── Web Enrichment (auto-researches public figures during persona gen) ───
# Also powers the /api/graph/fetch-url URL importer — models without native
# browsing must use an ":online" variant.
WEB_ENRICHMENT_ENABLED=true
# WEB_SEARCH_MODEL=google/gemini-3-flash-preview:online

# ─── Embedding batching ───
# How many texts per HTTP request. Higher is faster on graph builds;
# drop to 32 if your provider returns 413.
EMBEDDING_BATCH_SIZE=128

# ─── Anthropic prompt caching ───
# Attaches cache_control to the system message when the active model is
# Claude-family. ~10% cost on cache reads; big win on the ReACT report loop.
# Silent no-op for non-Anthropic models.
LLM_PROMPT_CACHING_ENABLED=true

# ─── Live oracle seeds (FeedOracle MCP) ───

```

--------------------------------

### Run Setup and Development Server with Claude Code

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Commands to set up all components and start the development server after configuring MiroShark to use Claude Code.

```bash
npm run setup:all && npm run dev
```

--------------------------------

### Start Simulation

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Once the simulation preparation is completed, you can start the simulation execution using its unique simulation ID.

```bash
# Once status is "completed", start simulation
curl -X POST /api/simulation/start \
  -d '{"simulation_id": "sim_..."}'
```

--------------------------------

### Example Environment Variables for Configuration

Source: https://github.com/aaronjmars/miroshark/blob/main/README_DEPLOYMENT.md

This example .env file demonstrates comprehensive configuration for LLM/Embedding providers, Neo4j connection settings, admin authentication, and multiple notification channels.

```dotenv
# LLM Provider Configuration
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Embedding Provider Configuration
EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_API_KEY=sk-...

# Neo4j Connection Settings
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Admin Authentication
ADMIN_AUTH_KEY=your_secret_admin_key

# Notification Channels
WEBHOOK_URL=https://your.webhook.url
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USER=user@example.com
EMAIL_PASSWORD=email_password
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...

# Other settings
DATABASE_URL=postgresql://user:password@host:port/database
```

--------------------------------

### Install and Initialize DKG Daemon

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/DKG.md

Installs the OriginTrail DKG daemon globally and initializes its configuration. Node.js v22+ is required. The init command can optionally fund a testnet wallet.

```bash
# OriginTrail's TypeScript daemon — Node 22+ required
npm install -g @origintrail-official/dkg

# Initialize: creates ~/.dkg/config.yaml, auto-funds a wallet on the
# testnet faucet. Use ``--no-fund`` to bring your own wallet.
dkg init
```

--------------------------------

### SMTP Configuration Examples

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/NOTIFICATIONS.md

These examples show different SMTP configurations for sending notifications. Choose the configuration that matches your email provider.

```env
SMTP_HOST=relay.internal
SMTP_PORT=25
SMTP_TO=research@example.com
```

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=miroshark-bot@example.com
SMTP_PASSWORD=<gmail-app-password>
SMTP_FROM=alerts@miroshark.app
SMTP_TO=research@example.com,ops@example.com
```

--------------------------------

### Clone MiroShark Repository and Configure Environment

Source: https://github.com/aaronjmars/miroshark/blob/main/README.md

Clone the MiroShark repository, navigate into the directory, copy the example environment file, and paste your OpenRouter API key into the specified fields. This is part of the initial setup for running MiroShark.

```bash
git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
# 将你的 OpenRouter 密钥粘贴到 LLM_API_KEY / SMART_API_KEY /
# NER_API_KEY / OPENAI_API_KEY / EMBEDDING_API_KEY 五个字段
```

--------------------------------

### Start Simulation Response

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

This is a successful response when starting a simulation. It confirms the simulation is running and provides initial status details.

```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_...",
    "status": "running",
    "current_round": 0,
    "max_rounds": 10,
    "runner_pid": 12345,
    "started_at": "2024-06-08T15:30:00Z"
  }
}
```

--------------------------------

### Start Neo4j Service

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Starts the Neo4j database service using system package managers. Use the appropriate command for your operating system (macOS or Linux).

```bash
brew services start neo4j  # macOS
sudo systemctl start neo4j  # Linux
```

--------------------------------

### Example .env Configuration

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/configuration.md

A comprehensive example of an .env file for configuring Miroshark, including LLM, database, embedding, and security settings.

```dotenv
# LLM Models
LLM_PROVIDER=openai
LLM_API_KEY=sk-proj-...your-openrouter-key...
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL_NAME=xiaomi/mimo-v2-flash

SMART_PROVIDER=openai
SMART_API_KEY=sk-proj-...same-or-different-key...
SMART_BASE_URL=https://openrouter.ai/api/v1
SMART_MODEL_NAME=google/gemini-3-flash-preview

# Database
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-neo4j-password

# Embedding
EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_BASE_URL=http://localhost:11434

# Webhook
WEBHOOK_URL=https://hooks.slack.com/...

# Security
MIROSHARK_ADMIN_TOKEN=your-admin-bearer-token
PUBLIC_BASE_URL=https://miroshark.yourdomain.com
```

--------------------------------

### Run Summary Tracking for Mixed Setups

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/cleanup/07-legacy.md

This line is a pricing-table lookup with current entries. The comment 'Tracked for mixed / legacy setups' refers to the data's purpose, not a conditional code path.

```python
RUN_SUMMARY_PRICING = {
    # ... pricing entries ...
}
```

--------------------------------

### Start DKG Daemon

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/DKG.md

Starts the DKG daemon, which will run on http://127.0.0.1:9200. The daemon uses the chain configuration from ~/.dkg/config.yaml.

```bash
# Start the daemon — runs on http://127.0.0.1:9200
dkg start
```

--------------------------------

### GET /api/simulation/{simulation_id}/replay.gif

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Get an animated GIF replay of the simulation. Note that this requires ffmpeg to be installed.

```http
GET /api/simulation/{simulation_id}/replay.gif HTTP/1.1
```

--------------------------------

### GET /api/simulation/{simulation_id}/replay.gif

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

Generates an animated GIF replay of a simulation. Requires ffmpeg to be installed.

```APIDOC
## GET /api/simulation/{simulation_id}/replay.gif

### Description
Generate animated GIF replay of simulation (requires ffmpeg).

### Method
GET

### Endpoint
/api/simulation/{simulation_id}/replay.gif

### Response
#### Success Response (200)
- **Response Body**: GIF (width=640, ~2fps, max 30 seconds)
```

--------------------------------

### POST /api/simulation/start

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Launches the execution of a prepared simulation.

```APIDOC
## POST /api/simulation/start

### Description
Launch simulation execution.

### Method
POST

### Endpoint
/api/simulation/start

### Request Body
- **simulation_id** (string) - Required - The ID of the simulation to start.

### Request Example
```json
{
  "simulation_id": "sim_..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains execution details.
  - **simulation_id** (string) - The ID of the simulation.
  - **status** (string) - The status of the simulation after starting (e.g., "running").
  - **current_round** (integer) - The current round of execution.
  - **max_rounds** (integer) - The maximum number of rounds for the simulation.
  - **runner_pid** (integer) - The process ID of the simulation runner.

#### Response Example
```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_...",
    "status": "running",
    "current_round": 0,
    "max_rounds": 10,
    "runner_pid": 12345
  }
}
```
```

--------------------------------

### Verified Endpoint with Filters

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/FEATURES.md

Example of a GET request to the verified endpoint, filtering for bearish calls with a recorded outcome.

```http
GET /api/simulation/public?verified=1&consensus=bearish
```

--------------------------------

### Minimum Required Configuration

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/CONFIGURATION.md

Sets up the essential environment variables for LLM, Neo4j, and embeddings. Ensure you replace placeholders like 'your-api-key' with actual credentials.

```bash
# LLM
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://openrouter.ai/api/v1     # or http://localhost:11434/v1 for Ollama
LLM_MODEL_NAME=xiaomi/mimo-v2-flash

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=miroshark

# Embeddings
EMBEDDING_PROVIDER=openai                     # or "ollama"
EMBEDDING_MODEL=openai/text-embedding-3-large
EMBEDDING_API_KEY=your-api-key
EMBEDDING_DIMENSIONS=768
```

--------------------------------

### Gallery Search with Filters

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/FEATURES.md

Example of a GET request to the public simulation endpoint with active filters for query, consensus, quality, sort, and page.

```http
GET /api/simulation/public?q=…&consensus=bullish&quality=excellent&sort=rounds&page=2
```

--------------------------------

### Smart Setup (Scenario Auto-Suggest)

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/FEATURES.md

Generates three scenario cards (Bull, Bear, Neutral) based on a document preview. These cards include a YES/NO question, probability band, and rationale.

```APIDOC
## POST /api/simulation/suggest-scenarios

### Description
This endpoint triggers the Smart Setup feature, which analyzes a document preview and suggests three market-style scenario cards to help users define a simulation prompt.

### Method
POST

### Endpoint
/api/simulation/suggest-scenarios

### Parameters
#### Request Body
- **document_preview** (string) - Required - A preview of the extracted text from the document.

### Response
#### Success Response (200)
- **scenarios** (array) - An array of scenario objects, each containing a question, probability band, and rationale.
- **scenario** (object)
  - **question** (string) - The YES/NO question for the scenario.
  - **probability_band** (string) - The initial probability band for the scenario.
  - **rationale** (string) - A one-sentence rationale for the scenario.
```

--------------------------------

### Get Detailed Run Status Response

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

This response provides detailed metrics for a simulation, including per-round and per-platform breakdowns. It is only available after the simulation has started.

```json
{
  "success": true,
  "data": {
    "rounds": [
      {
        "round": 1,
        "duration_seconds": 45,
        "twitter_posts": 40,
        "twitter_engagement": {
          "total_likes": 240,
          "total_retweets": 80
        },
        "reddit_posts": 25,
        "polymarket_trades": 10
      }
    ],
    "platforms": {
      "twitter": {
        "total_posts": 120,
        "avg_posts_per_agent": 2.4,
        "total_engagement": 1240
      },
      "reddit": {
        "total_posts": 75,
        "avg_posts_per_agent": 1.5
      }
    }
  }
}
```

--------------------------------

### POST /api/simulation/start

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/API.md

Launches the Wonderwall subprocess for simulation execution (Step 3).

```APIDOC
## POST /api/simulation/start

### Description
Launches the Wonderwall subprocess for simulation execution (Step 3).

### Method
POST

### Endpoint
/api/simulation/start

### Purpose
Launch Wonderwall subprocess (Step 3)
```

--------------------------------

### Launch MiroShark Local Launcher

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Executes the MiroShark launcher script for local development. This script handles dependency checks, starts Neo4j, installs dependencies, and launches the frontend and backend.

```bash
./miroshark
```

--------------------------------

### Configure Environment for Claude Code

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Copies the example environment file and sets the LLM provider to 'claude-code'. Optionally, a specific Claude Code model can be set.

```bash
cp .env.example .env
```

```bash
LLM_PROVIDER=claude-code
# Optional: pick a specific model (default uses your Claude Code default)
# CLAUDE_CODE_MODEL=claude-sonnet-4-20250514
```

--------------------------------

### Dockerfile for MiroShark Deployment

Source: https://github.com/aaronjmars/miroshark/blob/main/README_DEPLOYMENT.md

This Dockerfile installs Node.js and Python dependencies, copies source code, exposes ports, and starts the frontend and backend in development mode. It uses a Python 3.11 base image with uv for dependency management.

```docker
FROM python:3.11

WORKDIR /app

# Install Node.js and npm
RUN apt-get update && apt-get install -y nodejs npm

# Install Python dependencies using uv
COPY backend/requirements.txt .
RUN pip install uv
RUN uv pip install -r requirements.txt

# Copy frontend and backend source code
COPY frontend/ ./frontend/
COPY backend/ ./backend/

# Expose ports
EXPOSE 3000
EXPOSE 5001

# Start frontend and backend in development mode
CMD ["npm", "run", "dev"]
```

--------------------------------

### Install MiroShark CLI

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/CLI.md

Install the MiroShark CLI from a local checkout or run it directly without installation. Set the MIROSHARK_API_URL environment variable to target a remote deployment.

```bash
# From a checkout with the backend installed:

```

```bash
pip install -e backend/

```

```bash
miroshark-cli ask "Will the EU AI Act survive trilogue?"

```

```bash
# Or run directly — no install, no third-party deps:

```

```bash
python backend/cli.py --help

```

--------------------------------

### POST /api/simulation/start

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

Launches a simulation execution. The simulation must be in a 'prepared' state before starting. This operation spawns a long-running subprocess that continues in the background.

```APIDOC
## POST /api/simulation/start

### Description
Launch simulation execution (requires prepared state).

### Method
POST

### Endpoint
/api/simulation/start

### Request Body
- **simulation_id** (string) - Required - The ID of the simulation to start.

### Request Example
```json
{
  "simulation_id": "sim_..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains simulation execution details.
  - **simulation_id** (string) - The ID of the simulation.
  - **status** (string) - The current status of the simulation (e.g., "running").
  - **current_round** (integer) - The current round number.
  - **max_rounds** (integer) - The maximum number of rounds for the simulation.
  - **runner_pid** (integer) - The process ID of the simulation runner.
  - **started_at** (string) - The timestamp when the simulation started.

#### Response Example
```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_...",
    "status": "running",
    "current_round": 0,
    "max_rounds": 10,
    "runner_pid": 12345,
    "started_at": "2024-06-08T15:30:00Z"
  }
}
```

### Error Codes
- `400` — Simulation not in "prepared" state
- `503` — Subprocess spawn failed, cleanup registration failed
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/INSTALL.md

Installs the Anthropic Claude Code command-line interface globally.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Install Neo4j on macOS

Source: https://github.com/aaronjmars/miroshark/blob/main/README.md

Use Homebrew to install Neo4j on macOS. This is a prerequisite for running MiroShark.

```bash
brew install neo4j
```

--------------------------------

### GET /api/simulation/{simulation_id}/chart.svg

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Get an SVG chart visualizing the sentiment evolution of the simulation.

```http
GET /api/simulation/{simulation_id}/chart.svg HTTP/1.1
```

--------------------------------

### GET /api/simulation/{simulation_id}/polymarket.json

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Get all prediction market data for the simulation in JSON format.

```http
GET /api/simulation/{simulation_id}/polymarket.json HTTP/1.1
```

--------------------------------

### Create Project for Multi-Document Analysis

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Initiate a new project for analyzing multiple documents. Provide a name for the project, and the API will return a unique project ID.

```bash
# 1. Create project
curl -X POST /api/graph/project \
  -d '{"name": "Q3 Earnings Analysis"}'

# Returns: { "project_id": "proj_..." }
```

--------------------------------

### GET /api/simulation/{simulation_id}/agents.json

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Get all agent profiles as a JSON export for the specified simulation.

```http
GET /api/simulation/{simulation_id}/agents.json HTTP/1.1
```

--------------------------------

### POST /api/simulation/create

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

Creates a new simulation with a specified scenario and document. This is the initial step to set up a simulation environment.

```APIDOC
## POST /api/simulation/create

### Description
Create new simulation with scenario + document.

### Method
POST

### Endpoint
/api/simulation/create

### Parameters
#### Request Body
- **scenario** (string) - Required - The scenario for the simulation.
- **document** (string) - Required - The document content for the simulation.
- **document_source** (string) - Optional - The source of the document (manual|url|file|ask|trending|suggest).
- **max_rounds** (integer) - Optional - The maximum number of rounds for the simulation.
- **num_agents** (integer) - Optional - The number of agents in the simulation.
- **project_id** (string) - Optional - The ID of the project for the simulation workflow.

### Request Example
```json
{
  "scenario": "Bitcoin reaches $200k by end of year",
  "document": "Bitcoin just hit a new all-time high...",
  "document_source": "manual",
  "max_rounds": 10,
  "num_agents": 50,
  "project_id": "proj_..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains simulation details.
  - **simulation_id** (string) - The unique identifier for the simulation.
  - **status** (string) - The current status of the simulation.
  - **scenario** (string) - The scenario of the simulation.
  - **num_agents** (integer) - The number of agents.
  - **max_rounds** (integer) - The maximum number of rounds.
  - **created_at** (string) - The timestamp when the simulation was created.
  - **created_by** (string) - The entity that created the simulation (user|api).
  - **project_id** (string) - The project ID associated with the simulation, if any.

#### Response Example
```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_550e8400e29b41d4a716",
    "status": "initializing",
    "scenario": "Bitcoin reaches $200k...",
    "num_agents": 50,
    "max_rounds": 10,
    "created_at": "2024-06-08T15:00:00Z",
    "created_by": "user",
    "project_id": null
  }
}
```

### Error Codes
- `400` — Missing `scenario` or `document`
- `503` — Internal key missing on protected deployment
```

--------------------------------

### Start Ollama Serve

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Ensure the Ollama service is running by executing 'ollama serve' to fix graph building failures caused by the embedding service being down.

```bash
ollama serve
```

--------------------------------

### Prepare Simulation

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Prepare a simulation by building its knowledge graph, generating agent profiles, and configuring simulation parameters. This step is necessary before starting the simulation. The response provides a task ID for progress tracking.

```bash
# Prepare (build graph, generate profiles, config)
curl -X POST /api/simulation/prepare \
  -d '{"simulation_id": "sim_..."}'

# Returns: { "task_id": "550e8400..." }
```

--------------------------------

### GET /api/observability/health

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/system-and-settings-api.md

Performs an extended health check to get detailed system status. Requires an internal key for authentication.

```APIDOC
## GET /api/observability/health

### Description
Extended health check (detailed system status). Requires an internal key for authentication.

### Method
GET

### Endpoint
/api/observability/health

### Headers
- **x-miroshark-internal-key** (string) — Required internal key

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object)
  - **status** (string)
  - **checks** (object)
    - **neo4j** (object)
      - **status** (string)
      - **latency_ms** (integer)
      - **nodes** (integer)
    - **embedding_service** (object)
      - **status** (string)
      - **provider** (string)
      - **latency_ms** (integer)
    - **llm** (object)
      - **status** (string)
      - **provider** (string)
      - **latency_ms** (integer)
      - **quota_remaining** (integer)
    - **disk** (object)
      - **status** (string)
      - **free_gb** (integer)
      - **upload_folder_size_gb** (integer)
  - **timestamp** (string)

#### Response Example
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "checks": {
      "neo4j": {
        "status": "ok",
        "latency_ms": 15,
        "nodes": 15000
      },
      "embedding_service": {
        "status": "ok",
        "provider": "ollama",
        "latency_ms": 45
      },
      "llm": {
        "status": "ok",
        "provider": "openrouter",
        "latency_ms": 250,
        "quota_remaining": 95000
      },
      "disk": {
        "status": "ok",
        "free_gb": 50,
        "upload_folder_size_gb": 15
      }
    },
    "timestamp": "2024-06-08T16:00:00Z"
  }
}
```

### Error Codes
- **401** — Missing/invalid internal key
- **503** — Health check failed (one or more services down)
```

--------------------------------

### Install Neo4j on Linux

Source: https://github.com/aaronjmars/miroshark/blob/main/README.md

Install Neo4j on Linux using the appropriate package manager command for your distribution. This is a prerequisite for running MiroShark.

```bash
sudo apt install neo4j
```

--------------------------------

### Create Simulation from Project Graph

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Create a new simulation that is seeded or informed by the knowledge graph built from a project. This allows for simulations based on complex, multi-document analyses.

```bash
# 6. Create simulation from graph
curl -X POST /api/simulation/create \
  -d '{ 
    "project_id": "proj_...",
    "scenario": "Auto-generated from project analysis",
    "max_rounds": 10
  }'
```

--------------------------------

### Publish Simulation to Gallery

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Publish a simulation to the public gallery with a title, description, and tags. Requires an admin token.

```bash
# Publish to gallery
curl -X POST /api/simulation/sim_.../publish \
  -H "Authorization: Bearer $MIROSHARK_ADMIN_TOKEN" \
  -d '{
    "title": "Market Reaction Simulation",
    "description": "Simulated response...",
    "tags": ["market", "finance"]
  }'
```

--------------------------------

### Download and Run Analyst Notebook

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/API.md

Download a pre-populated Jupyter notebook for simulation analysis, including embedded trajectory data and charting capabilities.

```bash
curl -fsSL "https://your-host/api/simulation/<id>/notebook.ipynb" \
  -o simulation.ipynb
jupyter lab simulation.ipynb     # or: code simulation.ipynb, or upload to Colab
```

--------------------------------

### POST /api/simulation/create

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Creates a new simulation from scratch, defining a scenario, initial document, and simulation parameters.

```APIDOC
## POST /api/simulation/create

### Description
Create simulation from scratch (no project).

### Method
POST

### Endpoint
/api/simulation/create

### Parameters
#### Request Body
- **scenario** (string) - Required - A description of the simulation scenario.
- **document** (string) - Required - The initial document content for the simulation.
- **max_rounds** (integer) - Optional - The maximum number of rounds for the simulation.
- **num_agents** (integer) - Optional - The number of agents participating in the simulation.

### Request Example
```json
{
  "scenario": "Bitcoin hits $100k - what's the market reaction?",
  "document": "Bitcoin surged to new ATHs today...",
  "max_rounds": 10,
  "num_agents": 50
}
```

### Response
#### Success Response (200)
- **simulation_id** (string) - The unique identifier for the created simulation.
- **status** (string) - The current status of the simulation (e.g., "initializing").
- **scenario** (string) - The description of the simulation scenario.
- **created_at** (string) - Timestamp of simulation creation.

#### Response Example
```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_...",
    "status": "initializing",
    "scenario": "Bitcoin hits $100k...",
    "created_at": "2024-06-08T15:00:00Z"
  }
}
```
```

--------------------------------

### Get Simulation Demographic Breakdown

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/FEATURES.md

Endpoint to get the distribution and engagement of agents clustered into archetypes for a simulation. Useful for identifying narrative drivers.

```http
GET /api/simulation/<id>/demographics
```

--------------------------------

### GET /api/simulation/{simulation_id}/posts - Get Simulation Posts

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Retrieves all posts and comments generated during a simulation. Supports filtering by platform and agent, with a default limit.

```json
{
  "success": true,
  "data": [
    {
      "post_id": "p_...",
      "platform": "twitter",
      "agent": "AlexM",
      "content": "Breaking: market reacts...",
      "round": 1,
      "timestamp": "2024-06-08T15:00:00Z",
      "engagement": {
        "likes": 45,
        "retweets": 12,
        "replies": 3
      }
    }
  ]
}
```

--------------------------------

### POST /api/simulation/prepare

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/simulation-api.md

Prepares a simulation by building its knowledge graph and generating configuration. This is a prerequisite for running the simulation.

```APIDOC
## POST /api/simulation/prepare

### Description
Build knowledge graph and generate simulation config (pre-execution setup).

### Method
POST

### Endpoint
/api/simulation/prepare

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The ID of the simulation to prepare.
- **max_rounds** (integer) - Optional - The maximum number of rounds for the simulation.
- **num_agents** (integer) - Optional - The number of agents in the simulation.
- **use_web_enrichment** (boolean) - Optional - Whether to use web enrichment.
- **use_demographic_grounding** (boolean) - Optional - Whether to use demographic grounding.
- **reuse_graph** (boolean) - Optional - Whether to reuse an existing knowledge graph.

### Request Example
```json
{
  "simulation_id": "sim_...",
  "max_rounds": 10,
  "num_agents": 50,
  "use_web_enrichment": true,
  "use_demographic_grounding": true,
  "reuse_graph": false
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains task details for preparation.
  - **task_id** (string) - The ID of the preparation task.
  - **status** (string) - The current status of the task.
  - **progress** (integer) - The completion progress of the task (0-100).
  - **message** (string) - A message describing the current status or next steps.
  - **estimated_duration_seconds** (integer) - The estimated time in seconds for the task to complete.

#### Response Example
```json
{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "progress": 0,
    "message": "Initializing graph builder...",
    "estimated_duration_seconds": 180
  }
}
```

### Error Codes
- `400` — Invalid simulation_id
- `503` — Neo4j offline, LLM unavailable, graph builder crashed
```

--------------------------------

### Build Knowledge Graph from Project

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Construct the knowledge graph for the project using the previously generated ontology and extracted text. This forms the basis for simulations and analyses.

```bash
# 5. Build graph
curl -X POST /api/graph/build \
  -d '{"project_id": "proj_..."}'
```

--------------------------------

### GET /api/simulation/{simulation_id}/run-status - Get Run Status

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Fetches the current execution status and progress of a running simulation. Useful for monitoring real-time performance.

```json
{
  "success": true,
  "data": {
    "status": "running",
    "current_round": 3,
    "max_rounds": 10,
    "progress": 30,
    "elapsed_seconds": 145,
    "eta_seconds": 300,
    "posts_generated": 120
  }
}
```

--------------------------------

### GET /api/simulation/{simulation_id} - Get Simulation State

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Retrieves the current state and metadata of a specific simulation. This includes its status, scenario details, and configuration parameters.

```json
{
  "success": true,
  "data": {
    "simulation_id": "sim_...",
    "status": "prepared",
    "scenario": "...",
    "num_agents": 50,
    "max_rounds": 10,
    "graph_id": "g_...",
    "published": false,
    "quality_score": 0.82
  }
}
```

--------------------------------

### Configure Hybrid Mode with Local and Cloud Models

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/MODELS.md

Set environment variables to use a local model for general tasks and a cloud model (Claude) for smart/report generation.

```bash
LLM_MODEL_NAME=qwen2.5:32b
SMART_PROVIDER=claude-code
SMART_MODEL_NAME=claude-sonnet-4-20250514
```

--------------------------------

### Start Simulation

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Begins the execution of a prepared simulation. This endpoint should only be called after the simulation preparation task has successfully completed.

```APIDOC
## POST /api/simulation/start

### Description
Initiates the execution of a simulation that has already been prepared.

### Method
POST

### Endpoint
/api/simulation/start

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The ID of the simulation to start.

### Response
#### Success Response (200)
- (No specific fields mentioned, implies success confirmation.)
```

--------------------------------

### Agent Tool Call Example

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/FEATURES.md

An example of an agent making a tool call using a self-closing tag format. The runner parses these tags to dispatch calls.

```xml
<mcp_call server="web_search" tool="search" args='{"q":"..."}' />
```

--------------------------------

### GET /api/simulation/{simulation_id}/timeline - Get Simulation Timeline

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Fetches the complete timeline of actions and posts during a simulation. Allows filtering by platform, agent, or round number.

```json
{
  "success": true,
  "data": {
    "timeline": [
      {
        "timestamp": "2024-06-08T15:00:00Z",
        "round": 1,
        "agent": "AlexM",
        "action": "CREATE_POST",
        "platform": "twitter",
        "content": "Just saw the news about...",
        "engagement": {
          "likes": 12,
          "retweets": 3
        }
      }
    ]
  }
}
```

--------------------------------

### Run Miroshark Launcher

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Launches the Miroshark application, checking dependencies, starting Neo4j, and serving the frontend. Ensure LLM_API_KEY and NEO4J_PASSWORD are set.

```bash
# Requires: Python 3.11+, Node 18+, Neo4j
./miroshark  # Launcher checks deps, starts Neo4j, installs frontend, serves :3000 & :5001
```

--------------------------------

### POST /api/simulation/prepare

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/API.md

Initiates the profile generation process for a simulation (Step 2).

```APIDOC
## POST /api/simulation/prepare

### Description
Initiates the profile generation process for a simulation (Step 2).

### Method
POST

### Endpoint
/api/simulation/prepare

### Purpose
Kick off profile generation (Step 2)
```

--------------------------------

### GET /api/simulation/{simulation_id}/run-status/detail - Get Detailed Run Metrics

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/endpoints.md

Retrieves detailed execution metrics for a simulation, broken down by round and platform. Provides insights into performance and activity.

```json
{
  "success": true,
  "data": {
    "rounds": [
      {
        "round": 1,
        "duration_seconds": 45,
        "twitter_posts": 40,
        "reddit_posts": 25,
        "polymarket_trades": 10
      }
    ],
    "platforms": {
      "twitter": {
        "total_posts": 120,
        "avg_engagement": 5.2
      }
    }
  }
}
```

--------------------------------

### Task Data Model Example

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/types.md

An example JSON representation of a Task object during processing. Shows typical fields like ID, type, status, timestamps, and progress details.

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_type": "graph_build",
  "status": "processing",
  "created_at": "2024-06-08T15:30:00Z",
  "updated_at": "2024-06-08T15:35:00Z",
  "progress": 65,
  "message": "Indexing vectors: 1250/2000 chunks processed",
  "progress_detail": {
    "stage": "embedding",
    "chunks_processed": 1250,
    "total_chunks": 2000
  }
}
```

--------------------------------

### Download All Simulation Data

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Download a zip archive containing all data related to a simulation.

```bash
# Download everything
curl /api/simulation/sim_.../archive.zip > full-sim.zip
```

--------------------------------

### Download Complete Simulation Archive

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/api-reference/report-and-export-api.md

Download the entire simulation as a ZIP archive, containing all relevant data files and artifacts. This is ideal for full backups and offline analysis.

```text
sim_{id}/
  simulation.json          # Full state
  scenario.txt
  document.txt
  config.json              # Wonderwall config
  profiles.json            # Agent profiles
  transcript.json          # All posts/actions
  graph-export.json        # Neo4j graph
  report.md                # Generated report
  article.md               # Narrative article
  metadata/
    created_at
    completed_at
    quality_score
  artifacts/
    share-card.png
    chart.svg
    replay.gif
    badge.svg
```

--------------------------------

### Create Simulation

Source: https://github.com/aaronjmars/miroshark/blob/main/_autodocs/INDEX.md

Use this endpoint to initiate a new simulation. You can specify parameters like the scenario description, source document, maximum simulation rounds, and the number of agents involved. The response includes a unique simulation ID.

```bash
# Create simulation
curl -X POST /api/simulation/create \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "Bitcoin reaches $200k",
    "document": "Bitcoin just hit ATH...",
    "max_rounds": 10,
    "num_agents": 50
  }'

# Returns: { "simulation_id": "sim_..." }
```

--------------------------------

### Clarify Script Execution Location in Simulation Setup

Source: https://github.com/aaronjmars/miroshark/blob/main/docs/cleanup/08-slop.md

Updates comments to accurately reflect where run scripts are located and how they are executed during simulation setup. Scripts are now noted to live in the backend/scripts/ directory and are executed in place.

```diff
- # Note: run scripts remain in backend/scripts/ directory, no longer copied to simulation directory
- # When starting simulation, simulation_runner will run scripts from the scripts/ directory
+ # Run scripts live in backend/scripts/ and are executed in place;
+ # they are not copied into the per-simulation directory.
```