Finance Algorithms is a Python 3.13 research workspace with two related parts:
invest_algorithms/: the legacy FastAPI service for arithmetic and geometric investment-pyramid order sizing.quantlab/: a portfolio-grade personal quant research lab with point-in-time data, vectorized backtesting, strategy comparison, local result tracking, and portfolio construction experiments.
The current product direction is tracked under .agents/specs/, with SPECS.md as the stable registry and NEXT_STEPS.md as the rolling handoff memo.
| Doc | Path | Audience |
|---|---|---|
| User manual (EN / 繁中) | docs/manual/{en,zh-tw}/index.html |
Operators, researchers |
| Executive review | docs/review/index.html |
Stakeholders |
| Feature catalog | docs/FEATURES.md |
Everyone |
| Traceability bridge | .agents/specs/RTM.md |
Verification context |
Regeneration steps live in docs/MANUAL_GENERATION_GUIDE.md and
docs/REVIEW_GENERATION_GUIDE.md. Readiness claims in these docs are copied from
.agents/specs/**/review.md; every model slice carries an explicit
no_alpha_claim boundary.
Software source code is licensed under the Apache License 2.0. See LICENSE.
Original project documentation, manuals, review pages, and portfolio materials
are licensed under CC BY 4.0. See LICENSE-DOCS.md.
Third-party dependencies, market data, reconstructed historical data, point-in-time
snapshots, trademarks, external media, and private credentials are not licensed by
this repository unless a file explicitly says otherwise. See NOTICE.
| Path | Purpose |
|---|---|
invest_algorithms/ |
Existing pyramid-calculation API and CSV output flow. Treat as the stable legacy baseline. |
quantlab/contracts/ |
Protocols and generated Pydantic models used by the backtest foundation. |
quantlab/data/ |
Point-in-time data providers, fixtures, and vintage snapshot loading. Must stay framework-agnostic. |
quantlab/engine/ |
Vectorized backtest engine, metrics, and walk-forward logic. Must stay framework-agnostic. |
quantlab/strategies/ |
Baselines, hedge strategy, buy-and-hold, and ML strategy adapters. |
quantlab/portfolio/ |
Portfolio optimization and pyramid-entry adapter work from Epic C. |
quantlab/tracking/ |
Local result store and leaderboard support. |
scripts/ |
Reproducible demos and daily vintage data capture. |
data/vintage/raw/ |
Append-only daily point-in-time snapshots. |
tests/ |
Legacy API tests plus QuantLab spec tests and governance guards. |
.agents/specs/ |
SDD artifacts, reviews, tasks, change requests, and program planning. |
This repo uses uv and Python 3.13.
uv syncIf you are using an already-created virtualenv, the same commands below can be run through uv run without manually activating it.
The FastAPI app lives in invest_algorithms/api.py. Because that module uses legacy top-level imports, run Uvicorn from inside invest_algorithms/:
cd invest_algorithms
uv run uvicorn api:app --host 127.0.0.1 --port 2224Useful environment variables:
| Variable | Default | Purpose |
|---|---|---|
API_HOST |
127.0.0.1 |
Host reported by the root endpoint. |
API_PORT |
2224 |
Port reported by the root endpoint. |
API_CORS_ORIGINS |
empty | Comma-separated CORS allowlist. |
GLOBAL_LOG_LEVEL |
INFO |
Python logging level. |
Main endpoints:
GET /api/pyramidArithmeticGET /api/pyramidGeometric
Both endpoints accept budget, price range, transaction count, minimum unit, sizing parameter, initial unit, and toCsv.
Run the synthetic TSMC hedge slice:
uv run python scripts/run_tsmc_hedge_slice.pyInspect vintage data readiness and run the real-data OOS-net demo. Accumulated
vintage data is now sufficient, so the SP500 market-index slice runs a computed
candidate-vs-baseline comparison (fail-closed to insufficient_data / exit 2 on
thin, degenerate, or sampling-oversampled universes; no_alpha_claim throughout):
uv run python scripts/run_vintage_slice.py
uv run python scripts/run_real_data_oos_backtest.py # SP500 index OOS-net comparisonEpic H adds a deep-learning research lab: a framework-free deterministic reference
MLP forecaster with a multi-framework backend registry (slice H-1) and a real PyTorch
training path (slice H-2, scripts/run_dl_experiment.py --backend pytorch) that degrades
honestly to the reference backend when torch is absent. Slice H-3
(h-interactive-research-ui) adds an interactive parameter UI over those H artifacts on the
showcase dashboard — a deterministic static_replay model-vs-baseline leaderboard with
OOS-net-only ranking, approximate-data warnings, and fail-closed behavior on unsupported
parameters or stale checksums. Slice H-4 (h-live-rerun-api) adds a real Python ASGI
live-rerun backend (live_compute mode) over that UI — validated-parameter recompute via
run_experiment, an honest static-replay fallback, a 5-state async lifecycle, and a charter
guard against any actionable-signal surface (Implemented · Review PASSED; deployed to
the hosted demo on 2026-06-21). Frameworks stay behind
quantlab/models/dl/ (import-linter enforced); torch is an optional lane kept out of the
default lock; everything is no_alpha_claim.
A deep historical backfill (CR-B21) extends the research vintage back to 1990,
so approximate_availability=True runs can span multiple business cycles
(dot-com, GFC, COVID, 2022). It is explicitly is_approximate=true research data
(NOT true point-in-time) and is excluded by strict PIT mode; no_alpha_claim
throughout:
uv run python scripts/backfill_history.py --since 1990-01-01 # idempotent; marks approximateCapture today's append-only point-in-time snapshot:
uv run python scripts/daily_snapshot.pyPreview snapshot jobs without writing files:
uv run python scripts/daily_snapshot.py --dry-runCanonical test command:
uv run pytest -qType-check the QuantLab package:
uv run mypy quantlab/ --ignore-missing-importsCheck architecture contracts:
uv run lint-importsThe import-linter contract enforces that quantlab.engine and quantlab.data do not depend on torch, tensorflow, jax, or flax.
The implemented QuantLab foundation includes:
- A0 backtest foundation: contracts, PIT data provider, vectorized engine, metrics, walk-forward, parallel execution, and local tracking.
- Epic A TSMC hedge slice: hedge strategy, LSTM adapter, baselines, and leaderboard writeup.
- Epic B data platform: vintage snapshot loader, FRED price proxies, as-of alignment, and
pit_strictness. - Epic C portfolio core: optimizer, multi-period allocation, regime rebalance selector, pyramid-entry adapter, and integration leaderboard.
- Epic D model families: PIT-safe deterministic regime signal, return/risk forecaster, robust optimizer, and family evaluator — OOS-net baseline comparison with a no-alpha claim boundary.
- Epic E MLOps-lite: experiment registry, config catalog, checksum snapshot durability, registry→dashboard bridge, and a Tier3 readiness gate (local smoke evidence; production-tier proof fails closed without externally-proven serving/retraining/drift URIs).
- Epic F showcase dashboard: ShowcaseReadAPI + Next.js static export, browser-visual diff, and a public-hosting probe — a canonical local result-store scenario (
local_demo_only), not a live backend service. - Epic G alt-data slices: source-contract-first local CSV loader, two optional default-disabled slices.
- Epic H deep-learning research lab: framework-free reference MLP forecaster (H-1), a real PyTorch training path behind a lazy backend boundary (H-2), and an interactive parameter UI over the H artifacts on the dashboard — deterministic
static_replay, OOS-net-only ranking, fail-closed on unsupported parameters or stale checksums (H-3), and a real Python ASGI live-rerun backend (live_compute) over that UI (H-4, Review PASSED; deployed 2026-06-21).
Every slice declares no_alpha_claim. See .agents/specs/SPECS.md and .agents/specs/NEXT_STEPS.md before starting new feature work.