MiroFish is an AI prediction engine that simulates the future using thousands of AI agents. Upload a document, ask a question, and watch thousands of simulated people interact — then get a prediction report.
This fork makes it accessible to English speakers with multi-provider LLM support.
The original MiroFish is an incredible project, but the entire UI, prompts, and documentation are in Chinese. This fork:
- Full English UI — Every button, label, log message, and report is in English
- English LLM prompts — AI agents think, speak, and write reports in English
- Multi-provider support — Use OpenAI, Groq (free), OpenRouter, Together AI, or any OpenAI-compatible API
- Rate limit protection — Auto-retry with exponential backoff on 429 errors
- Better docs — Clear setup instructions for English-speaking developers
| Tool | Version | Install Check |
|---|---|---|
| Node.js | 18+ | node -v |
| Python | 3.11 - 3.12 | python --version |
| uv | Latest | uv --version |
git clone https://github.com/psdew2ewqws/MiroFish-EN.git
cd MiroFish-EN
# Create your config
cp .env.example .envEdit .env with your API keys:
# LLM Configuration — any OpenAI-compatible API works
# Option 1: OpenAI
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o-mini
# Option 2: Groq (free tier available)
# LLM_API_KEY=gsk_your-groq-key
# LLM_BASE_URL=https://api.groq.com/openai/v1
# LLM_MODEL_NAME=llama-3.3-70b-versatile
# Option 3: OpenRouter (access to Claude, Gemini, etc.)
# LLM_API_KEY=sk-or-your-key
# LLM_BASE_URL=https://openrouter.ai/api/v1
# LLM_MODEL_NAME=anthropic/claude-sonnet-4-20250514
# Option 4: Together AI
# LLM_API_KEY=your-together-key
# LLM_BASE_URL=https://api.together.xyz/v1
# LLM_MODEL_NAME=meta-llama/Llama-3.3-70B-Instruct-Turbo
# Zep Cloud — free tier at https://app.getzep.com/
ZEP_API_KEY=your_zep_api_key# Install everything (Node + Python)
npm run setup:allNote: If you have Python 3.13+, install Python 3.12 first:
uv python install 3.12Then inbackend/:uv sync --python 3.12
npm run dev- Frontend: http://localhost:3000
- Backend API: http://localhost:5001
- Upload — Drop in a PDF, markdown, or text file as "seed material"
- Describe — Tell MiroFish what you want to predict in plain English
- Graph Building — Extracts entities, relationships, and builds a knowledge graph
- Simulation — Thousands of AI agents interact across two social platforms
- Report — An AI analyst generates a detailed prediction report
- Interact — Chat with any agent in the simulated world
- Business Strategy — "Will my product succeed if I launch in this market?"
- Market Prediction — "How will competitors react to our pricing change?"
- Crisis Simulation — "What happens if this news leaks? How does public opinion shift?"
- Content & Stories — "How would this novel's plot unfold?"
- Policy Testing — "If we implement this policy, what are the social consequences?"
| Provider | Model | Cost (per 1M tokens) | Best For |
|---|---|---|---|
| OpenAI | gpt-4o-mini | $0.15 in / $0.60 out | Best balance of cost & quality |
| OpenAI | gpt-4o | $2.50 in / $10.00 out | Highest quality |
| Groq | llama-3.3-70b | Free tier available | Testing & experimentation |
| OpenRouter | Any model | Varies | Access to Claude, Gemini, etc. |
| Together | Llama-3.3-70B | ~$0.60 in / $0.60 out | Good open-source option |
Tip: Start with gpt-4o-mini — it's cheap (~$0.30 per simulation) and good enough for most use cases.
cp .env.example .env
# Edit .env with your keys
docker compose up -d- Rate limits? The built-in retry handler will auto-wait and retry (up to 5 times)
- Zep quota? Free tier supports basic simulations. Create a new account at https://app.getzep.com/ if you hit limits
- Cost control? Use fewer agents (10-15) and fewer rounds (10-20) to reduce API costs
- Python 3.13? Use
uv python install 3.12anduv sync --python 3.12in the backend directory
- Original project: MiroFish by the MiroFish team
- Simulation engine powered by OASIS (CAMEL-AI)
- Strategic support from Shanda Group
AGPL-3.0 — Same as the original MiroFish project.