Comprehensive Overview of MiroFish-Offline: A Fully Local Multi-Agent Social Simulation Engine

Introduction

MiroFish-Offline represents a groundbreaking advancement in social simulation technology, offering a fully offline alternative to its original cloud-dependent counterpart. Unlike the parent project, which relied on proprietary APIs and external cloud services for knowledge graph storage (Zep Cloud) and large language model (LLM) inference (DashScope), MiroFish-Offline is designed to run entirely on local hardware. This ensures privacy, independence from third-party dependencies, and enhanced scalability across diverse environments.

This guide explores the core functionalities, technical architecture, workflows, and practical applications of MiroFish-Offline while emphasizing its advantages over cloud-based alternatives.

---

Core Concept: Multi-Agent Swarm Intelligence Engine

MiroFish-Offline is a simulation engine that models public opinion, market sentiment, and social dynamics through an ensemble of AI agents. Each agent possesses unique traits—such as personality, opinion bias, reaction speed, and memory retention—which enable them to interact dynamically within simulated social platforms.

Key Features

• No Cloud Dependencies: Eliminates reliance on external APIs by leveraging local databases (Neo4j) and LLMs (Ollama).
• English User Interface: Unlike the original Chinese UI, MiroFish-Offline provides a fully translated interface with over 1,000 strings.
• Real-Time Social Dynamics: Agents engage in conversations, argue, shift opinions, and propagate topics across simulated networks.
• Structured Reporting: A specialized ReportAgent analyzes simulation outcomes by querying the knowledge graph and synthesizing insights.

---

Technical Architecture

MiroFish-Offline employs a modular architecture to ensure flexibility and maintainability. The system is divided into several layers:

1. Graph Database Layer (Neo4j Community Edition 5.15)

• Knowledge Graph Construction: Extracts entities (e.g., individuals, organizations) and relationships from input documents using Named Entity Recognition (NER).
• Memory Storage: Agents retain historical interactions via Neo4j’s graph database, enabling persistent learning.
• Query Interface: Hybrid search techniques combine vector similarity (70%) with keyword-based matching (30%), improving retrieval accuracy.

2. Service Layer

The backend consists of several interconnected services:

• EntityReader: Parses input documents to identify entities and relationships.
• GraphToolsService: Manages graph operations, including memory updates and agent interactions.
• ReportAgent: Generates structured analyses by querying the knowledge graph and interviewing sampled agents.

3. Local LLM Layer (Ollama)

• Model Integration: Supports multiple models (e.g., Qwen2.5, Llama3) via Ollama’s lightweight deployment framework.
• Embedding Service: Uses nomic-embed-text to generate semantic embeddings for document analysis.

4. Frontend Interface

A responsive web application allows users to upload documents, initiate simulations, and interact with agents in real time.

---

Workflow Breakdown

MiroFish-Offline operates through a five-step process:

1. Graph Build: Knowledge Extraction

• Input: Users provide documents (e.g., press releases, financial reports).
• Process:
• The system extracts entities (e.g., "Elon Musk," "NASA") and relationships (e.g., "collaborated with").
• A knowledge graph is constructed in Neo4j, storing individual and group memories.
• Output: A structured graph representing the input’s semantic landscape.

2. Environment Setup: Agent Generation

• Agent Creation:
• Hundreds of AI agents are generated, each with unique attributes:
  • Personality traits (e.g., sarcastic, analytical).
  • Opinion biases (pro/anti-trend).
  • Reaction speeds and influence levels.
• Memory Initialization: Agents retain past interactions within the graph database.

3. Simulation: Social Interaction

• Dynamic Engagement:
• Agents post content, reply to others, and argue based on their personalities.
• The system tracks sentiment evolution, topic propagation, and influence dynamics in real time.
• Platform Simulation: Simulated social media platforms mimic real-world interactions (e.g., Twitter threads).

4. Report Generation

• Analysis Phase:
• A ReportAgent queries the knowledge graph for evidence and synthesizes insights.
• Focus groups of agents are interviewed to provide qualitative perspectives.
• Output: Structured reports detailing sentiment shifts, topic trends, and influence dynamics.

5. Agent Interaction: Chat with Simulated Entities

• Users can engage directly with agents by asking questions about their posts or opinions.
• Persistent memory ensures agents retain context across interactions.

---

Quick Start Guide

Prerequisites

To run MiroFish-Offline, users must meet the following requirements:

• Docker & Docker Compose (recommended) or manual installation with Python 3.11+, Node.js 18+, Neo4j 5.15+, and Ollama.
• Hardware specifications: Minimum: 16GB RAM, 20GB disk space; Recommended: 32GB RAM, 50GB disk space.

Option A: Docker Deployment (Easiest)

1. Clone the repository:

   git clone https://github.com/nikmcfly/MiroFish-Offline.git
   cd MiroFish-Offline

2. Copy .env.example to .env and configure settings.
3. Start services using Docker Compose:

   docker compose up -d

4. Pull required models via Ollama:

   docker exec mirofish-ollama ollama pull qwen2.5:32b
   docker exec mirofish-ollama ollama pull nomic-embed-text

5. Access the application at http://localhost:3000.

Option B: Manual Installation

1. Start Neo4j:

   docker run -d --name neo4j \
     -p 7474:7474 -p 7687:7687 \
     -e NEO4J_AUTH=neo4j/mirofish \
     neo4j:5.15-community

2. Initialize Ollama and Pull Models:

   ollama serve &
   ollama pull qwen2.5:32b  # or qwen2.5:14b for lower VRAM usage
   ollama pull nomic-embed-text

3. Configure Backend:

• Copy .env.example to .env.
• Install dependencies: bash cd backend pip install -r requirements.txt python run.py

3. Run Frontend:

   cd frontend
   npm install
   npm run dev

5. Access the application at http://localhost:3000.

---

Configuration

All settings are managed via .env, which includes:

• LLM Configuration: Specifies Ollama’s API endpoint and model name.

  LLM_API_KEY=ollama
  LLM_BASE_URL=http://localhost:11434/v1
  LLM_MODEL_NAME=qwen2.5:32b

• Neo4j Credentials: Default credentials are neo4j/mirofish.
• Embedding Model: Uses nomic-embed-text via Ollama.

Compatibility with Other LLMs

MiroFish-Offline supports any OpenAI-compatible API by adjusting:

LLM_BASE_URL=<provider_url>

Examples include switching from Ollama to Claude or GPT-4.

---

Hardware Requirements

| Component | Minimum | Recommended | |-----------------|--------------|-----------------| | RAM | 16 GB | 32 GB | | VRAM (GPU) | 10 GB (for 14b model) | 24 GB (for 32b model) | | Disk Space | 20 GB | 50 GB | | CPU Cores | 4 cores | 8+ cores |

Note: CPU-only mode is slower but functional for lighter setups.

---

Use Cases

MiroFish-Offline finds applications across diverse domains:

1. PR Crisis Testing

• Simulate public reactions to press releases before publication.
• Identify potential backlash and refine messaging strategies.

2. Market Sentiment Analysis

• Feed financial news into the system to generate trading signals.
• Analyze sentiment shifts in real-time simulations.

3. Policy Impact Assessment

• Test draft regulations against simulated public responses.
• Detect unintended consequences or popular support.

4. Creative Experiments

• Explore narrative continuity by feeding fictional documents (e.g., incomplete novels).
• Agents generate coherent conclusions based on their personalities.

---

Architectural Innovations

1. GraphStorage Abstraction Layer

• Allows users to swap Neo4j with other graph databases by implementing a custom GraphStorage class.
• Ensures compatibility across different database backends.

2. Dependency Injection via Flask

• Eliminates global singletons, promoting modularity and testability.

3. Hybrid Search Technique

• Combines vector similarity (70%) with BM25 keyword search (30%).
• Improves retrieval accuracy for semantic queries.

4. Synchronous NER/RE Extraction

• Uses local LLMs to extract named entities and relationships in real time.
• Replaces asynchronous Zep episodes, enhancing responsiveness.

---

License & Attribution

MiroFish-Offline is released under the AGPL-3.0 license, ensuring open-source compatibility with the original project. The system is a modified fork of the work by 666ghj, originally supported by the Shanda Group.

---

Conclusion

MiroFish-Offline represents a significant leap forward in social simulation technology, offering a fully offline alternative to cloud-dependent systems. By leveraging local Neo4j and Ollama, it ensures privacy, scalability, and independence from third-party APIs. Whether for crisis management, market analysis, or creative experimentation, MiroFish-Offline provides a powerful toolkit for simulating public opinion in real time.

For further exploration, users can refer to the GitHub repository and contribute to its development community. The system’s modular design also encourages future extensions, such as integrating additional graph databases or LLMs.

---

Image References:

1. 
2.