### Configure Environment Variables

Source: https://deepwiki.com/666ghj/MiroFish/2.3-docker-deployment

Example configuration for the .env file, including required keys for LLM services (OpenAI-compatible) and Zep Cloud graph services. Ensure these values are updated with valid credentials before starting the application.

```text
# LLM API Configuration (OpenAI SDK compatible)
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud Configuration
ZEP_API_KEY=your_zep_api_key_here
```

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

### POST /api/simulation/start

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

Initializes and starts a new simulation or restarts a cleaned simulation.

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

### Description
Starts a simulation process with the specified configuration.

### Method
POST

### Endpoint
/api/simulation/start

### Request Body
- **simulation_id** (string) - Required - ID of the simulation.
- **platform** (string) - Optional - Platform target (e.g., "parallel").
- **max_rounds** (integer) - Optional - Limit for simulation rounds.

### Response
#### Success Response (200)
- **status** (string) - The current status of the simulation.

#### Response Example
{
  "status": "started",
  "simulation_id": "sim_xxx"
}
```

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

### Initialize Environment Configuration

Source: https://deepwiki.com/666ghj/MiroFish/2.3-docker-deployment

Copies the template configuration file to the required .env file in the project root directory. This file is essential for storing API credentials used by both frontend and backend services.

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

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

### Verify Python and uv Installation (Shell)

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

These commands help verify that Python and the uv package manager are correctly installed and accessible in your system's PATH. This is crucial for the backend setup process.

```shell
python --version  # Should show 3.11.x or 3.12.x
which python

uv --version
which uv
```

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

### Console Log Entry Examples

Source: https://deepwiki.com/666ghj/MiroFish/4.2-oasis-multi-agent-simulation

Examples of console log entries showing real-time progress during graph search and tool execution. These logs provide human-readable updates on the process.

```text
[19:46:14] INFO: 图谱搜索: graph_id=mirofish_abc, query=舆情走向...
[19:46:14] INFO: 搜索完成: 找到 15 条相关事实
[19:46:15] INFO: InsightForge完成: 42条事实, 8个实体, 12条关系链

```

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

### Node.js Environment Verification

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Commands to verify the installed versions of Node.js and npm, and to manually trigger dependency installation when automated setup scripts fail.

```bash
# Verify Node.js and npm versions
node -v  # Should show v18.x or higher
npm -v   # Should show 9.x or higher

# Check npm configuration
npm config list

# Manual dependency installation
npm install
cd frontend && npm install
```

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

### Start Development Environment

Source: https://deepwiki.com/666ghj/MiroFish

Command to initiate the development environment by running both the frontend and backend services concurrently.

```shell
npm run dev
```

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

### Start Backend Development Server

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

Command-line instructions for launching the backend development server with hot reloading and debug mode enabled.

```bash
cd backend
uv run python run.py
```

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

### Manual Backend Synchronization (Shell)

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

This command manually synchronizes backend dependencies using uv. It's a step to troubleshoot `npm run setup:backend` failures, especially if network issues are suspected.

```shell
cd backend
uv sync
```

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

### POST /api/simulation/start

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Starts the simulation execution process by spawning a subprocess.

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

### Description
Initiates the simulation execution on specified platforms.

### Method
POST

### Endpoint
/api/simulation/start

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The ID of the simulation.
- **platform** (string) - Required - Target platform (twitter, reddit, or parallel).
- **max_rounds** (integer) - Optional - Maximum simulation rounds.
- **enable_graph_memory_update** (boolean) - Optional - Whether to update graph memory.
- **graph_id** (string) - Required if memory update is enabled.

### Request Example
{
  "simulation_id": "sim_xxxx",
  "platform": "parallel"
}

### Response
#### Success Response (200)
- **success** (boolean) - Operation status.
- **data** (object) - Contains runner status and PID.

#### Response Example
{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "runner_status": "starting",
    "process_pid": 12345
  }
}
```

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

### Structured Agent Log Entry Example

Source: https://deepwiki.com/666ghj/MiroFish/4.2-oasis-multi-agent-simulation

