# CLAUDE.md — UQO Research WP41

## CHRONOS-X: Universal Intraday Representation Learning for Probabilistic Financial Forecasting

**Project ID:** `wp41_uqo` · **Institution:** Université du Québec en Outaouais (UQO) · **PI:** Simon-Pierre Boucher
**Language:** English · **Primary data:** FinData OS, `https://findata.spboucher.ai/api/v1` (FirstRate Data, private license)
**Status:** research hypotheses, not established findings. Built autonomously on 2026-11-02 under the owner's brief
(the owner's original brief is the authoritative text; this file condenses it and records the decisions taken).

## Mission and hard rules
Build, test, benchmark, document and publish a reproducible research software package and a LaTeX working paper on one
question: can a compact, transferable, multi-resolution model learn minute-level structure and improve *calibrated*
forecasts of the next 5, 15, 30 and 60 minutes? Rules:
1. Never promise positive results, trading profits, novelty or journal acceptance. Null findings are reported.
2. Preserve every other working paper and production system in `Recherche-UQO/` and on the cluster. This directory is
   its own git repository (`origin = gitsrv:srv/git/wp41_uqo.git`).
3. No fake experiments, invented figures, invented citations or untested code. Every phase ends with
   `docs/PHASE_N_REPORT.md` (commands, artifacts, test counts, coverage, hardware, wall-clock, memory, blockers, go/no-go).
4. FinData OS is the mandatory primary source. Finnhub (or any other vendor) is optional, separate and unused unless its
   credentials, terms and history are verified and documented. Never log credentials; never commit secrets.
5. FirstRate Data private-use license: no raw bars in git, logs, figures, the manuscript or any release. Release code,
   aggregate results and synthetic fixtures only (`docs/LICENSE.md`).
6. Read `API.md`, `DATA_DICTIONARY.md`, `DISCOVERY.md` (FinData repo) and the live OpenAPI before any ingestion.
7. Do not proceed past a failed leakage, numerical or provenance gate.

## Hypotheses (falsifiable)
H1 multi-resolution history beats equal-budget 1m-only models on probabilistic scores · H2 pooled training transfers
to unseen instruments better than matched baselines · H3 history-only regime conditioning improves calibration during
regime shifts · H4 a coherent joint-path decoder improves path-level scores over independent minute marginals ·
H5 (exploratory) incremental economic information after realistic costs.

## Data conventions (verified against the live API on 2026-11-02, see docs/PHASE_0_REPORT.md)
- `timestamp_utc` = bar OPEN; the 09:30 bar is complete at 09:31. Regular XNYS session 09:30–16:00 ET: 391 bars on a
  normal day (390 + the 16:00 closing print), 211 on a 13:00 early close. Extended hours 04:00–20:00 ET are separate.
- Zero-volume minutes are absent at the source: never forward-fill silently; missingness is a feature and a mask.
- Stored bars are raw; splits are applied explicitly (`adjustment=split`); dividends are not applied to intraday
  returns (window-dependent artifact). Corporate-action policy is in `docs/DATA_CARD.md`.
- At origin t only completed bars are used; targets are log returns of completed future bars; origins whose horizon
  crosses the close are excluded for regular-hours models.

## Where things are
| Item | Location |
|---|---|
| Configs | `configs/{pilot,main,ablations,baselines,final}.yaml` |
| Code | `src/chronos_x/{data,models,train,eval,baselines,inference}` |
| Scripts | `scripts/{audit_api,build_universe,download_pilot,train_pilot,train_main,evaluate,benchmark}.py` |
| Tests | `tests/{unit,integration,leakage,synthetic,numerical}` (`pytest`; live tests need `WP41_LIVE=1`) |
| Manifests / synthetic data | `data/manifests`, `data/synthetic` (never proprietary bars) |
| Results | `results/{tables,figures,metrics,logs}` |
| Paper | `paper/main.tex`, `sections/`, `figures/`, `tables/`, `appendix/`, `references.bib` |
| Docs | `docs/{DATA_CARD,MODEL_CARD,REPRODUCIBILITY,LICENSE,OPERATIONS}.md`, `docs/PHASE_N_REPORT.md` |

## Compute
Compute node **M3U96b** (Mac Studio M3 Ultra, 28 CPU cores, 60 GPU cores, 96 GB) — `~/wp41_uqo`, venv `.venv`
(Python 3.12, PyTorch MPS). Data over the LAN from M3U96a (`FINDATA_BASE_URL=http://192.168.2.80:8600/api/v1`),
bars cache `~/wp41-cache` (outside git). Laptop = mirror and LaTeX build. See `docs/OPERATIONS.md`.