MiroFish

81K stars
AGPL-3.0
Active this week
Last commit 6 days ago

Last verified Oct 21, 2026

Run multi-agent swarm intelligence simulations that forecast future outcomes from seed data including news events, policy drafts, and financial signals.

Visit website GitHub81K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who MiroFish is for#

Policy analysts modeling public response before deployment

A policy team uploads a draft proposal and recent news coverage as seed data, runs a simulation of agents representing different demographic segments, and receives a prediction report on likely public reactions. Dynamic variable injection lets them test how modifying policy language shifts sentiment across segments.

Skip if:

You need legally defensible impact assessments. Simulation outputs are probabilistic models, not certified forecasts. Regulatory or legal contexts require validated actuarial or econometric methods.

Researchers studying information diffusion in social networks

Academic researchers in sociology, political science, or computational social science can model how information spreads through a population with varied prior beliefs. The AGPL-3.0 license and self-hosting path keep institutional data on university infrastructure without routing it through a commercial platform.

Skip if:

Your institution requires a validated simulation framework with published peer-review validation records. MiroFish is a research-grade engine but does not yet carry formal scientific certification.

Financial analysts exploring market sentiment scenarios

Financial teams can seed MiroFish with macroeconomic signals, earnings releases, or geopolitical news to simulate how market participants might react. The GitHub topics list financial-forecasting explicitly, and a demo video covers this use case alongside public opinion analysis.

Skip if:

You need production-grade quantitative trading signals or a latency-optimized data feed. MiroFish is a scenario exploration tool, not a backtesting framework or real-time market data system.

Data scientists building swarm intelligence prediction systems

Developers exploring multi-agent architectures can use MiroFish as a foundation for domain-specific prediction systems. The Python backend is extensible, the LLM layer is provider-agnostic, and the underlying simulation engine is the open source OASIS framework from CAMEL-AI.

Skip if:

Your use case is simple time-series forecasting or regression prediction on tabular data. MiroFish is designed for complex social simulation; lighter statistical methods carry much lower infrastructure overhead for straightforward forecasting tasks.

the problem

The problem it solves#

Predicting how complex social systems evolve is a problem that statistical models handle poorly. A regression model can extrapolate a trend, but it cannot capture the emergent behavior that arises when thousands of individuals with different opinions, memories, and social connections interact. Public opinion shifts, financial market sentiment, and the trajectory of a policy controversy are all shaped by these non-linear dynamics.

The practical consequence is that decision-makers in government, finance, and public relations rely on tools that are either too simple (trend extrapolation) or too expensive (enterprise simulation platforms with significant license costs). There has been no affordable, self-hosted way to run agent-based social simulations at meaningful scale without building the infrastructure from scratch.

how MiroFish solves it

How it solves it#

Multi-agent simulation with independent AI agents

Spawns thousands of independent AI agents, each with individual personalities, behavioral logic, and long-term memory. Each agent responds to inputs from other agents and from injected variables, producing emergent collective behavior that single-model approaches cannot replicate. Agent count and simulation rounds are configurable per run.

Knowledge graph construction via GraphRAG

Automatically extracts a structured knowledge graph from your seed materials. Entity relationships are identified and used to build the social and informational substrate that agents navigate during simulation. Supported seed types include news articles, data analysis reports, policy documents, and narrative text.

Dynamic variable injection during simulation

Lets you intervene in a running simulation from a system-level view to test what-if scenarios. You can introduce breaking news, policy changes, or market shocks mid-simulation and observe how agent behavior shifts in response. The README calls this the God's-eye perspective.

ReportAgent with post-simulation deep interaction

After simulation completes, a dedicated ReportAgent generates a structured prediction report. You can also chat directly with any agent in the simulated world to explore specific perspectives or probe individual reasoning. The README describes this stage as deep interaction with the post-simulation environment.

OpenAI-compatible LLM layer

Works with any LLM API that speaks the OpenAI SDK format, including locally hosted models. You configure the base URL, API key, and model name in a .env file. The README recommends Alibaba's Qwen-plus model via the Bailian platform but does not require it.

Docker and source deployment paths

Supports both Docker deployment (docker compose up -d) and source code installation. The source path uses Node.js 18+ and Python 3.11-3.12 with one-command dependency installation via npm run setup:all. Frontend runs on port 3000, backend API on port 5001.

strengths · trade-offs

Strengths and trade-offs#

Strengths

73,000+ GitHub stars with sustained active development73,153 stars and 11,290 forks indicate genuine community adoption. The repo was created in November 2025 and had commits as recently as September 2026, showing sustained momentum despite being under a year old. 128 open issues is low relative to that activity level.
Provider-agnostic LLM layer with no vendor lock-inMiroFish works with any LLM API that speaks the OpenAI SDK format, including self-hosted models via Ollama or similar. You configure the endpoint, key, and model name in the .env file. Teams with data-sovereignty requirements can route all inference through an on-premises model.
Covers financial, social, political, and creative prediction domainsThe GitHub topics explicitly include financial-forecasting, public-opinion-analysis, and social-prediction. Demo videos cover a university campus event simulation and a novel ending prediction from 80 chapters of source text. The same engine applies to serious policy research and exploratory creative scenarios.
Self-hosted cost model bounded by token consumptionRunning MiroFish on your own server limits ongoing costs to LLM API token consumption. There are no per-seat fees and no managed-service subscription. For internal research or analytics teams, this makes cost predictable and scales with usage rather than team size.

