MiroFish

MiroFish is an open-source multi-agent prediction platform that turns raw seed information — news articles, policy drafts, financial signals, literary texts — into a high-fidelity parallel digital world populated by thousands of AI agents with distinct personalities, long-term memory, and behavioral logic. Rather than extrapolating trends from historical data alone, it lets agents interact freely and undergo social evolution, surfacing emergent outcomes that statistical models miss.

The platform follows a four-stage pipeline: knowledge graph construction from uploaded seed materials, environment setup where entities from the graph are converted into OASIS agent profiles, dual-platform parallel simulation across Twitter-style and Reddit-style social environments, and finally ReportAgent-driven analysis that lets users interrogate the simulated world through natural language. Each stage exposes an API, making MiroFish composable with existing analytical pipelines.

At the infrastructure layer, MiroFish relies on Zep Cloud’s GraphRAG memory system to give agents persistent long-term memory and relationship awareness across simulation rounds. The OASIS simulation engine (from CAMEL-AI) drives the social interaction mechanics, while any OpenAI-compatible LLM API handles reasoning and generation — meaning users can plug in Alibaba Qwen, GPT-4o, or local models without changing application code.

Use cases span from decision-maker rehearsal laboratories (stress-testing public relations strategies or policy proposals at zero real-world cost) to creative sandboxes (predicting alternate endings for literary works). The project is incubated by Shanda Group and has rapidly grown to over 66,000 stars, reflecting strong interest in emergent-behavior prediction as a complement to traditional forecasting.

What You Get

• A four-stage prediction pipeline: knowledge graph construction, agent profile generation, dual-platform social simulation, and ReportAgent-driven interactive analysis
• Zep Cloud GraphRAG integration that gives every simulated agent persistent long-term memory and relationship awareness across multiple simulation rounds
• Dual-platform simulation running Twitter-style and Reddit-style social environments in parallel, each with distinct action sets and content-propagation mechanics
• An LLM-agnostic backend that accepts any OpenAI SDK-compatible API — Alibaba Qwen, GPT-4o, or self-hosted models — without code changes
• A ReportAgent powered by a ReACT reasoning loop that can interrogate the post-simulation graph with tools like InsightForge deep retrieval and PanoramaSearch
• Docker Compose deployment alongside source-code deployment, with a Vue 3 frontend and a Flask REST API backend exposed on separate ports
• Internationalization support across the full stack with a locale utility layer covering both the backend services and Vue i18n on the frontend
• Configurable simulation parameters — rounds, agent activity levels, timezone-aware activity multipliers, and per-platform action sets — auto-generated by an LLM from the input material

Common Use Cases

• Public opinion rehearsal — Upload a policy draft or corporate statement, run a simulation, and observe how different agent cohorts react before the announcement goes live
• Financial signal analysis — Inject breaking financial news as seed material and simulate how market participants with varied risk profiles and information access respond across rounds
• Political scenario modeling — Model how a legislative proposal propagates through distinct voter segments, media organizations, and advocacy groups in a controlled digital environment
• Creative narrative prediction — Feed a partial novel or screenplay as seed material and let agents with personalities derived from characters simulate plausible story continuations
• Crisis communications testing — Stress-test PR messaging strategies by simulating how journalists, influencers, and ordinary users with different priors spread and distort the narrative
• Research into emergent social dynamics — Study how information cascades, opinion polarization, and rumor diffusion emerge from individual agent interactions without top-down orchestration

Under The Hood

Architecture MiroFish is structured as a layered monolith with clear separation between its four pipeline stages: graph construction, environment setup, simulation execution, and report generation. Each stage exposes its own Flask blueprint with a well-defined REST contract, and asynchronous task management is handled through an in-process TaskManager that tracks state transitions across long-running operations. The simulation runner spawns isolated subprocess workers via IPC, which insulates the main Flask process from the CPU-intensive OASIS event loops and enables pause, resume, and stop semantics without blocking the API. Data flows from uploaded seed text through a text-chunking layer into Zep Cloud’s GraphRAG, where entity nodes and typed relationship edges form the persistent substrate that all later stages read from.

