mirofish-swarm-intelligence

What this skill does

```markdown
---
name: mirofish-swarm-intelligence
description: MiroFish is a multi-agent swarm intelligence engine that builds high-fidelity digital parallel worlds from seed data to simulate and predict social, financial, and narrative outcomes.
triggers:
  - set up MiroFish swarm intelligence
  - simulate multi-agent social prediction
  - run MiroFish prediction engine
  - configure MiroFish agents
  - predict outcomes with swarm intelligence
  - build parallel world simulation
  - use MiroFish for financial forecasting
  - deploy MiroFish multi-agent system
---

# MiroFish Swarm Intelligence Engine

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

MiroFish is a Python-based multi-agent swarm intelligence engine that ingests seed materials (news, policy drafts, financial signals, fiction text) and constructs a high-fidelity digital parallel world. Thousands of agents with distinct personalities, long-term memory, and behavioral logic interact and evolve, enabling deep simulation and prediction of social trends, financial outcomes, public opinion, and narrative continuations. Built on top of OASIS (CAMEL-AI) with a React frontend and Flask backend.

---

## Architecture Overview

```
Seed Material (text/data)
        ↓
[Graph Construction] — Entity extraction, GraphRAG, memory injection
        ↓
[Environment Setup] — Agent persona generation, relationship mapping
        ↓
[Dual-Platform Simulation] — Parallel agent interaction + temporal memory updates
        ↓
[Report Generation] — ReportAgent with toolset queries simulation world
        ↓
[Deep Interaction] — Chat with any agent or ReportAgent
```

**Stack:**
- **Backend:** Python ≥3.11, ≤3.12 (Flask, OASIS engine)
- **Frontend:** Node.js 18+, React (port 3000)
- **Memory:** Zep Cloud (long-term agent memory)
- **LLM:** Any OpenAI-SDK-compatible API (Qwen, GPT-4, etc.)
- **Package manager:** `uv` for Python

---

## Installation

### Prerequisites

| Tool | Version | Check |
|------|---------|-------|
| Node.js | 18+ | `node -v` |
| Python | ≥3.11, ≤3.12 | `python --version` |
| uv | latest | `uv --version` |

Install `uv` if missing:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Clone and Configure

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

# Copy environment template
cp .env.example .env
```

### Environment Variables (`.env`)

```env
# LLM — must be OpenAI SDK compatible
# Recommended: Alibaba Qwen via DashScope
LLM_API_KEY=$LLM_API_KEY
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# Zep Cloud — agent long-term memory
# Free tier at https://app.getzep.com/
ZEP_API_KEY=$ZEP_API_KEY
```

**Other supported LLM providers** (change `LLM_BASE_URL` and `LLM_MODEL_NAME`):
```env
# OpenAI
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-4o

# Local Ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL_NAME=llama3.1
LLM_API_KEY=ollama
```

### Install All Dependencies

```bash
# One-command full install (Node + Python)
npm run setup:all
```

Or step-by-step:
```bash
npm run setup           # Node.js deps (root + frontend)
npm run setup:backend   # Python deps via uv (creates .venv automatically)
```

---

## Running MiroFish

### Development Mode (Both Services)

```bash
# From project root — starts frontend (3000) and backend (5001)
npm run dev
```

### Individual Services

```bash
npm run backend    # Flask API on http://localhost:5001
npm run frontend   # React UI on http://localhost:3000
```

### Docker Deployment

```bash
cp .env.example .env
# Edit .env with your keys

docker compose up -d
# Frontend: http://localhost:3000
# Backend:  http://localhost:5001
```

---

## Key Configuration

### Simulation Parameters

When starting a simulation via the UI or API, key parameters include:

| Parameter | Description | Recommended |
|-----------|-------------|-------------|
| `num_agents` | Number of agents in simulation | 50–500 |
| `max_rounds` | Simulation time steps | Start with <40 for testing |
| `seed_material` | Input text/data describing the world | Required |
| `prediction_query` | Natural language prediction question | Required |

