1. The Core Bottleneck: What Engineering Deadlock Does It Break?

Traditional prediction models rely heavily on static statistical regression or single-prompt LLM generation, completely missing non-linear game dynamics and collective emergence. When handling breaking news or macro policies, isolated models lack interactive memory, leading to severe distortion in long-horizon forecasting. MiroFish shifts this paradigm. Instead of trusting a single model's intuition, it transforms real-world seed data into autonomous agents via graph extraction. Thousands of agents with independent memories and behavioral rules interact within a digital sandbox, surfacing macroscopic trends through microscopic collisions and solving the historical blind spot of quantifying swarm behavior.

💡 Core Architectural Insight: By parsing seed texts into structured graphs and initializing heterogeneous agent clusters, MiroFish turns static text prediction into a dynamic social game simulation.

2. Core Architecture and Underlying Data Flow

The MiroFish architecture operates through a clear data pipeline, transforming raw seed input into an interactive simulation environment.

[ Seed Data / PDF / Text ] ---> [ Graph Building & GraphRAG ] ---> [ Entity & Persona Extraction ]
                                                                           │
[ ReportAgent & Interactive Chat ] <--- [ Dual-Platform Simulation Engine ] <┘

The execution pipeline consists of four distinct phases. First, the GraphRAG module parses input seeds to extract entities and multi-dimensional relations. Second, the environment setup phase converts entities into active agent nodes injected with persona configurations. Third, the dual-platform simulation engine advances temporal states across iterations, dynamically updating agent memories. Finally, the report generation phase invokes ReportAgent tools to deeply analyze simulation results, enabling users to chat with any agent or query comprehensive prediction outputs directly.

3. Technology Selection and Hardcore Benchmarking

Evaluation Dimension MiroFish Implementation Traditional Paradigms Typical Competitor Setup Production ROI
Prediction Mechanism Multi-agent graph emergence Static single prompt call Sequential single-agent retrieval Accurately captures non-linear social interactions
Memory Layer External graph DB & distillation Prompt-window caching Local VectorDB retrieval Sustains thousands of turns without context loss
Interactivity Dynamic God-eye & variable injection Static trajectory replay Offline log inspection Enables real-time testing of system resilience
Deployment Complexity Automated npm & uv bootstrap Manual venv & multi-container Complex distributed orchestration Minimizes local debugging overhead for engineering teams
LLM Ecosystem OpenAI SDK compatible endpoints Hardcoded closed-source APIs Custom-locked open-source frameworks Freedom to swap between low-cost and high-performance inference

MiroFish maintains architectural flexibility while avoiding the operational black hole of distributed systems. Using graph structures for state representation and OpenAI-compatible interfaces for execution, it prevents vendor lock-in and gives engineering teams predictable cost audits.

4. Hands-on Geek Guide: Building the Minimal Loop

Ensure Node.js 18+, Python 3.11 to 3.12, and the uv package manager are installed before proceeding. Clone the repository and initialize the configuration file:

# Copy the example configuration file
lp .env.example .env

Edit the .env file in the root directory, supplying your OpenAI-compatible API credentials and Zep long-term memory keys:

# Configure LLM API access credentials
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# Configure Zep Cloud memory service keys
ZEP_API_KEY=your_zep_api_key

Run the unified setup command to install root, frontend, and backend dependencies automatically:

# One-click installation for all project workspaces
npm run setup:all

Once dependencies finish installing, start the full-stack development environment from the project root:

# Start both frontend and backend development servers
npm run dev

The frontend service runs at http://localhost:3000, while the backend API is accessible at http://localhost:5001. Upload seed files via the web interface to kick off parallel agent simulations.

5. Production Gotchas and Mitigation Strategies

In high-concurrency or long-horizon simulation tests, dispatching continuous LLM requests can trigger rate limits. Limit initial test runs to under 40 simulation rounds to monitor token burn rates and context overhead.

⚠️ Gotcha Warning [Token Consumption Spike]: When scaling agent pools past a hundred nodes for over a hundred rounds, context propagation generates massive token overheads. Enable summary trimming or integrate Zep caching layers in production to compress payload size.

Python interpreter versions must remain strictly bounded between 3.11 and 3.12. Using newer runtimes will cause compilation failures in underlying async C-extensions.

⚠️ Gotcha Warning [Python Version Mismatch]: The backend relies heavily on specific async libraries and the uv toolchain. Running standard Python 3.13 breaks underlying native compilation packages. Enforce correct interpreters using pyenv.