NewQuant/AGENTS.md

AGENTS.md - Quant Trading Project Guidelines

This document provides guidelines for agentic coding agents operating in this repository.

对话语言规则 (Conversation Language Rules)

• 请始终使用简体中文进行回复，除非我明确要求使用其他语言。
• 涉及编程术语时，请保留英文原文并（在必要时）提供中文解释。

Project Overview

Python-based quantitative trading system with:

• Backtesting engine (src/backtest_engine.py)
• Multiple strategy implementations (src/strategies/)
• TQSdk integration for real-time trading (src/tqsdk_engine.py, src/tqsdk_real_engine.py)
• Strategy management (strategy_manager/)
• Data processing and analysis (src/analysis/)

Build, Lint, and Test Commands

Python Environment

# Install dependencies
pip install -r requirements.txt

# Run single test file
pytest test/test_file.py -v

# Run single test function
pytest test/test_file.py::TestClass::test_function -v

# Run tests with coverage
pytest --cov=src --cov-report=term-missing

# Run tests matching pattern
pytest -k "test_name_pattern"

Jupyter Notebooks

Several research notebooks exist in root directory:

• main.ipynb, main2.ipynb, main_multi.ipynb
• grid_search.ipynb, grid_search_multi_process.ipynb
• tqsdk_main.ipynb, tqsdk_main2.ipynb

Run via Jupyter Lab:

jupyter lab

Strategy Manager (Web Backend)

cd strategy_manager && python start.py

Code Style Guidelines

Imports

• Use absolute imports from src package:

  from src.backtest_engine import BacktestEngine
  from src.strategies.base_strategy import Strategy
  

• Group imports: standard library → third-party → local modules
• Use TYPE_CHECKING for circular import avoidance with type hints:

  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from src.core_data import Order
  

Naming Conventions

• Classes: PascalCase (BacktestEngine, SimpleLimitBuyStrategy)
• Functions/Variables: snake_case (get_current_positions, send_order)
• Constants: UPPER_SNAKE_CASE (BEIJING_TZ, TRADING_SESSIONS_TIMES)
• Private members: Leading underscore (_indicator_cache, _clean_params_for_hashing)

Type Annotations

• Use Python's typing module for type hints
• Common patterns:

  from typing import Dict, Any, Optional, List, Union
  def func(param: Dict[str, Any]) -> Optional[float]:
  

• Use string annotations for forward references when needed:

  def send_order(self, order: "Order") -> Optional[Order]:
  

Error Handling

• Use specific exception types, not bare except:
• Log errors with context:

  try:
      # operation
  except Exception as e:
      self.log(f"Operation failed: {e}")
  

• Raise descriptive exceptions:

  raise ValueError("Step direction inconsistent with range")
  

Docstrings and Comments

• Use Chinese for comments and docstrings (project convention)
• Document public methods with Args/Returns sections:

  def generate_parameter_range(start, end, step):
      """
      根据开始、结束和步长生成参数值列表。
  
      Args:
          start: 参数范围的起始值
          end: 参数范围的结束值
          step: 参数的步长
  
      Returns:
          生成的参数值列表
      """
  

Code Formatting

• No strict formatting rules (no ruff/black config found)
• Follow Python PEP 8 generally
• Maximum line length: 120 characters recommended
• Use 4 spaces for indentation

Project-Specific Patterns

Strategy Implementation

All strategies inherit from Strategy ABC:

from src.strategies.base_strategy import Strategy

class MyStrategy(Strategy):
    def on_open_bar(self, open: float, symbol: str):
        # Implement strategy logic
        pass

Backtest Context

Strategies interact with BacktestContext for:

• Order management (send_order, cancel_order)
• Position tracking (get_current_positions)
• Historical data (get_price_history, get_bar_history)

Trading Sessions

Define trading hours in src/common_utils.py:

TRADING_SESSIONS_TIMES: List[Tuple[time, time]] = [
    (time(9, 0, 0), time(11, 30, 0)),
    (time(13, 30, 0), time(15, 0, 0)),
    (time(21, 0, 0), time(23, 0, 0))
]

File Organization

NewQuant/
├── src/                    # Core codebase
│   ├── strategies/         # Strategy implementations
│   ├── analysis/           # Result analysis tools
│   ├── indicators/         # Technical indicators
│   └── *.py               # Engine and utility modules
├── futures_trading_strategies/  # Additional strategies by commodity
├── strategy_manager/       # Web backend and launcher
├── test/                   # Tests (Jupyter notebooks)
├── data/                   # Data files
└── *.ipynb                # Research notebooks

Key Files for Reference

• src/strategies/base_strategy.py - Strategy interface definition
• src/backtest_engine.py - Backtesting core
• src/common_utils.py - Utility functions and constants
• strategy_manager/start.py - Web service entry point