MiroFish

The Problem

MiroFish functions as a swarm intelligence engine for predicting outcomes from seed data, but its codebase contains structural issues that increase operational risk and hinder maintenance. The most significant findings from static analysis include 15 high-severity issues across 22 files with deep nesting (max indentation depth 11) and 17 oversized files exceeding 1,300 lines each. Additionally, 9 instances of broad exception handling swallow errors indiscriminately, and 1,128 repeated code blocks across 26 files violate DRY principles. These conditions mean that changes to core modules carry wide blast radius and that error paths are difficult to trace or debug.

What This Does

MiroFish is a multi-agent AI prediction engine that constructs a parallel digital world from seed materials (news, policy drafts, financial signals) where thousands of agents with independent personalities interact and evolve. The system allows users to inject variables from a "God's-eye view" to deduce future trajectories through simulation.

The repository contains two primary domains: a Python backend (38 files, 35 code files) and a Vue.js frontend (32 files, 9 code files). The backend structure organizes services into simulation, API, and utility modules under backend/app/services/, backend/app/api/, and backend/app/utils/. Key entry points include backend/run.py:25 which reaches 43 functions, and simulation scripts in backend/scripts/. The frontend builds on Vite with Vue Router and provides a simulation interface through components like Step3Simulation.vue and SimulationRunView.vue, with API calls routed through frontend/src/api/. Docker and docker-compose are configured for containerized deployment, and the system declares 18 dependencies across Python and JavaScript ecosystems.

How It Is Wired

Execution begins at backend/run.py:25 (main function), which routes to 43 downstream functions. The internal call graph contains 731 resolved call edges between self-contained functions; the most connected symbol is t, called from 94 places, followed by to_dict (36 places) and SimulationManager (13 places). Representative edges show generate_report -> t x23, prepare_simulation -> t x16, and interview_agents -> t x11.

The call graph reveals several hub modules with high in-degree: backend/app/config (15 modules depend on it, 0 depend on anything else), backend/app/utils/logger (15 dependents), and backend/app/utils/locale (14 dependents). These hubs carry high blast radius—modifications to config.py or the logger propagate to many callers. The simulation pipeline flows through prepare_simulation -> progress_callback x10 -> t x16, with build_graph -> t x9 and interview_agents_batch -> t x8 as significant paths. Entry points run_reddit_simulation.py:523 and simulation_ipc.py:313 start independent execution threads that reach 15 and 2 functions respectively.

Outside the codebase, the system touches databases (9 functions), files (23 functions), model inference (9 functions), and external commands (2 functions). Shortest paths from entry to process exit include main -> run_twitter_simulation [filesystem via os.remove] and run -> process_commands -> send_response [filesystem via os.remove].

How To Use It

Setup:

# Clone the repository
git clone https://github.com/moses-y/MiroFish

# Backend dependencies
cd MiroFish/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Frontend dependencies
cd ../..
npm install

# Environment configuration
cp .env.example .env
# Edit .env to set required variables including SECRET_KEY

# Start the application
docker-compose up -d
# Or run manually: backend/run.py and frontend/vite dev server

Configuration: The file backend/.env.example documents required environment variables. Critical is SECRET_KEY—the code health audit flags that a 19-character literal fallback exists and should be removed; the system should fail to start when this key is absent rather than using a default.

Running it: The primary entry point is backend/run.py:25 (the main function). To start a simulation: python backend/run.py or via docker-compose up. For Reddit-specific simulations: python backend/scripts/run_reddit_simulation.py. The Dockerfile builds from python:3.11 and the docker-compose.yml orchestrates the full stack.

Real-World Use

A policy team uploads a draft regulatory document as seed material and specifies "analyze public reaction trajectories over 12 months." The system extracts entities, constructs agent personalities with long-term memory, runs hundreds of simulation iterations, and returns a detailed prediction report with interactive digital world snapshots. The team adjusts variables (e.g., "increase media coverage by 20%") and re-runs to observe divergent outcomes—effectively rehearsing policy impacts in a sandbox before real-world deployment.

Code Health & Issues

The static analysis identified 52 total findings across 5 categories:

• HIGH/cognitive_load: Deep nesting in backend/app/services/simulation_runner.py, backend/app/services/oasis_profile_generator.py, backend/app/services/zep_entity_reader.py (max indentation depth 11)
• HIGH/cognitive_load: Oversized files same as above plus backend/app/services/zep_tools.py (1,355 code lines)
• MEDIUM/resilience: Broad exception handling in backend/app/services/simulation_runner.py, backend/app/services/oasis_profile_generator.py, backend/app/utils/file_parser.py
• MEDIUM/clarity: Hub modules with 14+ dependents: backend/app/config.py, backend/app/utils/logger.py, backend/app/utils/locale.py
• HIGH/clarity: Duplicated code blocks—1,128 repeated 6-line patterns across 26 files including backend/app/api/graph.py, backend/app/api/simulation.py, backend/app/api/report.py

The code health audit adds 9 SDLC findings: GitHub Actions pins use mutable tags (HIGH), hardcoded SECRET_KEY fallback in backend/app/config.py (HIGH), no Dependabot/Renovate configuration (MEDIUM), mutable Docker base image python:3.11 (MEDIUM), no dependency vulnerability scanning in CI (MEDIUM), container runs as root (MEDIUM), only 1 test file against 60 source files (MEDIUM), no workflow job timeouts (LOW), and missing convention files (.editorconfig, .gitattributes) (LOW).

The Bottom Line

MiroFish delivers a functional swarm intelligence prediction engine with a working frontend and containerized deployment, but its codebase carries significant technical debt. The 15 high-severity findings—particularly the hardcoded signing key, untagged Docker base image, and mutable GitHub Action references—represent immediate operational risks. The structural issues (deep nesting, oversized files, duplicated logic) will slow feature development and increase bug risk. This repository is suitable for experienced teams willing to invest in refactoring, particularly splitting the oversized service files and hardening the configuration and CI pipeline. Teams needing stable, well-maintained code should look elsewhere or budget for substantial remediation.

Word count: 547