Five stages turn source material into a simulated society
MiroFish takes a PDF, Markdown file, or text file and builds a graph from the material. It extracts entities, creates personas, configures a dual-platform social environment, runs agent interactions, and hands the resulting records to ReportAgent. The final interface supports a generated report plus conversations with simulated characters. That 5-stage flow is coherent, and the Vue frontend makes a complicated chain easier to observe than a folder of agent logs.
The default README calls the result a prediction engine, but the project's English FAQ draws a firmer boundary. OASIS supplies behavior and the multi-agent environment; LLMs generate the ontology, personas, configuration, behavior, and report; Zep stores graph and memory data. The FAQ says this combination must not be equated with a scientifically calibrated classical agent-based model. It does not automatically provide causal validity, calibrated opinion drift, or a prediction-confidence measure.
Two external API credentials are required for a real run
A dynamic deployment needs an LLM endpoint that works through the OpenAI Python SDK and a separate Zep Cloud key. The live demo linked in the README is a prebuilt static presentation, not a compute service for uploaded scenarios. The full source route also calls for Node.js 18+, Python 3.11 or 3.12, and uv. Docker reduces local packaging work but still reads the same credentials from .env.
The phrase "OpenAI-compatible" deserves caution. MiroFish depends on structured responses, request fields, context capacity, and parameter behavior that compatible providers may implement differently. Zep Cloud is the only officially integrated graph backend on current main, according to the FAQ, and startup rejects a legacy self-hosted Zep URL. Users seeking an offline model plus a local graph database would have to adopt unmerged community work or build the integration themselves.
What happened when we ran it
Our sandbox installed 31 npm packages in 13 seconds and used 14 MB on disk. The subsequent build failed with exit code 127 after 7 seconds. The root build script changed into frontend and invoked its build command, but the shell returned vite: not found. npm audit reported 0 known vulnerabilities across the packages installed by our run.
There was no tests script or target, so we skipped tests rather than inventing a substitute command. The 9.1 MB checkout held 128 files and about 51,770 source lines. It included a tests directory, two CI workflow files, a Dockerfile, and a Compose file. Those signals show that more validation exists in the repository, but they do not turn an unavailable package-script target into a test result.
The same input can produce different cohorts and conclusions
Open issue 751 reports that byte-identical input and interview prompts produced 9.5% and 60.0% abstention rates across two runs because cohort construction changed. Issue 759 follows the problem further: with the relevant temperatures set to zero, two consecutive graph builds in the same container returned 27 and 26 entities, with 24 shared. These are issue-reporter measurements, not our sandbox results, but they directly concern the product's central claim.
Variation can be useful for fiction and scenario discovery. It is a serious confound when someone compares policy options or treats one simulated crowd as representative. A defensible workflow would preserve every input and model setting, repeat the run, report disagreements, and compare the behavior with real observations or a baseline model. MiroFish does not currently do all of that for the user, and an attractive generated report can make the uncertainty easy to overlook.
Refreshing Step 3 can destroy the run you meant to inspect
Open issue 757 describes a browser refresh remounting Step 3 and sending a forced restart. In the reported sequence, the backend killed the subprocess, deleted the run files, and restarted at round 0 without a confirmation prompt. The project's FAQ separately says there is no general checkpoint or resume protocol across graph construction, configuration, simulation, and reporting. Report regeneration is only a limited exception when the underlying data survived.
That is costly because one simulation consumes two external services and may run for many rounds. The README itself advises starting below 40 rounds because consumption is high. A larger failed run can lose time, LLM spend, or Zep quota, and issue 688 asks for resumability for exactly that reason. Before committing a large document, test the complete flow on a smaller seed, back up backend/uploads, and avoid treating a browser reload as harmless.
A local demo is not a production multi-user service
Docker Compose publishes ports 3000 and 5001 and persists backend/uploads. The official FAQ warns against exposing backend port 5001 directly to the public internet and says the default configuration has no finished public multi-user security boundary. It recommends a trusted personal or local network. Authentication, tenant isolation, TLS, rate limiting, secret handling, audit logs, and path-boundary checks remain work for anyone turning the demo into a service.
71,575 stars coexist with an early release and active defects
GitHub showed 71,575 stars and 120 combined issues and pull requests. The last push was August 17, 2026, while detailed issue reports were still being updated on August 25. The latest release is v0.1.2 from March 7, 2026, and the project's July FAQ warned that main was already 96 commits ahead of that tag. This is active work, but choosing latest, v0.1.2, or main can produce materially different behavior.
MiroFish is interesting because it packages graph construction, persona generation, simulation, and questioning into one visible workflow. The 7-second build failure is fixable setup friction; the harder problem is epistemic. A simulated society built by an LLM and a changing entity extractor can produce useful hypotheses without producing a reliable forecast. Use the output to ask better questions, then verify those questions with data or a model whose assumptions you can test.