MiroShark: Multi-Agent Scenario Simulation with Grounded Personas

MiroShark's scenario simulation boundary

MiroShark addresses a specific problem: exploring how a population of synthetic agents might respond to a scenario before a decision is made. The README presents examples including PR crisis testing, market reaction analysis, advertising review, policy analysis, altered historical events, and creative continuation of a novel. This makes the project relevant to people who want to inspect reactions from several social contexts in one workflow, rather than asking one general-purpose language model for a list of possible answers.

The project is aimed at users who can supply a scenario and interpret the resulting behavior. That includes product teams testing messaging, researchers exploring social dynamics, and developers building applications around scenario analysis. It is not presented as a conventional forecasting package with documented statistical validation. The README uses terms such as prediction, forecasting, and future prediction among its topics, but its central output is a generated simulation with agents, posts, arguments, trades, and a report. A simulated market move is therefore evidence of behavior inside the configured world, not evidence that the same move will occur in a real market.

The scope also depends on what the agents are allowed to consume. MiroShark emphasizes grounded personas and real context, including demographic seeds, web enrichment, semantic search, relationships, and graph attributes. The repository does not provide a benchmark or validation procedure showing how closely those personas reproduce a particular population. Users should treat grounding as an input-building mechanism, not as proof that the resulting sample represents real people.

The five-stage MiroShark pipeline

According to the README, MiroShark follows five phases: Ontology Generation, Graph Building, Agent Setup, Simulation Execution, and Report and Interaction. The user first provides a scenario or document. MiroShark generates an ontology for the situation, constructs a world graph around it, and creates agent personas. The simulation then runs across X, Reddit, and a prediction market. A ReAct report agent writes the recap after the simulation and supports interaction with individual agents, breaking-news injection, and timeline forking.

This architecture separates the world representation from the social surfaces. The graph stores entities and relationships, while platform-specific agents generate activity. The README describes information propagating through X, herd effects forming in Reddit and Polymarket, and more than 100 agent personas operating across three platforms. The report is consequently downstream of the activity log rather than a separate prediction formula.

The visible repository layout supports this interpretation. The project has separate `backend/` and `frontend/` directories, a `miroshark` launcher, Docker files, Neo4j configuration, and Ollama support. The `docker-compose.yml` file connects the application to Neo4j at `bolt://neo4j:7687` and an OpenAI-compatible Ollama endpoint at `http://ollama:11434/v1`. The frontend is exposed on port `3000`, while the backend is exposed on port `5001`. This is a multi-service application rather than a single Python library.

Grounded agents and generated platform behavior

MiroShark's agent setup is its main distinction from a prompt-only simulation. The README says that each agent is grounded in five layers: a demographic seed, web enrichment, semantic search, relationships, and graph attributes. The system can then give agents roles that interact across simulated X, Reddit, and prediction-market environments. The documented example says agents post, argue, and trade in real time while the report is written.

That design creates several kinds of observable output. A reader can inspect whether agents amplify a claim, disagree in a forum, or change a simulated market position after a news event. The project documentation also links examples for PR crisis testing, financial news reactions, audience testing, draft regulations, altered history, and creative writing. These examples show intended use cases, not guaranteed outcomes.

The main limitation is epistemic. Grounding an agent in web-derived material does not make its action factual, representative, or free from model bias. The README does not document a confidence interval, calibration procedure, sampling frame, or comparison against observed social and market outcomes. It also does not explain how claims made by simulated agents should be separated from real source material. The report's cited posts and trades should therefore be read as records of the simulation, with provenance handled according to the surrounding application.

Installing MiroShark and starting the local stack

The README gives a short local-start path. It clones the repository, copies the environment template, requests an OpenRouter key, and runs the project launcher. The launcher is documented as installing dependencies, starting Neo4j and the servers, and serving the interface at `http://localhost:3000`.

git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env    # paste one OpenRouter key
./miroshark             # deps + Neo4j + servers → http://localhost:3000

