MiroFish User Guide

MiroFish is a swarm-intelligence prediction engine. You give it seed material — a news report, a policy draft, a financial signal, or even a novel — describe what you want to predict in plain language, and MiroFish builds a high-fidelity digital world populated by thousands of AI agents. Those agents have their own personalities, long-term memory, and behavior, and they interact on simulated social platforms. From the resulting "what if" you get a detailed prediction report and a living world you can keep talking to.

This guide shows you how to install MiroFish, run a prediction end to end, and get good results. It covers everything you do from the browser; deep configuration, the HTTP API, and internals live in the companion Administrator & Developer Guide.

Note

MiroFish's simulation engine is powered by OASIS (Open Agent Social Interaction Simulations) from the CAMEL-AI team. You bring an LLM API key and a Zep Cloud key; MiroFish orchestrates the rest.

1. Quick Start

If you already have Node.js, Python, and uv installed, you can be running in five commands.

# 1. Clone the repository
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

# 2. Create your environment file and add your API keys
cp .env.example .env
#    then edit .env — set LLM_API_KEY and ZEP_API_KEY

# 3. Install everything (root + frontend + backend)
npm run setup:all

# 4. Start the frontend and backend together
npm run dev

Then open the frontend in your browser:

• Frontend (the app): http://localhost:3000
• Backend API: http://localhost:5001

[backend] MiroFish Backend 启动完成
[frontend]   ➜  Local:   http://localhost:3000/

The browser opens automatically. From the home page you upload a seed document, describe your prediction goal, and walk through the five-step workflow described in Section 5.

Important

MiroFish will not start without a valid LLM_API_KEY and ZEP_API_KEY. The backend validates both on startup and exits with 配置错误 ("configuration error") if either is missing. See Installation.

2. What You Need First

MiroFish is not self-contained — it drives two external services on your behalf. Before installing, gather the following.

Tip

The project authors recommend Alibaba's Qwen-plus model via the Bailian platform as a strong, cost-aware default. Whatever you choose, MiroFish talks to it through the standard OpenAI SDK format, so any compatible endpoint works.

Warning

A full simulation can consume a large number of LLM tokens — every agent reasons every round. The authors suggest starting with simulations of fewer than 40 rounds until you understand the cost of your chosen model. Several community reports of 429/500 errors trace back to provider rate limits and quotas under heavy multi-agent load.

3. Installation

MiroFish ships two supported install paths: running from source (recommended for development and full control) or running the prebuilt Docker image (fastest to try).

3.1 Prerequisites

Caution

The backend requires Python 3.11 or 3.12. Python 3.13 is explicitly excluded (requires-python = ">=3.11,<3.13"). Installing on 3.13 will fail dependency resolution.

3.2 Option 1 — Run from source (recommended)

Step 1 — Configure environment variables.

cp .env.example .env

Open .env and fill in at least the two required keys:

# LLM API (any OpenAI-SDK-compatible endpoint)
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# Zep Cloud
ZEP_API_KEY=your_zep_api_key

Note

.env.example also lists an optional "boost" LLM block (LLM_BOOST_API_KEY, LLM_BOOST_BASE_URL, LLM_BOOST_MODEL_NAME) for a second, faster model. If you are not using it, leave those three lines out of your .env entirely — don't set them to placeholder values.

Step 2 — Install dependencies.

One command (everything)

npm run setup:all

Step by step

# Node dependencies (root + frontend)
npm run setup

# Python dependencies (backend; uv auto-creates the venv)
npm run setup:backend

Step 3 — Start the services.

Both together

npm run dev

Separately

npm run backend    # backend only, on :5001
npm run frontend   # frontend only, on :3000

npm run dev uses concurrently to run the backend and the Vite dev server side by side, color-coded backend (green) and frontend (cyan), and stops both if either one dies.

3.3 Option 2 — Docker

If you have Docker with Compose, you can skip the toolchain setup entirely.

# 1. Configure environment variables (same .env as source install)
cp .env.example .env
#    edit .env with your keys

# 2. Pull the image and start
docker compose up -d