An example of a structured log entry in JSON Lines format, detailing a tool call during the report generation stage. It includes timestamp, elapsed time, action, stage, section information, and specific tool call details.

```json
{
  "timestamp": "2025-12-13T19:46:14.123",
  "elapsed_seconds": 12.5,
  "action": "tool_call",
  "stage": "generating",
  "section_title": "舆情走向分析",
  "section_index": 2,
  "details": {
    "iteration": 1,
    "tool_name": "insight_forge",
    "parameters": {"query": "..."},
    "result": "..."
  }
}
```

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

### Initialize Project Directory Structure and Permissions

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Creates the necessary backend directory structure and applies appropriate read/write permissions to ensure the application functions correctly.

```bash
mkdir -p backend/uploads/projects
mkdir -p backend/uploads/simulations
mkdir -p backend/uploads/reports
mkdir -p backend/logs

chmod -R 755 backend/uploads
chmod -R 755 backend/logs

ls -ld backend/uploads/
ls -ld backend/logs/
```

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

### Frontend npm Scripts and Dependencies (package.json)

Source: https://deepwiki.com/666ghj/MiroFish/2.3-docker-deployment

Manages the frontend-specific npm scripts and dependencies, primarily for the Vue.js application built with Vite. This file dictates how the frontend is developed, built, and served.

```json
{
  "name": "frontend",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "d3": "^7.8.5",
    "vue": "^3.3.4",
    "vite": "^4.4.9"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^4.2.0"
  }
}
```

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

### Verify Simulation Configuration Files

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

Checks for the existence of essential simulation configuration files before starting a simulation. This includes the main simulation configuration, Twitter profiles, and Reddit profiles.

```shell
ls {simulation_dir}/simulation_config.json
ls {simulation_dir}/twitter_profiles.csv
ls {simulation_dir}/reddit_profiles.json
```

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

### POST /api/simulation/prepare

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Prepares the simulation environment asynchronously, including LLM-powered profile generation and configuration setup.

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

### Description
Prepare simulation environment asynchronously. It auto-detects existing preparation to avoid redundant work and generates agent profiles for entities.

### Method
POST

### Endpoint
/api/simulation/prepare

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The ID of the simulation.
- **entity_types** (array) - Optional - Filter for specific entity types.
- **use_llm_for_profiles** (boolean) - Optional - Whether to use LLM for profile generation (default: true).
- **parallel_profile_count** (integer) - Optional - Number of parallel processes (default: 5).
- **force_regenerate** (boolean) - Optional - Force regeneration of profiles (default: false).

### Request Example
{
  "simulation_id": "sim_xxxx",
  "entity_types": ["Student", "PublicFigure"],
  "use_llm_for_profiles": true,
  "parallel_profile_count": 5,
  "force_regenerate": false
}

### Response
#### Success Response (200)
- **success** (boolean) - Operation status.
- **data** (object) - Contains task_id, status, and simulation details.

#### Response Example
{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "task_id": "task_xxxx",
    "status": "preparing",
    "message": "准备任务已启动"
  }
}
```

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

### GET /api/simulation/actions

Source: https://deepwiki.com/666ghj/MiroFish/3-user-guide

Retrieves the combined action logs for the current simulation run.

```APIDOC
## GET /api/simulation/actions

### Description
Fetches the combined action log (actions.jsonl) for the active simulation.

### Method
GET

### Endpoint
/api/simulation/actions

### Response
#### Success Response (200)
- **actions** (array) - A list of actions performed by the simulation agents.

#### Response Example
{
  "actions": [{"action": "initialize", "status": "success"}]
}
```

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

### Configure LLM Boost Settings

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Environment variables to configure secondary LLM endpoints to mitigate rate limiting issues during simulation.

```bash
LLM_BOOST_API_KEY=your_second_key
LLM_BOOST_BASE_URL=your_second_url
LLM_BOOST_MODEL_NAME=your_second_model
```

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

### POST /api/simulation/cleanup-logs

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

Cleans up simulation artifacts, logs, and temporary database files to prepare for a fresh start.

```APIDOC
## POST /api/simulation/cleanup-logs

