You have a giant sandbox. But instead of sand, you fill it with little people — each one has their own personality, memories, and opinions.

You drop in a newspaper article or a new rule, and then you sit back and watch what happens.

The little people read the news, argue about it, share posts, change their minds, and form groups — all on their own.

Serious Stuff

• Will people be angry about a new policy?
• How will financial markets react to a rumor?
• What happens if a company launches a controversial product?
• How does public opinion shift after a crisis?

Fun Stuff

• What if characters from a novel had social media?
• How would historical figures tweet about modern events?
• What ending would readers vote for in a choose-your-own-adventure?
• Could you simulate a fictional election?

• No real people harmed — test controversial ideas safely
• Replay with changes — tweak one variable, run it again
• Speed up time — simulate months of social dynamics in minutes

• God-mode view — watch every agent's thoughts and actions
• Interview agents — ask any simulated person why they did what they did
• Open source — 37.8k stars, fully hackable

Key Numbers

What the LLM does

Given uploaded documents and a natural-language simulation requirement, the OntologyGenerator asks the LLM to produce a structured schema:

• Up to 10 entity types (people, orgs, policies, etc.)
• Up to 10 edge types (relationships between entities)
• Each with typed attributes and descriptions
• Auto-adds Person and Organization fallbacks

Output format

{
  "entity_types": [
    {
      "name": "Politician",
      "description": "A public official",
      "attributes": [
        {"name": "party",
         "description": "Political party"}
      ]
    }
  ],
  "edge_types": [
    {
      "name": "opposes",
      "source_targets": [
        {"source": "Politician",
         "target": "Policy"}
      ]
    }
  ]
}

GraphBuilderService flow

Dynamic ontology mapping

Entity types from the LLM become actual Python classes at runtime:

# Dynamic class creation
entity_class = type(
    name,           # "Politician"
    (EntityModel,), # Zep base
    attrs           # Fields from ontology
)

# Edge classes with source/target pairs
edge_class = type(
    class_name,   # "Opposes"
    (EdgeModel,),
    attrs
)
# Bound to EntityEdgeSourceTarget

From graph entities to agents

The ZepEntityReader reads all nodes from the knowledge graph, filtering out system labels (Entity, Node). Each entity becomes a candidate agent.

The OasisProfileGenerator then enriches each entity with:

• Dual Zep search — edges (facts) + nodes (summaries) via ThreadPoolExecutor
• Context builder — attributes, relationships, up to 3000 chars of Zep retrieval
• LLM persona synthesis — separate prompts for individuals vs. institutions

Profile structure

{
  "user_id": 1,
  "name": "Wang Xiaoming",
  "age": 34,
  "gender": "male",
  "mbti": "ENTJ",
  "profession": "Policy Analyst",
  "country": "China",
  "interested_topics": [...],
  "persona": "2000-char biography
  with memories, opinions,
  behavioral tendencies...",
  "bio": "Short public bio"
}

Retry logic: 3 attempts with decreasing temperature (0.7 → 0.5 → 0.3). JSON repair for truncated LLM output.

LLM-driven simulation parameters

Instead of manual tuning, the SimulationConfigGenerator asks the LLM to reason about optimal parameters given:

• The simulation requirement (natural language)
• The document text (context)
• Entity list and types
• Platform selection (Twitter, Reddit, or both)

The LLM outputs a SimulationParameters object with reasoning for its choices.

Generated parameters include

Process management

The SimulationRunner launches OASIS as a subprocess using Python's subprocess module. It supports three modes:

• run_twitter_simulation.py
• run_reddit_simulation.py
• run_parallel_simulation.py (both)

State machine

class RunnerStatus(Enum):
    IDLE      STARTING
    RUNNING   PAUSED
    STOPPING  STOPPED
    COMPLETED FAILED

Real-time monitoring

Agent actions are logged to JSONL files. The runner parses these in real time:

# Each action is an AgentAction
{
  "round": 3,
  "platform": "twitter",
  "agent_id": 42,
  "action": "CREATE_POST",
  "success": true,
  "timestamp": "..."
}

Completion detected via "simulation_end" event. Cross-platform cleanup uses killpg (Unix) or taskkill (Windows). Signal handlers + atexit callbacks ensure orphan prevention.

The simulation backbone

OASIS (Open Agent Social Interaction Simulations) is an external framework by CAMEL-AI that MiroFish wraps.

It provides:

• Social platform simulation (Twitter-like, Reddit-like)
• Agent behavior loops — each agent has an LLM "brain"
• Action types per platform:
  • CREATE_POST, LIKE_POST, REPOST, FOLLOW
  • CREATE_COMMENT, SEARCH_POSTS, VOTE
• Round-based execution with configurable tick rates

MiroFish adds

• GraphRAG knowledge injection — agents start with structured world knowledge from Zep
• Automated profile synthesis — entities from your documents become OASIS agents
• Dual-platform parallel simulation — Twitter and Reddit simultaneously
• Real-time IPC — interview agents mid-simulation
• ReACT report generation — post-simulation analysis
• Graph memory updates — Zep integration for entity relationship extraction during simulation

How reports are generated

The ReportAgent uses a ReACT loop (Reason + Act) to write each section of the prediction report.

Min 3 tool calls, max 5 per section. Conflict resolution with 3-tier retry.

The four tools

Output structure

reports/{report_id}/
  meta.json
  outline.json
  progress.json
  section_01.md ... section_N.md
  full_report.md
  agent_log.jsonl
  console_log.txt

