SimuVerse

A Simple and Universal Swarm Intelligence Engine, Predicting Anything

简洁通用的群体智能引擎，预测万物

English | 中文文档

Evolved from the open-source project MiroFish.

SimuVerse 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 interact and evolve socially. You can inject variables dynamically from a "God's-eye view" to precisely deduce future trajectories.

You only need to: upload seed materials (data analysis reports or interesting novel stories) and describe your prediction requirements in natural language.

SimuVerse returns: a detailed prediction report and a deeply interactive high-fidelity digital world.

---

📑 Table of Contents

• Features
• Architecture & Workflow
• Tech Stack
• Project Structure
• Quick Start
• Configuration
• Usage Guide
• Documentation
• License

---

✨ Features

SimuVerse is a full-pipeline AI prediction platform that turns a piece of raw material into a verifiable forecast. It does not give a single answer — it builds a living, interactive world where a future can be rehearsed from many angles before you decide.

What it does for you:

• Turn raw material into a modeled world — feed in a data report, a piece of news, or a story; SimuVerse extracts the entities, relationships, and underlying logic and reconstructs them into a high-fidelity parallel digital world.
• Run a crowd of independent agents — the world is populated with thousands of agents, each with its own persona, long-term memory, and behavioral logic. They interact and evolve socially, producing collective behavior that a single model cannot foresee.
• Simulate "what if" at scale — inject new variables from a "God's-eye view" at any time (a policy change, a market shock, a plot twist) and watch how the whole society reacts, so you can compare multiple scenarios side by side.
• Get a structured, evidence-backed report — a ReportAgent with a rich toolset digs into the simulated world and produces a detailed prediction report with reasoning and evidence.
• Interact with the result — talk to any agent in the world or query the ReportAgent to challenge assumptions and probe deeper into the forecast.
• Reuse across projects — every project is stored in a history database with the same export capabilities (Markdown / PDF), so past simulations and reports stay accessible.

Core capabilities:

• GraphRAG Knowledge Graph — extract entities and relations, inject individual & collective memory for grounded reasoning.
• Swarm Emergence — capture collective behavior that emerges from individual interactions.
• God's-eye View — dynamically inject variables to precisely deduce future trajectories.
• Deep Interaction — chat with any agent in the simulated world, and interact with the ReportAgent.
• Rich Exports — export simulation processes, reports, and interaction histories as Markdown or PDF.

🏗 Architecture & Workflow

 ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
 │ Graph      │   │ Environment│   │ Simulation │   │ Report     │   │ Deep       │
 │ Building   │ → │ Setup      │ → │            │ → │ Generation │ → │ Interaction│
 │            │   │            │   │            │   │            │   │            │
 └────────────┘   └────────────┘   └────────────┘   └────────────┘   └────────────┘

1. Graph Building — seed extraction, individual & collective memory injection, GraphRAG construction.
2. Environment Setup — entity-relation extraction, persona generation, environment config injection.
3. Simulation — dual-platform parallel simulation, automatic prediction-requirement parsing, dynamic temporal memory updates.
4. Report Generation — ReportAgent with a rich toolset for deep interaction with the post-simulation environment.
5. Deep Interaction — chat with any agent in the simulated world, and interact with the ReportAgent.

🧩 Tech Stack

Layer	Technology
Frontend	Vue 3, Vite, Recharts
Backend	Python, Flask, uvicorn
Graph Engine	Zep Cloud / Graphiti (local Neo4j)
Simulation Engine	OASIS (Open Agent Social Interaction Simulations)
LLM	DashScope/Qwen, DeepSeek, OpenAI, or any OpenAI-compatible endpoint
Deployment	Docker Compose, GitHub Actions

📁 Project Structure