### Description
Removes temporary files including run_state.json, .db files, and action logs to reset the simulation state.

### Method
POST

### Endpoint
/api/simulation/cleanup-logs

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

### Response
#### Success Response (200)
- **message** (string) - Confirmation that logs and temporary files were removed.

#### Response Example
{
  "status": "cleaned",
  "simulation_id": "sim_xxx"
}
```

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

### Enable Debugging and Tail Logs

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Configures the backend for debug mode and provides commands to monitor real-time application and service logs.

```bash
export FLASK_DEBUG=1
npm run backend

tail -f backend/logs/app.log
tail -f backend/uploads/simulations/<simulation_id>/console_log.txt
tail -f backend/uploads/reports/<report_id>/console_log.txt
```

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

### Start Simulation Execution

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Triggers the simulation execution process by spawning a subprocess. Supports multi-platform simulation and optional graph memory updates.

```json
{
  "simulation_id": "sim_xxxx",
  "platform": "parallel",
  "max_rounds": 120,
  "enable_graph_memory_update": false,
  "graph_id": "mirofish_xxxx"
}
```

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

### Debug Agent Logs with CLI

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Extracts error-related entries from agent logs using grep and jq for easier analysis of failed processes.

```bash
cat backend/uploads/reports/<report_id>/agent_log.jsonl | grep -B 2 -A 2 "error" | jq
```

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

### Monitor and Manage Disk Space

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

Commands to inspect disk usage and perform maintenance by cleaning up old simulation and report data or archiving files.

```bash
df -h
du -sh backend/uploads/
du -sh backend/uploads/simulations/* | sort -hr | head -10

# Cleanup
find backend/uploads/simulations -type d -mtime +7 -exec rm -rf {} +
find backend/uploads/reports -type d -mtime +30 -exec rm -rf {} +

# Archive
tar -czf simulations_backup_$(date +%Y%m%d).tar.gz backend/uploads/simulations/
```

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

### Python Dependencies Definition (pyproject.toml)

Source: https://deepwiki.com/666ghj/MiroFish/2.3-docker-deployment

Specifies the Python dependencies for the backend application using the PEP 518 standard. This file is used by build tools like `uv` to install and manage backend packages.

```toml
[tool.poetry]
name = "backend"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
flask = "^3.0.0"
python-dotenv = "^1.0.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

```

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

### Development and Production Deployment

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

Provides instructions for setting up the development environment and outlines the configuration differences between development and production deployments.

```APIDOC
## Development and Production Deployment

### Development Mode
Starts the backend development server using `uvicorn`.

#### Commands:
```bash
cd backend
uvicorn run:app --reload
```

#### Development Configuration:
- Flask debug mode is enabled.
- Hot reloading is active for code changes.
- Detailed error tracebacks are included in responses.
- CORS is configured to allow all origins.
```

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

### Root npm Scripts and Dependencies (package.json)

Source: https://deepwiki.com/666ghj/MiroFish/2.3-docker-deployment

Defines the root-level npm scripts and project dependencies for the MiroFish application. This file is crucial for managing the overall build and execution of the project.

```json
{
  "name": "mirofish",
  "version": "1.0.0",
  "scripts": {
    "dev": "concurrently \"npm run dev --prefix frontend\" \"python backend/run.py\"",
    "build": "npm run build --prefix frontend",
    "start": "node server.js"
  },
  "devDependencies": {
    "concurrently": "^8.0.0"
  },
  "dependencies": {}
}
```

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

### Load Environment Configuration in Python

Source: https://deepwiki.com/666ghj/MiroFish/8.4-llm-configuration-and-optimization

Demonstrates how the simulation script initializes configuration by loading environment variables from the .env file located in the project root directory.

```python
import os
from dotenv import load_dotenv

# Load from project root .env file
_env_file = os.path.join(_project_root, '.env')
if os.path.exists(_env_file):
    load_dotenv(_env_file)
```

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

### List Generated Report Sections

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

This command lists all files in the report directory that start with 'section_' and end with '.md'. It helps verify which report sections have actually been generated as Markdown files.

```bash
ls backend/uploads/reports/<report_id>/section_*.md
```

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

### Configure Dual LLM API Keys

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

This example shows how to configure separate API keys for primary and secondary LLM services in a .env file. The secondary key is designated for specific platforms like Reddit to manage API usage.

```dotenv
# .env file
LLM_API_KEY=primary_key
LLM_BOOST_API_KEY=secondary_key  # Used for Reddit
```

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

### Check Report Status via API

Source: https://deepwiki.com/666ghj/MiroFish/9-troubleshooting

This command uses curl to make an HTTP GET request to the report status API endpoint. It retrieves the current status of a specific report generation process.

```bash
curl http://localhost:5001/api/report/<report_id>/status
```

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

### Check Platform Completion Status in run_state.json

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

This JSON example shows the structure of the run_state.json file, which tracks the completion and running status of different platforms like Twitter and Reddit. This helps in diagnosing partial platform completion issues.

```json
// run_state.json
{
  "twitter_completed": true,
  "reddit_completed": false,
  "twitter_running": false,
  "reddit_running": true
}
```

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

### GET /api/report/<report_id>/progress

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Get real-time progress updates on the generation of a specific report.

```APIDOC
## GET /api/report/<report_id>/progress

### Description
Get real-time report generation progress.

### Method
GET

### Endpoint
/api/report/<report_id>/progress

### Parameters
#### Path Parameters
- **report_id** (string) - Required - The ID of the report for which to get progress.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the generation progress details.
  - **status** (string) - The current status of the report generation (e.g., "generating").
  - **progress** (integer) - The percentage of completion.
  - **message** (string) - A message describing the current stage of generation.
  - **current_section** (string) - The title of the section currently being generated.
  - **completed_sections** (array) - A list of titles of sections that have been completed.
  - **updated_at** (string) - Timestamp when the progress information was last updated.

#### Response Example
```json
{
  "success": true,
  "data": {
    "status": "generating",
    "progress": 45,
    "message": "正在生成章节: 关键发现",
    "current_section": "关键发现",
    "completed_sections": ["执行摘要", "模拟背景"],
    "updated_at": "2025-12-09T15:30:00"
  }
}
```
```

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

### Initialize Logger and Log Messages

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

Demonstrates the centralized logging configuration used across the Mirofish backend. It shows how to instantiate a service-specific logger and utilize standard log levels for diagnostics and error tracking.

```python
logger = get_logger('mirofish.service_name')

logger.debug("Detailed diagnostic info")
logger.info("General informational messages")
logger.warning("Warning messages")
logger.error("Error messages with exceptions")
```

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

### Execute Batch Interviews for Twitter Platform (Python)

Source: https://deepwiki.com/666ghj/MiroFish/7.3-interview-and-ipc-api

Builds a dictionary of manual actions for Twitter interviews and executes them using the environment's step function. This is part of the execution phase of batch interviews. It retrieves agent information, creates 'ManualAction' objects with interview prompts, and then calls `env.step()` for the Twitter environment.

```python
# Assuming 'self.twitter_agent_graph', 'ActionType', 'ManualAction', and 'self.twitter_env' are defined
# Assuming 'twitter_interviews' is populated and 'agent_id' and 'prompt' are available
twitter_actions = {}
for interview in twitter_interviews:
    # agent_id needs to be correctly obtained for each interview or context
    # For simplicity, using a placeholder agent_id here
    current_agent_id = agent_id # Replace with actual agent ID retrieval if needed
    agent = self.twitter_agent_graph.get_agent(current_agent_id)
    # Assuming 'prompt' is available in the context or interview object
    current_prompt = prompt # Replace with actual prompt retrieval if needed
    twitter_actions[agent] = ManualAction(
        action_type=ActionType.INTERVIEW,
        action_args={"prompt": current_prompt}
    )
# Assuming 'self.twitter_env.step' is an async method
# await self.twitter_env.step(twitter_actions)
print(f"Simulating Twitter environment step with actions: {twitter_actions}") # Placeholder for async call

```

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

### Docker Production Deployment for Python Backend

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

This Dockerfile outlines the steps to containerize the Python backend application for production. It specifies the base Python image, sets the working directory, copies application files, installs dependencies using uv, and defines the command to run the application.

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY backend/ .
RUN pip install uv && uv sync
CMD ["uv", "run", "python", "run.py"]
```

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

### GET /api/simulation/timeline

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieves simulation timeline aggregated by round.

```APIDOC
## GET /api/simulation/timeline

### Description
Retrieves simulation timeline aggregated by round, including active agents and key events.

### Method
GET

### Endpoint
/api/simulation/timeline

### Parameters
#### Query Parameters
- **simulation_id** (string) - Required - Simulation ID
- **start_round** (integer) - Optional - Starting round (default: 0)
- **end_round** (integer) - Optional - Ending round (default: all)

### Response
#### Success Response (200)
- **data** (object) - Contains timeline array

#### Response Example
{
  "success": true,
  "data": {
    "timeline": [
      {
        "round_num": 1,
        "simulated_hour": 0,
        "twitter_actions": 15,
        "reddit_actions": 12,
        "active_agents": [1, 3, 5, 7, 9],
        "key_events": ["模拟开始"]
      }
    ]
  }
}
```

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

### GET /api/simulation/actions

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

Queries the detailed action history for a specific simulation with optional filtering.

```APIDOC
## GET /api/simulation/actions

### Description
Retrieves a list of recent actions performed during the simulation. Supports filtering by platform or agent ID.

### Method
GET

### Endpoint
/api/simulation/actions

### Parameters
#### Query Parameters
- **simulation_id** (string) - Required - The ID of the simulation
- **limit** (integer) - Optional - Number of records to return
- **platform** (string) - Optional - Filter by platform (e.g., "twitter")
- **agent_id** (integer) - Optional - Filter by agent ID

### Response
#### Success Response (200)
- **recent_actions** (array) - List of action objects

#### Response Example
{
  "recent_actions": [{"id": 1, "action": "post", "agent_id": 5}]
}
```

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

### GET /api/report/<report_id>

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

Retrieves the complete content of a generated report by its unique identifier.

```APIDOC
## GET /api/report/<report_id>

### Description
Fetches the full report details for a given report ID.

### Method
GET

### Endpoint
/api/report/{report_id}

### Parameters
#### Path Parameters
- **report_id** (string) - Required - The unique identifier of the report.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates success.
- **data** (object) - The full report object.

#### Response Example
{
  "success": true,
  "data": { "id": "rep_12345", "content": "..." }
}
```

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

### Parallel Task Execution with Asyncio

Source: https://deepwiki.com/666ghj/MiroFish/7.3-interview-and-ipc-api

Demonstrates how to execute multiple tasks concurrently using asyncio.gather to aggregate results from different platforms.

```python
platform_results = await asyncio.gather(*tasks)
```

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

### GET /api/report/logs/agent

Source: https://deepwiki.com/666ghj/MiroFish/3-user-guide

Retrieves detailed agent logs generated during the report creation phase.

```APIDOC
## GET /api/report/logs/agent

### Description
Retrieves the trace logs generated by agents during the report generation process.

### Method
GET

### Endpoint
/api/report/logs/agent

### Response
#### Success Response (200)
- **agent_log** (array) - List of log entries from the report generation agents.

#### Response Example
{
  "agent_log": [{"timestamp": "2023-10-01T12:00:00Z", "message": "Generating section 1..."}]
}
```

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

### GET /api/simulation/run/status

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieves real-time execution status for a running simulation.

```APIDOC
## GET /api/simulation/run/status

### Description
Query real-time execution status, including round counts and platform-specific progress.

### Method
GET

### Endpoint
/api/simulation/run/status

### Parameters
#### Query Parameters
- **simulation_id** (string) - Required - The ID of the simulation.

### Response
#### Success Response (200)
- **success** (boolean) - Operation status.
- **data** (object) - Contains current round, progress percentage, and platform metrics.

#### Response Example
{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "runner_status": "running",
    "current_round": 35
  }
}
```

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

### SimulationIPCClient Usage Pattern

Source: https://deepwiki.com/666ghj/MiroFish/7.3-interview-and-ipc-api

Provides a high-level interface for sending simulation commands and handling responses via the SimulationIPCClient.

```python
from .simulation_ipc import SimulationIPCClient, CommandType, IPCResponse

client = SimulationIPCClient(simulation_id)
response = client.send_command(
    CommandType.INTERVIEW,
    args={"agent_id": 42, "prompt": "What is your opinion?", "platform": "twitter"},
    timeout=30
)

if response.status == "completed":
    print(response.result)
else:
    print(f"Error: {response.error}")
```

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

### GET /api/simulation/status

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

Retrieves the current status of the simulation runner, including progress and action counts.

```APIDOC
## GET /api/simulation/status

### Description
Returns the current state of the simulation, including the runner status, round progress, and action counts.

### Method
GET

### Endpoint
/api/simulation/status

### Response
#### Success Response (200)
- **runner_status** (string) - Current status (e.g., "running")
- **current_round** (integer) - Current round number
- **total_rounds** (integer) - Total rounds in simulation
- **progress_percent** (float) - Completion percentage
- **twitter_actions_count** (integer) - Total actions on Twitter
- **reddit_actions_count** (integer) - Total actions on Reddit

#### Response Example
{
  "runner_status": "running",
  "current_round": 45,
  "total_rounds": 120,
  "progress_percent": 37.5,
  "twitter_actions_count": 1230,
  "reddit_actions_count": 1180
}
```

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

### Prepare Simulation Environment

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Initializes the simulation environment asynchronously using LLM-powered profile generation. It returns a task_id for progress tracking and avoids redundant work if the environment is already prepared.

```json
{
  "simulation_id": "sim_xxxx",
  "entity_types": ["Student", "PublicFigure"],
  "use_llm_for_profiles": true,
  "parallel_profile_count": 5,
  "force_regenerate": false
}
```

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

### Perform Full Simulation Cleanup and Restart

Source: https://deepwiki.com/666ghj/MiroFish/9.3-report-generation-issues

This API sequence initiates a full cleanup of simulation logs and related files, followed by a status check to ensure the simulation is ready, and finally restarts the simulation. This is used for a clean restart after a failure.

```bash
# Full cleanup sequence
POST /api/simulation/cleanup-logs
{
  "simulation_id": "sim_xxx"
}
 
# Verify cleanup
GET /api/simulation/{simulation_id}
# Should show: "status": "ready"
 
# Restart with fresh state
POST /api/simulation/start
{
  "simulation_id": "sim_xxx",
  "platform": "parallel",
  "max_rounds": 100  # Optional: limit rounds to test
}
```

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

### GET /api/report/<report_id>/download

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Download a specific report as a Markdown file.

```APIDOC
## GET /api/report/<report_id>/download

### Description
Download report as Markdown file.

### Method
GET

### Endpoint
/api/report/<report_id>/download

### Parameters
#### Path Parameters
- **report_id** (string) - Required - The ID of the report to download.

### Response
#### Success Response (200)
- **Content-Type**: `text/markdown` - The response will be a file download.

### Response Example
(File download stream of Markdown content)
```

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

### GET /api/report/list

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

List all generated reports, with optional filtering by simulation ID.

```APIDOC
## GET /api/report/list

### Description
List all generated reports.

### Method
GET

### Endpoint
/api/report/list

### Parameters
#### Query Parameters
- **simulation_id** (string) - Optional - Filter reports by simulation ID.
- **limit** (integer) - Optional - Maximum number of results to return. Defaults to 50.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of report objects.
- **count** (integer) - The total number of reports found.

#### Response Example
```json
{
  "success": true,
  "data": [ /* array of report objects */ ],
  "count": 10
}
```
```

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