File-based IPC protocol

MiroFish uses a simple but effective file-based inter-process communication system to talk to running OASIS simulations:

simulation_dir/
  ipc_commands/
    {uuid}.json   ← server writes
  ipc_responses/
    {uuid}.json   ← OASIS writes back
  env_status.json ← alive/stopped

The SimulationIPCClient writes a command JSON, then polls the responses directory at 0.5s intervals with a 60s timeout.

Command types

Why file-based?

• OASIS runs as a separate Python process
• No shared memory or socket setup needed
• Works cross-platform (Windows + Unix)
• Commands are naturally persistent and debuggable
• Cleanup is just deleting JSON files

GraphRAG for agent knowledge

Zep Cloud provides the knowledge graph infrastructure that gives agents their "world knowledge".

• Graph creation — each simulation gets a unique Zep graph
• Episode ingestion — text chunks become graph episodes
• Entity extraction — Zep automatically identifies entities and relationships
• Temporal metadata — edges have valid_at, invalid_at, expired_at timestamps

Three Zep integration points

Pagination helper

# zep_paging.py
def fetch_all_nodes(client, graph_id):
    # Handles Zep's paginated API
    # Returns complete node list

def fetch_all_edges(client, graph_id):
    # Same for edges

View structure

Step components

• Step1GraphBuild — upload, ontology preview, graph visualization
• Step2EnvSetup — entity review, profile generation progress
• Step3Simulation — dual-platform timeline feed
• Step4Report — section-by-section report output
• Step5Interaction — chat with agents

Real-time patterns

• Status polling every 2 seconds
• Detail polling every 3 seconds
• Action deduplication on client side
• Phase transitions: starting → running → completed

Simulation API (largest)

Graph API

Report API

The task pattern

Long-running operations use a consistent pattern across the codebase:

def build_graph_async(self, text, ...):
    # 1. Create a task ID
    task_id = self.task_manager.create_task(
        task_type="graph_build",
        metadata={...}
    )

    # 2. Spawn daemon thread
    thread = threading.Thread(
        target=self._build_graph_worker,
        args=(task_id, text, ...)
    )
    thread.daemon = True
    thread.start()

    # 3. Return task ID immediately
    return task_id

Progress tracking

Workers update task progress via the TaskManager:

self.task_manager.update_task(
    task_id,
    status=TaskStatus.PROCESSING,
    progress=60,
    message="Waiting for Zep..."
)

The frontend polls /prepare/status to get updates. This avoids WebSockets while still providing real-time feedback.

Multi-layer JSON repair

# Layer 1: Fix truncated JSON
def _fix_truncated_json(text):
    # Count open/close braces
    # Append missing closers

# Layer 2: Regex extraction
def _try_fix_json(text):
    # Strip markdown code fences
    # Remove control characters
    # Extract JSON via regex
    # Fallback to basic structure

# Layer 3: Temperature descent
# Retry: 0.7 → 0.5 → 0.3
# Lower temp = more deterministic

ReACT conflict handling

When the LLM simultaneously outputs a tool call AND a final answer (a common failure mode):

• Tier 1: Strip the final answer, keep the tool call
• Tier 2: Re-prompt with explicit instruction
• Tier 3: Force content generation at iteration limit

Prompt engineering guards

• Chinese-only enforcement with translation
• Minimum tool call requirements (3 per section)
• Single tool call per LLM response enforced
• Previous sections capped at 4000 chars to prevent token bloat

Exponential backoff everywhere

def _call_with_retry(
    self, func,
    operation_name,
    max_retries=3,
    initial_delay=1.0
):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            delay = initial_delay * (2 ** attempt)
            time.sleep(delay)
    raise Exception(
        f"Failed after {max_retries}"
    )

Resilience strategies across the codebase

Source code

# Prerequisites
Node.js 18+ / Python 3.11-3.12 / uv

# One-click setup
$ npm run setup:all

# Launch both services
$ npm run dev
# Frontend → :3000
# Backend  → :5001

Environment variables

# .env (from .env.example)
LLM_API_KEY=sk-...
LLM_BASE_URL=https://...
LLM_MODEL_NAME=qwen-plus
ZEP_API_KEY=z_...

Docker

# Single command
$ docker compose up -d

The docker-compose.yml bundles both services. GitHub Actions CI builds the image on push.

Required external services

Strengths

• Zero-config barrier — LLM generates everything: ontology, profiles, simulation config, reports
• End-to-end pipeline — documents in, prediction reports out
• GraphRAG integration — agents have structured world knowledge, not just prompts
• Dual-platform simulation — Twitter + Reddit capture different social dynamics
• Agent interviews — interrogate the simulation for qualitative insights
• Streaming results — sections save incrementally, partial reports on failure

Trade-offs

• LLM cost — many LLM calls per simulation (ontology + profiles + config + report)
• Polling over push — 2-3s latency from threading + HTTP polling vs WebSockets
• File-based IPC — simple but higher latency than sockets/shared memory
• Zep dependency — requires external cloud service for graph storage
• No validation layer — predictions are only as good as the agent model quality
• Sequential pipeline — each stage must complete before the next starts

What MiroFish really is

An orchestration layer that chains together:

• LLMs for schema/profile/config/report generation
• Zep for GraphRAG knowledge storage
• OASIS for multi-agent social simulation
• Vue frontend for a guided wizard experience

The key innovation is making this accessible: upload documents, describe what you want to predict, get a report.

Numbers worth remembering