QuantRL-Lab: Instructions file for Codex

AGENTS.md

This file provides guidance to agents (i.e., ADAL) when working with code in this repository.

Essential Commands

Package Management

This project uses uv (not Poetry). The lock file is uv.lock.

uv sync                                    # Core deps only
uv sync --extra dev --extra notebooks      # With dev/notebook extras
uv sync --all-extras                       # All optional features
source .venv/bin/activate

Optional dependency groups: dev, notebooks, ml (torch/transformers/litellm), tuning, viz, storage, full.

Testing

uv run pytest -m "not integration"         # Unit tests only (CI/CD - no API keys needed)
uv run pytest -m integration               # Integration tests (requires .env with API keys)
uv run pytest tests/data/test_indicators.py  # Specific test file
uv run pytest -k "test_portfolio"          # Tests matching pattern
uv run pytest --cov=quantrl_lab            # With coverage

Code Quality (Pre-commit Hooks)

Pre-commit hooks run automatically on git commit. Run manually with:

pre-commit install                         # One-time setup
pre-commit run --all-files
pre-commit run --files path/to/file.py     # Before committing changes

Hook configuration (.pre-commit-config.yaml):

• Black: --line-length=120 --skip-string-normalization
• isort: --profile black
• flake8: --max-line-length=120
• docformatter: Google-style, --wrap-summaries=72

CRITICAL: Always verify pre-commit hooks pass after making changes. Common failures: unused imports (flake8), line length violations, missing/malformed docstrings.

Documentation

uv run mkdocs serve    # Local preview
uv run mkdocs build    # Build (always run before committing API changes)

When renaming modules or changing public APIs, update docs/api-reference/ to match actual module paths and run mkdocs build to verify.

Standalone guide tabs (top-level nav, each a self-contained reference):

• docs/DATA_SOURCES.md — data loaders, capability matrix, usage per source
• docs/data-processing.md — DataProcessor and DataPipeline with all 7 pipeline steps
• docs/environments.md — action/observation/reward spaces, all reward strategies, full env example
• docs/experiments.md — BacktestRunner, ExperimentJob, JobGenerator, AgentExplainer, OptunaRunner