This runs the published image ghcr.io/666ghj/mirofish:latest, reads your root .env, and maps both ports: 3000 (frontend) and 5001 (backend). Uploaded files and generated data persist in ./backend/uploads via a bind mount, so they survive container restarts.

Tip

If the image pulls slowly, docker-compose.yml includes a commented mirror address (ghcr.nju.edu.cn/666ghj/mirofish:latest). Swap the image: line to use it.

Verify your install:

• [x] .env created with LLM_API_KEY and ZEP_API_KEY
• [x] Dependencies installed (source) or image pulled (Docker)
• [x] http://localhost:3000 loads the home page
• [x] http://localhost:5001/health returns {"status": "ok", "service": "MiroFish Backend"}

4. Preparing Your Seed Material

A MiroFish prediction is only as good as the seed you feed it. The seed is one or more documents that establish the world: who the actors are, what just happened, and what tensions exist.

Supported file types: .pdf, .md, .markdown, .txt. Each upload is capped at 50 MB.

Note

PDFs are parsed with PyMuPDF; Markdown and text files are read with automatic character-encoding detection, so non-UTF-8 files (for example GBK-encoded Chinese text) are handled gracefully.

Good seeds include:

• A breaking-news article or incident report (predict public reaction)
• A policy or product draft (rehearse the rollout before it happens)
• A market/financial brief (deduce sentiment-driven movement)
• A novel or story excerpt (explore alternate endings — the authors demonstrate this with the first 80 chapters of Dream of the Red Chamber)

Tip

Pair your document with a clear, specific prediction requirement in natural language — for example, "If Wuhan University publishes this statement, how will student opinion evolve over the next 48 hours?" MiroFish uses this requirement to shape the ontology, the agent population, and the report. Vague requirements produce vague predictions.

5. The Five-Step Workflow

Every prediction moves through five stages. MiroFish automates the hard parts — you mostly upload, describe, and click forward, watching live progress at each stage. The frontend guides you through them as views named Process → Simulation → Report → Interaction.

1. Graph Building     Upload seed → extract an ontology → build a knowledge graph
2. Environment Setup  Read entities → generate agent personas → auto-write the sim config
3. Simulation         Run thousands of agents on Twitter/Reddit-style platforms
4. Report Generation  An AI ReportAgent analyzes the finished world and writes a report
5. Deep Interaction   Chat with any agent, or with the ReportAgent, about the outcome

Step 1 — Graph Building

You upload your seed document(s) and type your prediction requirement. MiroFish then:

1. Extracts text from each file and stitches it together.
2. Generates an ontology — an LLM reads your documents and your requirement and proposes the entity types (e.g. Student, PublicFigure, Organization) and relationship types that matter for this world. You see a short analysis summary of what it found.
3. Builds a knowledge graph in Zep Cloud (a GraphRAG construction). Your text is split into overlapping chunks and ingested as graph "episodes"; Zep extracts entities and relationships into a queryable graph.

Graph building runs in the background and reports live progress ("creating graph", "adding chunks 12/40", "waiting for processing"). It finishes with a node and edge count.

Note

A project moves through clear states: created → ontology_generated → graph_building → graph_completed. If a build fails, you can reset the project and rebuild without re-uploading.

Step 2 — Environment Setup

With the graph built, MiroFish prepares the simulated world — fully automatically:

