Preecha

Posted on Aug 16

What Is MiroFish? A Multi-Agent AI Simulation Platform for Predicting Social Media Outcomes

Introduction

You’ve seen it happen: a company announces a policy, a celebrity makes a controversial statement, or an unexpected news story breaks. Social media reacts immediately, and the consequences can spread in ways nobody predicted.

Try Apidog today

What if you could test how a scenario might play out before it reaches the real world?

MiroFish is a multi-agent AI simulation platform for exploring social-media “what if” questions. It creates a digital parallel world where hundreds of AI agents—with distinct personalities, memories, and behavior patterns—interact freely.

Provide seed material such as a news article, policy draft, or research paper, then simulate how different audiences might react over time.

💡 The MiroFish team built and tested its simulation APIs with Apidog. From graph-construction endpoints to interview API responses, Apidog acted as the backend/frontend contract source of truth during development.

This guide explains how MiroFish works, how to run a simulation, and where the platform is most useful.

What Problem Does MiroFish Solve?

The prediction gap

Most social-media analysis tools are retrospective:

Sentiment analysis shows what people think now.
Trend monitoring shows what is popular today.
Engagement metrics measure what already happened.

These tools do not help answer questions such as:

What happens if we publish this announcement?
Which stakeholder groups might oppose a new policy?
How could a controversy evolve over the next 24–72 hours?

The alternative: digital parallel worlds

MiroFish simulates a social environment instead of analyzing live social media.

The workflow is:

Build a knowledge graph from source documents.
Extract entities such as people, organizations, and media outlets.
Convert entities into AI agents.
Assign behavior parameters, including activity level, influence, and topic stance.
Run simulated interactions across time.
Analyze the narratives, dominant voices, and counter-movements that emerge.

Think of it as a flight simulator for social-media scenarios.

How MiroFish Works: The Five-Step Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Step 1    │ ──► │   Step 2    │ ──► │   Step 3    │ ──► │   Step 4    │ ──► │   Step 5    │
│  Ontology   │     │  GraphRAG   │     │   Env       │     │ Simulation  │     │   Report    │
│  Generation │     │   Build     │     │   Setup     │     │   Run       │     │ Generation  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Step 1: Generate an ontology

MiroFish analyzes the input documents and simulation requirements, then uses an LLM to generate a custom ontology.

The ontology defines:

10 entity types, such as Student, Professor, University, MediaOutlet, and GovernmentAgency
10 relationship types, such as WORKS_FOR, COMMENTS_ON, and RESPONDS_TO
Attributes for every entity and relationship type

The system uses a two-tier structure:

Eight content-specific entity types
Two fallback types: Person and Organization

The fallback types capture entities that do not fit the domain-specific categories.

Step 2: Build the GraphRAG knowledge graph

Source documents are split into 500-character chunks with a 50-character overlap, then sent to Zep Cloud in batches.

The graph-building process:

Create a standalone graph with a unique ID.
Apply the generated ontology.
Upload document chunks for entity and relationship extraction.
Wait for Zep to process each episode.
Retrieve the completed graph, including nodes and edges.

The output is a knowledge graph containing hundreds or thousands of connected entities.

Step 3: Generate the simulation environment

MiroFish analyzes the knowledge graph and generates agent and platform configuration.

Generated settings include:

Time configuration based on Chinese timezone patterns
- Peak hours: 19:00–22:00
- Low-activity hours: 00:00–05:00
Event configuration for initial posts and hot topics
Agent activity configuration
- Posts per hour
- Response delays
- Influence weights
Platform configuration for Twitter and Reddit, including different viral thresholds

Step 4: Run the simulation

Agents become active according to their schedules. They post, comment, and react based on their personas and the simulation state.

MiroFish runs Twitter and Reddit simulations in parallel and writes each action to JSONL logs in real time.

A typical 72-hour run generates thousands of actions across both platforms.

Step 5: Generate a report

