# Agents Guide — A股超短期选股工具

> 中文项目说明见 [README.md](README.md)

## Project Overview

Ultra-short-term (T+0/T+1) stock selection system for A-shares. Combines ML (LightGBM + XGBoost) for quantitative scoring with LLM (DeepSeek API) for news sentiment analysis.

## Quick Start

```bash
# Install dependencies (requires --break-system-packages on this system)
pip3 install --break-system-packages akshare pandas numpy scikit-learn lightgbm xgboost ta openai click httpx

# Run daily stock selection
python3 cli.py screen --top 10 --no-llm

# Analyze a single stock
python3 cli.py analyze -s 000001

# With LLM analysis (requires DEEPSEEK_API_KEY env var)
DEEPSEEK_API_KEY=sk_xxx python3 cli.py screen --top 10

# Clear data cache
python3 cli.py cache-clear
```

## Architecture

```
cli.py → main.py (orchestrator)
  ├── data/fetcher.py      — akshare A-share data (fallback to Sina)
  ├── data/sina_fetcher.py — Sina Finance API (primary data source)
  ├── data/cache.py        — local pickle cache (avoids rate limiting)
  ├── data/preprocessor.py — ST/limit/suspended stock filtering
  ├── features/technical.py — 47+ technical indicators (RSI, MACD, BB, ATR, OBV, etc.)
  ├── features/money_flow.py — capital flow features (main force, big/super orders)
  ├── features/market_context.py — market breadth, sector rotation
  ├── models/ensemble.py   — LightGBM (0.6) + XGBoost (0.4) weighted ensemble
  ├── llm/analyzer.py      — DeepSeek API for news sentiment + report generation
  ├── strategy/screener.py — risk gates + final ranking
  └── strategy/backtest.py — simple backtester + label generation
```

## Key Commands

| Command | What it does |
|---------|-------------|
| `python3 cli.py screen -n 10` | Run full pipeline, output top 10 with buy probability |
| `python3 cli.py screen --no-llm` | Skip LLM (faster, free) |
| `python3 cli.py screen -s` | Save results to JSON file |
| `python3 cli.py analyze -s 000001` | Analyze stock with buy probability + advice |
| `python3 cli.py tips` | Show usage tips and trading rules |
| `python3 cli.py top` | Show latest saved screening results |
| `python3 cli.py cache-clear` | Purge all cached market data |
| `python3 cli.py cache-info` | Show cache file count and sizes |

## Daily Workflow

Two runs/day: **盘前规划版** (watchlist, predicts *today*) + **盘中确认版** (real-time, predicts *tomorrow*, decision to buy). Before 9:15 the market snapshot has no trading data (opens stay at 0), so pre-market runs are identical at any pre-auction time; 9:15-9:25 captures auction data.

```
9:20       Run: python3 cli.py screen --mode pre --no-llm      (optional LLM)
9:25-9:30  Observe auction strength of planned stocks (gap, auction volume)
10:00      Run: python3 cli.py screen --mode confirm             (decision version)
10:00-10:30 Buy 2-3 stocks from top 5 (probability > 55%)
Next day   Sell: +5% take profit, -5% stop loss
```

- **Mode auto-detection**: `screen` without `--mode` detects `pre` if snapshot turnover sum is 0, else `confirm`.
- **Pre-market candidate pool**: uses the last saved intraday snapshot (auto-saved on every confirm run via `save_snapshot`) sorted by 成交额; falls back to 总市值 if no snapshot exists yet (first day).
- **Predictions**: tagged with `session: pre|confirm` in `training_data/predictions.json`; each session replaces only its own same-day record, so both coexist. Return tracking (`_track_actual_returns`) fills `actual_return` for the previous session.

## Environment

- **Python**: 3.12.3 (system, use `--break-system-packages` for pip)
- **LLM**: Set `DEEPSEEK_API_KEY` env var. Fallback: `DEEPSEEK_BASE_URL` (default: https://api.deepseek.com), `DEEPSEEK_MODEL` (default: deepseek-chat)
- **Data source**: Sina Finance (primary), akshare/东方财富 (fallback). Cache TTL: 4 hours for daily data, 1 hour for minute data
- **Models**: Saved to `saved_models/` directory. Auto-loads if present; falls back to feature-rank scoring if no trained model found

## Data Sources

- **Sina Finance**: Works from cloud servers. Used for market snapshots and K-line data.
- **akshare (东方财富)**: May be blocked from datacenter IPs. Used as fallback.
- Rate limits: ~3 req/s. Cache results to avoid hitting limits.

## Training the ML Model

The model needs historical labeled data. Use `strategy/backtest.py:generate_labels()` to create labels from historical price data, then train:

```python
from models.ensemble import EnsembleModel
model = EnsembleModel()
metrics = model.train(X, y)  # y = binary label (1 if return > 2% in N days)
model.save()  # saves to saved_models/ensemble_lgbm.txt + ensemble_xgb.json
```

Walk-forward validation available via `models.lgbm_model:WalkForwardTrainer`.

## File Structure

```
├── cli.py              # CLI entry point (click)
├── main.py             # Pipeline orchestrator
├── config.py           # Config: paths, API keys, filter thresholds
├── report.py           # HTML report generator
├── train.py            # Model training script
├── requirements.txt    # Python dependencies
├── data/
│   ├── fetcher.py      # akshare wrappers with Sina fallback
│   ├── sina_fetcher.py # Sina Finance API (primary data source)
│   ├── cache.py        # pickle-based local cache
│   └── preprocessor.py # Data cleaning/filtering
├── features/
│   ├── technical.py    # 47 technical indicators
│   ├── money_flow.py   # Capital flow features
│   └── market_context.py # Market breadth + sector features
├── models/
│   ├── lgbm_model.py   # LightGBM + walk-forward trainer
│   ├── xgb_model.py    # XGBoost wrapper
│   └── ensemble.py     # Weighted model fusion
├── llm/
│   ├── client.py       # OpenAI-compatible API client
│   └── analyzer.py     # Sentiment + limit-up analysis
├── strategy/
│   ├── screener.py     # Risk gates + ranking
│   └── backtest.py     # Backtester + label generation
├── reports/            # HTML reports (auto-created)
├── cache/              # Runtime data cache (auto-created)
├── saved_models/       # Trained model files (auto-created)
└── training_data/      # Training data cache (auto-created)
```