88 lines
3.7 KiB
Markdown
88 lines
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
TradingAgentsX is a multi-agent AI trading analysis system that simulates real-world investment firm operations. It uses LangGraph to orchestrate 12 specialized AI agents (analysts, researchers, traders, risk managers) that collaborate through structured debate workflows to generate trading decisions.
|
|
|
|
**Stack**: Python 3.10+ backend (FastAPI) + Next.js 16 frontend (React 19, TypeScript)
|
|
|
|
## Build & Run Commands
|
|
|
|
### Backend (FastAPI)
|
|
```bash
|
|
pip install -e . # Install package in editable mode
|
|
pip install -r backend/requirements.txt # Install backend dependencies
|
|
python -m backend # Run server (default: localhost:8000)
|
|
python -m backend --host 0.0.0.0 --port 8000 --reload true # With options
|
|
```
|
|
|
|
### Frontend (Next.js)
|
|
```bash
|
|
bun install --cwd frontend # Install dependencies
|
|
bun run --cwd frontend dev # Development server (localhost:3000)
|
|
bun run --cwd frontend build # Production build
|
|
bun run --cwd frontend lint # ESLint
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### CLI
|
|
```bash
|
|
tradingagents <commands> # After pip install -e .
|
|
python main.py # Standalone analysis
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Agent System (`tradingagents/`)
|
|
- **12 AI agents** organized into teams using LangGraph orchestration
|
|
- `agents/analysts/` - Market, News, Social Media, Fundamentals analysts
|
|
- `agents/researchers/` - Bull & Bear case researchers + Research Manager
|
|
- `agents/risk_mgmt/` - Aggressive, Conservative, Neutral debaters + Risk Manager
|
|
- `agents/trader/` - Final trading decision aggregator
|
|
- `graph/trading_graph.py` - Main `TradingAgentsXGraph` class orchestrating the workflow
|
|
- `dataflows/` - Data vendor integrations (Yahoo Finance, Alpha Vantage, FinMind, Google News, Reddit)
|
|
|
|
### Backend (`backend/`)
|
|
- `app/main.py` - FastAPI app with security middleware (rate limiting 30/min, security headers)
|
|
- `app/api/routes.py` - `/api/analyze`, `/api/task/{id}`, `/api/chat`, `/api/download`
|
|
- `app/api/auth.py` - Google OAuth flow
|
|
- `app/services/trading_service.py` - Orchestrates agent graph execution
|
|
- `app/services/task_manager.py` - Async task lifecycle
|
|
- `app/services/pdf_generator.py` - Report generation (complex, 61KB)
|
|
|
|
### Frontend (`frontend/`)
|
|
- `app/` - Next.js App Router pages (analysis, history, auth)
|
|
- `components/AgentFlowDiagram.tsx` - 12-agent visualization
|
|
- `lib/crypto.ts` - AES-GCM encryption for API keys (BYOK model)
|
|
- `lib/reports-db.ts` - IndexedDB wrapper for local report storage
|
|
- `contexts/` - AuthContext, LanguageContext
|
|
|
|
## Key Entry Points
|
|
|
|
- **Backend**: `python -m backend` → `backend/__main__.py` → `backend/app/main.py`
|
|
- **Frontend**: `bun run dev` → `frontend/app/layout.tsx` → `frontend/app/page.tsx`
|
|
- **Core Logic**: `TradingAgentsXGraph.propagate(ticker, date)` in `tradingagents/graph/trading_graph.py`
|
|
|
|
## Environment Variables
|
|
|
|
Required in `.env` (see `.env.example`):
|
|
- LLM API keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc.
|
|
- Data APIs: `ALPHA_VANTAGE_API_KEY`, `FINMIND_API_KEY`
|
|
- Auth: `JWT_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
|
|
- Config: `NEXT_PUBLIC_API_URL`, `CORS_ORIGINS`, `FRONTEND_URL`
|
|
|
|
## Key Dependencies
|
|
|
|
- **Agent Framework**: LangGraph 0.4.8+, LangChain 0.1.0+
|
|
- **LLM Providers**: langchain-openai, langchain-anthropic, langchain-google-genai
|
|
- **Data**: yfinance, pandas, polars, ChromaDB (vector store)
|
|
- **Backend**: FastAPI, SQLAlchemy 2.0+, Redis, asyncpg
|
|
- **Frontend**: Next.js 16, React 19, Tailwind CSS 4, shadcn/ui, Dexie.js (IndexedDB)
|