MiroFish Deployment & Practical Guide: Building a Public Opinion Simulation System from Scratch

Foreword

Have you ever wondered if you could predict the public's reaction to a new policy or the ripple effects of a PR crisis before they even happen?

Traditional public opinion analysis relies on historical data and expert experience, which is essentially "looking in the rearview mirror." However, MiroFish offers a brand-new approach: letting AI construct a high-fidelity digital parallel world where thousands of agents with independent personalities and long-term memories interact freely, allowing us to observe the emergence of collective behavior.

This is known as "Swarm Intelligence."

MiroFish is an open-source multi-agent prediction engine released in 2025, powered by the OASIS simulation engine. It can take any seed material (press releases, analytical reports, or even novel plots), automatically build a digital world, and output predictive reports.

Today, we will start from scratch to deploy MiroFish and build a simple public opinion simulation system.

Core Concepts

Before we get hands-on, let's understand a few key concepts.

Seed Information

Seed information is the starting point of a prediction. It can be a news report, a financial analysis, a snippet of a novel, or even a trending discussion on social media. MiroFish extracts key entities, relationships, and event backgrounds from these materials.

Digital Parallel World

This is the core innovation of MiroFish. Instead of simply having AI generate a block of text, it constructs a real "world":

• Each agent has an independent personality, memory, and behavioral logic.
• Agents interact, spread information, and form factions.
• The entire system exhibits swarm characteristics that are unpredictable through individual behavior alone.

Imagine planting a piece of fake news into this world and observing how it ferments, reverses, and eventually shapes public opinion—that is the power of a digital parallel world.

Workflow

The complete MiroFish workflow consists of 5 steps:

1. Graph Construction: Extract entities and relationships from seed materials to build a knowledge graph.
2. Environment Setup: Generate agent personas and configure simulation parameters.
3. Simulation Run: Parallel simulation across dual platforms with dynamic memory updates.
4. Report Generation: The ReportAgent analyzes simulation results and generates predictive reports.
5. Deep Interaction: You can talk to any character within the simulated world.

---

Environment Preparation

MiroFish is a full-stack project with separate deployments for the frontend and backend.

Hardware Requirements

Software Dependencies

Check your environment:

node -v    # Should be >= 18.0.0
python --version  # Should be between 3.11 - 3.12
uv --version

---

Quick Deployment

We will demonstrate the deployment using the source code method for maximum flexibility.

1. Clone the Project

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

2. Configure Environment Variables

cp .env.example .env

Edit the .env file and fill in your API configuration. You have two options:

Option A: Using Alibaba Cloud Bailian (Official Recommendation)

LLM_API_KEY=your_aliyun_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

Option B: Using other OpenAI-compatible APIs

LLM_API_KEY=your_api_key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o

You also need to configure Zep Cloud (for agent memory management):

ZEP_API_KEY=your_zep_api_key

3. Install Dependencies

npm run setup:all

This will simultaneously install:

• Node dependencies in the root directory
• Frontend dependencies
• Python dependencies (automatically creating a virtual environment)

If the network is slow, you can execute these steps separately:

npm run setup           # Frontend
npm run setup:backend   # Backend

4. Start the Services

npm run dev

Once the services are started:

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

Alternative: Docker Deployment

If you want to get started quickly, you can use Docker:

# 1. Configure environment variables
cp .env.example .env

# 2. Start the containers
docker compose up -d

The Docker method will automatically map ports 3000 (frontend) and 5001 (backend).

---

Practical Exercise

Now, let's create a public opinion simulation task.

1. Access the Web UI

Open http://localhost:3000 in your browser to see the MiroFish main interface.

2. Create a Prediction Task

Click "New Prediction" and select the "Public Opinion Simulation" type.

3. Input Seed Material

Enter some news material into the text box, for example:

A well-known internet company announced today that it will lay off 10% of its workforce, citing the need for business adjustments to focus more on core areas. 
The news immediately sparked heated discussions on social media. Some employees expressed dissatisfaction, 
arguing the company failed to communicate in advance; meanwhile, some netizens expressed understanding regarding corporate operational pressures. 
The company CEO emphasized in an internal letter that this was a difficult but necessary decision, 
and the company will provide generous severance packages and assist employees with job referrals.

4. Describe Prediction Requirements

