diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 49d6795..a64bfbd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,13 +7,22 @@ on: branches: [main] workflow_dispatch: workflow_call: + inputs: + release_version: + description: Exact version to embed in a release candidate + required: false + type: string -env: - PYTHON_VERSION: "3.12" +permissions: + contents: read concurrency: group: ci-${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true + cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }} + +env: + PYTHON_VERSION: "3.12" + UV_VERSION: "0.10.9" jobs: lint: @@ -21,43 +30,28 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 with: - version: "0.10.9" - - - name: Set up Python - run: uv python install ${{ env.PYTHON_VERSION }} - - - name: Install dependencies - run: uv sync --python ${{ env.PYTHON_VERSION }} --dev - - - name: Run ruff check - run: uv run ruff check src/ tests/ - - - name: Run ruff format check - run: uv run ruff format --check src/ tests/ + version: ${{ env.UV_VERSION }} + - run: uv python install ${{ env.PYTHON_VERSION }} + - run: uv sync --python ${{ env.PYTHON_VERSION }} --dev + - name: Run Ruff lint + run: uv run ruff check src/ tests/ examples/ scripts/ + - name: Run Ruff format check + run: uv run ruff format --check src/ tests/ examples/ scripts/ typecheck: name: Type Check runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 with: - version: "0.10.9" - + version: ${{ env.UV_VERSION }} - name: Set up Python run: uv python install ${{ env.PYTHON_VERSION }} - - name: Install dependencies - run: >- - uv sync --python ${{ env.PYTHON_VERSION }} --dev - --extra store --extra viz - + run: uv sync --python ${{ env.PYTHON_VERSION }} --dev --extra store --extra viz - name: Run ty check run: uv run --no-sync ty check @@ -66,83 +60,153 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 with: - version: "0.10.9" - + version: ${{ env.UV_VERSION }} - name: Set up Python run: uv python install ${{ env.PYTHON_VERSION }} - - name: Export locked environments run: | uv export --locked --no-dev --no-emit-project --no-hashes \ --output-file "${{ runner.temp }}/core.txt" uv export --locked --all-extras --all-groups --no-emit-project --no-hashes \ --output-file "${{ runner.temp }}/complete.txt" + - name: Audit runtime and contributor environments + run: | + uv run --with pip-audit python -m pip_audit \ + --requirement "${{ runner.temp }}/core.txt" --progress-spinner off + uv run --with pip-audit python -m pip_audit \ + --requirement "${{ runner.temp }}/complete.txt" --progress-spinner off + + coverage: + name: Coverage + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + version: ${{ env.UV_VERSION }} + - name: Set up Python + run: uv python install ${{ env.PYTHON_VERSION }} + - name: Install dependencies + run: uv sync --python ${{ env.PYTHON_VERSION }} --dev --extra ta --extra store --extra viz + - name: Measure line and branch coverage + env: + NUMBA_DISABLE_JIT: "1" + run: >- + uv run pytest tests/ -q --cov-report= + --cov-report=json:coverage.json --cov-report=term:skip-covered + - name: Enforce release thresholds + run: uv run python scripts/check_coverage.py coverage.json - - name: Audit locked environments + documentation: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + version: ${{ env.UV_VERSION }} + - run: uv python install ${{ env.PYTHON_VERSION }} + - run: uv sync --python ${{ env.PYTHON_VERSION }} --dev --extra docs + - name: Run documented workflows + run: uv run python tests/documentation_workflows.py + - name: Check every README link + run: uv run python scripts/ci/check_readme_links.py README.md + - name: Build strict documentation + run: uv run mkdocs build --strict + + build-candidate: + name: Build Candidate + runs-on: ubuntu-latest + needs: [lint, typecheck, security, coverage, documentation] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + version: ${{ env.UV_VERSION }} + - run: uv python install ${{ env.PYTHON_VERSION }} + - run: uv sync --python ${{ env.PYTHON_VERSION }} --dev + - name: Set release candidate version + if: ${{ inputs.release_version != '' }} + env: + RELEASE_VERSION: ${{ inputs.release_version }} + run: echo "SETUPTOOLS_SCM_PRETEND_VERSION=$RELEASE_VERSION" >> "$GITHUB_ENV" + - name: Build source and wheel artifacts once + run: uv build --out-dir candidate/dist + - name: Record candidate commit, tree, version, and SHA256 digests + run: >- + uv run python scripts/ci/candidate.py create candidate + --commit-sha "${{ github.sha }}" + --git-tree "$(git rev-parse HEAD^{tree})" + - name: Validate artifact metadata and manifest run: | - uv run pip-audit --requirement "${{ runner.temp }}/core.txt" - uv run pip-audit --requirement "${{ runner.temp }}/complete.txt" + uv run twine check candidate/dist/* + uv run python scripts/ci/candidate.py verify candidate \ + --expected-commit "${{ github.sha }}" \ + --expected-tree "$(git rev-parse HEAD^{tree})" + - name: Upload release candidate + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: release-candidate + path: candidate/ + if-no-files-found: error test: name: Qualify (${{ matrix.os }}, Python ${{ matrix.python-version }}) runs-on: ${{ matrix.os }} + needs: build-candidate timeout-minutes: 45 strategy: fail-fast: false matrix: os: [ubuntu-latest, macos-latest, windows-latest] python-version: ["3.12", "3.13", "3.14"] - steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 with: - version: "0.10.9" - + version: ${{ env.UV_VERSION }} - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: ${{ matrix.python-version }} - - - name: Install dependencies - run: uv sync --python python --dev --extra ta --extra store --extra viz - - - name: Import package - run: uv run --no-sync python -c "import ml4t.engineer" - - - name: Run ty check - run: uv run --no-sync ty check --python-version ${{ matrix.python-version }} - - - name: Build package - run: uv build --python python - + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: release-candidate + path: candidate + - name: Verify candidate identity + shell: bash + run: >- + python scripts/ci/candidate.py verify candidate + --expected-commit "${{ github.sha }}" + --expected-tree "$(git rev-parse HEAD^{tree})" - name: Export installed-wheel test environment run: >- uv export --locked --group dev --extra ta --extra store --extra viz --no-emit-project --no-hashes --output-file "${{ runner.temp }}/test-requirements.txt" - - - name: Install built wheel + - name: Install the candidate wheel in a clean environment shell: bash run: | uv venv --python python .artifact-venv - artifact_wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)" + wheel="$(find candidate/dist -maxdepth 1 -name '*.whl' -print -quit)" UV_CACHE_DIR="${{ runner.temp }}/fresh-wheel-cache" \ - uv pip install --python .artifact-venv "$artifact_wheel" - uv pip install --python .artifact-venv --requirements "${{ runner.temp }}/test-requirements.txt" - - - name: Import built wheel + uv pip install --python .artifact-venv "$wheel" + uv pip install --python .artifact-venv \ + --requirements "${{ runner.temp }}/test-requirements.txt" + - name: Import the installed candidate run: uv run --python .artifact-venv --no-project python -c "import ml4t.engineer" - - - name: Run tests + - name: Run ty check + run: >- + uv run --python .artifact-venv --no-project + ty check --python-version ${{ matrix.python-version }} + - name: Run the installed-wheel suite repeatedly shell: bash run: | for iteration in {1..10}; do @@ -150,83 +214,25 @@ jobs: uv run --python .artifact-venv --no-project \ python -m pytest tests/ -q --tb=short --no-cov done - - - name: Run documented workflows from built wheel + - name: Run documented workflows from the installed candidate run: >- uv run --python .artifact-venv --no-project python tests/documentation_workflows.py - coverage: - name: Coverage - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 - with: - version: "0.10.9" - - - name: Set up Python - run: uv python install ${{ env.PYTHON_VERSION }} - - - name: Install dependencies - run: >- - uv sync --python ${{ env.PYTHON_VERSION }} --dev - --extra ta --extra store --extra viz - - - name: Measure line and branch coverage - env: - NUMBA_DISABLE_JIT: "1" - run: >- - uv run pytest tests/ -q - --cov-report= - --cov-report=json:coverage.json - --cov-report=term:skip-covered - - - name: Enforce release thresholds - run: uv run python scripts/check_coverage.py coverage.json - build: name: Build Package runs-on: ubuntu-latest - needs: [lint, typecheck, security, test, coverage] + needs: [build-candidate, test] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: - version: "0.10.9" - - - name: Set up Python - run: uv python install ${{ env.PYTHON_VERSION }} - - - name: Build package - run: uv build - - - name: Validate package metadata - run: uv run twine check dist/* - - - name: Validate release version - if: startsWith(github.ref, 'refs/tags/') + name: release-candidate + path: candidate + - name: Verify the qualified candidate run: >- - uv run python -c - "import os; from ml4t.engineer import __version__; - tag=os.environ['GITHUB_REF_NAME']; - assert tag == f'v{__version__}', f'{tag} does not match v{__version__}'" - - - name: Validate wheel installation - run: | - uv venv --python ${{ env.PYTHON_VERSION }} .artifact-venv - uv pip install --python .artifact-venv dist/*.whl - uv run --python .artifact-venv --no-project python -c "import ml4t.engineer" - - - name: Upload build artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: dist - path: dist/ + python scripts/ci/candidate.py verify candidate + --expected-commit "${{ github.sha }}" + --expected-tree "$(git rev-parse HEAD^{tree})" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c69b137..26d4fd5 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,51 +3,35 @@ name: Docs on: push: branches: [main] + pull_request: + branches: [main] workflow_dispatch: permissions: contents: read concurrency: - group: "docs" + group: docs-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +env: + PYTHON_VERSION: "3.12" + UV_VERSION: "0.10.9" + jobs: build: - name: Build & Deploy Docs + name: Build Documentation runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 with: - fetch-depth: 0 - - - name: Install uv - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 - with: - version: "0.10.9" - - - name: Set up Python - run: uv python install 3.12 - - - name: Install dependencies - run: uv sync --python 3.12 --dev --extra docs - + version: ${{ env.UV_VERSION }} + - run: uv python install ${{ env.PYTHON_VERSION }} + - run: uv sync --python ${{ env.PYTHON_VERSION }} --dev --extra docs - name: Run documented workflows run: uv run python tests/documentation_workflows.py - - - name: Build docs + - name: Check every README link + run: uv run python scripts/ci/check_readme_links.py README.md + - name: Build strict documentation run: uv run mkdocs build --strict - - - name: Deploy to website repo - uses: cpina/github-action-push-to-another-repository@55306faa4ed53b815ae49e564af8cfb359d32ae2 # v1.7.3 - env: - SSH_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }} - with: - source-directory: site/ - destination-github-username: ml4t - destination-repository-name: website - target-directory: static/docs/engineer/ - target-branch: main - commit-message: "docs(engineer): update from ml4t/engineer@${{ github.sha }}" - user-name: ml4t-bot - user-email: bot@ml4trading.io diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b563506..4d4985f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,12 +1,74 @@ name: Release on: - push: - tags: ["v*"] + workflow_dispatch: + inputs: + version: + description: Release version without the v prefix + required: true + type: string + candidate_commit: + description: Full commit SHA currently at the tip of main + required: true + type: string + +permissions: + contents: read + +concurrency: + group: release-${{ inputs.version }} + cancel-in-progress: false jobs: + validate: + name: Validate Release Request + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + commit: ${{ steps.identity.outputs.commit }} + tree: ${{ steps.identity.outputs.tree }} + version: ${{ steps.identity.outputs.version }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.candidate_commit }} + fetch-depth: 0 + - name: Require the current main commit and an unused version + id: identity + env: + CANDIDATE_COMMIT: ${{ inputs.candidate_commit }} + GH_TOKEN: ${{ github.token }} + RELEASE_VERSION: ${{ inputs.version }} + run: | + if [[ ! "$CANDIDATE_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then + echo "candidate_commit must be a full lowercase commit SHA" >&2 + exit 1 + fi + if [[ ! "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]]; then + echo "version must be a stable or prerelease PEP 440 version" >&2 + exit 1 + fi + git fetch origin main --no-tags + if [[ "$(git rev-parse HEAD)" != "$CANDIDATE_COMMIT" ]] || \ + [[ "$(git rev-parse origin/main)" != "$CANDIDATE_COMMIT" ]] || \ + [[ "${{ github.sha }}" != "$CANDIDATE_COMMIT" ]]; then + echo "dispatch the workflow from candidate_commit at the current main revision" >&2 + exit 1 + fi + if git show-ref --verify --quiet "refs/tags/v${RELEASE_VERSION}" || \ + gh release view "v${RELEASE_VERSION}" --repo "${{ github.repository }}" >/dev/null 2>&1; then + echo "tag or GitHub release v${RELEASE_VERSION} already exists" >&2 + exit 1 + fi + python scripts/ci/release.py require-absent ml4t-engineer "$RELEASE_VERSION" + echo "commit=$CANDIDATE_COMMIT" >> "$GITHUB_OUTPUT" + echo "tree=$(git rev-parse HEAD^{tree})" >> "$GITHUB_OUTPUT" + echo "version=$RELEASE_VERSION" >> "$GITHUB_OUTPUT" + ecosystem-qualification: name: Ecosystem Qualification + needs: validate permissions: contents: read uses: ml4t/ecosystem/.github/workflows/qualify-library.yml@457678d8860d0c816b1dc376e7e2691daa93af4d # v0.1.0 @@ -15,40 +77,226 @@ jobs: prerelease-exception: python-315-polars qualification: - name: Qualify Release + name: Qualify Release Candidate + needs: validate permissions: contents: read uses: ./.github/workflows/ci.yml + with: + release_version: ${{ needs.validate.outputs.version }} + + select-candidate: + name: Select Qualified Candidate + runs-on: ubuntu-latest + needs: [validate, ecosystem-qualification, qualification] + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.validate.outputs.commit }} + fetch-depth: 0 + - name: Download qualified release candidate + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: release-candidate + path: candidate + - name: Verify candidate commit, tree, version, and SHA256 manifest + run: >- + python scripts/ci/candidate.py verify candidate + --expected-commit "${{ needs.validate.outputs.commit }}" + --expected-tree "${{ needs.validate.outputs.tree }}" + --expected-tag "v${{ needs.validate.outputs.version }}" + - name: Retain selected candidate + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: qualified-release-candidate + path: candidate/ + if-no-files-found: error + + docs: + name: Publish Qualified Documentation + runs-on: ubuntu-latest + needs: [validate, select-candidate] + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.validate.outputs.commit }} + - 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: "3.12" + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: qualified-release-candidate + path: candidate + - name: Verify selected candidate + run: >- + python scripts/ci/candidate.py verify candidate + --expected-commit "${{ needs.validate.outputs.commit }}" + --expected-tree "${{ needs.validate.outputs.tree }}" + --expected-tag "v${{ needs.validate.outputs.version }}" + - name: Build revision-identified documentation + env: + ML4T_DOCS_COMMIT: ${{ needs.validate.outputs.commit }} + ML4T_DOCS_VERSION: ${{ needs.validate.outputs.version }} + run: | + uv sync --dev --extra docs --python 3.12 + uv run mkdocs build --strict + python - <<'PY' + import json + import os + from pathlib import Path + + Path("site/release.json").write_text( + json.dumps( + { + "commit": os.environ["ML4T_DOCS_COMMIT"], + "library": "engineer", + "version": os.environ["ML4T_DOCS_VERSION"], + }, + sort_keys=True, + ) + + "\n", + encoding="utf-8", + ) + PY + - name: Require deploy credentials + env: + DOCS_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }} + run: | + if [[ -z "$DOCS_DEPLOY_KEY" ]]; then + echo "DOCS_DEPLOY_KEY is required for a stable release" >&2 + exit 1 + fi + - name: Deploy stable documentation + uses: cpina/github-action-push-to-another-repository@55306faa4ed53b815ae49e564af8cfb359d32ae2 # v1.7.3 + env: + SSH_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }} + with: + source-directory: site/ + destination-github-username: ml4t + destination-repository-name: website + target-directory: static/docs/engineer/ + target-branch: main + commit-message: "docs(engineer): publish v${{ needs.validate.outputs.version }} from ${{ needs.validate.outputs.commit }}" + user-name: ml4t-bot + user-email: bot@ml4trading.io + - name: Deploy versioned documentation + uses: cpina/github-action-push-to-another-repository@55306faa4ed53b815ae49e564af8cfb359d32ae2 # v1.7.3 + env: + SSH_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }} + with: + source-directory: site/ + destination-github-username: ml4t + destination-repository-name: website + target-directory: static/docs/engineer/releases/${{ needs.validate.outputs.version }}/ + target-branch: main + commit-message: "docs(engineer): retain v${{ needs.validate.outputs.version }} from ${{ needs.validate.outputs.commit }}" + user-name: ml4t-bot + user-email: bot@ml4trading.io + - name: Verify deployed documentation identity + env: + RELEASE_COMMIT: ${{ needs.validate.outputs.commit }} + RELEASE_VERSION: ${{ needs.validate.outputs.version }} + run: uv run python scripts/ci/verify_docs_deployment.py publish: name: Publish to PyPI runs-on: ubuntu-latest - needs: [ecosystem-qualification, qualification] + needs: [validate, ecosystem-qualification, select-candidate, docs] environment: pypi permissions: + contents: read id-token: write steps: - - name: Download build artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: - name: dist - path: dist/ - - - name: Publish to PyPI + name: qualified-release-candidate + path: candidate + - name: Publish the qualified artifacts uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 + with: + packages-dir: candidate/dist/ + print-hash: true github-release: name: Create GitHub Release runs-on: ubuntu-latest - needs: publish + needs: [validate, publish] permissions: contents: write steps: - - name: Create GitHub Release + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: qualified-release-candidate + path: candidate + - name: Create tag and GitHub release from the candidate commit env: + CANDIDATE_COMMIT: ${{ needs.validate.outputs.commit }} GH_TOKEN: ${{ github.token }} - GH_REPO: ${{ github.repository }} + RELEASE_VERSION: ${{ needs.validate.outputs.version }} + run: | + args=( + "v${RELEASE_VERSION}" + --repo "${{ github.repository }}" + --target "$CANDIDATE_COMMIT" + --generate-notes + candidate/dist/* + candidate/candidate.json + ) + if [[ "$RELEASE_VERSION" =~ (a|b|rc)[0-9]+$ ]]; then + args+=(--prerelease) + fi + gh release create "${args[@]}" + + verify-release: + name: Verify Published Release + runs-on: ubuntu-latest + needs: [validate, github-release] + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.validate.outputs.commit }} + fetch-depth: 0 + - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 + with: + version: "0.10.9" + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: qualified-release-candidate + path: candidate + - name: Verify PyPI metadata and artifact SHA256 digests + run: python scripts/ci/release.py verify candidate + - name: Install the published wheel and run the README quick start + env: + RELEASE_VERSION: ${{ needs.validate.outputs.version }} run: >- - gh release create "${{ github.ref_name }}" - --generate-notes - --verify-tag + uv run --isolated --no-project + --with "ml4t-engineer==${RELEASE_VERSION}" + python tests/documentation_workflows.py --readme-only + - name: Verify GitHub release artifacts against the manifest + env: + GH_TOKEN: ${{ github.token }} + RELEASE_VERSION: ${{ needs.validate.outputs.version }} + run: | + mkdir -p released/dist + gh release download "v${RELEASE_VERSION}" --repo "${{ github.repository }}" \ + --pattern candidate.json --dir released + gh release download "v${RELEASE_VERSION}" --repo "${{ github.repository }}" \ + --pattern '*.whl' --pattern '*.tar.gz' --dir released/dist + python scripts/ci/candidate.py verify released \ + --expected-commit "${{ needs.validate.outputs.commit }}" \ + --expected-tree "${{ needs.validate.outputs.tree }}" \ + --expected-tag "v${RELEASE_VERSION}" + - name: Repeat deployed documentation identity check + env: + RELEASE_COMMIT: ${{ needs.validate.outputs.commit }} + RELEASE_VERSION: ${{ needs.validate.outputs.version }} + run: python scripts/ci/verify_docs_deployment.py diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml new file mode 100644 index 0000000..7f3da52 --- /dev/null +++ b/.github/workflows/security.yml @@ -0,0 +1,41 @@ +name: Security + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: "23 8 * * 1" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: security-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + dependency-review: + name: Dependency Review + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0 + with: + fail-on-severity: high + + codeql: + name: CodeQL + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: github/codeql-action/init@fddeee1a7ece751b577e409a89057319e3172939 # v4 + with: + languages: python + - uses: github/codeql-action/analyze@fddeee1a7ece751b577e409a89057319e3172939 # v4 diff --git a/README.md b/README.md index f41e578..99261b4 100644 --- a/README.md +++ b/README.md @@ -2,204 +2,112 @@ [![Python 3.12-3.14](https://img.shields.io/badge/python-3.12--3.14-blue.svg)](https://www.python.org/downloads/) [![PyPI](https://img.shields.io/pypi/v/ml4t-engineer)](https://pypi.org/project/ml4t-engineer/) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -Feature engineering for financial machine learning: validated features, labeling -methods, alternative bars, and leakage-safe dataset preparation. +Feature engineering, labeling, alternative bars, and leakage-safe datasets for +financial ML. -## Part of the ML4T Library Ecosystem - -This library is one of six interconnected libraries supporting the machine -learning for trading workflow described in -[Machine Learning for Trading](https://www.ml4trading.io/): - -![ML4T Library Ecosystem](docs/images/ml4t_ecosystem_workflow_color.png) - -Together they cover data infrastructure, feature engineering, modeling, signal evaluation, strategy backtesting, and live deployment. - -## What This Library Does - -Transforming raw price data into predictive features is a core task in -quantitative research. `ml4t-engineer` provides: - -- 120 registry features across 11 categories (momentum, volatility, trend, - microstructure, and more) -- Triple-barrier, ATR-based, percentile, trend-scanning, and meta-labeling - methods from *Advances in Financial Machine Learning* -- Alternative bar sampling (volume bars, dollar bars, tick imbalance bars) -- Dataset building, preprocessing, and feature discovery for leakage-safe ML - workflows - -The library is built on Polars with Numba JIT compilation for numerical -operations. 60 features are validated against TA-Lib at `1e-6` tolerance. - -![ml4t-engineer Architecture](docs/images/ml4t_engineer_architecture_print.jpeg) +`ml4t-engineer` provides 120 registry features across 11 categories, path-dependent +and fixed-horizon labeling, activity-based bar sampling, and train-only preprocessing. +The core interface uses Polars DataFrames. ## Installation +`ml4t-engineer` supports Python 3.12, 3.13, and 3.14 on Linux, macOS, and Windows. + ```bash pip install ml4t-engineer ``` -Optional dependencies: +The quick start uses only core dependencies. Optional extras provide TA-Lib validation, +DuckDB and PyArrow storage, market calendars, visualization, statistics, and ML tools: ```bash -pip install ml4t-engineer[ta] # TA-Lib backend -pip install ml4t-engineer[viz] # Visualization -pip install ml4t-engineer[calendars] # Trading calendars +pip install "ml4t-engineer[ta]" +pip install "ml4t-engineer[store]" +pip install "ml4t-engineer[calendars]" +pip install "ml4t-engineer[viz]" +pip install "ml4t-engineer[stats]" +pip install "ml4t-engineer[ml]" ``` +TA-Lib requires its native library. The core package does not require an external +service, credentials, or special hardware. Python 3.15 is not supported while the +active Polars compatibility exception applies. + ## Quick Start + ```python +from datetime import date, timedelta + import polars as pl from ml4t.engineer import compute_features -df = pl.read_parquet("ohlcv.parquet") - -# Compute features with default parameters -result = compute_features(df, ["rsi", "macd", "atr", "obv"]) - -# Or with custom parameters -result = compute_features(df, [ - {"name": "rsi", "params": {"period": 20}}, +close = [100.0 + i * 0.1 + (i % 7) * 0.2 for i in range(100)] +ohlcv = pl.DataFrame( { - "name": "bollinger_bands", - "params": {"period": 20, "nbdevup": 2.0, "nbdevdn": 2.0}, - }, -]) -``` - -## Feature Registry - -```python -from ml4t.engineer.core.registry import get_registry - -registry = get_registry() -print(registry.list_all()) # All 120 features -print(registry.list_by_category("momentum")) # 31 momentum indicators -print(registry.list_ta_lib_compatible()) # 60 TA-Lib validated features -print(registry.list_normalized()) # 37 bounded (0-100, -1 to 1) -``` - -## Feature Categories - -| Category | Count | Examples | -|----------|-------|----------| -| Momentum | 31 | RSI, MACD, Stochastic, CCI, ADX, MFI | -| Microstructure | 15 | Kyle Lambda, VPIN, Amihud, Roll spread | -| Volatility | 15 | ATR, Bollinger, Yang-Zhang, Parkinson | -| Statistics | 14 | Variance, Linear Regression, Correlation | -| ML | 14 | Fractional Diff, Entropy, Lag features | -| Trend | 10 | SMA, EMA, WMA, DEMA, TEMA, KAMA | -| Risk | 6 | Max Drawdown, Sortino, CVaR | -| Price Transform | 5 | Typical Price, Weighted Close | -| Regime | 4 | Hurst Exponent, Choppiness Index | -| Volume | 3 | OBV, AD, ADOSC | -| Math | 3 | MAX, MIN, SUM | - -## Triple-Barrier Labeling - -```python -from ml4t.engineer.config import LabelingConfig -from ml4t.engineer.labeling import triple_barrier_labels, atr_triple_barrier_labels - -# Fixed barriers -tb_config = LabelingConfig.triple_barrier( - upper_barrier=0.02, # 2% profit target - lower_barrier=0.01, # 1% stop loss - max_holding_period=20, # 20 bars -) -labels = triple_barrier_labels( - df, - config=tb_config, + "timestamp": [date(2024, 1, 1) + timedelta(days=i) for i in range(100)], + "open": close, + "high": [price + 1.0 for price in close], + "low": [price - 1.0 for price in close], + "close": close, + "volume": [100_000 + i * 100 for i in range(100)], + } ) -# ATR-based dynamic barriers -atr_config = LabelingConfig.atr_barrier( - atr_tp_multiple=2.0, - atr_sl_multiple=1.0, - atr_period=14, - max_holding_period=20, -) -labels = atr_triple_barrier_labels( - df, - config=atr_config, -) +features = compute_features(ohlcv, ["rsi", "macd", "atr"]) -# Time-based horizons -tb_time_config = LabelingConfig.triple_barrier( - upper_barrier=0.02, - lower_barrier=0.01, - max_holding_period="4h", # 4 hours -) -labels = triple_barrier_labels( - df, - config=tb_time_config, -) +assert {"rsi", "macd", "atr"} <= set(features.columns) +assert features.height == ohlcv.height ``` -## Alternative Bars +`compute_features()` returns the input columns with the requested feature columns +appended. Use the feature registry to inspect categories and parameters before building +larger pipelines. -```python -from ml4t.engineer.bars import VolumeBarSampler, DollarBarSampler, TickImbalanceBarSampler +## Supported Workflows -# Volume bars (equal volume per bar) -vbars = VolumeBarSampler(volume_per_bar=1000).sample(tick_data) +- Technical, volatility, risk, microstructure, statistical, and ML-oriented features +- Triple-barrier, ATR-barrier, percentile, fixed-horizon, trend-scanning, and meta-labels +- Tick, volume, dollar, imbalance, and run bars +- Train/test splitting with train-only scaling +- Feature metadata search and discovery -# Dollar bars (equal dollar volume per bar) -dbars = DollarBarSampler(dollars_per_bar=1_000_000).sample(tick_data) - -# Tick imbalance bars (information-driven) -ibars = TickImbalanceBarSampler(expected_ticks_per_bar=100).sample(tick_data) -``` - -## Documentation - -- [Docs Home](https://www.ml4trading.io/docs/engineer/) - library overview and - workflow map -- [Quickstart](https://www.ml4trading.io/docs/engineer/getting-started/quickstart/) - - first working feature and labeling workflow -- [Features](https://www.ml4trading.io/docs/engineer/user-guide/features/) - - 120 features across 11 registry categories -- [Labeling](https://www.ml4trading.io/docs/engineer/user-guide/labeling/) - - 7 labeling methods for supervised learning -- [Dataset Builder](https://www.ml4trading.io/docs/engineer/user-guide/dataset-builder/) - - leakage-safe train/test preparation -- [Examples](https://github.com/ml4t/engineer/blob/main/examples/README.md) - - runnable scripts for complete workflows and focused features - -## Technical Characteristics - -- **Polars-native**: All computations use Polars expressions -- **Numba-accelerated**: JIT compilation for numerical kernels -- **TA-Lib validated**: 60 features validated at `1e-6` tolerance -- **AFML-compliant**: Labeling methods verified against *Advances in Financial Machine Learning* -- **ML-ready outputs**: 37 features produce bounded outputs (0-100, -1 to 1) for direct model input; remaining features work with standard preprocessing (returns, z-scores, robust scaling) +See the [documentation](https://www.ml4trading.io/docs/engineer/) for tutorials, +task-oriented guides, explanations, and the API reference. Report defects and request +changes through [GitHub Issues](https://github.com/ml4t/engineer/issues). ## Related Libraries -- **ml4t-specs**: Shared feed and artifact schema definitions across the ML4T stack -- **ml4t-data**: Market data acquisition and storage -- **ml4t-diagnostic**: Signal evaluation and statistical validation -- **ml4t-backtest**: Event-driven backtesting -- **ml4t-live**: Live trading with broker integration +- [`ml4t-specs`](https://github.com/ml4t/specs) defines the shared market-data and + artifact contracts used by this package. +- [`ml4t-data`](https://github.com/ml4t/data) supplies validated market data for feature + computation. +- [`ml4t-diagnostic`](https://github.com/ml4t/diagnostic) evaluates features, labels, and + model signals produced from engineered datasets. ## Development ```bash git clone https://github.com/ml4t/engineer.git -cd ml4t-engineer -uv sync -uv run pytest tests/ -q +cd engineer +uv sync --dev --extra docs --extra ta --extra store --extra viz +uv run ruff check src/ tests/ examples/ scripts/ +uv run ruff format --check src/ tests/ examples/ scripts/ uv run ty check +uv run pytest tests/ -q +uv build +uv run mkdocs build --strict ``` -## References - -- Lopez de Prado, M. (2018). *Advances in Financial Machine Learning*. Wiley. -- Lopez de Prado, M. (2020). *Machine Learning for Asset Managers*. Cambridge. +Pull requests must also pass the supported Python and operating-system matrix, +dependency and vulnerability review, clean-wheel installation, documented workflow +tests, and ecosystem qualification. -## License +## Project Information -MIT License - see [LICENSE](LICENSE) for details. +- [Documentation](https://www.ml4trading.io/docs/engineer/) +- [Issue tracker](https://github.com/ml4t/engineer/issues) +- [Releases and changelog](https://github.com/ml4t/engineer/releases) +- [License](LICENSE) diff --git a/api.yaml b/api.yaml index abd00b1..4bac3ec 100644 --- a/api.yaml +++ b/api.yaml @@ -1,7 +1,7 @@ name: ml4t-engineer version: 1.0.0 python_requires: ">=3.12,<3.15" -description: High-performance feature engineering for financial machine learning +description: Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML. modules: - path: ml4t.engineer diff --git a/docs/index.md b/docs/index.md index 4ff66ea..fd54e0a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # ML4T Engineer -Turn OHLCV and tick data into model-ready features, labels, and sampling schemes -without rewriting the same research code in every notebook and pipeline. +Feature engineering, labeling, alternative bars, and leakage-safe datasets for +financial ML. `ml4t-engineer` is the feature-engineering layer in the ML4T stack. It sits between `ml4t-data`, which prepares canonical datasets, and `ml4t-diagnostic`, which diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 1fd85f1..9db7922 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -2,6 +2,9 @@ {% block extrahead %} {{ super() }} + + +
{{ config.site_name }} - is part of the ML4T documentation suite. + + version {{ config.extra.release_version }} at + {{ config.extra.release_commit[:12] }}. +
Docs Hub diff --git a/mkdocs.yml b/mkdocs.yml index 444aa1f..827dec0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,7 +2,7 @@ # MkDocs Material configuration with Picasso Blue palette site_name: ML4T Engineer -site_description: High-performance feature engineering for financial machine learning +site_description: Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML. site_url: https://www.ml4trading.io/docs/engineer/ repo_url: https://github.com/ml4t/engineer repo_name: ml4t/engineer @@ -121,6 +121,8 @@ nav: # Extra configuration extra: + release_version: !ENV [ML4T_DOCS_VERSION, development] + release_commit: !ENV [ML4T_DOCS_COMMIT, local] ml4t_docs_hub_url: /docs/ ml4t_libraries_url: /libraries/ ml4t_chapters_url: /chapters/ diff --git a/pyproject.toml b/pyproject.toml index b61e34b..c24132a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,4 +1,4 @@ -# ML4T Engineer - Institutional-grade quantitative finance feature engineering +# ML4T Engineer - feature engineering for financial machine learning # Independent package configuration for standalone distribution [build-system] @@ -8,9 +8,6 @@ build-backend = "hatchling.build" [tool.hatch.version] source = "vcs" -[tool.hatch.build.hooks.vcs] -version-file = "src/ml4t/engineer/_version.py" - [tool.hatch.build.targets.wheel] packages = ["src/ml4t"] namespaces = true @@ -29,17 +26,18 @@ include = [ [project] name = "ml4t-engineer" dynamic = ["version"] -description = "High-performance quantitative finance feature engineering library" +description = "Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML." readme = "README.md" license = { text = "MIT" } authors = [ - { name = "Stefan Jansen", email = "stefan@ml4trading.io" }, + { name = "Stefan Jansen", email = "stefan@applied-ai.com" }, ] maintainers = [ - { name = "Stefan Jansen", email = "stefan@ml4trading.io" }, + { name = "Stefan Jansen", email = "pm@ml4trading.io" }, ] keywords = [ "finance", + "algorithmic-trading", "features", "feature-engineering", "machine-learning", @@ -58,6 +56,9 @@ classifiers = [ "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", + "Operating System :: MacOS", + "Operating System :: Microsoft :: Windows", + "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", @@ -186,11 +187,11 @@ all = [ ] [project.urls] -Homepage = "https://github.com/ml4t/engineer" +Homepage = "https://www.ml4trading.io/" Documentation = "https://www.ml4trading.io/docs/engineer/" Repository = "https://github.com/ml4t/engineer" Issues = "https://github.com/ml4t/engineer/issues" -Changelog = "https://github.com/ml4t/engineer/blob/main/CHANGELOG.md" +Changelog = "https://github.com/ml4t/engineer/releases" [dependency-groups] test = [ @@ -243,7 +244,6 @@ markers = [ line-length = 100 target-version = "py312" fix = true -exclude = ["_version.py"] # Auto-generated by setuptools-scm [tool.ruff.lint] select = [ diff --git a/scripts/ci/candidate.py b/scripts/ci/candidate.py new file mode 100644 index 0000000..5f17726 --- /dev/null +++ b/scripts/ci/candidate.py @@ -0,0 +1,205 @@ +from __future__ import annotations + +import argparse +import hashlib +import json +import tarfile +import zipfile +from email.message import Message +from email.parser import BytesParser +from pathlib import Path +from typing import Any + +SCHEMA_VERSION = 1 + + +def _sha256(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as stream: + for chunk in iter(lambda: stream.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + + +def _distribution_files(candidate_dir: Path) -> tuple[Path, Path]: + dist_dir = candidate_dir / "dist" + wheels = tuple(dist_dir.glob("*.whl")) + sdists = tuple(dist_dir.glob("*.tar.gz")) + if len(wheels) != 1 or len(sdists) != 1: + raise ValueError( + f"candidate must contain one wheel and one sdist, found {len(wheels)} and {len(sdists)}" + ) + return wheels[0], sdists[0] + + +def _wheel_metadata(wheel: Path) -> Message: + with zipfile.ZipFile(wheel) as archive: + metadata_names = [ + name for name in archive.namelist() if name.endswith(".dist-info/METADATA") + ] + if len(metadata_names) != 1: + raise ValueError(f"wheel must contain one METADATA file: {wheel}") + return BytesParser().parsebytes(archive.read(metadata_names[0])) + + +def _identity(metadata: Message, path: Path) -> tuple[str, str]: + name = metadata.get("Name") + version = metadata.get("Version") + if not name or not version: + raise ValueError(f"distribution metadata is missing Name or Version: {path}") + return name, version + + +def _sdist_metadata(sdist: Path) -> Message: + with tarfile.open(sdist, "r:gz") as archive: + metadata_members = [ + member + for member in archive.getmembers() + if member.name.count("/") == 1 and member.name.endswith("/PKG-INFO") + ] + if len(metadata_members) != 1: + raise ValueError(f"sdist must contain one top-level PKG-INFO file: {sdist}") + stream = archive.extractfile(metadata_members[0]) + if stream is None: + raise ValueError(f"cannot read sdist metadata: {sdist}") + return BytesParser().parsebytes(stream.read()) + + +def _public_metadata(metadata: Message) -> dict[str, Any]: + project_urls = {} + for value in metadata.get_all("Project-URL", []): + label, url = value.split(",", maxsplit=1) + project_urls[label.strip()] = url.strip() + return { + "author_email": metadata.get("Author-email"), + "classifiers": sorted(metadata.get_all("Classifier", [])), + "description": metadata.get("Summary"), + "keywords": sorted( + keyword.strip() for keyword in (metadata.get("Keywords") or "").split(",") if keyword + ), + "license": metadata.get("License-Expression") or metadata.get("License"), + "maintainer_email": metadata.get("Maintainer-email"), + "project_urls": project_urls, + "requires_python": metadata.get("Requires-Python"), + } + + +def _artifact_record(path: Path) -> dict[str, str | int]: + return {"filename": path.name, "sha256": _sha256(path), "size": path.stat().st_size} + + +def create(candidate_dir: Path, commit_sha: str, git_tree: str) -> None: + wheel, sdist = _distribution_files(candidate_dir) + wheel_metadata = _wheel_metadata(wheel) + sdist_metadata = _sdist_metadata(sdist) + wheel_identity = _identity(wheel_metadata, wheel) + sdist_identity = _identity(sdist_metadata, sdist) + if wheel_identity != sdist_identity: + raise ValueError( + f"wheel identity {wheel_identity!r} does not match sdist identity {sdist_identity!r}" + ) + name, version = wheel_identity + public_metadata = _public_metadata(wheel_metadata) + if public_metadata != _public_metadata(sdist_metadata): + raise ValueError("wheel and sdist public metadata do not match") + manifest = { + "schema_version": SCHEMA_VERSION, + "commit_sha": commit_sha, + "git_tree": git_tree, + "name": name, + "version": version, + "metadata": public_metadata, + "artifacts": [_artifact_record(wheel), _artifact_record(sdist)], + } + (candidate_dir / "candidate.json").write_text( + json.dumps(manifest, indent=2, sort_keys=True) + "\n", + encoding="utf-8", + ) + + +def _load_manifest(candidate_dir: Path) -> dict[str, Any]: + value = json.loads((candidate_dir / "candidate.json").read_text(encoding="utf-8")) + if not isinstance(value, dict): + raise ValueError("candidate manifest must be a JSON object") + return value + + +def verify( + candidate_dir: Path, + *, + expected_commit: str | None = None, + expected_tree: str | None = None, + expected_tag: str | None = None, +) -> None: + manifest = _load_manifest(candidate_dir) + if manifest.get("schema_version") != SCHEMA_VERSION: + raise ValueError(f"unsupported candidate schema: {manifest.get('schema_version')!r}") + if expected_commit is not None and manifest.get("commit_sha") != expected_commit: + raise ValueError("candidate commit does not match the requested release commit") + if expected_tree is not None and manifest.get("git_tree") != expected_tree: + raise ValueError("candidate tree does not match the requested release tree") + if expected_tag is not None and expected_tag != f"v{manifest.get('version')}": + raise ValueError( + f"release tag {expected_tag!r} does not match candidate version {manifest.get('version')!r}" + ) + + wheel, sdist = _distribution_files(candidate_dir) + actual_files = {wheel.name: wheel, sdist.name: sdist} + records = manifest.get("artifacts") + if not isinstance(records, list) or len(records) != 2: + raise ValueError("candidate manifest must describe exactly two artifacts") + recorded_files = {record.get("filename"): record for record in records} + if set(recorded_files) != set(actual_files): + raise ValueError("candidate manifest artifact inventory does not match dist directory") + for filename, path in actual_files.items(): + record = recorded_files[filename] + if record.get("sha256") != _sha256(path) or record.get("size") != path.stat().st_size: + raise ValueError(f"candidate artifact integrity check failed: {filename}") + + wheel_metadata = _wheel_metadata(wheel) + sdist_metadata = _sdist_metadata(sdist) + identity = _identity(wheel_metadata, wheel) + if identity != _identity(sdist_metadata, sdist): + raise ValueError("candidate wheel and sdist identities do not match") + if identity != (manifest.get("name"), manifest.get("version")): + raise ValueError("candidate metadata does not match the manifest") + public_metadata = _public_metadata(wheel_metadata) + if public_metadata != _public_metadata(sdist_metadata): + raise ValueError("candidate wheel and sdist public metadata do not match") + if public_metadata != manifest.get("metadata"): + raise ValueError("candidate public metadata does not match the manifest") + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser() + subparsers = parser.add_subparsers(dest="command", required=True) + + create_parser = subparsers.add_parser("create") + create_parser.add_argument("candidate_dir", type=Path) + create_parser.add_argument("--commit-sha", required=True) + create_parser.add_argument("--git-tree", required=True) + + verify_parser = subparsers.add_parser("verify") + verify_parser.add_argument("candidate_dir", type=Path) + verify_parser.add_argument("--expected-commit") + verify_parser.add_argument("--expected-tree") + verify_parser.add_argument("--expected-tag") + + return parser + + +def main() -> None: + args = _parser().parse_args() + if args.command == "create": + create(args.candidate_dir, args.commit_sha, args.git_tree) + else: + verify( + args.candidate_dir, + expected_commit=args.expected_commit, + expected_tree=args.expected_tree, + expected_tag=args.expected_tag, + ) + + +if __name__ == "__main__": + main() diff --git a/scripts/ci/check_readme_links.py b/scripts/ci/check_readme_links.py new file mode 100644 index 0000000..d4b957a --- /dev/null +++ b/scripts/ci/check_readme_links.py @@ -0,0 +1,75 @@ +"""Validate every local and HTTP link in the root README.""" + +from __future__ import annotations + +import argparse +import re +import time +from pathlib import Path +from urllib.error import HTTPError, URLError +from urllib.parse import unquote, urlparse +from urllib.request import Request, urlopen + +LINK = re.compile(r"(?[^)]+)\)") +USER_AGENT = "ml4t-engineer-readme-check/1.0" + + +def targets(readme: Path) -> tuple[str, ...]: + """Return distinct README link targets in source order.""" + return tuple( + dict.fromkeys(match["target"].strip() for match in LINK.finditer(readme.read_text())) + ) + + +def validate_local(root: Path, target: str) -> None: + """Require a relative link to resolve inside the repository.""" + parsed = urlparse(target) + path = (root / unquote(parsed.path)).resolve() + try: + path.relative_to(root.resolve()) + except ValueError as error: + raise ValueError(f"README link escapes the repository: {target}") from error + if not path.exists(): + raise ValueError(f"README link does not exist: {target}") + + +def validate_http(target: str, *, attempts: int = 3, retry_seconds: float = 1.0) -> None: + """Require an HTTP target to return a non-error response.""" + last_error: Exception | None = None + for attempt in range(attempts): + request = Request(target, headers={"User-Agent": USER_AGENT}) + try: + with urlopen(request, timeout=20) as response: + if response.status < 400: + return + except (HTTPError, URLError, TimeoutError) as error: + last_error = error + if attempt + 1 < attempts: + time.sleep(retry_seconds) + raise RuntimeError(f"README link failed: {target}: {last_error}") + + +def check(readme: Path, *, check_http: bool = True) -> None: + """Validate every Markdown link in *readme*.""" + root = readme.resolve().parent + for target in targets(readme): + scheme = urlparse(target).scheme + if scheme in {"http", "https"}: + if check_http: + validate_http(target) + elif not scheme: + validate_local(root, target) + else: + raise ValueError(f"README uses unsupported link scheme: {target}") + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("readme", type=Path, nargs="?", default=Path("README.md")) + parser.add_argument("--local-only", action="store_true") + args = parser.parse_args() + check(args.readme, check_http=not args.local_only) + + +if __name__ == "__main__": + main() diff --git a/scripts/ci/release.py b/scripts/ci/release.py new file mode 100644 index 0000000..fb378c5 --- /dev/null +++ b/scripts/ci/release.py @@ -0,0 +1,90 @@ +"""Preflight and verify an ml4t-engineer PyPI publication.""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any +from urllib.error import HTTPError +from urllib.request import Request, urlopen + +PYPI_URL = "https://pypi.org/pypi/{name}/{version}/json" +USER_AGENT = "ml4t-engineer-release-verifier/1.0" + + +def _package(name: str, version: str) -> dict[str, Any]: + request = Request( + PYPI_URL.format(name=name, version=version), headers={"User-Agent": USER_AGENT} + ) + with urlopen(request, timeout=20) as response: + value = json.load(response) + if not isinstance(value, dict): + raise ValueError("PyPI response must be a JSON object") + return value + + +def require_version_absent(name: str, version: str) -> None: + try: + _package(name, version) + except HTTPError as error: + if error.code == 404: + return + raise + raise ValueError(f"{name} {version} already exists on PyPI") + + +def verify_publication(candidate_dir: Path) -> None: + manifest = json.loads((candidate_dir / "candidate.json").read_text(encoding="utf-8")) + package = _package(manifest["name"], manifest["version"]) + info = package.get("info") + if not isinstance(info, dict): + raise ValueError("PyPI response has no project metadata") + if (info.get("name"), info.get("version")) != (manifest["name"], manifest["version"]): + raise ValueError("PyPI project identity does not match the candidate manifest") + metadata = { + "author_email": info.get("author_email"), + "classifiers": sorted(info.get("classifiers", [])), + "description": info.get("summary"), + "keywords": sorted( + keyword.strip() for keyword in (info.get("keywords") or "").split(",") if keyword + ), + "license": info.get("license"), + "maintainer_email": info.get("maintainer_email"), + "project_urls": info.get("project_urls"), + "requires_python": info.get("requires_python"), + } + if metadata != manifest.get("metadata"): + raise ValueError("PyPI public metadata does not match the candidate manifest") + + published = { + item.get("filename"): (item.get("digests", {}).get("sha256"), item.get("size")) + for item in package.get("urls", []) + if isinstance(item, dict) + } + expected = {item["filename"]: (item["sha256"], item["size"]) for item in manifest["artifacts"]} + if published != expected: + raise ValueError("PyPI artifacts do not match the candidate manifest") + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser() + subparsers = parser.add_subparsers(dest="command", required=True) + absent = subparsers.add_parser("require-absent") + absent.add_argument("name") + absent.add_argument("version") + verify = subparsers.add_parser("verify") + verify.add_argument("candidate_dir", type=Path) + return parser + + +def main() -> None: + args = _parser().parse_args() + if args.command == "require-absent": + require_version_absent(args.name, args.version) + else: + verify_publication(args.candidate_dir) + + +if __name__ == "__main__": + main() diff --git a/scripts/ci/verify_docs_deployment.py b/scripts/ci/verify_docs_deployment.py new file mode 100644 index 0000000..294ef76 --- /dev/null +++ b/scripts/ci/verify_docs_deployment.py @@ -0,0 +1,71 @@ +"""Verify that public documentation identifies the release being published.""" + +from __future__ import annotations + +import json +import os +import time +from urllib.error import URLError +from urllib.parse import urlencode +from urllib.request import Request, urlopen + +USER_AGENT = "ml4t-engineer-release-verifier/1.0" + + +def _read_identity(url: str, commit: str, attempt: int) -> object: + query = urlencode({"commit": commit, "attempt": attempt}) + request = Request( + f"{url}?{query}", + headers={"User-Agent": USER_AGENT}, + ) + with urlopen(request, timeout=20) as response: + return json.load(response) + + +def verify( + urls: tuple[str, ...], + expected: dict[str, str], + *, + attempts: int = 20, + retry_seconds: float = 15, +) -> None: + if attempts < 1: + raise ValueError("attempts must be positive") + + observed: list[object] = [] + last_error: Exception | None = None + for attempt in range(attempts): + try: + observed = [_read_identity(url, expected["commit"], attempt) for url in urls] + last_error = None + if all(value == expected for value in observed): + return + except (OSError, URLError, ValueError) as error: + last_error = error + + if attempt + 1 < attempts: + time.sleep(retry_seconds) + + raise RuntimeError( + f"deployed documentation identity did not match {expected!r}; " + f"last observed {observed!r}; last error {last_error!r}" + ) + + +def main() -> None: + expected = { + "commit": os.environ["RELEASE_COMMIT"], + "version": os.environ["RELEASE_VERSION"], + "library": "engineer", + } + verify( + ( + "https://www.ml4trading.io/docs/engineer/release.json", + f"https://www.ml4trading.io/docs/engineer/releases/{expected['version']}/release.json", + ), + expected, + ) + + +if __name__ == "__main__": + main() diff --git a/src/ml4t/engineer/__init__.py b/src/ml4t/engineer/__init__.py index 060e0ec..908eb94 100644 --- a/src/ml4t/engineer/__init__.py +++ b/src/ml4t/engineer/__init__.py @@ -1,8 +1,7 @@ """ml4t-engineer - A Financial Machine Learning Feature Engineering Library. -ml4t-engineer is a comprehensive FML stack designed for correctness, reproducibility, -and performance. It provides tools for feature engineering, labeling, and preprocessing -for financial machine learning models. +ml4t-engineer provides features, labels, alternative bars, and leakage-safe dataset +preparation for financial machine learning. Agent Navigation: This package includes AGENTS.md files for AI agent navigation. @@ -45,12 +44,9 @@ ) try: - from ._version import version as __version__ -except Exception: - try: - __version__ = _dist_version("ml4t-engineer") - except _PackageNotFoundError: - __version__ = "0+unknown" + __version__ = _dist_version("ml4t-engineer") +except _PackageNotFoundError: + __version__ = "0+unknown" def get_agent_docs() -> dict[str, _Path]: diff --git a/src/ml4t/engineer/core/schemas.py b/src/ml4t/engineer/core/schemas.py index 00ec723..3e32f46 100644 --- a/src/ml4t/engineer/core/schemas.py +++ b/src/ml4t/engineer/core/schemas.py @@ -79,7 +79,7 @@ def validate_ohlcv_schema( require_asset_id: bool = True, allow_flexible_time: bool = True, ) -> None: - """Validate OHLCV schema compatibility with qdata. + """Validate OHLCV schema compatibility with market data inputs. This validator ensures that input data conforms to the expected OHLCV format for ml4t-engineer. It's more flexible than strict schema validation, diff --git a/src/ml4t/engineer/logging/core.py b/src/ml4t/engineer/logging/core.py index 7b957d0..f1df4b4 100644 --- a/src/ml4t/engineer/logging/core.py +++ b/src/ml4t/engineer/logging/core.py @@ -79,7 +79,7 @@ def __init__(self, name: str, level: int = logging.INFO): level : int Logging level (default: INFO) """ - self.logger = logging.getLogger(f"mlquant.features.{name}") + self.logger = logging.getLogger(f"ml4t.engineer.{name}") self.logger.setLevel(level) # Add custom formatter if no handlers exist diff --git a/tests/__init__.py b/tests/__init__.py index 070fb76..088806f 100644 --- a/tests/__init__.py +++ b/tests/__init__.py @@ -1 +1 @@ -"""Test suite for QuantLab-TA.""" +"""Test suite for ML4T Engineer.""" diff --git a/tests/conftest.py b/tests/conftest.py index 96810de..2e7f259 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -35,7 +35,7 @@ def crypto_data(): possible_paths = [ Path.cwd() / "data" / "crypto" / "spot" / "BTC.parquet", Path.cwd().parent / "data" / "crypto" / "spot" / "BTC.parquet", - Path.home() / "quantlab" / "data" / "crypto" / "spot" / "BTC.parquet", + Path.home() / "ml4t" / "data" / "crypto" / "spot" / "BTC.parquet", Path("/tmp") / "test_data" / "BTC.parquet", # CI environment ] diff --git a/tests/documentation_workflows.py b/tests/documentation_workflows.py index 9c75257..499e5c5 100644 --- a/tests/documentation_workflows.py +++ b/tests/documentation_workflows.py @@ -2,6 +2,7 @@ from __future__ import annotations +import argparse import re import subprocess import sys @@ -9,6 +10,7 @@ ROOT = Path(__file__).resolve().parents[1] DOCUMENTS = [ + ROOT / "README.md", ROOT / "docs/index.md", ROOT / "docs/getting-started/quickstart.md", *sorted((ROOT / "docs/user-guide").glob("*.md")), @@ -34,10 +36,12 @@ def documented_workflows() -> list[tuple[Path, int, str]]: return workflows -def run_documented_workflows() -> None: +def run_documented_workflows(*, readme_only: bool = False) -> None: """Run each workflow in an isolated interpreter.""" failures: list[str] = [] for document, line_number, source in documented_workflows(): + if readme_only and document != ROOT / "README.md": + continue result = subprocess.run( [sys.executable, "-c", source], cwd=ROOT, @@ -58,4 +62,6 @@ def run_documented_workflows() -> None: if __name__ == "__main__": - run_documented_workflows() + parser = argparse.ArgumentParser() + parser.add_argument("--readme-only", action="store_true") + run_documented_workflows(readme_only=parser.parse_args().readme_only) diff --git a/tests/test_accuracy_validation.py b/tests/test_accuracy_validation.py index da5acee..7924e00 100644 --- a/tests/test_accuracy_validation.py +++ b/tests/test_accuracy_validation.py @@ -234,5 +234,5 @@ def benchmark_with_timeit(): benchmarks = benchmark_with_timeit() for name, talib_ms, our_ms, speedup in benchmarks: print( - f"{name:<10} TA-Lib: {talib_ms:6.3f}ms QuantLab: {our_ms:6.3f}ms Speedup: {speedup:5.2f}x", + f"{name:<10} TA-Lib: {talib_ms:6.3f}ms ML4T: {our_ms:6.3f}ms Speedup: {speedup:5.2f}x", ) diff --git a/tests/test_config.py b/tests/test_config.py index 7ea3f2a..2a431e4 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -1,5 +1,5 @@ """ -Global test configuration for QuantLab-TA. +Global test configuration for ML4T Engineer. This module defines strict accuracy requirements and common test utilities to ensure all indicators match TA-Lib output within acceptable tolerances. diff --git a/tests/test_logging.py b/tests/test_logging.py index f2c785f..2d12d2f 100644 --- a/tests/test_logging.py +++ b/tests/test_logging.py @@ -23,7 +23,7 @@ def test_logger_creation(self): """Test logger creation and basic functionality.""" logger = FeatureLogger("test_module") assert logger.name == "test_module" - assert logger.logger.name == "mlquant.features.test_module" + assert logger.logger.name == "ml4t.engineer.test_module" def test_log_feature_lifecycle(self, caplog): """Test logging feature calculation lifecycle.""" diff --git a/tests/test_performance.py b/tests/test_performance.py index f7c84a6..e4b4376 100644 --- a/tests/test_performance.py +++ b/tests/test_performance.py @@ -1,4 +1,4 @@ -"""Performance benchmark tests for QuantLab-TA. +"""Performance benchmark tests for ML4T Engineer. These tests measure performance against reference implementations and validate our 10-50x performance claims. diff --git a/tests/test_release_candidate.py b/tests/test_release_candidate.py new file mode 100644 index 0000000..b28eedd --- /dev/null +++ b/tests/test_release_candidate.py @@ -0,0 +1,170 @@ +from __future__ import annotations + +import json +import subprocess +import tarfile +import zipfile +from io import BytesIO +from pathlib import Path +from urllib.error import HTTPError +from urllib.parse import parse_qs, urlparse +from urllib.request import Request + +import pytest + +from scripts.ci import candidate, check_readme_links, release, verify_docs_deployment + + +@pytest.fixture(scope="module") +def candidate_dir(tmp_path_factory: pytest.TempPathFactory) -> Path: + directory = tmp_path_factory.mktemp("candidate") + subprocess.run(["uv", "build", "--out-dir", str(directory / "dist")], check=True) + candidate.create(directory, commit_sha="a" * 40, git_tree="b" * 40) + return directory + + +def test_candidate_manifest_binds_both_artifacts_to_source(candidate_dir: Path) -> None: + manifest = json.loads((candidate_dir / "candidate.json").read_text(encoding="utf-8")) + candidate.verify( + candidate_dir, + expected_commit="a" * 40, + expected_tree="b" * 40, + expected_tag=f"v{manifest['version']}", + ) + assert manifest["name"] == "ml4t-engineer" + assert manifest["version"] + assert manifest["metadata"]["description"] == ( + "Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML." + ) + assert manifest["metadata"]["author_email"] == "Stefan Jansen " + assert manifest["metadata"]["maintainer_email"] == "Stefan Jansen " + assert len(manifest["artifacts"]) == 2 + assert all(len(record["sha256"]) == 64 for record in manifest["artifacts"]) + + +def test_candidate_verification_is_atomic_for_wrong_identity_and_bytes( + candidate_dir: Path, +) -> None: + with pytest.raises(ValueError, match="does not match candidate version"): + candidate.verify(candidate_dir, expected_tag="v0.0.0") + + wheel = next((candidate_dir / "dist").glob("*.whl")) + original = wheel.read_bytes() + try: + wheel.write_bytes(original + b"modified") + with pytest.raises(ValueError, match="integrity check failed"): + candidate.verify(candidate_dir) + finally: + wheel.write_bytes(original) + + +def test_distributions_contain_public_metadata_and_required_files(candidate_dir: Path) -> None: + wheel, sdist = candidate._distribution_files(candidate_dir) + with zipfile.ZipFile(wheel) as archive: + metadata_name = next( + name for name in archive.namelist() if name.endswith(".dist-info/METADATA") + ) + metadata = archive.read(metadata_name).decode() + members = set(archive.namelist()) + assert "Author-email: Stefan Jansen " in metadata + assert "Maintainer-email: Stefan Jansen " in metadata + assert "ml4t/engineer/py.typed" in members + + with tarfile.open(sdist, "r:gz") as archive: + members = {member.name.partition("/")[2] for member in archive.getmembers()} + assert {"README.md", "LICENSE", "CHANGELOG.md"} <= members + + +def test_readme_link_checker_validates_local_and_http_targets( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +) -> None: + (tmp_path / "LICENSE").write_text("license\n", encoding="utf-8") + readme = tmp_path / "README.md" + readme.write_text("[local](LICENSE) [remote](https://example.test/docs)\n", encoding="utf-8") + requests: list[Request] = [] + + def open_url(request: Request, *, timeout: int) -> BytesIO: + requests.append(request) + assert timeout == 20 + response = BytesIO(b"ok") + response.status = 200 # type: ignore[attr-defined] + return response + + monkeypatch.setattr(check_readme_links, "urlopen", open_url) + check_readme_links.check(readme) + assert requests[0].get_header("User-agent") == check_readme_links.USER_AGENT + + +def test_docs_verifier_checks_release_identity(monkeypatch: pytest.MonkeyPatch) -> None: + expected = {"commit": "a" * 40, "library": "engineer", "version": "0.1.4"} + responses = iter(({**expected, "commit": "old"}, expected)) + requests: list[Request] = [] + + def open_url(request: Request, *, timeout: int) -> BytesIO: + requests.append(request) + assert timeout == 20 + return BytesIO(json.dumps(next(responses)).encode()) + + monkeypatch.setattr(verify_docs_deployment, "urlopen", open_url) + monkeypatch.setattr(verify_docs_deployment.time, "sleep", lambda _: None) + verify_docs_deployment.verify( + ("https://www.ml4trading.io/docs/engineer/release.json",), + expected, + attempts=2, + retry_seconds=0, + ) + assert [parse_qs(urlparse(request.full_url).query)["attempt"] for request in requests] == [ + ["0"], + ["1"], + ] + + +def test_release_preflight_accepts_only_a_missing_pypi_version( + monkeypatch: pytest.MonkeyPatch, +) -> None: + def missing_package(_name: str, _version: str) -> dict[str, object]: + raise HTTPError("https://example.test", 404, "missing", {}, None) + + monkeypatch.setattr(release, "_package", missing_package) + release.require_version_absent("ml4t-engineer", "9.9.9") + + monkeypatch.setattr(release, "_package", lambda _name, _version: {}) + with pytest.raises(ValueError, match="already exists"): + release.require_version_absent("ml4t-engineer", "9.9.9") + + +def test_pypi_publication_must_match_candidate_manifest( + monkeypatch: pytest.MonkeyPatch, + candidate_dir: Path, +) -> None: + manifest = json.loads((candidate_dir / "candidate.json").read_text(encoding="utf-8")) + metadata = manifest["metadata"] + response = { + "info": { + "author_email": metadata["author_email"], + "classifiers": metadata["classifiers"], + "keywords": ",".join(metadata["keywords"]), + "license": metadata["license"], + "maintainer_email": metadata["maintainer_email"], + "name": manifest["name"], + "project_urls": metadata["project_urls"], + "requires_python": metadata["requires_python"], + "summary": metadata["description"], + "version": manifest["version"], + }, + "urls": [ + { + "filename": record["filename"], + "digests": {"sha256": record["sha256"]}, + "size": record["size"], + } + for record in manifest["artifacts"] + ], + } + monkeypatch.setattr(release, "_package", lambda _name, _version: response) + release.verify_publication(candidate_dir) + + response["urls"][0]["digests"]["sha256"] = "0" * 64 + with pytest.raises(ValueError, match="artifacts do not match"): + release.verify_publication(candidate_dir) diff --git a/tests/test_release_policy.py b/tests/test_release_policy.py index bb695b2..730f520 100644 --- a/tests/test_release_policy.py +++ b/tests/test_release_policy.py @@ -51,34 +51,36 @@ def test_ci_qualifies_required_python_platform_matrix() -> None: def test_each_matrix_cell_runs_all_release_checks_without_masking_failures() -> None: steps = _load_workflow("ci.yml")["jobs"]["test"]["steps"] - commands = {step["name"]: step["run"] for step in steps if "run" in step} + commands = {step["name"]: step["run"] for step in steps if "run" in step and "name" in step} setup = next( step for step in steps if step.get("name") == "Set up Python ${{ matrix.python-version }}" ) assert { - "Install dependencies", - "Import package", - "Run tests", + "Verify candidate identity", "Run ty check", - "Build package", "Export installed-wheel test environment", - "Install built wheel", - "Import built wheel", + "Install the candidate wheel in a clean environment", + "Import the installed candidate", + "Run the installed-wheel suite repeatedly", + "Run documented workflows from the installed candidate", } <= commands.keys() - assert commands["Install dependencies"] == ( - "uv sync --python python --dev --extra ta --extra store --extra viz" - ) assert setup["with"] == {"python-version": "${{ matrix.python-version }}"} - assert "--no-sync" in commands["Import package"] - assert "--python python" not in commands["Import package"] + identity = commands["Verify candidate identity"] + assert "candidate.py verify candidate" in identity + assert '--expected-commit "${{ github.sha }}"' in identity + assert '--expected-tree "$(git rev-parse HEAD^{tree})"' in identity + assert ( + next(step for step in steps if step.get("name") == "Verify candidate identity")["shell"] + == "bash" + ) + assert "--python-version ${{ matrix.python-version }}" in commands["Run ty check"] - assert "--no-sync" in commands["Run ty check"] + assert "--python .artifact-venv --no-project" in commands["Run ty check"] assert "--exclude" not in commands["Run ty check"] assert "--extra-search-path" not in commands["Run ty check"] - assert "--python python" in commands["Build package"] - test_command = commands["Run tests"] + test_command = commands["Run the installed-wheel suite repeatedly"] assert "for iteration in {1..10}" in test_command assert "--python .artifact-venv --no-project" in test_command assert "python -m pytest tests/" in test_command @@ -89,44 +91,125 @@ def test_each_matrix_cell_runs_all_release_checks_without_masking_failures() -> export_command = commands["Export installed-wheel test environment"] assert "--group dev --extra ta --extra store --extra viz" in export_command assert "--no-emit-project" in export_command - wheel_install = commands["Install built wheel"] + wheel_install = commands["Install the candidate wheel in a clean environment"] assert 'UV_CACHE_DIR="${{ runner.temp }}/fresh-wheel-cache"' in wheel_install - assert 'uv pip install --python .artifact-venv "$artifact_wheel"' in wheel_install + assert 'uv pip install --python .artifact-venv "$wheel"' in wheel_install assert "--requirements" in wheel_install - assert wheel_install.index('"$artifact_wheel"') < wheel_install.index("--requirements") + assert wheel_install.index('"$wheel"') < wheel_install.index("--requirements") step_names = [step.get("name") for step in steps] - assert step_names.index("Install built wheel") < step_names.index("Run tests") + assert step_names.index( + "Install the candidate wheel in a clean environment" + ) < step_names.index("Run the installed-wheel suite repeatedly") def test_release_publishes_only_the_qualified_artifact() -> None: ci_jobs = _load_workflow("ci.yml")["jobs"] - build_steps = ci_jobs["build"]["steps"] - build_commands = {step["name"]: step["run"] for step in build_steps if "run" in step} - assert ci_jobs["build"]["needs"] == ["lint", "typecheck", "security", "test", "coverage"] - assert "twine check dist/*" in build_commands["Validate package metadata"] - assert "GITHUB_REF_NAME" in build_commands["Validate release version"] - assert "tag == f'v{__version__}'" in build_commands["Validate release version"] - assert "uv pip install" in build_commands["Validate wheel installation"] - assert 'python -c "import ml4t.engineer"' in build_commands["Validate wheel installation"] - - release_jobs = _load_workflow("release.yml")["jobs"] + candidate_steps = ci_jobs["build-candidate"]["steps"] + candidate_commands = { + step["name"]: step["run"] for step in candidate_steps if "run" in step and "name" in step + } + assert ci_jobs["build-candidate"]["needs"] == [ + "lint", + "typecheck", + "security", + "coverage", + "documentation", + ] + assert candidate_commands["Build source and wheel artifacts once"] == ( + "uv build --out-dir candidate/dist" + ) + version_step = next( + step for step in candidate_steps if step.get("name") == "Set release candidate version" + ) + assert version_step["if"] == "${{ inputs.release_version != '' }}" + assert version_step["env"] == {"RELEASE_VERSION": "${{ inputs.release_version }}"} + assert "SETUPTOOLS_SCM_PRETEND_VERSION" in version_step["run"] + manifest = candidate_commands["Record candidate commit, tree, version, and SHA256 digests"] + assert "candidate.py create candidate" in manifest + assert "github.sha" in manifest + assert "git rev-parse HEAD^{tree}" in manifest + assert ( + "twine check candidate/dist/*" + in candidate_commands["Validate artifact metadata and manifest"] + ) + upload = next( + step for step in candidate_steps if "actions/upload-artifact@" in step.get("uses", "") + ) + assert upload["with"]["name"] == "release-candidate" + assert ci_jobs["build"]["needs"] == ["build-candidate", "test"] + assert not any("uv build" in step.get("run", "") for step in ci_jobs["build"]["steps"]) + + release = _load_workflow("release.yml") + release_jobs = release["jobs"] + assert set(release["on"]["workflow_dispatch"]["inputs"]) == {"version", "candidate_commit"} + assert release_jobs["select-candidate"]["needs"] == [ + "validate", + "ecosystem-qualification", + "qualification", + ] assert release_jobs["qualification"]["uses"] == "./.github/workflows/ci.yml" - assert release_jobs["publish"]["needs"] == ["ecosystem-qualification", "qualification"] - - release_step = release_jobs["github-release"]["steps"][0] - assert release_step["env"]["GH_REPO"] == "${{ github.repository }}" - assert "--verify-tag" in release_step["run"] + assert release_jobs["qualification"]["with"]["release_version"] == ( + "${{ needs.validate.outputs.version }}" + ) + assert release_jobs["docs"]["needs"] == ["validate", "select-candidate"] + assert release_jobs["publish"]["needs"] == [ + "validate", + "ecosystem-qualification", + "select-candidate", + "docs", + ] + assert release_jobs["github-release"]["needs"] == ["validate", "publish"] + assert release_jobs["verify-release"]["needs"] == ["validate", "github-release"] publish_steps = release_jobs["publish"]["steps"] - download = next(step for step in publish_steps if step["name"] == "Download build artifacts") - assert download["with"] == {"name": "dist", "path": "dist/"} + publisher = next( + step for step in publish_steps if "pypa/gh-action-pypi-publish@" in step.get("uses", "") + ) + assert publisher["with"]["packages-dir"] == "candidate/dist/" + assert not any( + "uv build" in step.get("run", "") + for job in release_jobs.values() + for step in job.get("steps", []) + ) + + release_step = next( + step + for step in release_jobs["github-release"]["steps"] + if step.get("name") == "Create tag and GitHub release from the candidate commit" + ) + assert '--target "$CANDIDATE_COMMIT"' in release_step["run"] + assert "candidate/candidate.json" in release_step["run"] + + verify_commands = { + step["name"]: step["run"] + for step in release_jobs["verify-release"]["steps"] + if "run" in step and "name" in step + } + assert ( + "release.py verify candidate" + in verify_commands["Verify PyPI metadata and artifact SHA256 digests"] + ) + assert ( + "--readme-only" + in verify_commands["Install the published wheel and run the README quick start"] + ) + assert ( + "candidate.py verify released" + in verify_commands["Verify GitHub release artifacts against the manifest"] + ) + assert ( + "verify_docs_deployment.py" + in verify_commands["Repeat deployed documentation identity check"] + ) def test_ci_enforces_independent_line_and_branch_coverage_thresholds() -> None: coverage_steps = _load_workflow("ci.yml")["jobs"]["coverage"]["steps"] - commands = {step["name"]: step["run"] for step in coverage_steps if "run" in step} + commands = { + step["name"]: step["run"] for step in coverage_steps if "run" in step and "name" in step + } measurement = next( step for step in coverage_steps if step.get("name") == "Measure line and branch coverage" ) @@ -147,14 +230,14 @@ def test_standalone_typecheck_installs_optional_type_dependencies() -> None: def test_ci_audits_core_and_complete_locked_environments() -> None: steps = _load_workflow("ci.yml")["jobs"]["security"]["steps"] - commands = {step["name"]: step["run"] for step in steps if "run" in step} + commands = {step["name"]: step["run"] for step in steps if "run" in step and "name" in step} export = commands["Export locked environments"] assert "--no-dev --no-emit-project" in export assert "--all-extras --all-groups --no-emit-project" in export - audit = commands["Audit locked environments"] - assert audit.count("pip-audit --requirement") == 2 + audit = commands["Audit runtime and contributor environments"] + assert audit.count("python -m pip_audit") == 2 assert "core.txt" in audit assert "complete.txt" in audit diff --git a/tests/test_validation.py b/tests/test_validation.py index e3e9368..a72aa71 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -1,4 +1,4 @@ -"""Validation tests for QuantLab-TA against reference implementations. +"""Validation tests for ML4T Engineer against reference implementations. This module tests our Polars-based technical indicators against established libraries like TA-Lib to ensure mathematical accuracy.