A Simple and Universal Swarm Intelligence Engine, Predicting Anything
A Simple and Universal Swarm Intelligence Engine, Predicting Anything

README | Alternate Copy

⚡ Overview

MiroFish is a next-generation AI prediction engine powered by multi-agent technology. By extracting seed information from the real world such as breaking news, policy drafts, or financial signals, it automatically constructs a high-fidelity parallel digital world. Within this space, thousands of intelligent agents with independent personalities, long-term memory, and behavioral logic freely interact and undergo social evolution. You can inject variables dynamically from a God's-eye view to infer future trajectories with much higher context.

You only need to upload seed materials such as reports or stories and describe your prediction request in natural language.
MiroFish returns a detailed prediction report and a deeply interactive high-fidelity digital world.

Vision

MiroFish aims to build a swarm-intelligence mirror of reality by modeling emergent collective behavior from individual interactions:

• Macro use cases: a rehearsal lab for decision-makers to test policy or communications strategies with near-zero real-world risk.
• Micro use cases: a creative sandbox for individuals to explore novel endings, alternate histories, or speculative scenarios.

From serious forecasting to playful simulation, MiroFish is designed to make "what if" questions explorable.

🌐 Live Demo

Try the online demo here: mirofish-live-demo

📸 Screenshots

🎬 Demo Videos

1. Wuhan University Public Opinion Simulation + MiroFish Introduction

Click the image to watch the full demo video based on a BettaFish-generated Wuhan University public-opinion report.

2. Dream of the Red Chamber Lost Ending Simulation

Click the image to watch MiroFish infer a lost ending based on the first 80 chapters of Dream of the Red Chamber.

More examples for finance, politics, and current-events forecasting are planned.

🔄 Workflow

1. Graph Building: extract seeds from source material, inject individual and collective memory, and build a GraphRAG-ready graph.
2. Environment Setup: extract entities and relationships, generate personas, and inject simulation parameters.
3. Simulation: run dual-platform simulations, parse the prediction request, and update temporal memory dynamically.
4. Report Generation: use ReportAgent and its tools to analyze the post-simulation environment.
5. Deep Interaction: talk to agents inside the simulated world or continue through ReportAgent.

🚀 Quick Start

Option 1: Run From Source

Prerequisites

Tool	Version	Description	Check
Node.js	18+	Frontend runtime, includes npm	node -v
Python	>=3.11, <=3.12	Backend runtime	python --version
uv	Latest	Python package manager	uv --version

1. Configure environment variables

cp .env.example .env

Fill in the required API keys in .env.

# LLM API configuration (any OpenAI-compatible API)
LLM_API_KEY=your_api_key
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

2. Install dependencies

npm run setup:all

Or install by layer:

npm run setup
npm run setup:backend

3. Start services

npm run dev

Service URLs:

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001

Run individually:

npm run backend
npm run frontend

Option 2: Docker

cp .env.example .env
docker compose up -d

This reads the root .env file and maps ports 3000 and 5001.

📬 Contact

The MiroFish team is recruiting full-time and internship roles. Contact: mirofish@shanda.com

📄 Acknowledgments

MiroFish has received strategic support and incubation from Shanda Group.

MiroFish's simulation engine is powered by OASIS. Thanks to the CAMEL-AI team for the open-source foundation.

📈 Project Statistics