> ⚠️ **Cost Note:** Simulations consume significant LLM tokens. Use <40 rounds for initial testing.

### Agent Memory (Zep Cloud)

MiroFish uses Zep for persistent agent memory across simulation rounds:

```python
# Backend uses ZEP_API_KEY from environment
# Each agent gets a unique Zep session for long-term memory
# Memory is updated each round with new interactions
```

---

## Backend API Reference

Base URL: `http://localhost:5001`

### Start a Simulation

```python
import requests

response = requests.post("http://localhost:5001/api/simulation/start", json={
    "seed_material": "Your seed text here — news article, report, or story excerpt",
    "prediction_query": "What will public opinion look like in 30 days?",
    "num_agents": 100,
    "max_rounds": 30
})

simulation_id = response.json()["simulation_id"]
print(f"Simulation started: {simulation_id}")
```

### Check Simulation Status

```python
import requests

status = requests.get(f"http://localhost:5001/api/simulation/{simulation_id}/status")
print(status.json())
# {"status": "running", "current_round": 15, "total_rounds": 30}
```

### Get Prediction Report

```python
report = requests.get(f"http://localhost:5001/api/simulation/{simulation_id}/report")
print(report.json()["report"])
```

### Chat with an Agent

```python
response = requests.post(f"http://localhost:5001/api/simulation/{simulation_id}/chat", json={
    "agent_id": "agent_042",
    "message": "What do you think about the recent policy changes?"
})
print(response.json()["reply"])
```

### Chat with ReportAgent

```python
response = requests.post(f"http://localhost:5001/api/simulation/{simulation_id}/report-agent/chat", json={
    "message": "Summarize the key opinion clusters that emerged in this simulation"
})
print(response.json()["reply"])
```

### List All Agents

```python
agents = requests.get(f"http://localhost:5001/api/simulation/{simulation_id}/agents")
for agent in agents.json()["agents"]:
    print(f"{agent['id']}: {agent['persona']['name']} — {agent['persona']['role']}")
```

---

## Python Backend Integration Examples

### Direct Python Usage (Backend Module)

```python
import asyncio
import os
from backend.engine.simulation import MiroFishSimulation

async def run_prediction():
    sim = MiroFishSimulation(
        llm_api_key=os.environ["LLM_API_KEY"],
        llm_base_url=os.environ["LLM_BASE_URL"],
        llm_model_name=os.environ["LLM_MODEL_NAME"],
        zep_api_key=os.environ["ZEP_API_KEY"]
    )
    
    # Load seed material
    with open("my_report.txt", "r") as f:
        seed_text = f.read()
    
    # Build the knowledge graph and agent world
    await sim.initialize(
        seed_material=seed_text,
        num_agents=100
    )
    
    # Run simulation
    result = await sim.run(
        prediction_query="How will public opinion evolve over the next month?",
        max_rounds=30
    )
    
    print(result.report)
    return result

asyncio.run(run_prediction())
```

### Custom Agent Persona Definition

```python
from backend.engine.agent import AgentPersona

# Define a custom agent persona
persona = AgentPersona(
    name="Zhang Wei",
    age=34,
    occupation="Software Engineer",
    political_leaning="moderate",
    personality_traits=["analytical", "skeptical", "tech-savvy"],
    background="Lives in Shanghai, follows tech news closely",
    initial_beliefs={
        "topic_stance": "cautiously optimistic",
        "trust_in_media": 0.6
    }
)
```

### Knowledge Graph Construction

```python
from backend.engine.graph import KnowledgeGraphBuilder

builder = KnowledgeGraphBuilder(
    llm_api_key=os.environ["LLM_API_KEY"],
    llm_base_url=os.environ["LLM_BASE_URL"],
    llm_model_name=os.environ["LLM_MODEL_NAME"]
)

# Extract entities and relationships from seed material
graph = await