MiroFish/
├── backend/                 # Python Flask backend
│   ├── app/
│   │   ├── api/             # REST API blueprints (graph, simulation, report)
│   │   └── services/        # Business logic (graph_provider, simulation, report)
│   └── run.py               # Backend entry point
├── frontend/                # Vue 3 frontend
│   └── src/
│       ├── components/      # Reusable Vue components
│       └── views/           # Page views
├── locales/                 # i18n dictionaries (zh / en)
├── scripts/                 # Utility scripts (e.g. star history)
├── static/                  # Static assets (logos, screenshots)
├── tests/                   # Backend tests
├── docs/                    # Project documentation
├── docker-compose.yml       # Docker deployment
├── .env.example             # Environment variable template
└── README.md                # This file

🚀 Quick Start

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

Option 1: Source Code Deployment (Recommended)

1. Configure Environment Variables

cp .env.example .env

Edit .env and fill in the required API keys:

# LLM API config (supports any OpenAI-SDK-compatible LLM API)
# Recommended: Alibaba Qwen via Bailian Platform: https://bailian.console.aliyun.com/
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# Zep Cloud config (free monthly quota is enough for basic use)
ZEP_API_KEY=your_zep_api_key

2. Install Dependencies

# One-click install (root + frontend + backend)
npm run setup:all

Or step by step:

npm run setup          # Node dependencies (root + frontend)
npm run setup:backend  # Python dependencies (backend, auto-creates venv)

3. Start Services

npm run dev

Service URLs:

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

Start individually:

npm run backend   # Backend only
npm run frontend  # Frontend only

Option 2: Docker Deployment

cp .env.example .env   # Configure environment variables
docker compose up -d   # Pull image and start

Reads .env from the root directory by default, maps ports 3000 (frontend) / 5001 (backend). Faster mirror addresses are provided as comments in docker-compose.yml.

⚙️ Configuration

LLM, Graph Engine & Compute Profile

At project creation, SimuVerse persists three choices with the project so a later .env change cannot silently switch an existing run:

Choice	Available values	Notes
LLM profile	Any configured LLM_PROVIDER_<NAME>_* group, or the default LLM_* variables	Supports DashScope/Qwen, DeepSeek, OpenAI, and OpenAI-compatible local endpoints (e.g. Ollama)
Graph engine	zep_cloud / graphiti	Zep uses the hosted graph service; Graphiti uses the local Neo4j
Compute profile	cpu / gpu	Applies to Graphiti's local embedding & reranking models

For Graphiti, start Neo4j first and set NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD. The default CPU environment and the optional CUDA environment are intentionally separate. See docs/INSTALL.md for verified setup commands and GPU wheel guidance.

Graphiti ingestion cost is dominated by the structured extraction LLM call. For a stable first run, keep the following defaults:

GRAPHITI_LLM_CONCURRENCY=1
GRAPHITI_LLM_ENABLE_THINKING=auto
GRAPHITI_MAX_EPISODE_CHARS=3000

In auto mode, DashScope Qwen3.x structured extraction automatically disables the long-thinking path (recommended latency setting). Set true to restore thinking or false to disable explicitly. Do not change the graph engine or project binding while ingestion is active.

📖 Usage Guide

1. Create a project — choose an LLM profile, graph engine, and compute profile; upload seed materials and describe your prediction requirement in natural language.
2. Build the graph — the system extracts entities and relations and constructs a GraphRAG knowledge graph.
3. Run simulation — thousands of agents interact and evolve in the parallel world.
4. Generate report — the ReportAgent produces a detailed prediction report.
5. Deep interaction — chat with any agent or the ReportAgent, and export results.

Exportable Outputs

• Step 3 — export simulation process/results as Markdown or PDF.
• Step 4 — export the generated report as Markdown or PDF.
• Step 5 — export simulation-world interaction and interview/chat history as Markdown or PDF.
• History database — exposes the same report, simulation, and interaction exports for completed projects.

📚 Documentation

Document	Description
docs/INSTALL.md	Verified installation & GPU setup guide
docs/	Additional design, API, and deployment docs

📄 License

This project is open-sourced under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.