Describe what you want to predict in natural language:

Predict how public reaction will evolve after this layoff news is released. 
Will it form a negative public opinion crisis? How long might it last? Which groups will take what stances?

5. Start Simulation

Click "Start Simulation," and the system will:

1. Extract key entities (Company, CEO, Employees, Netizens) from the seed material.
2. Build a knowledge graph.
3. Generate multiple agents with different personas (sympathetic netizens, rational analysts, curious bystanders, etc.).
4. Begin the interaction simulation.

6. View Prediction Results

Once the simulation is complete, you will see a detailed prediction report, including:

• Public opinion trend curves
• Distribution of major viewpoints
• Prediction of key turning points
• Recommended response strategies

7. Deep Interaction

This is the most interesting part of MiroFish. You can:

• Have a one-on-one conversation with any agent: "You are the netizen who sympathizes with employees; what is your take on this?"
• Ask the ReportAgent specific questions: "If the company issues an open letter in response, how will public opinion change?"

---

AI Provider Configuration

We used the Alibaba Cloud Bailian model above. However, if you want to reduce costs or use other models, consider the Defapi platform.

Defapi is an API relay service with prices as low as half the official rate, supporting:

• OpenAI (GPT-4o, GPT-4.5)
• Anthropic (Claude Sonnet, Claude Opus)
• Google (Gemini)

It is fully compatible with the OpenAI SDK; you only need to modify two parameters:

# Using Defapi
LLM_API_KEY=your_Defapi-Key
LLM_BASE_URL=https://api.defapi.org/v1
LLM_MODEL_NAME=openai/gpt-4o-mini

Or use it in code:

from openai import OpenAI

client = OpenAI(
    api_key="your_Defapi-Key",
    base_url="https://api.defapi.org/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

---

Troubleshooting

1. npm install Fails

Check your Node.js version:

node -v

It must be 18+. If the version is correct but installation fails, try:

npm cache clean --force
npm install --legacy-peer-deps

2. Python Dependency Installation Stuck

Confirm your Python version is between 3.11 and 3.12:

python --version

If it's outside this range, use pyenv or conda to manage your Python versions.

3. Backend Reports "Model not found"

Check if LLM_MODEL_NAME is correct. Different API providers use different naming formats:

• Alibaba Cloud: qwen-plus
• OpenAI: gpt-4o
• Defapi: openai/gpt-4o-mini

4. Simulation is Very Slow

A few optimization tips:

• Reduce simulation rounds (e.g., from 40 to 20).
• Use a smaller model.
• Reduce the number of agents.
• Ensure a stable network connection (API calls have latency).

5. High Memory Usage

If your machine has less than 16GB of RAM, you can limit concurrency in .env:

MAX_CONCURRENT_AGENTS=10

Alternatively, reduce the number of agents interacting per round.

6. Frontend Page is Blank

Check if the backend is running properly:

curl http://localhost:5001/health

If it returns an error, check if the .env configuration is loaded correctly.

---

Advanced Directions

Customizing Agent Personalities

MiroFish allows you to customize agent personas when creating tasks. You can specify:

• Age, occupation, and character traits.
• Stance leanings (Supportive/Opposed/Neutral).
• Background stories.

Fine-tuning personas makes the simulation much closer to real-world scenarios.

Connecting More Data Sources

Currently, text-based seed materials are supported. In the future, you could connect:

• Social Media APIs (crawling real public opinion data).
• News RSS feeds.
• Financial databases.

Expanding Use Cases

Beyond public opinion simulation, MiroFish can be used for:

• Financial Prediction: Simulating the evolution of market sentiment.
• Policy Simulation: Predicting social reactions after a policy is released.
• Creative Writing: Simulating the progression of novel plots (e.g., letting AI predict the final 40 chapters of Dream of the Red Chamber).
• Crisis Simulation: Rehearsing response strategies for PR crises.

---

Further Reading

• GitHub Repository: https://github.com/666ghj/MiroFish
• Online Demo: https://666ghj.github.io/mirofish-demo/
• Official Docs: https://deepwiki.com/666ghj/MiroFish
• Defapi Platform: https://defapi.org
• OASIS Engine: https://github.com/camel-ai/oasis

If you are interested in multi-agent systems and want to experience "letting AI predict the future," MiroFish is an excellent starting point.