$ show 666ghj/MiroFish
MiroFish is a full-stack web application that implements a swarm intelligence prediction engine. It ingests real-world documents (PDF, Markdown, TXT), extracts seed information via LLM-driven ontology generation, builds a knowledge graph using Zep Cloud, and then generates agent profiles and simulation configurations for the OASIS multi-agent simulation framework. The system runs dual-platform simulations (Twitter-like and Reddit-like) to model social evolution and produce predictive reports through a ReACT-based report agent that queries the knowledge graph and interviews simulated agents. The frontend is a Vue 3 SPA with a 5-step wizard guiding users through graph building, environment setup, simulation execution, report generation, and deep interaction with agents. The architecture follows a monolith-with-subprocesses pattern: a Flask backend serves REST APIs for graph management, simulation lifecycle, and report generation, while simulation subprocesses run independently and communicate via a file-based IPC protocol. The system relies heavily on external services: an OpenAI-compatible LLM API for generation tasks, Zep Cloud for persistent graph storage and retrieval, and the OASIS simulation engine. The codebase is well-structured with clear separation into API routes, service modules, utility functions, and frontend components. It includes comprehensive i18n support (7 locales), Docker deployment, and CI/CD via GitHub Actions. While primarily an application, MiroFish has strong data/research characteristics: its core value proposition is predictive simulation driven by LLM-generated ontologies and agent profiles, and it uses GraphRAG techniques for report generation. The repository includes standalone scripts for star history tracking and validation, but these are auxiliary to the main application. The code demonstrates good engineering practices with reusable utilities (LLM client with retry, Zep pagination, file parser, retry decorators) and a consistent pattern for asynchronous task management and polling.
The LLM identified 6 files worth highlighting for reuse:
Provides a unified client for OpenAI-compatible chat completions with built-in JSON parsing, retry logic, and fallback from response_format to prompt-based JSON extraction. Handles token limit truncation and supports both sync and async calls. Reusable in any project requiring structured LLM output.
Implements opaque cursor-based pagination for Zep Cloud graph nodes and edges. Provides fetch_all_nodes and fetch_all_edges functions that handle pagination transparently, with configurable page size and retry. Can be extracted for any Zep-based project needing complete graph traversal.
Provides decorators for synchronous and asynchronous retry with exponential backoff, configurable max retries, base delay, and exception filtering. Includes a helper to create retry configurations for specific error types. A standalone utility applicable to any Python project needing resilient external calls.
Implements a file-based command/response protocol between the Flask backend and simulation subprocesses. Uses JSON files for commands and responses with polling and timeout. Supports commands like interview, close_env, and status queries. Demonstrates a simple, dependency-free IPC pattern suitable for process coordination.
Implements a ReACT (Reasoning + Acting) agent for report generation. The agent plans an outline, then iteratively calls tools (insight_forge, panorama_search, quick_search, interview_agents) to gather information, with conflict detection between tool calls and final answers. Generates structured reports with sections and citations. The pattern is reusable for any LLM-driven research or analysis task.
A Vue 3 component that renders an interactive knowledge graph using D3.js force-directed layout. Supports zoom, pan, node/edge selection, detail panels, and legend display. The component is self-contained and can be reused in any Vue project that needs to visualize graph data with similar interaction patterns.