chore: sync current workspace changes
This commit is contained in:
383
README.md
383
README.md
@@ -5,32 +5,28 @@
|
||||
<h2 align="center">EvoTraders: A Self-Evolving Multi-Agent Trading System</h2>
|
||||
|
||||
<p align="center">
|
||||
📌 <a href="http://trading.evoagents.cn">Visit us at EvoTraders website !</a>
|
||||
📌 <a href="http://trading.evoagents.cn">Visit the EvoTraders website</a>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
EvoTraders is an open-source financial trading agent framework that builds a trading system capable of continuous learning and evolution in real markets through multi-agent collaboration and memory systems.
|
||||
EvoTraders is an open-source financial trading agent framework that combines multi-agent collaboration, run-scoped workspaces, and memory to support both backtests and live trading workflows.
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
**Multi-Agent Collaborative Trading**
|
||||
A team of 6 members, including 4 specialized analyst roles (fundamentals, technical, sentiment, valuation) + portfolio manager + risk management, collaborating to make decisions like a real trading team.
|
||||
**Multi-agent trading team**
|
||||
Six roles collaborate like a real desk: four specialist analysts (fundamentals, technical, sentiment, valuation), one portfolio manager, and one risk manager.
|
||||
|
||||
You can customize your Agents here: [Custom Configuration](#custom-configuration)
|
||||
**Continuous learning**
|
||||
Agents can persist long-term memory with ReMe, reflect after each cycle, and evolve their decision patterns over time.
|
||||
|
||||
**Continuous Learning and Evolution**
|
||||
Based on the ReMe memory framework, agents reflect and summarize after each trade, preserving experience across rounds, and forming unique investment methodologies.
|
||||
**Backtest and live modes**
|
||||
The same runtime model supports historical simulation and live execution with real-time market data.
|
||||
|
||||
Through this design, we hope that when AI Agents form a team and enter the real-time market, they will gradually develop their own trading styles and decision preferences, rather than one-time random inference.
|
||||
|
||||
**Real-Time Market Trading**
|
||||
Supports real-time market data integration, providing backtesting mode and live trading mode, allowing AI Agents to learn and make decisions in real market fluctuations.
|
||||
|
||||
**Visualized Trading Information**
|
||||
Observe agents' analysis processes, communication records, and decision evolution in real-time, with complete tracking of return curves and analyst performance.
|
||||
**Operator-facing UI**
|
||||
The frontend exposes the trading room, runtime controls, logs, approvals, agent workspaces, and explain/news views.
|
||||
|
||||
<p>
|
||||
<img src="docs/assets/performance.jpg" width="45%">
|
||||
@@ -39,83 +35,158 @@ Observe agents' analysis processes, communication records, and decision evolutio
|
||||
|
||||
---
|
||||
|
||||
## Current Architecture
|
||||
|
||||
The repository is currently in a transition from a modular monolith to split service surfaces. The split-service path is the default local development mode.
|
||||
|
||||
Current app surfaces:
|
||||
|
||||
- `backend.apps.agent_service` on `:8000`: control plane for workspaces, agents, skills, and guard/approval APIs
|
||||
- `backend.apps.trading_service` on `:8001`: read-only trading data APIs
|
||||
- `backend.apps.news_service` on `:8002`: read-only explain/news APIs
|
||||
- `backend.apps.runtime_service` on `:8003`: runtime lifecycle APIs
|
||||
- `backend.apps.openclaw_service` on `:8004`: read-only OpenClaw facade
|
||||
- WebSocket gateway on `:8765`: live event/feed channel for the frontend
|
||||
|
||||
The most important runtime path today is:
|
||||
|
||||
`frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage`
|
||||
|
||||
Reference notes for the migration live in [services/README.md](./services/README.md).
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
### 1. Install
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/agentscope-ai/agentscope-samples
|
||||
cd agentscope-samples/EvoTraders
|
||||
# clone this repository, then:
|
||||
cd evotraders
|
||||
|
||||
# Install dependencies (Recommend uv!)
|
||||
# recommended
|
||||
uv pip install -e .
|
||||
# optional: pip install -e .
|
||||
|
||||
# optional
|
||||
# uv pip install -e ".[dev]"
|
||||
# pip install -e .
|
||||
```
|
||||
|
||||
# Configure environment variables
|
||||
### 2. Configure environment
|
||||
|
||||
```bash
|
||||
cp env.template .env
|
||||
# Edit .env file and add your API Keys. The following config are required:
|
||||
```
|
||||
|
||||
# finance data API: At minimum, FINANCIAL_DATASETS_API_KEY is required, corresponding to FIN_DATA_SOURCE=financial_datasets; It is recommended to add FINNHUB_API_KEY, corresponding to FIN_DATA_SOURCE=finnhub; If using live mode, FINNHUB_API_KEY must be added
|
||||
FIN_DATA_SOURCE = #finnhub or financial_datasets
|
||||
FINANCIAL_DATASETS_API_KEY= #Required
|
||||
FINNHUB_API_KEY= #Optional
|
||||
The root `env.template` is the canonical local template. A `.env.example` is also kept in the repo for reference.
|
||||
|
||||
# LLM API for Agents
|
||||
Minimum useful variables:
|
||||
|
||||
```bash
|
||||
# watchlist
|
||||
TICKERS=AAPL,MSFT,GOOGL,NVDA,TSLA,META,AMZN
|
||||
|
||||
# market data
|
||||
FIN_DATA_SOURCE=finnhub
|
||||
FINANCIAL_DATASETS_API_KEY=
|
||||
FINNHUB_API_KEY=
|
||||
POLYGON_API_KEY=
|
||||
|
||||
# agent model
|
||||
OPENAI_API_KEY=
|
||||
OPENAI_BASE_URL=
|
||||
MODEL_NAME=qwen3-max-preview
|
||||
|
||||
# LLM & embedding API for Memory
|
||||
# memory (optional unless --enable-memory is used)
|
||||
MEMORY_API_KEY=
|
||||
```
|
||||
|
||||
### Running
|
||||
Notes:
|
||||
|
||||
- `FINNHUB_API_KEY` is required for live mode.
|
||||
- `POLYGON_API_KEY` enables long-lived market-store ingestion and refresh helpers.
|
||||
- `MEMORY_API_KEY` is only required when long-term memory is enabled.
|
||||
|
||||
### 3. Start the stack
|
||||
|
||||
Recommended local development flow:
|
||||
|
||||
**Backtest Mode:**
|
||||
```bash
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory # Use Memory
|
||||
./start-dev.sh
|
||||
```
|
||||
|
||||
If you do not have market data APIs and just want to try the backtest demo, download the offline data and unzip it into `backend/data`:
|
||||
This starts:
|
||||
|
||||
- `agent_service` at `http://localhost:8000`
|
||||
- `trading_service` at `http://localhost:8001`
|
||||
- `news_service` at `http://localhost:8002`
|
||||
- `runtime_service` at `http://localhost:8003`
|
||||
- gateway WebSocket at `ws://localhost:8765`
|
||||
|
||||
Then start the frontend in another terminal:
|
||||
|
||||
```bash
|
||||
evotraders frontend
|
||||
```
|
||||
|
||||
Open `http://localhost:5173`.
|
||||
|
||||
You can also run services manually:
|
||||
|
||||
```bash
|
||||
python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
|
||||
python -m uvicorn backend.apps.trading_service:app --host 0.0.0.0 --port 8001 --reload
|
||||
python -m uvicorn backend.apps.news_service:app --host 0.0.0.0 --port 8002 --reload
|
||||
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload
|
||||
python -m backend.main --mode live --host 0.0.0.0 --port 8765
|
||||
```
|
||||
|
||||
### 4. Run backtest or live mode from CLI
|
||||
|
||||
Backtest:
|
||||
|
||||
```bash
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01
|
||||
evotraders backtest --start 2025-11-01 --end 2025-12-01 --enable-memory
|
||||
evotraders backtest --config-name smoke_fullstack --start 2025-11-01 --end 2025-12-01
|
||||
```
|
||||
|
||||
Live:
|
||||
|
||||
```bash
|
||||
evotraders live
|
||||
evotraders live --enable-memory
|
||||
evotraders live --schedule-mode intraday --interval-minutes 60
|
||||
evotraders live --trigger-time 22:30
|
||||
```
|
||||
|
||||
Help:
|
||||
|
||||
```bash
|
||||
evotraders --help
|
||||
evotraders backtest --help
|
||||
evotraders live --help
|
||||
evotraders frontend --help
|
||||
```
|
||||
|
||||
### Offline backtest data
|
||||
|
||||
If you want a quick backtest demo without external market APIs, download the offline bundle and unzip it into `backend/data`:
|
||||
|
||||
```bash
|
||||
wget "https://agentscope-open.oss-cn-beijing.aliyuncs.com/ret_data.zip"
|
||||
unzip ret_data.zip -d backend/data
|
||||
```
|
||||
The zip includes basic stock price data so you can run the backtest demo out of the box.
|
||||
|
||||
**Live Trading:**
|
||||
```bash
|
||||
evotraders live # Run immediately (default)
|
||||
evotraders live --enable-memory # Use memory
|
||||
evotraders live --mock # Mock mode (testing)
|
||||
evotraders live -t 22:30 # Run daily at 22:30 local time (auto-converts to NYSE timezone)
|
||||
```
|
||||
---
|
||||
|
||||
**Get Help:**
|
||||
```bash
|
||||
evotraders --help # View global CLI help
|
||||
evotraders backtest --help # View backtest mode parameters
|
||||
evotraders live --help # View live/mock run parameters
|
||||
```
|
||||
## Runtime Data Layout
|
||||
|
||||
**Launch Visualization Interface:**
|
||||
```bash
|
||||
# Ensure npm is installed, otherwise install it:
|
||||
# npm install
|
||||
evotraders frontend # Default connects to port 8765, you can modify the address in ./frontend/env.local to change the port number
|
||||
```
|
||||
|
||||
Visit `http://localhost:5173/` to view the trading room, select a date and click Run/Replay to observe the decision-making process.
|
||||
|
||||
### Runtime Data Layout
|
||||
|
||||
- Long-lived research data is stored in `data/market_research.db`
|
||||
- Each task run writes run-scoped state under `runs/<run_id>/`
|
||||
- `runs/<run_id>/team_dashboard/*.json` is an export/compatibility layer for dashboard views, not the authoritative runtime source of truth
|
||||
- Runtime APIs prefer active runtime state, `server_state.json`, and `runtime.db`
|
||||
- Long-lived research data lives in `data/market_research.db`
|
||||
- Each run writes run-scoped state under `runs/<run_id>/`
|
||||
- `runs/<run_id>/BOOTSTRAP.md` stores run-specific bootstrap values and prompt body
|
||||
- `runs/<run_id>/state/runtime_state.json` stores runtime snapshot state
|
||||
- `runs/<run_id>/team_dashboard/*.json` is a compatibility/export layer for dashboard consumers, not the primary runtime source of truth
|
||||
|
||||
Optional retention control:
|
||||
|
||||
@@ -123,129 +194,147 @@ Optional retention control:
|
||||
RUNS_RETENTION_COUNT=20
|
||||
```
|
||||
|
||||
Only timestamped run folders like `YYYYMMDD_HHMMSS` are pruned automatically when starting a new runtime. Named runs such as `smoke_fullstack` or `test_*` are preserved.
|
||||
Only timestamped run folders like `YYYYMMDD_HHMMSS` are pruned automatically. Named runs such as `live`, `smoke_fullstack`, or `reload_demo_*` are preserved.
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
## Frontend Service Routing
|
||||
|
||||
|
||||
The frontend always uses the control plane and runtime APIs, and can optionally call split services directly for read-only data.
|
||||
|
||||
### Agent Design
|
||||
Useful frontend env vars:
|
||||
|
||||
**Analyst Team:**
|
||||
- **Fundamentals Analyst**: Financial health, profitability, growth quality
|
||||
- **Technical Analyst**: Price trends, technical indicators, momentum analysis
|
||||
- **Sentiment Analyst**: Market sentiment, news sentiment, insider trading
|
||||
- **Valuation Analyst**: DCF, residual income, EV/EBITDA
|
||||
|
||||
**Decision Layer:**
|
||||
- **Portfolio Manager**: Integrates analysis signals from analysts, executes communication strategies, combines analyst and team historical performance, recent investment memories, and long-term investment experience to make final decisions
|
||||
- **Risk Management**: Real-time price and volatility monitoring, position limits, multi-layer risk warnings
|
||||
|
||||
### Decision Process
|
||||
|
||||
```
|
||||
Real-time Market Data → Independent Analysis → Intelligent Communication (1v1/1vN/NvN) → Decision Execution → Performance Evaluation → Learning and Evolution (Memory Update)
|
||||
```bash
|
||||
VITE_CONTROL_API_BASE_URL=http://localhost:8000/api
|
||||
VITE_RUNTIME_API_BASE_URL=http://localhost:8003/api/runtime
|
||||
VITE_NEWS_SERVICE_URL=http://localhost:8002
|
||||
VITE_TRADING_SERVICE_URL=http://localhost:8001
|
||||
VITE_WS_URL=ws://localhost:8765
|
||||
```
|
||||
|
||||
Each trading day goes through five stages:
|
||||
|
||||
1. **Analysis Stage**: Each agent independently analyzes based on their respective tools and historical experience
|
||||
2. **Communication Stage**: Exchange views through private chats, notifications, meetings, etc.
|
||||
3. **Decision Stage**: Portfolio manager makes comprehensive judgments and provides final trades
|
||||
4. **Evaluation Stage**
|
||||
- **Performance Charts**: Track portfolio return curves vs. benchmark strategies (equal-weighted, market-cap weighted, momentum). Used to evaluate overall strategy effectiveness.
|
||||
|
||||
- **Analyst Rankings**: Click on avatars in the Trading Room to view analyst performance (win rate, bull/bear market win rate). Used to understand which analysts provide the most valuable insights.
|
||||
|
||||
- **Statistics**: Detailed position and trading history. Used for in-depth analysis of position management and execution quality.
|
||||
|
||||
5. **Review Stage**: Agents reflect on decisions and summarize experiences based on actual returns of the day, and store them in the ReMe memory framework for continuous improvement
|
||||
If these are not set, the frontend falls back to its local defaults and compatibility paths where available.
|
||||
|
||||
---
|
||||
|
||||
### Module Support
|
||||
## Decision Flow
|
||||
|
||||
- **Agent Framework**: [AgentScope](https://github.com/agentscope-ai/agentscope)
|
||||
- **Memory System**: [ReMe](https://github.com/agentscope-ai/reme)
|
||||
- **LLM Support**: OpenAI, DeepSeek, Qwen, Moonshot, Zhipu AI, etc.
|
||||
```text
|
||||
Market data -> independent analyst work -> team communication -> portfolio decision ->
|
||||
risk review -> execution/settlement -> reflection/memory update
|
||||
```
|
||||
|
||||
The runtime manager also tracks:
|
||||
|
||||
- agent registration and status
|
||||
- pending approvals
|
||||
- run events
|
||||
- current session key
|
||||
|
||||
---
|
||||
|
||||
## Custom Configuration
|
||||
|
||||
### Custom Analyst Roles
|
||||
### Add or change analyst roles
|
||||
|
||||
1. Register role information in [./backend/agents/prompts/analyst/personas.yaml](./backend/agents/prompts/analyst/personas.yaml), for example:
|
||||
1. Define the analyst persona in [backend/agents/prompts/analyst/personas.yaml](./backend/agents/prompts/analyst/personas.yaml)
|
||||
2. Register the role in [backend/config/constants.py](./backend/config/constants.py)
|
||||
3. Optionally add/update the frontend seat metadata in [frontend/src/config/constants.js](./frontend/src/config/constants.js)
|
||||
|
||||
Example persona entry:
|
||||
|
||||
```yaml
|
||||
comprehensive_analyst:
|
||||
name: "Comprehensive Analyst"
|
||||
focus:
|
||||
- ...
|
||||
preferred_tools: # Flexibly select based on situation
|
||||
- multi-factor synthesis
|
||||
preferred_tools:
|
||||
- get_stock_price
|
||||
- get_company_financials
|
||||
description: |
|
||||
As a comprehensive analyst ...
|
||||
A generalist analyst that combines multiple signals.
|
||||
```
|
||||
|
||||
2. Add role definition in [./backend/config/constants.py](./backend/config/constants.py)
|
||||
```python
|
||||
ANALYST_TYPES = {
|
||||
# Add new analyst
|
||||
"comprehensive_analyst": {
|
||||
"display_name": "Comprehensive Analyst",
|
||||
"agent_id": "comprehensive_analyst",
|
||||
"description": "Uses LLM to intelligently select analysis tools, performs comprehensive analysis",
|
||||
"order": 15
|
||||
}
|
||||
}
|
||||
```
|
||||
### Configure per-agent models
|
||||
|
||||
3. Introduce new role in frontend configuration [./frontend/src/config/constants.js](./frontend/src/config/constants.js) (optional)
|
||||
```javascript
|
||||
export const AGENTS = [
|
||||
// Override one of the agents
|
||||
{
|
||||
id: "comprehensive_analyst",
|
||||
name: "Comprehensive Analyst",
|
||||
role: "Comprehensive Analyst",
|
||||
avatar: `${ASSET_BASE_URL}/...`,
|
||||
colors: { bg: '#F9FDFF', text: '#1565C0', accent: '#1565C0' }
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Custom Models
|
||||
|
||||
Configure models used by different agents in the [.env](.env) file:
|
||||
Model overrides are configured in `.env`:
|
||||
|
||||
```bash
|
||||
AGENT_SENTIMENT_ANALYST_MODEL_NAME=qwen3-max-preview
|
||||
AGENT_FUNDAMENTALS_ANALYST_MODEL_NAME=deepseek-chat
|
||||
AGENT_TECHNICAL_ANALYST_MODEL_NAME=glm-4-plus
|
||||
AGENT_VALUATION_ANALYST_MODEL_NAME=moonshot-v1-32k
|
||||
AGENT_SENTIMENT_ANALYST_MODEL_NAME=deepseek-v3.2-exp
|
||||
AGENT_TECHNICAL_ANALYST_MODEL_NAME=glm-4.6
|
||||
AGENT_FUNDAMENTALS_ANALYST_MODEL_NAME=qwen3-max-preview
|
||||
AGENT_VALUATION_ANALYST_MODEL_NAME=Moonshot-Kimi-K2-Instruct
|
||||
AGENT_RISK_MANAGER_MODEL_NAME=qwen3-max-preview
|
||||
AGENT_PORTFOLIO_MANAGER_MODEL_NAME=qwen3-max-preview
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
### Run-scoped bootstrap config
|
||||
|
||||
Each run can override defaults through `runs/<run_id>/BOOTSTRAP.md`. The front matter is parsed by [backend/config/bootstrap_config.py](./backend/config/bootstrap_config.py) and can define values such as:
|
||||
|
||||
```yaml
|
||||
tickers:
|
||||
- AAPL
|
||||
- MSFT
|
||||
initial_cash: 100000
|
||||
margin_requirement: 0.5
|
||||
max_comm_cycles: 2
|
||||
schedule_mode: daily
|
||||
trigger_time: "09:30"
|
||||
enable_memory: false
|
||||
```
|
||||
EvoTraders/
|
||||
|
||||
Initialize a run workspace with:
|
||||
|
||||
```bash
|
||||
evotraders init-workspace --config-name my_run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```text
|
||||
evotraders/
|
||||
├── backend/
|
||||
│ ├── agents/ # Agent implementation
|
||||
│ ├── communication/ # Communication system
|
||||
│ ├── memory/ # Memory system (ReMe)
|
||||
│ ├── tools/ # Analysis toolset
|
||||
│ ├── servers/ # WebSocket services
|
||||
│ └── cli.py # CLI entry point
|
||||
├── frontend/ # React visualization interface
|
||||
└── logs_and_memory/ # Logs and memory data
|
||||
│ ├── agents/ # agent roles, prompts, skills, workspaces
|
||||
│ ├── api/ # FastAPI routers
|
||||
│ ├── apps/ # split service surfaces
|
||||
│ ├── core/ # pipeline, scheduler, state sync
|
||||
│ ├── runtime/ # runtime manager and agent runtime state
|
||||
│ ├── services/ # gateway, market/storage/db services
|
||||
│ └── cli.py # Typer CLI entrypoint
|
||||
├── frontend/ # React + Vite UI
|
||||
├── shared/ # shared clients and schemas for split services
|
||||
├── runs/ # run-scoped state and dashboards
|
||||
├── data/ # long-lived research artifacts
|
||||
└── services/README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Backend tests live under `backend/tests` and cover service apps, shared clients, domains, routing, enrichment, gateway support, and runtime support.
|
||||
|
||||
Typical commands:
|
||||
|
||||
```bash
|
||||
pytest
|
||||
pytest backend/tests/test_runtime_service_app.py
|
||||
pytest backend/tests/test_trading_service_app.py
|
||||
```
|
||||
|
||||
Frontend tests:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License and Disclaimer
|
||||
|
||||
EvoTraders is a research and educational project, open-sourced under the Apache 2.0 license.
|
||||
EvoTraders is a research and educational project. Review the repository license before redistribution or commercial use.
|
||||
|
||||
**Risk Warning**: Before trading with real funds, please conduct thorough testing and risk assessment. Past performance does not guarantee future returns. Investment involves risks, and decisions should be made with caution.
|
||||
**Risk warning**: this project is not investment advice. Test thoroughly before any real-money deployment. Past performance does not guarantee future returns.
|
||||
|
||||
Reference in New Issue
Block a user