The Report Agent analyzes simulation output with three retrieval tools:

InsightForge: Deep-dive search that decomposes a question into sub-queries
PanoramaSearch: Full-scope retrieval, including expired or invalid historical facts
InterviewAgents: Real-time interviews with active agents through IPC

The resulting report surfaces:

Narrative evolution
Key moments in the discussion
Influential voices
Counter-movements and competing narratives

What Are AI Agents in MiroFish?

Each MiroFish agent is an independent AI entity with a configurable profile.

Attribute	Description	Example
Identity	Name, username, bio	`@ZhangWei_Student`
Persona	Personality and background	Graduate student researching AI ethics
Activity level	Posting frequency from `0.0` to `1.0`	`0.8` = very active
Active hours	Hours when the agent is online	`[8, 9, 10, 11, 18, 19, 20, 21, 22, 23]`
Response delay	Time before reacting, in minutes	`5–30 min`
Influence weight	Likelihood that others see posts	`0.8` low to `3.0` high
Stance	Position on a topic	Supportive, opposing, neutral, observer
Memory	Past actions and interactions	Stored in the Zep Cloud graph

Agents make autonomous decisions about when to post, what to comment on, and how to react. Those decisions use the agent persona and the current simulation state.

What Can You Simulate?

News and policy announcements

Upload a policy draft or news article, then explore likely stakeholder reactions.

Questions to test:

Which voices amplify the announcement?
What criticism emerges first?
How do narratives change over 24–72 hours?

Academic research

Upload a research paper to simulate academic and public reception.

Use it to explore:

Which findings attract attention?
What misunderstandings might appear?
How do expert and non-expert responses differ?

Crisis scenarios

Upload incident reports or supporting background material, then test response strategies.

For example:

What changes if you respond immediately instead of waiting?
Which counter-narratives emerge?
Which influencers drive the discussion?

Literary and historical analysis

Upload a novel or historical text to explore alternate scenarios.

Possible questions include:

How might characters react beyond the original ending?
Which alternative outcomes are plausible?
Which relationships drive the key plot points?

What Makes MiroFish Different?

Swarm intelligence instead of a single agent

Many AI tools simulate a single user. MiroFish simulates hundreds of agents with distinct personalities.

This enables emergent behavior: narratives and movements arise from agent interactions rather than from a pre-written script.

Dual-platform simulation

MiroFish runs Twitter and Reddit in parallel, with different interaction dynamics:

Twitter: Fast viral spread and stronger influencer impact
Reddit: Threaded discussion and community-driven narratives

Comparing the outputs helps show how platform mechanics affect outcomes.

Temporal knowledge graph

MiroFish relationships include time metadata:

valid_at    # When a relationship became valid
invalid_at  # When a relationship became invalid
expired_at  # When a relationship was superseded

This makes it possible to analyze how relationships evolve over time instead of viewing only the current graph state.

Live agent interviews

You can interview active agents during or after a simulation.

Question:
"What do you think about the university’s response?"

Agent 12 (Student):
[Twitter] "They waited too long. By the time they responded, the narrative had already solidified."

[Reddit] "I get why they hesitated—legal review takes time. But the delay cost them credibility."

This provides qualitative context that complements quantitative simulation metrics.

Technical Architecture at a Glance

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Frontend       │     │  Backend        │     │  External       │
│  (Vue.js)       │ ◄─► │  (FastAPI)      │ ◄─► │  Services       │
│                 │     │                 │     │                 │
│ - Graph builder │     │ - REST API      │     │ - Zep Cloud     │
│ - Simulation    │     │ - Subprocess    │     │ - LLM API       │
│   monitor       │     │   management    │     │ - OASIS         │
│ - Report viewer │     │ - JSONL stream  │     │   Framework     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Backend stack

Python FastAPI for REST endpoints
OASIS Framework for agent simulation
Zep Cloud for knowledge graph storage and retrieval
SQLite for simulation state databases

