294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
<div align="center">
|
|
|
|
<img src="./static/image/MiroFish_logo_compressed.jpeg" alt="MiroFish Logo" width="75%"/>
|
|
|
|
<a href="https://trendshift.io/repositories/16144" target="_blank"><img src="https://trendshift.io/api/badge/repositories/16144" alt="666ghj%2FMiroFish | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
|
|
|
<em>A Simple and Universal Swarm Intelligence Engine, Predicting Anything</em>
|
|
|
|
<a href="https://www.shanda.com/" target="_blank"><img src="./static/image/shanda_logo.png" alt="666ghj%2MiroFish | Shanda" height="40"/></a>
|
|
|
|
[](https://github.com/666ghj/MiroFish/stargazers)
|
|
[](https://github.com/666ghj/MiroFish/watchers)
|
|
[](https://github.com/666ghj/MiroFish/network)
|
|
[](https://hub.docker.com/)
|
|
[](https://deepwiki.com/666ghj/MiroFish)
|
|
|
|
[](http://discord.gg/ePf5aPaHnA)
|
|
[](https://x.com/mirofish_ai)
|
|
[](https://www.instagram.com/mirofish_ai/)
|
|
|
|
[English](./README.md) | [中文文档](./README-ZH.md)
|
|
|
|
</div>
|
|
|
|
## ⚡ 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 precisely deduce future trajectories — **rehearse the future in a digital sandbox, and win decisions after countless simulations**.
|
|
|
|
> You only need to: Upload seed materials (data analysis reports or interesting novel stories) and describe your prediction requirements in natural language</br>
|
|
> MiroFish will return: A detailed prediction report and a deeply interactive high-fidelity digital world
|
|
|
|
### Our Vision
|
|
|
|
MiroFish is dedicated to creating a swarm intelligence mirror that maps reality. By capturing the collective emergence triggered by individual interactions, we break through the limitations of traditional prediction:
|
|
|
|
- **At the Macro Level**: We are a rehearsal laboratory for decision-makers, allowing policies and public relations to be tested at zero risk
|
|
- **At the Micro Level**: We are a creative sandbox for individual users — whether deducing novel endings or exploring imaginative scenarios, everything can be fun, playful, and accessible
|
|
|
|
From serious predictions to playful simulations, we let every "what if" see its outcome, making it possible to predict anything.
|
|
|
|
## 🌐 Live Demo
|
|
|
|
Welcome to visit our online demo environment and experience a prediction simulation on trending public opinion events we've prepared for you: [mirofish-live-demo](https://666ghj.github.io/mirofish-demo/)
|
|
|
|
## 📸 Screenshots
|
|
|
|
<div align="center">
|
|
<table>
|
|
<tr>
|
|
<td><img src="./static/image/Screenshot/screenshot1.png" alt="Screenshot 1" width="100%"/></td>
|
|
<td><img src="./static/image/Screenshot/screenshot2.png" alt="Screenshot 2" width="100%"/></td>
|
|
</tr>
|
|
<tr>
|
|
<td><img src="./static/image/Screenshot/screenshot3.png" alt="Screenshot 3" width="100%"/></td>
|
|
<td><img src="./static/image/Screenshot/screenshot4.png" alt="Screenshot 4" width="100%"/></td>
|
|
</tr>
|
|
<tr>
|
|
<td><img src="./static/image/Screenshot/screenshot5.png" alt="Screenshot 5" width="100%"/></td>
|
|
<td><img src="./static/image/Screenshot/screenshot6.png" alt="Screenshot 6" width="100%"/></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
## 🎬 Demo Videos
|
|
|
|
### 1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction
|
|
|
|
<div align="center">
|
|
<a href="https://www.bilibili.com/video/BV1VYBsBHEMY/" target="_blank"><img src="./static/image/wuhan-university-simulation-cover.png" alt="MiroFish Demo Video" width="75%"/></a>
|
|
|
|
Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"
|
|
</div>
|
|
|
|
### 2. Dream of the Red Chamber Lost Ending Simulation
|
|
|
|
<div align="center">
|
|
<a href="https://www.bilibili.com/video/BV1cPk3BBExq" target="_blank"><img src="./static/image/dream-of-the-red-chamber-simulation-cover.jpg" alt="MiroFish Demo Video" width="75%"/></a>
|
|
|
|
Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"
|
|
</div>
|
|
|
|
> **Financial Prediction**, **Political News Prediction** and more examples coming soon...
|
|
|
|
## 🔄 Workflow
|
|
|
|
1. **Graph Building**: Seed extraction & Individual/collective memory injection & GraphRAG construction
|
|
2. **Environment Setup**: Entity relationship extraction & Persona generation & Agent configuration injection
|
|
3. **Simulation**: Dual-platform parallel simulation & Auto-parse prediction requirements & Dynamic temporal memory updates
|
|
4. **Report Generation**: ReportAgent with rich toolset for deep interaction with post-simulation environment
|
|
5. **Deep Interaction**: Chat with any agent in the simulated world & Interact with ReportAgent
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Option 1: Docker Deployment (Recommended)
|
|
|
|
The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command.
|
|
|
|
```bash
|
|
# 1. Copy and configure environment variables
|
|
cp .env.example .env
|
|
# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default)
|
|
|
|
# 2. Pull images and start
|
|
docker compose up -d
|
|
```
|
|
|
|
Reads `.env` from the project root, exposes ports `3000` (frontend) and `5001` (backend).
|
|
|
|
> A faster mirror address is provided as a comment inside `docker-compose.yml`; uncomment to use it.
|
|
|
|
### Option 2: Source Code Deployment
|
|
|
|
#### Prerequisites
|
|
|
|
| Tool | Version | Description | Check Installation |
|
|
|------|---------|-------------|-------------------|
|
|
| **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` |
|
|
| **Neo4j** | 5.x Community | Local knowledge graph database | `neo4j --version` |
|
|
| **Ollama** | Latest | Local embedder host (default `mxbai-embed-large`) | `ollama --version` |
|
|
|
|
**Install Neo4j (choose one):**
|
|
|
|
```bash
|
|
# macOS
|
|
brew install neo4j
|
|
|
|
# Linux (Debian/Ubuntu)
|
|
# See official docs: https://neo4j.com/docs/operations-manual/current/installation/linux/
|
|
|
|
# Windows / All platforms
|
|
# Download Neo4j Desktop: https://neo4j.com/download/
|
|
|
|
# Set password before first start, then launch
|
|
neo4j-admin dbms set-initial-password your_neo4j_password
|
|
neo4j start
|
|
```
|
|
|
|
**Install Ollama and pull the default models:**
|
|
|
|
```bash
|
|
# macOS / Linux: https://ollama.com/download
|
|
ollama pull mxbai-embed-large # embedder for the knowledge graph
|
|
ollama pull qwen2.5:3b # reranker for Graphiti search results
|
|
# Ollama serves the OpenAI-compatible /v1 endpoint on http://localhost:11434
|
|
# by default — no further configuration required.
|
|
```
|
|
|
|
> If you prefer to run a remote embedder (OpenAI / Gemini), see the commented
|
|
> fallback block below; Ollama is the default but is not mandatory.
|
|
|
|
#### 1. Configure Environment Variables
|
|
|
|
```bash
|
|
# Copy the example configuration file
|
|
cp .env.example .env
|
|
|
|
# Edit the .env file and fill in the required API keys
|
|
```
|
|
|
|
**Required Environment Variables:**
|
|
|
|
```env
|
|
# LLM API Configuration (supports any LLM API with OpenAI SDK format)
|
|
# Recommended: Alibaba Qwen-plus model via Bailian Platform: https://bailian.console.aliyun.com/
|
|
# High consumption, try simulations with fewer than 40 rounds first
|
|
LLM_API_KEY=your_api_key
|
|
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
|
LLM_MODEL_NAME=qwen-plus
|
|
|
|
# Knowledge Graph — local Neo4j + Graphiti (free, no rate limits)
|
|
NEO4J_URI=bolt://localhost:7687
|
|
NEO4J_USER=neo4j
|
|
NEO4J_PASSWORD=your_neo4j_password
|
|
|
|
# Embeddings — default: local Ollama, free, no API key, OpenAI-compatible endpoint.
|
|
# Pre-requisite: `ollama pull mxbai-embed-large` (1024-dim, matches Graphiti).
|
|
# In Docker, host.docker.internal:11434 reaches the host daemon; in host mode
|
|
# (`npm run dev`) keep http://localhost:11434/v1 as below.
|
|
EMBEDDING_BASE_URL=http://localhost:11434/v1
|
|
EMBEDDING_API_KEY=ollama
|
|
EMBEDDING_MODEL=mxbai-embed-large
|
|
|
|
# Reranker — reorders Graphiti search results before the report tools see them.
|
|
# Default targets the same local Ollama host used for embeddings.
|
|
# Pre-requisite for the default: `ollama pull qwen2.5:3b`.
|
|
# Set RERANKER_PROVIDER=none to keep the legacy passthrough (useful for CI /
|
|
# slim containers that cannot pull a reranker model).
|
|
RERANKER_PROVIDER=ollama
|
|
RERANKER_MODEL=qwen2.5:3b
|
|
# Optional — both default to the EMBEDDING_* equivalents when unset.
|
|
# RERANKER_BASE_URL=http://localhost:11434/v1
|
|
# RERANKER_API_KEY=ollama
|
|
|
|
# Embeddings — remote fallback (uncomment ONE block if you prefer not to run
|
|
# Ollama locally). Note: any override must produce 1024-dim vectors to match
|
|
# Graphiti's vector index — 768-dim models (e.g. nomic-embed-text) are NOT
|
|
# supported.
|
|
#
|
|
# OpenAI:
|
|
# EMBEDDING_BASE_URL=https://api.openai.com/v1
|
|
# EMBEDDING_API_KEY=your_openai_api_key
|
|
# EMBEDDING_MODEL=text-embedding-3-small
|
|
#
|
|
# Gemini (set GRAPHITI_LLM_PROVIDER=gemini in this case):
|
|
# EMBEDDING_MODEL=gemini-embedding-001
|
|
```
|
|
|
|
**Embedder smoke test (recommended before the first graph build):**
|
|
|
|
```bash
|
|
curl -s "$EMBEDDING_BASE_URL/embeddings" \
|
|
-H "Authorization: Bearer $EMBEDDING_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"model":"'"$EMBEDDING_MODEL"'","input":"ping"}' \
|
|
| jq '.data[0].embedding | length'
|
|
# Expected output: 1024
|
|
```
|
|
|
|
**Optional — Accelerated LLM Configuration:**
|
|
|
|
If you have a faster/cheaper provider, you can route auxiliary calls through it.
|
|
**Omit these entirely** if not used (do not leave placeholder values).
|
|
|
|
```env
|
|
LLM_BOOST_API_KEY=your_api_key_here
|
|
LLM_BOOST_BASE_URL=your_base_url_here
|
|
LLM_BOOST_MODEL_NAME=your_model_name_here
|
|
```
|
|
|
|
> **Note:** MiroFish has migrated from Zep Cloud to local **Graphiti + Neo4j**. No third-party knowledge-graph account is required — completely free with no rate limits.
|
|
|
|
#### 2. Install Dependencies
|
|
|
|
```bash
|
|
# One-click installation of all dependencies (root + frontend + backend)
|
|
npm run setup:all
|
|
```
|
|
|
|
Or install step by step:
|
|
|
|
```bash
|
|
# Install Node dependencies (root + frontend)
|
|
npm run setup
|
|
|
|
# Install Python dependencies (backend, auto-creates virtual environment)
|
|
npm run setup:backend
|
|
```
|
|
|
|
#### 3. Start Services
|
|
|
|
```bash
|
|
# Start both frontend and backend (run from project root)
|
|
npm run dev
|
|
```
|
|
|
|
**Service URLs:**
|
|
- Frontend: `http://localhost:3000`
|
|
- Backend API: `http://localhost:5001`
|
|
|
|
**Start Individually:**
|
|
|
|
```bash
|
|
npm run backend # Start backend only
|
|
npm run frontend # Start frontend only
|
|
```
|
|
|
|
## 📬 Join the Conversation
|
|
|
|
<div align="center">
|
|
<img src="./static/image/qq-group.png" alt="QQ Group" width="60%"/>
|
|
</div>
|
|
|
|
|
|
|
|
The MiroFish team is recruiting full-time/internship positions. If you're interested in multi-agent simulation and LLM applications, feel free to send your resume to: **mirofish@shanda.com**
|
|
|
|
## 📄 Acknowledgments
|
|
|
|
**MiroFish has received strategic support and incubation from Shanda Group!**
|
|
|
|
MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interaction Simulations)](https://github.com/camel-ai/oasis)**, We sincerely thank the CAMEL-AI team for their open-source contributions!
|
|
|
|
## 📈 Project Statistics
|
|
|
|
<a href="https://www.star-history.com/#666ghj/MiroFish&type=date&legend=top-left">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&theme=dark&legend=top-left" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=666ghj/MiroFish&type=date&legend=top-left" />
|
|
</picture>
|
|
</a>
|