The Problem
Traditional prediction methods rely on static models or single-agent analysis, which fail to capture emergent behavior from many interacting actors. MiroFish addresses this by building a "parallel digital world" populated with autonomous agents that simulate social dynamics, allowing users to test "what if" scenarios before committing to real-world decisions.
What This Does
MiroFish is a full-stack swarm intelligence engine. The backend (backend/app/) is a Python service that ingests seed materials (news, reports, fiction), constructs an ontology graph, and runs multi-agent simulations. Key modules include graphbuilder.py for knowledge graph creation, simulationmanager.py for orchestrating agent runs, and reportagent.py for generating prediction summaries. It integrates with Zep for long-term agent memory (zepgraphmemoryupdater.py, zepentityreader.py).
The frontend (frontend/src/) is a Vue 3 application with a step-by-step workflow: build graph (Step1GraphBuild.vue), configure environment (Step2EnvSetup.vue), run simulation (Step3Simulation.vue), view report (Step4Report.vue), and interact with the world (Step5Interaction.vue). The UI communicates with the backend via REST APIs defined in frontend/src/api/.
How To Use It
Setup — The repo includes both Dockerfile and docker-compose.yml, so containerized deployment is the intended path. For local development, install Python dependencies via backend/requirements.txt or backend/pyproject.toml (pip or uv), and frontend dependencies via frontend/package.json (npm).
Configuration — Copy .env.example to .env and set required values. The backend reads configuration from backend/app/config.py, which likely loads LLM API keys and Zep connection details. The exact variables are not documented in the provided README excerpt; check .env.example for the full list.
Running it — Use Docker Compose for a full stack: docker-compose up --build
For local development, start the backend with python backend/run.py and the frontend with npm run dev inside frontend/. The README does not provide explicit commands, so these are inferred from the file structure.
Real-World Use
A policy analyst uploads a draft regulation and a set of stakeholder profiles. MiroFish builds a knowledge graph of actors and relationships, then runs thousands of agent interactions to simulate public reaction. The analyst receives a prediction report and can inject variables (e.g., "add a tax incentive") to see how the outcome shifts. The same pipeline works for fiction — upload a novel's first chapters and simulate how characters might evolve.
Code Health & Issues
High — No tests for core simulation logic: Only 1 test file exists (backend/scripts/testprofileformat.py). The simulation engine, graph builder, and report agent have no test coverage. This is a high-risk area given the complexity of agent interactions. Med — Tight coupling to Zep: zeptools.py and related modules depend on an external memory service. If Zep is unavailable, core functionality breaks. No fallback or local memory implementation is evident. Med — No CI pipeline: .github/workflows/docker-image.yml exists but only builds a Docker image. There's no CI for running tests or linting, which is a gap for a project of this size. Low — No input validation on uploads: fileparser.py handles user-uploaded files. Without explicit validation, malformed files could cause unexpected behavior or crashes. Low — License present: A LICENSE file exists, which is good. But the README does not clearly state the license type.
The Bottom Line
MiroFish is an ambitious project with a solid architectural split between a Python simulation backend and a Vue frontend. The concept is compelling, and the Docker setup makes it deployable. However, the lack of tests on core logic and the hard dependency on Zep are real risks for production use. It's best suited for teams exploring multi-agent simulation who can invest in hardening the codebase — not for teams needing a drop-in prediction tool.