ml4t-coursework 0.2.0__tar.gz

ml4t_coursework-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "release/**", "fix/**"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  OMP_NUM_THREADS: "1"
+  OPENBLAS_NUM_THREADS: "1"
+  MKL_NUM_THREADS: "1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.10.9"
+      - run: uv python install 3.14
+      - run: uv sync --python 3.14 --all-extras --locked
+      - run: uv run ruff check --isolated --select E4,E7,E9,F src tests
+
+  qualify:
+    name: Qualify (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.10.9"
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --python python --all-extras --locked
+      - name: Import package and data extra
+        run: >-
+          uv run --no-sync python -c
+          "import ml4t_coursework, yfinance; from ml4t_coursework import data;
+          assert data.fingerprint().shape == (100, 6)"
+      - run: uv run --no-sync pytest -q
+      - run: uv build --python python
+      - name: Install built wheel with data extra
+        shell: bash
+        run: |
+          uv venv --python python .artifact-venv
+          wheel="$(find dist -name '*.whl' -print -quit)"
+          uv pip install --python .artifact-venv "${wheel}[data]"
+          uv run --python .artifact-venv --no-project python -c \
+            "import ml4t_coursework, yfinance; from ml4t_coursework import data; assert data.fingerprint().shape == (100, 6)"
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [lint, qualify]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.10.9"
+      - run: uv python install 3.12
+      - run: uv sync --python 3.12 --all-extras --locked
+      - run: uv build --python 3.12
+      - run: uv run twine check dist/*
+      - name: Validate release version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: >-
+          uv run python -c
+          "import os; from ml4t_coursework import __version__;
+          tag=os.environ['GITHUB_REF_NAME'];
+          assert tag == f'v{__version__}', f'{tag} does not match v{__version__}'"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/

ml4t_coursework-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  qualification:
+    name: Qualify Release
+    permissions:
+      contents: read
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: qualification
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: publish
+    permissions:
+      contents: write
+    steps:
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: gh release create "${GITHUB_REF_NAME}" --generate-notes --verify-tag

ml4t_coursework-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/

ml4t_coursework-0.2.0/DATASET.md

@@ -0,0 +1,66 @@
+# The course price panel
+
+`etf_close.parquet`: split- and dividend-adjusted daily closing prices for 100 ETFs, 5,031
+sessions from 2006-01-03 to 2025-12-31, a wide frame indexed by date with one column per symbol.
+More than one ML4T course reads it, which is why the machinery that fetches and checks it lives
+here rather than inside either of them.
+
+**The file is not in any repository, and you fetch it once.** The price history is licensed and we
+are not permitted to redistribute it. Everything else - the symbol list, the window, the code that
+fetches it, and a fingerprint you can check your copy against - is in this package.
+
+In a notebook:
+
+```python
+from ml4t_coursework import data
+
+data.download()
+```
+
+It writes into your project folder and needs no path. From a shell, in a checkout with no Colab
+around it:
+
+```bash
+uv run --with "ml4t-coursework[data]" python -m ml4t_coursework.data --out data/etf_close.parquet
+```
+
+Either way it takes a minute or two, then compares your copy against the packaged fingerprint and
+tells you whether it is sound. Do this once. No unit notebook downloads anything, and none of them
+will run until the file is there.
+
+## Will your numbers match ours?
+
+Close enough that it does not matter, and here is the measurement rather than the reassurance.
+
+Adjusted prices are revised. Every dividend and every split restates the entire history behind it,
+so a series downloaded next year is not the same series of numbers as one downloaded today. That
+sounds worse than it is: the revision is a *constant factor* applied to the whole series, and a
+constant factor cancels out of every return. The courses compute on returns and on cross-sectional
+ranks, so they do not see the factor at all.
+
+Checked on 2026-08-17, a fresh download of all 100 symbols matched the copy the slides were
+computed on, session for session. Fifty-eight symbols were identical; the rest differed by a single
+scale factor, the largest of them 1.7%. The largest disagreement in any daily return anywhere in
+the panel was 0.000003.
+
+So expect your results to match the slides to three or four decimal places, and expect the fourth
+to move as time passes and revisions accumulate. If a unit reports an information coefficient of
+0.0164 and you get 0.0161, nothing has gone wrong and there is nothing to debug. What the course is
+teaching you to do is run the process and read the result correctly; a difference in the fourth
+decimal is not a difference in the answer.
+
+What would be worth investigating is a symbol missing entirely, a session count off by more than a
+few, or a volatility more than 1% away from the fingerprint. Those are delistings, ticker reuse and
+bad bars rather than revisions, and `data.check()` flags them by name.
+
+## Why there is no "exact reconstruction" file
+
+We considered shipping the adjustment factors so you could transform a fresh download back into the
+exact series behind the slides. Once the measurement above was in hand it stopped being worth
+doing: the factor is one number per symbol, it cancels in returns, and applying it would change no
+result you compute. A mechanism that reproduces the fourth decimal place of a number whose third
+decimal is already immaterial is complexity without a payoff.
+
+The fingerprint is deliberately one-way. It carries per-symbol session counts, dates, annualized
+volatility and average daily move - enough to tell you your download is sound, not enough to
+rebuild prices we are not allowed to hand you.

ml4t_coursework-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Jansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ml4t_coursework-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: ml4t-coursework
+Version: 0.2.0
+Summary: Project folder, component conformance checks and results log for the ML4T courses
+Project-URL: Homepage, https://github.com/ml4t/coursework
+Project-URL: Repository, https://github.com/ml4t/coursework
+Project-URL: Issues, https://github.com/ml4t/coursework/issues
+Project-URL: Changelog, https://github.com/ml4t/coursework/releases
+Author: Stefan Jansen
+License: MIT
+License-File: LICENSE
+Keywords: backtesting,education,finance,machine-learning,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: scikit-learn>=1.3
+Provides-Extra: data
+Requires-Dist: yfinance>=0.2.40; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.16.6; extra == 'dev'
+Requires-Dist: twine==7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ml4t-coursework
+
+**Support package for the ML for Trading courses.** It is the plumbing their notebooks run on: the
+student's project folder, the conformance checks that run when they save a piece of the pipeline
+they have written, the results log the closing unit reads, and the report they submit. It is named
+for what it holds rather than for a course, because more than one course installs it.
+
+It is published here so that the first cell of a notebook on a free Colab runtime can be
+
+```python
+!pip install -q "ml4t-coursework[data]"
+```
+
+with no account, no credential and no repository to clone. That is the whole reason it is on PyPI.
+
+It also owns the course price panel: the symbol list, the window, the one-time fetch and a one-way
+fingerprint to check a download against. [The dataset note](https://github.com/ml4t/coursework/blob/main/DATASET.md)
+explains what that panel is and why a fresh download differs from the slides in the fourth decimal
+place. More than one course reads it, which is why the machinery is here rather than inside either
+of them.
+
+**This package is not the course.** The video, the reading, the exercises, the checks for
+understanding and the market data all live elsewhere. What is here is useful mainly to someone
+enrolled; it is installable by anyone, and it will not teach you anything on its own.
+
+## What it does
+
+A notebook opens by saying which course it belongs to. That is what decides the project folder on
+the student's Drive and which stage names their results rows may carry, so two courses on one Drive
+never write over each other:
+
+```python
+import ml4t_coursework as mlc
+mlc.use("foundations")
+
+from ml4t_coursework import save_component, load_component, append_result, report
+```
+
+- **`save_component(name, obj)`** runs the component's contract test, prints what passed and what
+  did not, stamps the verdict, and writes the student's own source to their project folder.
+- **`load_component(name)`** returns their implementation when it is conformant and the shipped
+  reference when it is not, and always says which. A wrong Part 4 does not block Part 7.
+- **`append_result(row)`** appends one row per pipeline run. The final unit reads three of them
+  against each other and they are written weeks apart, so what persists is the numbers.
+- **`report(answers)`** writes the submission report: every component's verdict, the results rows,
+  and the written answers.
+
+`status()` shows where every component stands; `contract(name).describe()` shows what any one of
+them has to satisfy; `catalog()` lists them all.
+
+A course adds its own components and its own stage names without a change here:
+
+```python
+from ml4t_coursework import Course, register_course, add_source
+
+register_course(Course(key="...", title="...", folder="ml4t-...", env_var="ML4T_..._HOME",
+                       stages=("...",), terminal_stages=("...",)))
+add_source("your_package.components")   # every module in it registers one contract
+```
+
+## How the checks work, and what they deliberately do not do
+
+Each component carries a contract asserting **properties, never equality with a reference output**.
+Two correct fold splitters legitimately differ, and an equality check would fail correct work and
+teach the student to copy. Every contract runs the same four gating checks - interface, a leakage
+probe, determinism, and the component's own domain invariants - plus a reference delta that is
+reported and never enforced.
+
+A component is validated on **its source re-executed in an empty namespace**, not on the object in
+memory, because what a later notebook loads on a cold session is the file. Something that only
+works because of another cell in the same session fails at save time, with a message naming the
+missing symbol.
+
+Reference implementations ship with the package. That is by design rather than an oversight:
+the fallback is what stops one wrong component from blocking the rest of the course, so there is
+nothing here that could be leaked.
+
+## Data
+
+The course's price panel is not distributed with this package and is not ours to redistribute. What
+ships is everything else - the symbol list, the window, the fetch, and a one-way fingerprint to
+check a download against:
+
+```python
+from ml4t_coursework import data
+data.download()     # once, into the project folder
+data.load()         # what every notebook reads
+```
+
+## Licence
+
+MIT, in line with the other `ml4t-*` libraries. See `LICENSE`.

ml4t_coursework-0.2.0/README.md

@@ -0,0 +1,92 @@
+# ml4t-coursework
+
+**Support package for the ML for Trading courses.** It is the plumbing their notebooks run on: the
+student's project folder, the conformance checks that run when they save a piece of the pipeline
+they have written, the results log the closing unit reads, and the report they submit. It is named
+for what it holds rather than for a course, because more than one course installs it.
+
+It is published here so that the first cell of a notebook on a free Colab runtime can be
+
+```python
+!pip install -q "ml4t-coursework[data]"
+```
+
+with no account, no credential and no repository to clone. That is the whole reason it is on PyPI.
+
+It also owns the course price panel: the symbol list, the window, the one-time fetch and a one-way
+fingerprint to check a download against. [The dataset note](https://github.com/ml4t/coursework/blob/main/DATASET.md)
+explains what that panel is and why a fresh download differs from the slides in the fourth decimal
+place. More than one course reads it, which is why the machinery is here rather than inside either
+of them.
+
+**This package is not the course.** The video, the reading, the exercises, the checks for
+understanding and the market data all live elsewhere. What is here is useful mainly to someone
+enrolled; it is installable by anyone, and it will not teach you anything on its own.
+
+## What it does
+
+A notebook opens by saying which course it belongs to. That is what decides the project folder on
+the student's Drive and which stage names their results rows may carry, so two courses on one Drive
+never write over each other:
+
+```python
+import ml4t_coursework as mlc
+mlc.use("foundations")
+
+from ml4t_coursework import save_component, load_component, append_result, report
+```
+
+- **`save_component(name, obj)`** runs the component's contract test, prints what passed and what
+  did not, stamps the verdict, and writes the student's own source to their project folder.
+- **`load_component(name)`** returns their implementation when it is conformant and the shipped
+  reference when it is not, and always says which. A wrong Part 4 does not block Part 7.
+- **`append_result(row)`** appends one row per pipeline run. The final unit reads three of them
+  against each other and they are written weeks apart, so what persists is the numbers.
+- **`report(answers)`** writes the submission report: every component's verdict, the results rows,
+  and the written answers.
+
+`status()` shows where every component stands; `contract(name).describe()` shows what any one of
+them has to satisfy; `catalog()` lists them all.
+
+A course adds its own components and its own stage names without a change here:
+
+```python
+from ml4t_coursework import Course, register_course, add_source
+
+register_course(Course(key="...", title="...", folder="ml4t-...", env_var="ML4T_..._HOME",
+                       stages=("...",), terminal_stages=("...",)))
+add_source("your_package.components")   # every module in it registers one contract
+```
+
+## How the checks work, and what they deliberately do not do
+
+Each component carries a contract asserting **properties, never equality with a reference output**.
+Two correct fold splitters legitimately differ, and an equality check would fail correct work and
+teach the student to copy. Every contract runs the same four gating checks - interface, a leakage
+probe, determinism, and the component's own domain invariants - plus a reference delta that is
+reported and never enforced.
+
+A component is validated on **its source re-executed in an empty namespace**, not on the object in
+memory, because what a later notebook loads on a cold session is the file. Something that only
+works because of another cell in the same session fails at save time, with a message naming the
+missing symbol.
+
+Reference implementations ship with the package. That is by design rather than an oversight:
+the fallback is what stops one wrong component from blocking the rest of the course, so there is
+nothing here that could be leaked.
+
+## Data
+
+The course's price panel is not distributed with this package and is not ours to redistribute. What
+ships is everything else - the symbol list, the window, the fetch, and a one-way fingerprint to
+check a download against:
+
+```python
+from ml4t_coursework import data
+data.download()     # once, into the project folder
+data.load()         # what every notebook reads
+```
+
+## Licence
+
+MIT, in line with the other `ml4t-*` libraries. See `LICENSE`.

ml4t_coursework-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ml4t-coursework"
+version = "0.2.0"
+description = "Project folder, component conformance checks and results log for the ML4T courses"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Stefan Jansen" }]
+keywords = ["trading", "machine-learning", "finance", "backtesting", "education"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.24", "pandas>=2.2", "pyarrow>=14.0", "scikit-learn>=1.3"]
+
+[project.urls]
+Homepage = "https://github.com/ml4t/coursework"
+Repository = "https://github.com/ml4t/coursework"
+Issues = "https://github.com/ml4t/coursework/issues"
+Changelog = "https://github.com/ml4t/coursework/releases"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff==0.16.6", "twine==7.0.0"]
+data = ["yfinance>=0.2.40"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ml4t_coursework"]
+artifacts = ["src/ml4t_coursework/data/*.csv", "src/ml4t_coursework/py.typed"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/.workspace", "/publish.sh"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ml4t_coursework-0.2.0/src/ml4t_coursework/__init__.py

@@ -0,0 +1,29 @@
+"""The plumbing every ML4T course notebook runs on.
+
+    !pip install -q ml4t-coursework
+    import ml4t_coursework as mlc
+    mlc.use("foundations")
+
+    from ml4t_coursework import save_component, load_component, append_result, report
+
+The package holds the student's project folder, the components they write and the contracts those
+are checked against, their results log and their submission report. It is named for what it does
+rather than for a course, because more than one course installs it.
+"""
+
+__version__ = "0.2.0"
+
+from .components import catalog, load_component, save_component, source_of, status
+from .contracts import add_source
+from .contracts import get as contract
+from .course import Course, active_course, register_course, use
+from .project import describe, home, setup
+from .report import report
+from .results import append_result, latest, results
+
+__all__ = [
+    "save_component", "load_component", "append_result", "report",
+    "setup", "home", "describe", "status", "catalog", "contract", "results", "latest",
+    "source_of", "use", "Course", "register_course", "active_course", "add_source",
+    "__version__",
+]