### Spawn Subprocess for Simulation

Source: https://deepwiki.com/666ghj/MiroFish/6-backend-architecture

Illustrates the use of subprocess management to run OASIS simulations in isolation. Each simulation is tracked by its ID to ensure process management and resource cleanup.

```python
process = subprocess.Popen(cmd, ...)
cls._processes[simulation_id] = process
```

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

### GET /api/report/by-simulation/<simulation_id>

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieve a report associated with a specific simulation ID.

```APIDOC
## GET /api/report/by-simulation/<simulation_id>

### Description
Retrieve report by simulation ID.

### Method
GET

### Endpoint
/api/report/by-simulation/<simulation_id>

### Parameters
#### Path Parameters
- **simulation_id** (string) - Required - The ID of the simulation whose report is to be retrieved.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the report details (same structure as `GET /api/report/<report_id>`).
- **has_report** (boolean) - Indicates if a report exists for the given simulation ID.

#### Response Example
```json
{
  "success": true,
  "data": { /* report data */ },
  "has_report": true
}
```
```

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

### POST /api/simulation/interview

Source: https://deepwiki.com/666ghj/MiroFish/7.3-interview-and-ipc-api

Initiates an interview with a specific agent on a designated platform or across multiple platforms.

```APIDOC
## POST /api/simulation/interview

### Description
Sends a prompt to a specific agent within a simulation to retrieve their response. Can be used for single-platform queries or cross-platform comparisons.

### Method
POST

### Endpoint
/api/simulation/interview

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The unique identifier of the simulation.
- **agent_id** (integer) - Required - The ID of the agent being interviewed.
- **prompt** (string) - Required - The question or topic for the agent.
- **platform** (string) - Optional - The specific platform (e.g., "twitter", "reddit"). If omitted, may trigger cross-platform responses.

### Request Example
{
  "simulation_id": "sim_abc123",
  "agent_id": 42,
  "prompt": "What factors influenced your decision to support this policy?",
  "platform": "twitter"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was processed.
- **data** (object) - Contains the agent response, timestamp, and platform details.

#### Response Example
{
  "success": true,
  "data": {
    "agent_id": 42,
    "agent_name": "Alice Johnson",
    "response": "As a graduate student studying public policy, I supported this because...",
    "timestamp": "2024-12-10T15:30:00",
    "platform": "twitter"
  }
}
```

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

