chore: introduce asdf to manage tool versions

.github/actions/setup-holmes-env/action.yml

@@ -23,24 +23,23 @@ runs:
       with:
         python-version: ${{ inputs.python-version }}
 
-    - name: Install Python dependencies and Poetry
+    # asdf-vm/actions/install finds the .tool-versions from current directory or parent directories,
+    # but code is checked out in a subdirectory, so we need to copy it to the current directory to
+    # make sure asdf installs tools successfully.
+    - name: Copy asdf configuration file
       shell: bash
       run: |
-        python -m pip install --upgrade pip setuptools pyinstaller
-
-        # Install Poetry with specific version for consistency
-        curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
+        cp code/.tool-versions .
+    - name: Install Poetry
+      uses: asdf-vm/actions/install@v4
 
-        # Add Poetry to PATH
-        echo "$HOME/.local/bin" >> $GITHUB_PATH
-
-        # Configure Poetry to not create virtualenvs (we use system Python in CI)
-        $HOME/.local/bin/poetry config virtualenvs.create false
-
-    - name: Install project dependencies
+    - name: Configure Poetry and install dependencies
       shell: bash
       working-directory: ${{ inputs.working-directory }}
       run: |
+        # Configure Poetry to not create virtualenvs (we use system Python in CI)
+        poetry config virtualenvs.create false
+        python -m pip install --upgrade pip setuptools pyinstaller
         poetry install --no-root --with dev
 
     - name: Install kubectl

.github/workflows/build-and-deploy-docs.yaml

@@ -29,10 +29,11 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - name: Install Poetry
+        uses: asdf-vm/actions/install@v4
+      - name: Configure Poetry and install dependencies
         run: |
-          curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
           poetry config virtualenvs.create false
-      - run: poetry install --with dev
+          poetry install --with dev
       # Deploy versioned docs on stable release tags only (skip alpha, beta, rc)
       - name: Deploy versioned docs (release)
         if: startsWith(github.ref, 'refs/tags/') && !contains(github.ref, 'alpha') && !contains(github.ref, 'beta') && !contains(github.ref, 'rc')

.github/workflows/build-and-test.yaml

@@ -95,16 +95,14 @@ jobs:
             poetry-${{ matrix.python-version }}-
 
       - name: Install Poetry
+        uses: asdf-vm/actions/install@v4
+
+      - name: Install dependencies
         run: |
           # setuptools provides the distutils shim needed by Poetry installer on Python 3.12+
           python -m pip install --upgrade pip setuptools
-          if ! command -v poetry &> /dev/null; then
-            curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
-          fi
           poetry config virtualenvs.create false
-
-      - name: Install dependencies
-        run: poetry install --no-root --with dev
+          poetry install --no-root --with dev
 
       - name: Run tests
         shell: bash
@@ -168,18 +166,15 @@ jobs:
             poetry-3.11-
 
       - name: Install Poetry
-        run: |
-          python -m pip install --upgrade pip setuptools
-          if ! command -v poetry &> /dev/null; then
-            curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
-          fi
-          poetry config virtualenvs.create false
+        uses: asdf-vm/actions/install@v4
 
       - name: Install dependencies and build
         # if you change something here, you must also change it in .github/workflows/build-binaries-and-brew.yaml
         run: |
           python -m pip install --upgrade pip "setuptools<75" "pyinstaller>=6.11"
 
+          poetry config virtualenvs.create false
+
           poetry install --no-root
 
           sudo apt-get install -y binutils

.github/workflows/build-binaries-and-brew.yaml

@@ -33,19 +33,25 @@ jobs:
       with:
         python-version: '3.11'
 
+    - name: Install Poetry (Unix)
+      if: matrix.platform != 'windows'
+      uses: asdf-vm/actions/install@v4
+
     - name: Install dependencies (Unix)
       if: matrix.platform != 'windows'
       run: |
         python -m pip install --upgrade pip "setuptools<75" "pyinstaller>=6.11"
-        curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
         poetry config virtualenvs.create false
         poetry install --no-root
 
-    - name: Install dependencies (Windows)
+    - name: Install poetry and dependencies (Windows)
       if: matrix.platform == 'windows'
       run: |
         python -m pip install --upgrade pip "setuptools<75" "pyinstaller>=6.11"
-        curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
+        # asdf-vm does not support windows, so we install poetry by obtaining poetry version from .tool-version. 
+        $POETRY_VERSION = (Get-Content .tool-versions | Select-String '^poetry ').ToString().Split(' ')[1]
+        Write-Host "Installing Poetry version: $POETRY_VERSION"
+        (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python - --version $POETRY_VERSION
         C:\Users\runneradmin\AppData\Roaming\Python\Scripts\poetry config virtualenvs.create false
         C:\Users\runneradmin\AppData\Roaming\Python\Scripts\poetry install --no-root
 

.github/workflows/cli-performance.yaml

@@ -31,15 +31,14 @@ jobs:
         with:
           python-version: '3.12'
 
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: latest
-          virtualenvs-create: true
-          virtualenvs-in-project: true
 
-      - name: Install dependencies
-        run: poetry install --no-interaction
+      - name: Install Poetry
+        uses: asdf-vm/actions/install@v4
+      - name: Configure poetry and install dependencies
+        run: |
+          poetry config virtualenvs.create true
+          poetry config virtualenvs.in-project true
+          poetry install --no-interaction
 
       - name: Run benchmarks
         id: benchmark

.github/workflows/publish-pypi.yaml

@@ -17,17 +17,17 @@ jobs:
         python-version: '3.11'
 
     - name: Install Poetry
+      uses: asdf-vm/actions/install@v4
+
+    - name: Configure Poetry and install dependencies
       run: |
-        curl -sSL https://install.python-poetry.org | python3 - --version 1.4.0
         poetry config virtualenvs.create false
+        poetry install --no-root
 
     - name: Update package version
       run: |
         sed -i 's/__version__ = .*/__version__ = "${{ github.ref_name }}"/g' holmes/__init__.py
         sed -i 's/version = "0.0.0"/version = "${{ github.ref_name }}"/g' pyproject.toml
 
-    - name: Install dependencies
-      run: poetry install --no-root
-
     - name: Publish to PyPI
       run: poetry publish --build -u __token__ -p ${{ secrets.PYPI_TOKEN }}

.tool-versions

@@ -0,0 +1 @@
+poetry 2.3.2

CONTRIBUTING.md

@@ -8,12 +8,16 @@ Please make sure to read and observe our [Governance](./GOVERNANCE.md) docs.
 
 ### Prerequisites
 
+- [asdf](https://asdf-vm.com/) to manage tool versions — after installing, run:
+  ```bash
+  asdf install
+  ```
+  This will install the correct versions of all required tools (e.g., Poetry) as specified in `.tool-versions`.
 - Python `3.11` to `3.13` (Python 3.14+ is not yet supported due to a dependency limitation in prometrix)
   - **If using Python 3.14**, you can disable the Prometheus toolset to work around the issue:
     ```bash
     export DISABLE_PROMETHEUS_TOOLSET=true
     ```
-- Poetry `1.8.4` or higher
 - Git
 - An LLM API key (required to use and test HolmesGPT)
   - HolmesGPT supports multiple providers: OpenAI, Anthropic, Azure, Google Vertex AI, and more