Tech Stack The backend is Python 3.11–3.12 on Flask 3.x with Flask-CORS, managed by the uv package manager and structured as an installable package via Hatchling. LLM calls are made through the OpenAI SDK with a configurable base URL, so any compatible provider works without code changes. Zep Cloud 3.x provides the knowledge graph and semantic memory layer via its own typed Python client. Social simulation mechanics come from CAMEL-AI’s OASIS library (camel-oasis 0.2.5 / camel-ai 0.2.78). Document ingestion uses PyMuPDF for PDF parsing alongside charset-normalizer for encoding detection. The frontend is Vue 3 with Vue Router, Vue i18n, D3.js for graph visualization, and Axios for API calls, bundled by Vite 7. Deployment targets Docker Compose (dual containers on ports 3000 and 5001) or source-code setup via npm scripts coordinated with concurrently.

Code Quality The codebase is well-organized with consistent naming conventions and a clear separation of service, API, model, and utility layers throughout the backend. Type annotations using Python’s dataclass and Pydantic models are present in the service layer, providing structural clarity. Error handling uses explicit validation at configuration load time via a Config.validate() method that surfaces missing keys before any request is served. The test footprint is minimal — only a single test script exists in a scripts directory — with no formal pytest test suite discovered in the main application code. There is no CI configuration or linter setup evident in the repository, and logging is handled through a custom setup_logger utility rather than a standard framework integration.

What Makes It Unique The core innovation is treating prediction as emergent social simulation rather than statistical extrapolation. Most forecasting tools apply regression or transformer-based next-token prediction to historical sequences; MiroFish instead instantiates thousands of agents with heterogeneous personas derived from real entities extracted from the seed material, then observes what collective behaviors arise from their interactions. The use of Zep Cloud’s GraphRAG as an agent memory substrate is particularly distinctive — each agent can recall facts from prior rounds and its relationships with other agents, producing behavioral consistency across long simulations that flat prompt injection cannot achieve. The dual-platform architecture (Twitter and Reddit environments running in parallel with different action grammars) lets the system capture how the same event propagates differently across discussion-oriented and broadcast-oriented social contexts simultaneously.

Self-Hosting

MiroFish is released under the GNU Affero General Public License version 3 (AGPL-3.0). This is a strong copyleft license with a notable network provision: if you run MiroFish as a network service and users interact with it over the internet, you are required to make your modified source code available to those users under the same AGPL-3.0 terms. This makes AGPL suitable for internal use and research but creates legal obligations for commercial SaaS deployments built on top of it without additional licensing arrangements. There is no commercial license option currently advertised.

Running MiroFish yourself requires a meaningful set of external services in addition to your own infrastructure. You need an LLM API with an OpenAI-compatible endpoint (the documentation recommends Alibaba Qwen-plus via Bailian, noting it is high-consumption), and a Zep Cloud account for the knowledge graph and agent memory layer (a free monthly quota exists but may not suffice for large simulations). Compute requirements scale with simulation size: each round invokes LLM calls per agent, so simulations with many agents and many rounds accumulate significant API costs. The Docker Compose setup simplifies local deployment to two containers, but production hardening — reverse proxy, TLS, rate limiting, persistent volume management, and backup of Zep Cloud graph data — falls entirely on the operator.

There is no official managed or hosted tier for MiroFish at this time, so you give up the convenience of a maintained cloud platform in exchange for full control over your data and simulation configurations. The absence of a commercial support channel means that operational issues, upgrades, and compatibility with new versions of OASIS or Zep Cloud SDK must be managed by the team adopting it. The project is incubated by Shanda Group and is actively developed with multiple releases, which provides some confidence in continued upstream maintenance, but enterprise-grade SLAs, guaranteed uptime, and professional support are not available through official channels.