Trade-offs

-High token consumption per simulation runThe README warns that simulations consume LLM tokens at a high rate and explicitly recommends starting with fewer than 40 simulation rounds. Larger simulations with many agents and rounds can become expensive depending on the LLM provider and pricing tier. Cost scales with simulation complexity, not with user count.
-Requires external Zep Cloud for agent memoryAgent long-term memory depends on Zep Cloud, a third-party managed service. The README notes the free monthly quota is sufficient for simple usage, but production-grade simulations with many agents may exceed it. There is no documented path to replace Zep Cloud with a fully self-hosted memory backend.
-Moderate self-hosting complexitySource deployment requires Node.js 18+, Python 3.11-3.12 (not 3.13+), the uv package manager, and configuration of at least two API keys. It is not a one-command install and assumes familiarity with both Python and Node environments. Docker simplifies startup but still requires a configured .env file.
-AGPL-3.0 copyleft applies to hosted service deploymentsAGPL-3.0 allows running MiroFish for internal use, including commercial-internal use. If you modify MiroFish and offer it as a hosted service to external users, you must release those source modifications. Teams planning to build a managed prediction product on MiroFish should evaluate whether a commercial arrangement with the maintainers is needed.

versus alternatives

MiroFish vs alternatives#

MiroFish vs AnyLogic

AnyLogic is the leading commercial agent-based simulation platform, used by universities, governments, and enterprises for logistics, supply chain, healthcare, and social modeling. MiroFish targets an overlapping but distinct use case: AI-driven social prediction using LLM-powered agents rather than rule-based behavioral models.

Feature	MiroFish	AnyLogic
License	AGPL-3.0	Proprietary paid license
Self-hosting	Yes	No (desktop app with optional cloud output)
Agent model	LLM-powered, OpenAI-compatible	Rule-based discrete-event simulation
Primary strength	Social, political, financial prediction from text seeds	Logistics, supply chain, healthcare, pedestrian simulation
Input type	Unstructured text (news, policy, reports)	Structured mathematical models and diagrams

MiroFish is the better choice when your prediction problem involves unstructured text inputs, emergent social dynamics, and a need to keep data on-premises. The LLM-powered agent layer means agents reason from natural language seed data with no programming beyond configuration.

AnyLogic is still the better fit when your simulation requires precise, reproducible mathematical models with extensive validation history, or when you are building logistics and supply chain models where AnyLogic's domain-specific libraries (Road Traffic, Rail, Pedestrian, Fluid) are mature and tested. AnyLogic's graphical IDE also lowers the barrier for users who prefer not to edit configuration files.

MiroFish vs Enterprise ML Prediction Platforms

Platforms like DataRobot and H2O.ai automate traditional machine learning: they take tabular data, train models, and produce forecasts. They do not model agent behavior or social emergence. MiroFish takes a different approach better suited to complex social prediction, but it requires more compute and LLM API spend per run.

Feature	MiroFish	DataRobot / H2O.ai
License	AGPL-3.0	Proprietary enterprise SaaS
Self-hosting	Yes	Limited enterprise on-premises tier
Prediction method	Multi-agent social simulation	AutoML on tabular data
Best input type	Unstructured text, news, reports	Structured tabular datasets
Cost model	LLM API tokens plus server cost	Per-seat or usage-based enterprise pricing

For teams with tabular historical data who need explainable forecasts with minimal setup, DataRobot or AutoML tools remain the practical choice. MiroFish is not a tabular forecasting replacement. Its value is in scenarios where emergent social behavior and natural-language seeds are the inputs and a precise tabular dataset does not exist.

install · quick start

Quick start#

bash

Self-hosting with Docker reads from a configured .env file and maps ports 3000 and 5001.

```bash
cp .env.example .env
docker compose up -d
```

tech stack · detected from GitHub

What it's built on#

Languages: JavaScriptPython
Frameworks: FlaskVue

frequently asked

FAQ#

Is MiroFish free to use?

MiroFish is free to self-host under AGPL-3.0. You will need an LLM API key (any OpenAI-compatible provider works; Alibaba Qwen-plus is recommended) and a Zep Cloud account for agent memory. The Zep Cloud free monthly quota covers basic use. Your primary ongoing cost is LLM token consumption per simulation run, which scales with the number of agents and rounds.

What kinds of predictions can MiroFish make?