1. Reads and filters entities from the graph, keeping only the meaningful actors (those matching your ontology's entity types).
2. Generates an OASIS agent persona for each entity — a distinct personality, background, and behavioral profile, produced for both a Reddit-style and a Twitter-style platform.
3. Auto-writes the simulation configuration — an LLM derives sensible parameters (how many rounds, the time model, which events fire, platform settings) from your requirement. You don't hand-tune round counts; MiroFish proposes them.

You can watch personas appear in real time as they're generated, along with the expected total agent count.

Tip

Preparation is idempotent and cached. If you've already prepared a simulation, returning to this step reuses the existing personas and config instead of regenerating them (and burning tokens). Use the "regenerate" option only when you genuinely want a fresh population.

Step 3 — Simulation

Now the world runs. Thousands of agents take turns acting on the simulated platforms — posting, commenting, liking, reposting, following, and so on — round after round. Each agent reasons using its persona and its accumulated memory, and the graph's temporal memory updates dynamically as events unfold.

You control the run from the browser: start it (optionally overriding the recommended round count), watch live status and recent actions, and stop it early if you've seen enough.

As the simulation runs you can browse the generated posts, comments, a per-round timeline, and agent statistics.

Warning

This is the most token-intensive stage. Every active agent makes at least one LLM call per round, so cost scales with agents × rounds. Start small (the authors recommend < 40 rounds) and scale up once you trust your model and budget.

Step 4 — Report Generation

When the simulation has produced enough behavior, MiroFish's ReportAgent takes over. It's an autonomous analyst (a ReAct-style agent) that explores the finished world using a toolset — searching the knowledge graph, pulling statistics, reading what agents said and did — and writes a structured, sectioned prediction report.

Report generation is asynchronous. You can watch it build section by section, and even follow the agent's live reasoning log ("planning", "tool call: search graph", "section complete") and a console log as it works. Sections stream in as they're finished, so you can start reading before the whole report is done.

When it's finished you can read the full report in the browser and download it as Markdown.

Step 5 — Deep Interaction

The world doesn't disappear when the report is written. You can keep interacting with it in two ways:

• Interview any agent. Ask a specific agent — "Why did you change your mind?" — and it answers in character, drawing on its persona, memories, and everything it did during the simulation. You can interview one agent, a batch, or everyone at once.
• Chat with the ReportAgent. Ask follow-up questions about the prediction ("What drove the shift in sentiment around round 30?") and the agent answers, autonomously querying the graph for evidence as needed.

Note

Interviewing live agents requires the simulation environment to still be running. If you've closed it, MiroFish tells you the environment is no longer available for interviews. Chatting with the ReportAgent works any time after a report exists.

6. Common Tasks

Switch the interface language

MiroFish ships with English and Chinese and a language switcher in the UI. Your choice is remembered in the browser, and the backend honors it too — including the language the report and agent replies are written in.

Tip

Set your language before generating a report. The report is composed in your active interface language, so switching afterward won't translate an already-written report.

Reuse a world instead of rebuilding it

Every project, simulation, and report is saved on the backend. The home page shows your history of past simulations with their requirement, status, agent count, and round progress, so you can jump back into a finished world, reopen its report, or interview its agents without redoing any work.

Download a report for sharing

Open a completed report and use the download action to save it as a .md file. The Markdown is self-contained and renders anywhere.

Run a leaner simulation to save tokens

Choose a smaller, cheaper model in .env, keep your seed focused (fewer entities → fewer agents), and start with a low round count. You can always run a second, larger simulation on the same project once a small one looks promising.

7. Troubleshooting

MiroFish's backend reports errors in your selected interface language; the underlying messages below are shown as they appear in the code.

Error: LLM_API_KEY 未配置 / ZEP_API_KEY 未配置

Cause: A required API key is missing or empty. The backend refuses to start, and graph/simulation operations refuse to run, without both. Solution: Confirm .env exists in the project root, contains LLM_API_KEY and ZEP_API_KEY with real values, and that you restarted the backend after editing it. Prevention: Copy from .env.example and fill every required field before the first npm run dev.

Error: 500 on ontology generation with "thinking"/reasoning models

Cause: Reasoning models (for example Qwen3, DeepSeek-R1) emit chain-of-thought that can corrupt the strict JSON MiroFish expects when generating the ontology. This is reported in the community (issue #642). Solution: Use a standard instruction-tuned chat model (such as qwen-plus or gpt-4o-mini) for the LLM endpoint. MiroFish does strip <think>...</think> blocks and Markdown code fences from responses, but heavily reasoning-formatted output can still break. Prevention: Reserve reasoning models for tasks that don't require strict JSON; keep a reliable chat model configured as LLM_MODEL_NAME.

Error: LLM返回的JSON格式无效 (LLM returned invalid JSON)

Cause: The model returned text that wasn't valid JSON where structured output was required (ontology, persona, or config generation). Solution: Retry — MiroFish has automatic retry with backoff on LLM calls. If it persists, switch to a model that reliably honors JSON-mode requests. Prevention: Prefer models with solid JSON-mode support; avoid very small or experimental models for the generation steps.

Error: File upload fails / JSON parse error when uploading a PDF

Cause: Some PDFs trigger a parse error during upload (community issues #672 and #670 — Unexpected non-whitespace character after JSON). Solution: Convert the problematic PDF to Markdown or plain text and upload that instead, or try a different/regenerated PDF. Keep individual files under the 50 MB limit. Prevention: When possible, seed with .md/.txt; they parse most reliably.

Error: 不支持的文件格式 / 无法处理的文件格式 (unsupported file format)

Cause: You uploaded a file type MiroFish can't read. Only .pdf, .md, .markdown, and .txt are accepted. Solution: Convert your source to one of the supported formats. Prevention: Check the file extension before uploading.

Error: MiroFish could not complete this simulation run: fetch failed

Cause: The frontend couldn't reach the backend, or the backend lost its connection to the LLM/Zep provider mid-run (community issue #647). Solution: Confirm the backend is up (http://localhost:5001/health), check your network and provider status, and verify your API quotas aren't exhausted. Then restart the simulation. Prevention: Keep both services running and watch provider rate limits during long runs.

Error: HTTP 429 / repeated 500 during a long simulation

Cause: Your LLM provider is rate-limiting or quota-blocking the high call volume a multi-agent run generates (community issue #662). Solution: Reduce the round count and/or agent population, slow the run down, or move to a provider tier with higher limits. Prevention: Start with fewer than 40 rounds, then scale up gradually once you know your provider's ceiling.

The page hangs on a long operation

Cause: Graph building, environment preparation, and report generation are genuinely long-running; the client waits up to 5 minutes per request. Solution: This is expected — these steps run as background tasks and report live progress. Let them finish; don't refresh repeatedly. Prevention: Watch the on-screen progress indicators rather than assuming a stall.

Interviewing an agent says the environment isn't available

Cause: Live agent interviews require the simulation environment to still be running; it has been closed or has exited. Solution: Re-run the simulation to bring the environment back up, or use the ReportAgent chat (which works from saved data) instead. Prevention: Keep the environment open while you plan to interview agents.

8. Frequently Asked Questions

Q: Do I need a GPU or to host my own model? No. MiroFish calls a hosted LLM over the network using the OpenAI SDK format and uses Zep Cloud for the graph. There's no local model or GPU requirement.

Q: Which LLM should I use? Any OpenAI-compatible chat model. The authors recommend Qwen-plus via Alibaba Bailian as a balanced default; OpenAI models and other compatible endpoints also work. Avoid reasoning/"thinking" models for the generation steps (see Troubleshooting).

Q: How much will a run cost? It depends entirely on your model and the size of the run, since cost scales with agents × rounds. Start with a small simulation (< 40 rounds) to calibrate before committing to a large one.

Q: Can I predict stock prices / financial outcomes? MiroFish is a general "predict anything" engine and the authors point to financial prediction as a use case. It models collective behavior and sentiment, not market mechanics — treat its output as a scenario rehearsal, not financial advice.

Q: What languages does MiroFish support? English and Chinese out of the box, with an in-app switcher. The report and agent replies are written in your selected language.

Q: Where do my uploaded files and results go? They're stored by the backend under backend/uploads/ (projects, simulations, and reports), so your work persists across restarts. With Docker, that directory is bind-mounted to ./backend/uploads on your host.

Q: Can I re-open a finished prediction later? Yes. The home page lists your simulation history; from there you can revisit the world, reopen the report, or interview agents.

Q: Can I download the report? Yes — completed reports can be downloaded as Markdown from the report view.

Q: Can I change the number of simulation rounds? MiroFish proposes a round count automatically, but you can override it when you start a simulation.

Q: Is MiroFish free / open source? The project is released under the AGPL-3.0 license. You still pay your own LLM and Zep Cloud usage.

9. Reference

Service URLs

Required environment variables

Note

Additional optional and operational settings (the accelerated "boost" model, Flask host/port/debug, simulation round defaults, ReportAgent tuning) are documented in the Administrator & Developer Guide.

Supported seed file types

The workflow at a glance