evotraders/README.md

<p align="center">
  <img src="./docs/assets/bigtime_logo.jpg" width="45%">
</p>

<h2 align="center">大时代：自进化多智能体交易系统</h2>

<p align="center">
  📌 <a href="http://trading.evoagents.cn">Visit the 大时代 website</a>
</p>

![System Demo](./docs/assets/bigtime_demo.gif)

大时代 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.

The repository name still uses `evotraders`, but the product-facing branding now follows the 大时代 naming used by the reference branch.

---

## Core Features

**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.

**Continuous learning & Evolution**
Agents persist long-term memory with ReMe and reflect after each cycle. The **Autonomous Policy Optimizer (APO)** automatically tunes agent operational policies (`POLICY.md`) based on daily P&L feedback to correct recurring mistakes.

**Robust execution with recovery**
The trading pipeline supports **phase-based checkpointing**. If a run is interrupted, it can resume from the last successful phase (Analysis, Risk, Discussion, Decision, Execution, or Settlement), ensuring resilience in production.

**Backtest and live modes**
The same runtime model supports historical simulation and live execution with real-time market data.

**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%">
  <img src="./docs/assets/dashboard.jpg" width="45%">
</p>

---

## Current Architecture

The repository uses a **split-service runtime model** for local development and is the default supported path.

### Runtime vs Design-Time

- **runtime** — the active execution layer (scheduler, gateway, pipeline, approvals during a live run)
- **run** — one concrete execution instance (`runs/<run_id>/`)
- **design-time** — configuration and control-plane concepts before a specific runtime is launched
- **workspace** — the design-time registry exposed by `agent_service` (`workspaces/`)

### Service Surfaces

| Service | Port | Responsibility |
|---------|------|----------------|
| `backend.apps.agent_service` | `:8000` | Control plane for workspaces, agents, skills, and guard/approval APIs |
| `backend.apps.trading_service` | `:8001` | Read-only trading data APIs |
| `backend.apps.news_service` | `:8002` | Read-only explain/news APIs |
| `backend.apps.runtime_service` | `:8003` | Runtime lifecycle APIs |
| WebSocket gateway | `:8765` | Live event/feed channel for the frontend |

### Active Runtime Path

```
frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage
```

Runtime state is stored in `runs/<run_id>/` — this is the **runtime source of truth**. The `workspaces/` directory is the **design-time registry**, not the runtime execution path.

### Documentation

- [docs/README.md](./docs/README.md) — documentation index and reading order
- [docs/current-architecture.md](./docs/current-architecture.md) — canonical architecture facts
- [services/README.md](./services/README.md) — service boundaries and migration details
- [docs/current-architecture.excalidraw](./docs/current-architecture.excalidraw) — visual diagram
- [docs/development-roadmap.md](./docs/development-roadmap.md) — next-step execution plan
- [docs/terminology.md](./docs/terminology.md) — consistent terminology guide

---

## Quick Start

### 1. Install

```bash
# clone this repository, then:
cd evotraders

# install package entrypoint in editable mode
uv pip install -e .

# optional dev dependencies
# uv pip install -e ".[dev]"
```

Frontend dependencies:

```bash
cd frontend
npm ci
cd ..
```

Production deployment should prefer the checked-in Python package metadata in `pyproject.toml` for backend installation and `npm ci` for frontend so the pulled environment matches the checked-in dependency declarations and lockfiles.

### 2. Configure environment

```bash
cp env.template .env
```

The root `env.template` is the canonical local template. A `.env.example` is also kept in the repo for reference.

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

# memory (optional unless --enable-memory is used)
MEMORY_API_KEY=

