# 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)

```bash
# 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)

```bash
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 消耗和成本

```python
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`:
```bash
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