### GET /api/simulation/<simulation_id>/profiles

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieves generated agent profiles for a simulation.

```APIDOC
## GET /api/simulation/<simulation_id>/profiles

### Description
Retrieve generated agent profiles for a specific simulation and platform.

### Method
GET

### Endpoint
/api/simulation/<simulation_id>/profiles

### Parameters
#### Path Parameters
- **simulation_id** (string) - Required - The simulation ID

#### Query Parameters
- **platform** (string) - Optional - reddit or twitter (default: reddit)

### Response
#### Success Response (200)
- **data** (object) - Contains platform, count, and profiles list

#### Response Example
{
  "success": true,
  "data": {
    "platform": "reddit",
    "count": 68,
    "profiles": []
  }
}
```

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

### POST /api/simulation/batch-interview

Source: https://deepwiki.com/666ghj/MiroFish/7.3-interview-and-ipc-api

Allows for the submission of multiple interview requests in a single call to optimize performance and reduce file I/O overhead.

```APIDOC
## POST /api/simulation/batch-interview

### Description
Processes multiple interview requests simultaneously. This is the recommended approach for high-volume queries to minimize IPC overhead.

### Method
POST

### Endpoint
/api/simulation/batch-interview

### Parameters
#### Request Body
- **simulation_id** (string) - Required - The unique identifier of the simulation.
- **interviews** (array) - Required - A list of interview objects containing agent_id, prompt, and platform.

### Request Example
{
  "simulation_id": "sim_abc123",
  "interviews": [
    { "agent_id": 42, "prompt": "What is your stance?", "platform": "twitter" },
    { "agent_id": 99, "prompt": "How did you form your opinion?", "platform": "twitter" }
  ]
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the batch was processed.
- **data** (object) - Contains the count of interviews and a map of results.

#### Response Example
{
  "success": true,
  "data": {
    "interviews_count": 2,
    "results": {
      "twitter_42": { "agent_id": 42, "response": "...", "platform": "twitter" },
      "twitter_99": { "agent_id": 99, "response": "...", "platform": "twitter" }
    }
  }
}
```

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

