evotraders/CLAUDE.md

CLAUDE.md

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

Project Overview

EvoTraders is a self-evolving multi-agent trading system where 6 AI agents (4 analysts + portfolio manager + risk manager) collaborate to make trading decisions. Agents use the AgentScope framework with a ReMe memory system for continuous learning.

Development Commands

Backend (Python)

# Install dependencies
uv pip install -e .

# Run commands
evotraders backtest --start 2025-11-01 --end 2025-12-01  # Backtest mode
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory
evotraders live                              # Live trading
evotraders live --mock                       # Mock/testing mode
evotraders live -t 22:30                     # Scheduled daily trading
evotraders frontend                          # Launch visualization UI

# Dev server (starts FastAPI on port 8000)
./start-dev.sh
# Or manually:
python -m uvicorn backend.app:app --host 0.0.0.0 --port 8000 --reload --reload-dir backend

# Testing
pytest backend/tests

Frontend (React)

cd frontend
npm run dev          # Vite dev server (http://localhost:5173)
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Vitest
npm run test:watch   # Watch mode

Architecture

Multi-Agent System (backend/agents/)

6 Agent Roles (configured in prompts/analyst/personas.yaml):

• fundamentals_analyst - Financial health, profitability, growth quality
• technical_analyst - Price trends, indicators, momentum
• sentiment_analyst - Market sentiment, news, insider trading
• valuation_analyst - DCF, EV/EBITDA, intrinsic value
• portfolio_manager - Decision execution, trade coordination
• risk_manager - Real-time risk monitoring, position limits

Key Agent Files:

• base/evo_agent.py - Core agent implementation extending AgentScope
• base/hooks.py - Lifecycle hooks for agent execution (BootstrapHook, MemoryCompactionHook, HeartbeatHook, WorkspaceWatchHook)
• base/evaluation_hook.py - Post-execution evaluation
• base/skill_adaptation_hook.py - Dynamic skill adaptation
• factory.py - Agent factory for creating agent instances
• skills_manager.py - Skill loading and management (6 scopes: builtin/customized/installed/active/disabled/local)
• toolkit_factory.py - Tool collection factory for agents
• team/ - Team coordination (registry, coordinator, messenger, task_delegator)

Hook System (base/hooks.py):

• MemoryCompactionHook: 基于 CoPaw 设计的内存压缩，支持:
  • memory_compact_ratio: 压缩目标比例 (默认 0.75)
  • memory_reserve_ratio: 保留比例 (默认 0.1)
  • enable_tool_result_compact: 工具结果压缩
  • tool_result_compact_keep_n: 保留最近 N 条工具结果

Adding Custom Analysts:

1. Register in backend/agents/prompts/analyst/personas.yaml
2. Add to ANALYST_TYPES dict in backend/config/constants.py
3. Optionally update frontend config in frontend/src/config/constants.js

Backend Structure

backend/
├── agents/          # Multi-agent implementation
│   ├── base/        # Base classes, hooks, evaluation
│   ├── prompts/     # Agent prompts and personas
│   └── team/        # Team coordination logic
├── api/             # FastAPI endpoints
├── config/          # Constants and configuration
├── core/            # Pipeline execution logic
├── data/            # Market data handling
├── enrich/          # LLM response enrichment
├── explain/         # Decision explanation
├── llm/             # LLM integrations (with RetryChatModel, TokenRecordingModelWrapper)
├── services/        # Gateway, WebSocket services
├── skills/          # Skill definitions (builtin + custom)
└── tools/           # Trading and analysis tools

LLM Model Wrappers (backend/llm/models.py)

Based on CoPaw's model wrapper design:

• RetryChatModel: 自动重试瞬态 LLM 错误（rate limit、timeout、502/503 等），指数退避
  • max_retries: 最大重试次数 (默认 3)
  • initial_delay: 初始延迟秒数 (默认 1.0)
  • backoff_multiplier: 退避倍数 (默认 2.0)
• TokenRecordingModelWrapper: 追踪每个 provider 的 token 消耗和成本

from backend.llm.models import create_model, RetryChatModel

model = RetryChatModel(create_model("gpt-4o", "OPENAI"), max_retries=3)

Frontend Structure

frontend/src/
├── App.jsx              # Main React application
├── components/          # React components
│   ├── RuntimeView.jsx  # Trading runtime UI
│   ├── TraderView.jsx   # Trader interface
│   └── RuntimeSettingsPanel.jsx
├── services/            # API and WebSocket services
│   ├── runtimeApi.js    # Backend API calls
│   └── websocket.js      # Real-time communication
└── config/
    └── constants.js      # Agent definitions, configuration

Skill System (backend/skills/)

Skills are defined in SKILL.md files with:

• instructions - What the skill does
• triggers - When to invoke
• parameters - Input/output schema
• available_tools - Tools the skill can use

Skills are loaded by skills_manager.py and attached to agents via skill_adaptation_hook.py.

Pipeline Execution (backend/core/)

The daily trading flow:

1. Analysis Stage - Each agent analyzes independently
2. Communication Stage - Agent-to-agent messaging (1v1, 1vN, NvN)
3. Decision Stage - Portfolio manager makes final trades
4. Evaluation Stage - Performance tracking
5. Review Stage - Memory updates via ReMe

Environment Configuration

Required in .env:

FIN_DATA_SOURCE=finnhub|financial_datasets
FINANCIAL_DATASETS_API_KEY=   # Required for backtest
FINNHUB_API_KEY=              # Required for live trading
OPENAI_API_KEY=               # Agent LLM
OPENAI_BASE_URL=
MODEL_NAME=qwen3-max-preview
MEMORY_API_KEY=               # For ReMe memory system

Key Dependencies

• AgentScope - Multi-agent framework
• ReMe - Memory system for continuous learning
• FastAPI + uvicorn - Backend API server
• websockets - Real-time communication
• React 19 + Vite + TailwindCSS - Frontend
• Zustand - Frontend state management
• Three.js / React-Three-Fiber - 3D visualizations