Frontend stack

Vue.js 3 for the reactive UI
WebSocket for real-time updates
D3.js for graph visualization

API design with Apidog

The MiroFish backend exposes more than 40 endpoints across five services.

Service	Endpoints	Purpose
Graph Build	8	Ontology generation, batch upload, status polling
Entity Reader	4	Entity filtering, type selection, export
Config Generator	6	Time, event, agent, and platform config generation
Simulation Runner	12	Start, stop, monitoring, interviews, state management
Report Generator	5	Retrieval, analysis, summary generation

Apidog was used to:

Design API endpoints
Mock responses for frontend development
Generate API documentation
Catch schema mismatches earlier
Keep backend and frontend implementation aligned

When Should You Use MiroFish?

Good use cases

Scenario planning: “What if we announce X next week?”
Stakeholder analysis: “How will different groups react to Y?”
Narrative tracking: “What counter-arguments emerge against Z?”
Research validation: “Do our hypotheses about audience behavior hold up?”
Educational exploration: “How might these historical figures respond to modern events?”

Cases where it is not a fit

Precise prediction: MiroFish produces plausible outcomes, not guaranteed futures.
Real-time monitoring: It simulates hypothetical scenarios; it does not track live social media.
Small-scale analysis: The platform is designed for hundreds of agents and may be excessive for a simple survey.
Non-social phenomena: It models social-media dynamics, not physical or economic systems.

Getting Started with MiroFish

Requirements

Python 3.10+
Node.js 18+
Zep Cloud API key
OpenAI-compatible LLM API access

Quick start

# Clone the repository
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish

# Install dependencies
pip install -r requirements.txt
npm install

# Configure environment
cp .env.example .env

# Edit .env and add your API keys

# Start the backend
python backend/app/main.py

# Start the frontend
npm run dev

Run your first simulation

Upload source documents

Use PDF, TXT, or Markdown files containing the scenario material.
Define simulation requirements

State the question you want to explore.
Generate the ontology

Let MiroFish propose entity and relationship types from the input.
Build the knowledge graph

Extract entities and relationships from the documents.
Configure and start the run

Set the simulation duration, then start the simulation.
Monitor and interview agents

Watch actions in real time and query agents during or after the run.
Generate the report

Review the summary of narratives, key events, and influential participants.

A typical first simulation takes 30–60 minutes end to end.

Frequently Asked Questions

How accurate are the simulations?

MiroFish generates plausible scenarios from input data and behavioral models. It explores a possibility space rather than predicting specific outcomes.

Its value is in surfacing social dynamics that may not be obvious before a real-world event occurs.

How many agents can MiroFish simulate?

MiroFish handles 50–200 agents comfortably. Larger simulations with 500 or more agents are possible, but they require more compute and take longer to process.

Can I customize agent behavior?

Yes. You can modify:

Activity patterns
Influence weights
Stance distributions

Advanced users can edit agent configuration directly before starting a simulation.

Does MiroFish support non-Chinese scenarios?

The default time configuration is optimized for Chinese social-media behavior. You can adapt simulations for other regions by modifying the time configuration and activity patterns.

Is my data private?

Documents are processed locally and sent to Zep Cloud for entity extraction. Zep retains data according to its terms of service.

For sensitive material, consider using a local graph database alternative.

MiroFish’s predictive behavior comes from its swarm-intelligence simulation engine, which generates and resolves thousands of parallel agent interactions for each forecast.

Conclusion

MiroFish creates digital parallel worlds for testing social-media scenarios before they happen. By simulating hundreds of agents with distinct personalities and behavior patterns, it helps reveal emergent narratives, counter-movements, and influential voices that retrospective analytics can miss.

Use it to explore policy announcements, audience behavior, crisis response strategies, or literary “what if” scenarios—while treating the output as plausible scenario analysis rather than a guaranteed prediction.