Docs: runnable model tasks and verified book links

[stefan-jansen]

Outcome

A reader can run a bounded PCA forecast from the README or Quickstart with the base wheel, verify (2, 6) finite output, and follow task guides to exact generated API signatures and pinned public teaching files. The mobile documentation menu is visible at widths where Material hides tabs.

Closes #52.

Capability inventory

Supported workflow	Task guide	API reference	Executed example	Book match
PCA, RP-PCA, IPCA, CAE factor forecasts	Latent-Factor Pipelines; Latent-Factor Models	API Reference: package, configs, pipelines, contracts	latent_factor_pipeline.py; latent_factor_variants.py	Chapter 14 notebooks 04-06 teach methods manually; 09 illustrates stored case-study analysis
SDF weights and optional return projection	Stochastic Discount Factor	API Reference: SDF model, config, state, mapper	stochastic_discount_factor.py	Chapter 14 notebook 07 teaches the method manually
Direct SAE signals	Direct Asset Prediction	API Reference: SAE model, config, result	direct_asset_prediction.py	Chapter 14 notebook 08 teaches the method manually
Linear, LSTM, and DeepPortfolio allocation	Portfolio Learning	API Reference: generated signatures for all three models, configs, results	portfolio_learning.py; portfolio_neural.py	Chapter 17 notebooks 11-13 illustrate related/manual allocation methods, not library calls
Long-frame data contracts and downstream prediction frames	Data Contracts; Integration	API Reference: typed contracts and integration	integration_handoff.py	Case-study library bridge calls ml4t.models; Chapter 14 notebook 09 illustrates related analysis

The public 0.1 API has no designated experimental model family. _internal is unstable. The package does not fetch data, compute diagnostics, or simulate trades. Neural examples require deep; Parquet and Specs adapters require integration. Two-to-four-step neural smoke runs verify contracts only. Full book training and case-study registry runs need book data and longer compute.

Verification

• Built ml4t_models-0.1.4-py3-none-any.whl. Installed it into clean Python 3.12 environments under /tmp, one base and one with deep, and ran the README block, Quickstart block, and all seven repository examples from outside the source tree. All assertions passed. portfolio_learning.py also passed in the base-only environment.
• Public companion revision: d2edec54b1c7a6a9d7a97d8129eb05db4491e1eb of stefan-jansen/machine-learning-for-trading. Checked 10 distinct linked files against its Git tree and inspected notebook code for ml4t.models use. Chapter 14 teaching notebooks 04-09 and Chapter 17 notebooks 11-13 do not call the library; the case-study library_bridge.py does.
• Strict MkDocs build passed. Rendered link check resolved 4,482 local links and anchors. Reviewed home at 1440px and 390px; fixed the missing narrow-width menu.
• Ruff check and format, ty check, 423 tests, coverage gate (95.49% lines, 85.29% branches), uv build, and pre-commit run --all-files passed. Commit hook passed the same configured checks.

Review limits and follow-up

• Book notebooks and full research training were not rerun. Their data, package, and training requirements are described in the Book Guide; the small wheel examples are the executable API checks here.
• No documentation deployment or release was performed by this PR. The deployed route should be checked after merge and the next documentation publication.
• The book repository has no reciprocal link to this library's task guides. Its owner can add those links on the next book update; this PR makes the library documentation useful without them.

CI result

At public commit 39926d7703dba87204c01094102343edddcc057a, all 33 completed PR checks passed, including the cross-platform Python matrix and MPS neural qualification. Two workflow jobs were skipped by their configured conditions, including the RTX 3090 CUDA and performance job. GitHub reports the PR mergeable with a clean merge state.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.