### GET /api/simulation/actions

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieves paginated agent action history for a specific simulation.

```APIDOC
## GET /api/simulation/actions

### Description
Retrieves paginated agent action history. Use this for standard UI displays.

### Method
GET

### Endpoint
/api/simulation/actions

### Parameters
#### Query Parameters
- **simulation_id** (string) - Required - Simulation ID
- **limit** (integer) - Optional - Results per page (default: 100)
- **offset** (integer) - Optional - Pagination offset (default: 0)
- **platform** (string) - Optional - Filter by platform (twitter/reddit)
- **agent_id** (integer) - Optional - Filter by specific agent
- **round_num** (integer) - Optional - Filter by simulation round

### Response
#### Success Response (200)
- **data** (object) - Contains actions list, total count, and pagination info

#### Response Example
{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "actions": [],
    "total": 270,
    "limit": 100,
    "offset": 0
  }
}
```

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

### GET /api/simulation/logs/console

Source: https://deepwiki.com/666ghj/MiroFish/3-user-guide

Retrieves the console logs for simulation processes to assist in debugging and monitoring system health.

```APIDOC
## GET /api/simulation/logs/console

### Description
Fetches the raw console output logs for the current simulation environment.

### Method
GET

### Endpoint
/api/simulation/logs/console

### Response
#### Success Response (200)
- **logs** (string) - The content of the console logs.

#### Response Example
{
  "logs": "[INFO] Simulation started... [ERROR] Connection timeout..."
}
```

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