MiroFish models social, political, and financial outcomes by simulating agent behavior rather than extrapolating statistical trends. Documented examples include public opinion analysis for a university campus event, financial market sentiment from economic signals, and a creative scenario predicting the lost ending of a classic Chinese novel from 80 chapters of source text. Any domain where group dynamics and social interaction drive outcomes is a candidate.

Can I use my own LLM with MiroFish?

Yes. MiroFish works with any LLM API that speaks the OpenAI SDK format, including locally hosted models via Ollama or similar setups. You configure the base URL, API key, and model name in the .env file. The README recommends starting with a capable model like Qwen-plus because simulations consume tokens at a high rate per run.

How is MiroFish licensed?

AGPL-3.0. You can run it for internal or commercial-internal use and modify the code freely. If you deploy a modified version as a hosted service for external users, AGPL-3.0 requires you to release those source modifications. Teams planning to offer MiroFish as a managed prediction service to others should evaluate whether a commercial license from the maintainers is appropriate.

What are the prerequisites for self-hosting MiroFish?

Source deployment requires Node.js 18+, Python 3.11 or 3.12 (not 3.13+), and the uv Python package manager. You also need an LLM API key (any OpenAI-compatible endpoint) and a Zep Cloud API key for agent memory. Docker deployment reads from a configured .env file and maps port 3000 for the frontend and port 5001 for the backend API.

also worth a look

Similar open-source tools#

FckSignups

InCustomer Support

Open-source tools that work instantly, no signup required

4,511 GitHub stars
Licence GPL-3.0

DeskcommCRM

Alternative toHubSpot Sales Hub

AI agents for WhatsApp sales, fully audited, no per-user pricing

4,751 GitHub stars
Licence MIT

fmt

InCustomer Support

Fast, type-safe C++ formatting that replaces printf and iostreams

25,884 GitHub stars
Licence MIT

treg

Alternative toComposio

One token for 2,600+ agent tools across 47 providers

5,904 GitHub stars

OpenCompany

Alternative toMicrosoft Copilot Studio

Self-hosted AI agent canvas for every business function

1,017 GitHub stars
Licence MIT

Comp AI CRM

Alternative toAttio

Open source agentic CRM with a durable research agent

11,564 GitHub stars
Licence MIT

by category

Open source tools in these categories#

404

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,712 GitHub stars
Licence AGPL-3.0
#Email

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

4,904 GitHub stars
Licence Apache-2.0
#AI Agents

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

MiroFish vs AnyLogic

Feature	MiroFish	AnyLogic
License	AGPL-3.0	Proprietary paid license
Self-hosting	Yes	No (desktop app with optional cloud output)
Agent model	LLM-powered, OpenAI-compatible	Rule-based discrete-event simulation
Primary strength	Social, political, financial prediction from text seeds	Logistics, supply chain, healthcare, pedestrian simulation
Input type	Unstructured text (news, policy, reports)	Structured mathematical models and diagrams

MiroFish vs Enterprise ML Prediction Platforms

Feature	MiroFish	DataRobot / H2O.ai
License	AGPL-3.0	Proprietary enterprise SaaS
Self-hosting	Yes	Limited enterprise on-premises tier
Prediction method	Multi-agent social simulation	AutoML on tabular data
Best input type	Unstructured text, news, reports	Structured tabular datasets
Cost model	LLM API tokens plus server cost	Per-seat or usage-based enterprise pricing

Who MiroFish is for#

Policy analysts modeling public response before deployment

Skip if:

Researchers studying information diffusion in social networks

Skip if:

Financial analysts exploring market sentiment scenarios

Skip if:

Data scientists building swarm intelligence prediction systems

Skip if:

The problem it solves#

How it solves it#

Multi-agent simulation with independent AI agents

Knowledge graph construction via GraphRAG

Dynamic variable injection during simulation

ReportAgent with post-simulation deep interaction

OpenAI-compatible LLM layer

Docker and source deployment paths

Strengths and trade-offs#

Strengths

Trade-offs

MiroFish vs alternatives#

MiroFish vs AnyLogic

MiroFish vs Enterprise ML Prediction Platforms

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

AI & Machine Learning

Data & Analytics

Marketing & Growth

Finance & Fintech

Business & Productivity

Find open source alternatives to paid software

Who MiroFish is for#

Policy analysts modeling public response before deployment

Skip if:

Researchers studying information diffusion in social networks

Skip if:

Financial analysts exploring market sentiment scenarios

Skip if:

Data scientists building swarm intelligence prediction systems

Skip if:

The problem it solves#

How it solves it#

Multi-agent simulation with independent AI agents

Knowledge graph construction via GraphRAG

Dynamic variable injection during simulation

ReportAgent with post-simulation deep interaction

OpenAI-compatible LLM layer

Docker and source deployment paths

Strengths and trade-offs#

Strengths

Trade-offs

MiroFish vs alternatives#

MiroFish vs AnyLogic

MiroFish vs Enterprise ML Prediction Platforms

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

AI & Machine Learning

Data & Analytics

Marketing & Growth

Finance & Fintech

Business & Productivity

Find open source alternatives to paid software