tuft 0.1.0__tar.gz → 0.1.1__tar.gz

tuft-0.1.1/.gitattributes

@@ -0,0 +1,3 @@
+assets/countdown_rl.png filter=lfs diff=lfs merge=lfs -text
+assets/test_nll_sft.png filter=lfs diff=lfs merge=lfs -text
+assets/train_mean_nll_sft.png filter=lfs diff=lfs merge=lfs -text

tuft-0.1.1/.github/workflows/checks.yml

@@ -0,0 +1,65 @@
+name: Checks
+
+on:
+  push:
+    branches: [main, dev/**, feature/**]
+  pull_request:
+    branches: [main]
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      TEST_REDIS_URL: redis://localhost:6379/15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.21'
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Run ruff linter
+        run: uv run ruff check .
+
+      - name: Run ruff formatter check
+        run: uv run ruff format --check .
+
+      - name: Run nbqa-ruff on notebooks
+        run: uv run nbqa ruff --exclude .venv --exclude tinker .
+
+      - name: Run pyright type checker
+        run: uv run pyright
+
+      - name: Run pytest
+        run: uv run pytest
+
+      # - name: Check uv lockfile is up to date
+      #   run: |
+      #     uv lock --check

tuft-0.1.1/.github/workflows/docker/docker-compose.yml

@@ -0,0 +1,72 @@
+services:
+  # use 2 nodes to simulate a cluster environment
+  tuft-node-1:
+    image: tuft-unittest:20260123
+    pull_policy: never
+    command: bash -c "source /opt/venv/bin/activate && uv pip install -e .[dev,backend,persistence] && ray start --head --dashboard-host 0.0.0.0 --include-dashboard true --block"
+    environment:
+      - HF_ENDPOINT=https://hf-mirror.com
+      - RAY_ADDRESS=auto
+      - TUFT_CHECKPOINT_DIR=/mnt/checkpoints
+      - TUFT_TEST_MODEL=/mnt/models/Qwen3-0.6B
+      - TUFT_TEST_MODEL_1=/mnt/models/Qwen3-0.6B
+      - TUFT_TEST_MODEL_2=/mnt/models/Qwen3-1.7B
+      - TEST_REDIS_URL=redis://tuft-redis:6379
+      - VIRTUAL_ENV=/opt/venv
+    working_dir: /workspace
+    networks:
+      - tuft-network
+    volumes:
+      - tuft-volume:/mnt
+      - ../../..:/workspace
+    shm_size: "64G"
+    deploy:
+      resources:
+        reservations:
+          devices:
+          - driver: nvidia
+            device_ids: ['0', '1']
+            capabilities: [gpu]
+
+  tuft-node-2:
+    image: tuft-unittest:20260123
+    pull_policy: never
+    command: bash -c "source /opt/venv/bin/activate && uv pip install -e .[dev,backend,persistence] && ray start --address=tuft-node-1:6379 --block"
+    environment:
+      - HF_ENDPOINT=https://hf-mirror.com
+      - TUFT_CHECKPOINT_DIR=/mnt/checkpoints
+      - TUFT_TEST_MODEL=/mnt/models/Qwen3-0.6B
+      - TUFT_TEST_MODEL_1=/mnt/models/Qwen3-0.6B
+      - TUFT_TEST_MODEL_2=/mnt/models/Qwen3-1.7B
+      - TEST_REDIS_URL=redis://tuft-redis:6379
+      - VIRTUAL_ENV=/opt/venv
+    working_dir: /workspace
+    volumes:
+      - tuft-volume:/mnt
+      - ../../..:/workspace
+    depends_on:
+      - tuft-node-1
+    networks:
+      - tuft-network
+    shm_size: "64G"
+    deploy:
+      resources:
+        reservations:
+          devices:
+          - driver: nvidia
+            device_ids: ['2', '3']
+            capabilities: [gpu]
+
+  tuft-redis:
+    image: redis:7.0
+    command: ["redis-server", "--save", "60", "1", "--loglevel", "warning"]
+    networks:
+      - tuft-network
+
+networks:
+  tuft-network:
+    driver: bridge
+
+volumes:
+  tuft-volume:
+    external: true

tuft-0.1.1/.github/workflows/docker.yml

@@ -0,0 +1,77 @@
+name: Build and Publish Docker Image
+
+on:
+  release:
+    types: [published]
+
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'The git ref (branch or tag) to build the Docker image from.'
+        required: true
+      version:
+        description: 'Version tag for the Docker image (e.g., 0.1.0)'
+        required: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: self-hosted  # TODO: setup a self-hosted runner on a machine with sufficient resources
+    timeout-minutes: 360
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.inputs.ref || github.ref }}
+          path: tuft-${{ github.run_id }}
+      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      - name: Log in to the Container registry
+        uses: docker/login-action@v2
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=match,pattern=\d.\d.\d,enable=${{ github.event_name == 'release' }}
+            type=raw,value=${{ github.event.inputs.version }},enable=${{ github.event_name == 'workflow_dispatch' }}
+      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v4
+        with:
+          context: tuft-${{ github.run_id }}
+          push: true
+          file: tuft-${{ github.run_id }}/docker/Dockerfile
+          shm-size: 128g
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+
+      - name: Cleanup workspace
+        if: always()
+        run: |
+          sudo rm -rf tuft-${{ github.run_id }} 2>/dev/null

tuft-0.1.1/.github/workflows/install-script.yml

@@ -0,0 +1,241 @@
+name: Install Script
+
+on:
+  push:
+    branches: [main, dev/**, feature/**]
+    paths:
+      - 'scripts/install.sh'
+      - '.github/workflows/install-script.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'scripts/install.sh'
+      - '.github/workflows/install-script.yml'
+
+jobs:
+  test-install-script:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Test install script syntax
+        run: bash -n scripts/install.sh
+
+      - name: Test install script help
+        run: bash scripts/install.sh --help
+
+      - name: Run install script (local source)
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify tuft command exists
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          which tuft
+          tuft --help
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify tuft version
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          tuft version
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify Python environment
+        run: |
+          test -f "${TUFT_HOME}/venv/bin/python"
+          "${TUFT_HOME}/venv/bin/python" -c "import tuft; print('tuft imported successfully')"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Test tuft (dry run - check config error)
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          # Should fail with config error, not import error
+          tuft 2>&1 | grep -q "\-\-config" || tuft 2>&1 | grep -q "config"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+  test-install-default-with-backend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run install script (default includes backend)
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify backend dependencies installed
+        run: |
+          "${TUFT_HOME}/venv/bin/python" -c "import peft; print('peft imported successfully')"
+          "${TUFT_HOME}/venv/bin/python" -c "import redis; print('redis imported successfully')"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+  test-install-without-backend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run install script without backend
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE" --without-backend
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify minimal install (no peft)
+        run: |
+          # peft should NOT be installed in minimal mode
+          "${TUFT_HOME}/venv/bin/python" -c "import peft" 2>&1 && exit 1 || echo "peft not installed (expected)"
+          # tuft should still be importable
+          "${TUFT_HOME}/venv/bin/python" -c "import tuft; print('tuft imported successfully')"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+  test-wrapper-commands:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install tuft
+        run: bash scripts/install.sh --local-source "$GITHUB_WORKSPACE"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Test help command
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          tuft help
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Test version command
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          tuft version
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Test upgrade command
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          tuft upgrade
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+  test-clean-install:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Initial install
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE" --without-backend
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Create marker file to verify clean
+        run: |
+          echo "marker" > "${TUFT_HOME}/marker.txt"
+          test -f "${TUFT_HOME}/marker.txt"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Reinstall with --clean
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE" --without-backend --clean
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify marker file was removed
+        run: |
+          # Marker file should be gone after --clean
+          test ! -f "${TUFT_HOME}/marker.txt"
+          # But tuft should still be installed
+          "${TUFT_HOME}/venv/bin/python" -c "import tuft; print('tuft imported successfully')"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+  test-install-backend-command:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install without backend first
+        run: |
+          bash scripts/install.sh --local-source "$GITHUB_WORKSPACE" --without-backend
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify peft is NOT installed
+        run: |
+          "${TUFT_HOME}/venv/bin/python" -c "import peft" 2>&1 && exit 1 || echo "peft not installed (expected)"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Run install-backend command
+        run: |
+          export PATH="${TUFT_HOME}/bin:$PATH"
+          tuft install-backend
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Verify backend dependencies now installed
+        run: |
+          "${TUFT_HOME}/venv/bin/python" -c "import peft; print('peft imported successfully')"
+          "${TUFT_HOME}/venv/bin/python" -c "import redis; print('redis imported successfully')"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft
+
+      - name: Clean up installation
+        run: rm -rf "${TUFT_HOME}"
+        env:
+          TUFT_HOME: ${{ runner.temp }}/tuft

tuft-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Git ref to checkout (branch, tag, or commit SHA)'
+        required: true
+        default: 'main'
+        type: string
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.21'
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/tuft/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tuft-0.1.1/.github/workflows/unittest.yml

@@ -0,0 +1,103 @@
+name: unittest
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  checks: write
+  pull-requests: write
+
+jobs:
+  unittest:
+    # only run on pull request
+    if: ${{ github.event.issue.pull_request && (startsWith(github.event.comment.body, '/unittest')) && (github.event.comment.author_association == 'COLLABORATOR' || github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER') }}
+    runs-on: self-hosted
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        path: tuft-${{ github.run_id }}
+        ref: refs/pull/${{ github.event.issue.number }}/head
+
+    - name: Setup docker compose
+      working-directory: tuft-${{ github.run_id }}/.github/workflows/docker
+      run: |
+        docker compose up -d
+        sleep 15s
+
+    - name: Check ray status
+      working-directory: tuft-${{ github.run_id }}/.github/workflows/docker
+      run: |
+        MAX_RETRIES=20
+        RETRY_INTERVAL=5
+        for i in $(seq 1 $MAX_RETRIES); do
+          if docker compose exec tuft-node-1 bash -c "source /opt/venv/bin/activate && ray status" \
+            && docker compose exec tuft-node-2 bash -c "source /opt/venv/bin/activate && ray status"; then
+            break
+          fi
+          echo "Waiting for ray cluster to be ready... ($i/$MAX_RETRIES)"
+          sleep $RETRY_INTERVAL
+          if [ "$i" -eq "$MAX_RETRIES" ]; then
+            echo "Ray cluster failed to start after $MAX_RETRIES retries."
+            exit 1
+          fi
+        done
+
+    - name: Run unittest
+      working-directory: tuft-${{ github.run_id }}/.github/workflows/docker
+      # set a github env variable to indicate tests were run, so that subsequent steps can check it
+      run: |
+        echo "tests_run=true" >> $GITHUB_ENV
+        docker compose exec tuft-node-1 bash -c "source /opt/venv/bin/activate && pytest tests -v -s --gpu --basetemp /mnt/checkpoints --ctrf report.json"
+
+    - name: Convert report.json time to ms
+      working-directory: tuft-${{ github.run_id }}
+      if: env.tests_run == 'true' || failure()
+      run: |
+        REPORT=report.json
+        if [ -f "$REPORT" ]; then
+          jq '(.results.tests[] | .duration, .start, .stop) |= (. * 1000) | (.results.summary.start, .results.summary.stop) |= (. * 1000)' "$REPORT" > "$REPORT.tmp" && mv "$REPORT.tmp" "$REPORT"
+        fi
+
+    - name: Clean checkpoint dir
+      working-directory: tuft-${{ github.run_id }}/.github/workflows/docker
+      if: always()
+      run: |
+        docker compose exec tuft-node-1 rm -rf /mnt/checkpoints/*
+      continue-on-error: true
+
+    - name: Upload test results
+      if: env.tests_run == 'true' || failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: pytest-results
+        path: tuft-${{ github.run_id }}/report.json
+      continue-on-error: true
+
+    - name: Publish Test Report
+      if: env.tests_run == 'true' || failure()
+      uses: ctrf-io/github-test-reporter@v1
+      with:
+        report-path: tuft-${{ github.run_id }}/report.json
+        summary: true
+        pull-request: false
+        issue: ${{ github.event.issue.number }}
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      continue-on-error: true
+
+    - name: Remove docker compose
+      working-directory: tuft-${{ github.run_id }}/.github/workflows/docker
+      if: always()
+      run: |
+        docker compose down --remove-orphans
+      continue-on-error: true
+
+    - name: Cleanup workspace
+      if: always()
+      run: |
+        rm -rf tuft-${{ github.run_id }} 2>/dev/null
+      continue-on-error: true

tuft-0.1.1/.gitignore

@@ -0,0 +1,72 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+.env
+.env.*
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Pyright
+pyrightconfig.json
+
+# IDEs / editors
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# Ignore uv lockfile
+uv.lock
+
+# Ignore rdb files
+*.rdb
+
+# Sync history
+.sync_history