### Configure Retrieval and Analysis Service Settings

Source: https://deepwiki.com/666ghj/MiroFish/4.2-oasis-multi-agent-simulation

Configures retry logic for ZepToolsService and query limits for InsightForge. These settings control the depth and frequency of semantic analysis and sub-query generation.

```python
MAX_RETRIES = 3
RETRY_DELAY = 2.0
max_sub_queries = 5
semantic_facts_limit = 20
```

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

### Simulation Control API

Source: https://deepwiki.com/666ghj/MiroFish/3-user-guide

APIs for controlling the simulation execution process, including starting and stopping simulations.

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

### Description
Starts a new simulation by spawning a subprocess.

### Method
POST

### Endpoint
/api/simulation/start

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the simulation has started.

#### Response Example
```json
{
  "message": "Simulation started successfully."
}
```

## POST /api/simulation/stop

### Description
Stops the currently running simulation gracefully.

### Method
POST

### Endpoint
/api/simulation/stop

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the simulation has been stopped.

#### Response Example
```json
{
  "message": "Simulation stopped successfully."
}
```
```

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

### Configure Zep Cloud and LLM Environment Variables

Source: https://deepwiki.com/666ghj/MiroFish/4.2-oasis-multi-agent-simulation

Defines the required API keys and base URLs for Zep Cloud and LLM services. These variables are essential for enabling memory operations and context generation.

```env
ZEP_API_KEY=zep_xxx
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o-mini
LLM_BOOST_API_KEY=sk-yyy
LLM_BOOST_BASE_URL=https://api.alternative.com/v1
LLM_BOOST_MODEL_NAME=gpt-4o-mini
```

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

### GET /api/report/<report_id>/section/<section_index>

Source: https://deepwiki.com/666ghj/MiroFish/7-api-reference

Retrieve a specific section of a report by its index.

```APIDOC
## GET /api/report/<report_id>/section/<section_index>

### Description
Retrieve a specific section by index.

### Method
GET

### Endpoint
/api/report/<report_id>/section/<section_index>

### Parameters
#### Path Parameters
- **report_id** (string) - Required - The ID of the report.
- **section_index** (integer) - Required - The index of the section to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the specific section's details.
  - **filename** (string) - The filename of the section.
  - **section_index** (integer) - The index of the section.
  - **content** (string) - The Markdown content of the section.

#### Response Example
```json
{
  "success": true,
  "data": {
    "filename": "section_01.md",
    "section_index": 1,
    "content": "## 执行摘要\n\n..."
  }
}
```
```