Aalto_MS_Thesis

Imported from nntk072/Aalto_MS_Thesis (AGENTS.md). Install upstream with npx skills add nntk072/Aalto_MS_Thesis. Copyright stays with the author.

Aalto_MS_Thesis — Agent Guide

Quantitative RL trading system. PPO/SAC agents learn entry/exit timing on US100/US500 using structure-aware features (SMT divergence, PO3 state, liquidity sweeps, FVG zones).

Build & Test

uv sync                              # install deps
python scripts/prepare_data.py       # raw CSV → parquet → features
python -m quant_rl.train.train_rl --mvp   # smoke test (30 days)

# Local (implementation): scoped checks only
uv run ruff format --check <touched paths>
uv run ruff check <touched paths>
uv run pytest <relevant test files> -q

# Agent commit/push gate — REQUIRED (do not skip)
# Format/lint/types MUST be full-tree (`.`). Never substitute path-scoped mypy/ruff.
uv run ruff format --check .    # if fails: uv run ruff format . then re-check
uv run ruff check .
uv run mypy .                   # REQUIRED full tree — not mypy <touched paths>
uv run pytest <relevant test paths> -q   # NOT tests/ -v — keep scoped

# Full suite: GitHub CI / Orchestra phase 9 only (not agent default)
# uv run pytest tests/ -v

Full rule: .agents/rules/ci-verification.md (all agents). Commit checklist: .agents/rules/git-commit-rules.md.

Orchestra (orchestra/)

Multi-model CLI pipeline (triage → plan → implement → verify). Implementer agents run scoped tests only. Phase 9 (verification) runs the full CI gate (orchestra/ci_gate.py). Agent rules: .agents/rules/ci-verification.md.

orchestra doctor          # Tier-0 health (no inference)
orchestra run "task"      # full pipeline

Architecture

data → features → envs → models → train → evaluation
              ↕           ↕
         backtest ←───────┘

Full architecture map: .agents/architecture.md Domain-level context: .agents/domain_maps/*.md

Critical Invariants (DO NOT VIOLATE)

1. Causal features only — no future data in any indicator. All HTF features use align_timeframes with forward-fill (never backward).
2. Train-only normalization — rolling_zscore fits on train_mask only. Test rows use last known training statistics.
3. Purged walk-forward — purged_walk_forward() yields non-overlapping test folds; purge = purge_bars + label_horizon, embargo before each test. Legacy overlapping stepper is purged_walk_forward_legacy (deprecated).
4. Session labels are eligibility flags — never drop bars from feature dataset based on session. filter_session is mask-only.
5. Config is single source of truth — quant_rl/config/default.yaml. All YAML keys are read via cfg.<path>. Adding a feature flag? Add YAML key first.
6. Cache versioning — FEATURE_CACHE_VERSION plus content hash (feature_cache_path / .hash sidecar). Hand-bump alone is not enough.
7. Live risk ≈ training risk — live_risk_overrides must stay aligned with ftmo dollar limits. Silent divergence is the failure mode.
8. Locked OOS is final report — do not select architectures on the locked holdout; see docs/thesis/validation_protocol.md.

Context Routing

Task → read the matching domain map in .agents/domain_maps/ first. Use code-review-graph MCP tools (query_graph_tool, get_impact_radius_tool) to narrow scope before reading source.

Rules

All process rules: .agents/rules/README.md

MCP Tools: code-review-graph

This project has a knowledge graph. Start with the code-review-graph MCP tools to narrow scope, then read the source. The graph is cheaper than scanning files and gives you structural context (callers, dependents, test coverage) that file search cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes_tool or query_graph_tool instead of Grep
• Understanding impact: get_impact_radius_tool instead of manually tracing imports
• Code review: detect_changes_tool + get_review_context_tool instead of reading entire files
• Finding relationships: query_graph_tool with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview_tool + list_communities_tool

Verify in the source

• Narrow scope with the graph, then read the source. Do not change code from graph output alone.
• For any non-trivial change, read the implementation and the relevant tests before concluding.
• Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks, recovery, or compatibility code.
• When the graph and the source disagree, the source wins. The graph may be stale or may not model that relationship.
• An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".

Key Tools

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes_tool for code review.
3. Use get_affected_flows_tool to understand impact.
4. Use query_graph_tool pattern="tests_for" to check coverage.

Triton (Aalto HPC)

GPU training on Triton: see .agents/rules/triton-slurm.md. Helpers: scripts/triton/ (status.sh, find_gpu_session.sh, attach_or_alloc.sh).

• Reuse first: if a GPU tmux/srun already exists, run train/eval/tests there (tmux send-keys).
• srun needs confirmation: agents may allocate only after you explicitly OK it in-chat. No self-started short diagnostic jobs (<~120s).
• Before alloc: check sinfo/squeue for free GPU/CPU/RAM. Prefer H200 (gpu-h200-141g-short, --gpus=h200:1) when available; else GH200 (gpu-grace-h200-141g, --gpus=gh200:1). Always 1 GPU. Time 12h if MaxTime allows, else 6h. Start mem 128G / 8 CPUs. Match venv arch (H200=x86, GH200=aarch64).
• Do not scancel when a train finishes — keep the GPU bash + tmux for the next run (unless you ask, or replacing an OOM).
• Login SSH for ls / squeue / sinfo / tmux capture-pane / inspect-only scripts/triton/*.sh; never srun for those checks.