# experimental: switch selected analyst / risk roles to EvoAgent
EVO_AGENT_IDS=
```

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.
- `EVO_AGENT_IDS` currently supports analyst roles plus `risk_manager` and `portfolio_manager`, and is intended for staged rollout.

### Skill Sandbox Security | 技能沙盒安全

Skill scripts can be executed in multiple sandbox modes controlled by `SKILL_SANDBOX_MODE`:

| Mode | Description | Use Case |
|------|-------------|----------|
| `none` | Direct execution, no isolation | Development only (default) |
| `docker` | Docker container isolation | Production with Docker |
| `kubernetes` | Kubernetes Pod isolation | Enterprise (reserved) |

Default configuration (development):
```bash
SKILL_SANDBOX_MODE=none
```

For production with Docker isolation:
```bash
SKILL_SANDBOX_MODE=docker
SKILL_SANDBOX_MEMORY_LIMIT=512m
SKILL_SANDBOX_CPU_LIMIT=1.0
SKILL_SANDBOX_NETWORK=none
```

When running in `none` mode, a runtime security warning is displayed on first skill execution as a reminder that scripts execute directly without isolation.

Smoke test for a specific staged EvoAgent rollout target:

```bash
python3 scripts/smoke_evo_runtime.py --agent-id fundamentals_analyst
```

This script starts a temporary runtime, verifies the gateway log contains the
selected `EvoAgent`, checks `runtime_state.json`, validates the approval wake-up
path, and then stops the runtime.

You can also include it in the local release check:

```bash
./scripts/check-prod-env.sh --smoke-evo
```

Without `EVO_AGENT_IDS`, this release check now runs
`fundamentals_analyst`, `risk_manager`, and `portfolio_manager`
smoke paths by default.

For a production-style local start flow, you can also use:

```bash
./start.sh
```

The checked-in `production` label in the deploy scripts is only an example run
label. It should not be treated as a canonical root-level runtime directory.

### 3. Start the stack

Recommended local development flow:

```bash
./start-dev.sh
```

This starts directly from the script:

- `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` via `runtime_service` managed startup

Then start the frontend in another terminal:

```bash
cd frontend && npm run dev
```

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

# then create a runtime so runtime_service can spawn the Gateway subprocess
curl -X POST http://localhost:8003/api/runtime/start \
  -H "Content-Type: application/json" \
  -d '{"launch_mode":"fresh","tickers":["AAPL","MSFT"],"mode":"live"}'
```
### 4. Run backtest or live mode

Backtest:

```bash
curl -X POST http://localhost:8003/api/runtime/start \
  -H "Content-Type: application/json" \
  -d '{"launch_mode":"fresh","mode":"backtest","tickers":["AAPL","MSFT"],"start_date":"2025-11-01","end_date":"2025-12-01"}'
```

Live:

```bash
curl -X POST http://localhost:8003/api/runtime/start \
  -H "Content-Type: application/json" \
  -d '{"launch_mode":"fresh","mode":"live","tickers":["AAPL","MSFT"]}'
```

Help:

```bash
python backend/main.py --help  # compatibility standalone entrypoint only
```
### 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
```

---

## Runtime Data Layout

- 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
- `ENABLE_DASHBOARD_COMPAT_EXPORTS=false` can disable those compatibility JSON exports in controlled environments while keeping runtime state persistence intact

Legacy root-level directories such as `live/`, `production/`, and `backtest/`
should be treated as historical compatibility artifacts, not the default runtime
location for new work.

Optional retention control:

```bash
RUNS_RETENTION_COUNT=20
```

Only timestamped run folders like `YYYYMMDD_HHMMSS` are pruned automatically. Named runs such as `live`, `smoke_fullstack`, or `reload_demo_*` are preserved.

---

## Frontend Service Routing

The frontend always uses the control plane and runtime APIs, and can optionally call split services directly for read-only data.

Useful frontend env vars:

```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
```

If these are not set, the frontend falls back to its local defaults and compatibility paths where available.

---

## Decision Flow

```text
Market data -> independent analyst work -> team communication -> portfolio decision ->
risk review -> execution/settlement -> reflection/memory update -> APO policy tuning
```

The runtime manager also tracks:

- agent registration and status
- pending approvals
- run events
- current session key

---

## Custom Configuration

### Add or change analyst roles

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:
    - multi-factor synthesis
  preferred_tools:
    - get_stock_price
    - get_company_financials
  description: |
    A generalist analyst that combines multiple signals.
```

### Configure per-agent models

Model overrides are configured in `.env`:

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

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

Run-scoped workspaces are created automatically at runtime. No manual initialization is required.

---

## Project Structure

```text
evotraders/
├── backend/
│   ├── 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
├── 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

大时代 is a research and educational project. Review the repository license before redistribution or commercial use.

**Risk warning**: this project is not investment advice. Test thoroughly before any real-money deployment. Past performance does not guarantee future returns.