The repository package scripts also expose separate setup and development operations. The package requires Node.js `>=22.0.0`, while the README badge states Python `3.11+`. For a manually managed local setup, the package scripts provide the following sequence.

npm run setup:all
npm run dev

`setup:all` runs frontend setup and backend `uv sync`, while `dev` starts the backend and frontend through `concurrently`. The backend script uses `uv run python run.py`, and the frontend script runs the Vite development server. The README does not document the exact user interface steps for creating the first simulation, so the confirmed first real use is to open the local application, provide the scenario input, and follow the interface's simulation workflow. The Docker configuration provides another route, but it requires `NEO4J_PASSWORD` in the environment.

The local Ollama configuration in `docker-compose.yml` uses `qwen2.5:32b` as `LLM_MODEL_NAME` and `nomic-embed-text` as `EMBEDDING_MODEL`. That choice may require substantial local resources. The cloud-oriented `.env.example` instead points LLM, smart, NER, and simulation slots at OpenRouter model names, with an explicit note that the Wonderwall loop uses more than 850 calls and over 7 million tokens per run. Cost and runtime therefore depend heavily on the selected provider and model.

Deployment, licensing, and maintenance constraints

MiroShark is distributed under `AGPL-3.0`. That matters for organizations considering modification, network deployment, or integration with another application, because the license includes source-code and network-use obligations. This review does not provide legal advice. Review the repository's `LICENSE` file and obtain appropriate legal guidance before combining the code with a proprietary service.

The project is not archived, and its last push was on 2026-10-14, so the repository is not marked archived and its recorded development activity is recent relative to the stated date. However, the repository has no GitHub releases. That means there is no published release stream in the repository facts from which to establish a stable upgrade path or migration policy. The repository does include deployment files such as `README_DEPLOYMENT.md`, `railway.json`, `render.yaml`, `cloudbuild.yaml`, and multiple Docker Compose files, but those filenames alone do not confirm a particular hosting provider's current support status.

The Dockerfile uses Python `3.14`, Node.js `22`, and `uv`, then installs root and frontend dependencies with `npm ci` and backend dependencies with `uv sync --frozen`. This is a concrete upgrade consideration: changing Python, Node.js, model endpoints, or dependency locks may affect the build. The Docker Compose file also pins Neo4j to `neo4j:5.26-community`, while Ollama uses `ollama/ollama:latest`. The former is versioned, but the latter can change independently, which makes repeatable deployments harder to reason about.

MiroShark versus deterministic scenario analysis

The closest practical alternative is a conventional deterministic scenario model, such as a spreadsheet, rules engine, or event-driven simulation in which the analyst defines variables, equations, and transition rules. MiroShark instead generates many persona-driven interactions through language models and stores their relationships in a graph. Deterministic models are easier to inspect and reproduce when the rules are known. They do not naturally produce varied social arguments, platform-specific language, or emergent disagreement among agents.

MiroShark is more appropriate when the question concerns possible reactions across several simulated communities. A PR team might want to see whether a press release produces support, skepticism, or conflicting narratives. A market-oriented user might want to explore how simulated traders react to financial news. A creative user might ask agents to continue a novel's ending. These are exploratory tasks where the process and possible reactions matter as much as one numeric answer.

The trade-off is control. A rules-based model can be calibrated against known inputs and can show exactly why a state changed. MiroShark's agent loop depends on model outputs, prompts, personas, platform behavior, and the selected endpoint. The README does not document a deterministic replay guarantee or a method for measuring simulation error. For a decision that requires auditability, reproducibility, or a defensible quantitative forecast, MiroShark should not replace a validated analytical model.

Editorial conclusion

MiroShark suits engineers and researchers who need an explorable, multi-platform simulation environment and can operate its Python, Node.js, Neo4j, and model-provider stack. It is a poor fit for applications that require verified predictions, statistically calibrated probabilities, or a low-cost deterministic workflow. Before adoption, verify the available model credentials, Ollama or OpenRouter configuration, Neo4j setup, and whether generated posts and trades are appropriate as evidence for the intended use case.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. MiroShark/MiroShark on GitHub
4. Project website
5. README