87 lines
3.8 KiB
Markdown
87 lines
3.8 KiB
Markdown
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
npm run build # Build frontend (Vite)
|
|
```
|
|
|
|
### Backend (Python)
|
|
```bash
|
|
cd backend && uv run python run.py # Start Flask server
|
|
cd backend && uv run python -m pytest # Run tests (if any)
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
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:
|
|
1. **Graph Build** — Upload files → LLM extracts ontology → Zep Cloud builds knowledge graph
|
|
2. **Env Setup** — Read Zep entities → Generate OASIS agent profiles (AI personalities)
|
|
3. **Simulation** — CAMEL-OASIS runs agents on dual platforms (Twitter + Reddit) in parallel
|
|
4. **Report** — ReportAgent (ReACT loop) queries graph with tools: `SearchResult`, `InsightForge`, `Panorama`, `Interview`
|
|
5. **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
|