3.8 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MiroFish is a multi-agent swarm intelligence prediction engine. It builds knowledge graphs from seed data, simulates thousands of AI agents interacting on virtual Twitter/Reddit platforms (via CAMEL-OASIS), and generates analytical reports — all to predict outcomes of real-world scenarios.

Commands

Setup

npm run setup:all        # Install all dependencies (frontend + backend)
npm run setup            # Frontend npm install only
npm run setup:backend    # Backend: uv sync (Python deps)

Development

npm run dev              # Run backend + frontend concurrently
npm run backend          # Backend only: Flask on port 5001
npm run frontend         # Frontend only: Vite on port 3000

Build

npm run build            # Build frontend (Vite)

Backend (Python)

cd backend && uv run python run.py          # Start Flask server
cd backend && uv run python -m pytest       # Run tests (if any)

Docker

docker-compose up        # Full stack via Docker

Architecture

Stack

Backend: Python ≥3.11 Flask 3.0, managed by uv
Frontend: Vue 3 + Vite, port 3000; proxies /api → port 5001
LLM: OpenAI SDK-compatible (default: Qwen via dashscope; also works with GLM, OpenAI)
Memory/Graph: Zep Cloud (knowledge graph for entity storage and retrieval)
Simulation: CAMEL-OASIS (multi-agent Twitter + Reddit simulation)
Visualization: D3.js

Required Environment Variables

Copy .env.example to .env:

LLM_API_KEY         # Required
LLM_BASE_URL        # Default: https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME      # Default: qwen-plus
ZEP_API_KEY         # Required (Zep Cloud)

5-Step Pipeline

The core workflow is a sequential async pipeline:

Graph Build — Upload files → LLM extracts ontology → Zep Cloud builds knowledge graph
Env Setup — Read Zep entities → Generate OASIS agent profiles (AI personalities)
Simulation — CAMEL-OASIS runs agents on dual platforms (Twitter + Reddit) in parallel
Report — ReportAgent (ReACT loop) queries graph with tools: SearchResult, InsightForge, Panorama, Interview
Interaction — Chat with simulated agents or the ReportAgent

Backend Structure (`backend/app/`)

api/ — Flask blueprints: graph_bp, simulation_bp, report_bp
services/ — Core logic: graph building, simulation runner, report agent, Zep tools
models/ — Project and Task state objects (in-memory, JSON-serializable)
utils/ — LLM client wrapper, file parser, retry logic, Zep pagination
config/config.py — All configuration (LLM, Zep, chunking, simulation params)

Long-running operations (ontology generation, graph build, profile generation, report generation) run as background tasks tracked via Task objects with progress polling.

Frontend Structure (`frontend/src/`)

views/ — Page components mapped to routes; Process.vue is the main 50KB workflow orchestrator
components/ — Step1-5 step components + GraphPanel.vue (D3 graph visualization)
api/ — Axios services (graph.js, simulation.js, report.js) with 5-min timeout and exponential retry

Key Implementation Details

Reasoning model outputs (e.g., MiniMax/GLM with <think> tags or markdown code fences) are stripped before processing — see recent fix in commit 985f89f
Simulation state is managed in SimulationManager; IPC between processes via simulation_ipc.py
Interview/chat with agents uses prefix injection to suppress tool calls in responses
Default simulation: max 10 rounds, Twitter actions include CREATE_POST/LIKE/REPOST/FOLLOW/QUOTE/DO_NOTHING; Reddit adds CREATE_COMMENT/DISLIKE

3.8 KiB Raw Blame History