Update CI/CD workflow and enhance contributing guidelines (#51)

* chore: Update CI/CD workflow to support multiple Python versions and add contributing guidelines

- Modify CI/CD workflow to enforce Python 3.x and support versions 3.10, 3.11, and 3.12.
- Add a new yamllint configuration file for consistent YAML formatting.
- Create a contributing guide with setup instructions and CI expectations.
- Enhance README with instructions for creating a reproducible Python environment using pyenv and venv.
- Introduce a dev-setup script to automate environment setup.
- Ensure project root and source paths are included in test configurations.

* Update dev-setup.sh

Co-authored-by: Copilot <[email protected]>

* fix: Update Python version in CI configuration to 3.10

* fix: Disable ChromaDB anonymized telemetry for local development

* ci: quote python versions in workflow matrix to avoid YAML float parsing

---------

Co-authored-by: Copilot <[email protected]>

.github/workflows/main.yml

@@ -26,6 +26,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
+          # ensure CI enforces modern Python versions
           python-version: "3.10"
       - name: Install dev dependencies
         run: |
@@ -43,6 +44,12 @@ jobs:
   build-and-test:
     name: Build and test
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Quote versions so YAML treats them as strings. Unquoted 3.10 can be parsed as
+        # a float (3.1) which causes actions/setup-python to attempt to install the wrong
+        # runtime. Use '3.10', '3.11', etc.
+        python-version: ['3.10', '3.11', '3.12']
     env:
       PYTHONPATH: ${{ github.workspace }}
     steps:
@@ -53,7 +60,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -95,7 +102,8 @@ jobs:
         run: |
           set -e
           echo "Triggering deploy for Render service $RENDER_SERVICE_ID"
-          response=$(curl -s -X POST "https://api.render.com/v1/services/${RENDER_SERVICE_ID}/deploys" \
+          response=$(curl -s -X POST \
+            "https://api.render.com/v1/services/${RENDER_SERVICE_ID}/deploys" \
             -H "Authorization: Bearer ${RENDER_API_KEY}" \
             -H "Content-Type: application/json" \
             -d "{}")
@@ -122,8 +130,10 @@ jobs:
           retries=0
           max_retries=$MAX_RETRIES
           delay=$INITIAL_DELAY
-          while [ $retries -lt $max_retries ]; do
-            resp=$(curl -s -H "Authorization: Bearer ${RENDER_API_KEY}" "https://api.render.com/v1/services/${RENDER_SERVICE_ID}/deploys/${deploy_id}")
+            while [ $retries -lt $max_retries ]; do
+            resp=$(curl -s \
+              -H "Authorization: Bearer ${RENDER_API_KEY}" \
+              "https://api.render.com/v1/services/${RENDER_SERVICE_ID}/deploys/${deploy_id}")
             status=$(echo "$resp" | jq -r '.status')
             echo "Deploy status: $status"
             # Treat common Render success-like statuses as success so we proceed.
@@ -195,6 +205,9 @@ jobs:
           # create PR using GitHub API
           PR_TITLE="chore: update deployed.md after deploy"
           PR_BODY="Automated update of deployed.md after successful deploy."
-          curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" -H "Accept: application/vnd.github.v3+json" \
-            https://api.github.com/repos/${{ github.repository }}/pulls \
-            -d "{\"title\": \"${PR_TITLE}\", \"head\": \"${BRANCH_NAME}\", \"base\": \"main\", \"body\": \"${PR_BODY}\"}"
+          PR_PAYLOAD=$(printf '{"title":"%s","head":"%s","base":"main","body":"%s"}' "$PR_TITLE" "$BRANCH_NAME" "$PR_BODY")
+          curl -s -X POST \
+            -H "Authorization: token $GITHUB_TOKEN" \
+            -H "Accept: application/vnd.github.v3+json" \
+            "https://api.github.com/repos/${{ github.repository }}/pulls" \
+            -d "$PR_PAYLOAD"

.yamllint

@@ -0,0 +1,10 @@
+---
+# Repository yamllint configuration for msse-ai-engineering
+# Relax rules that commonly conflict with GitHub Actions workflow formatting
+extends: default
+rules:
+  document-start: disable
+  truthy: disable
+  line-length:
+    max: 140
+    level: error

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for wanting to contribute! This repository uses a strict CI and formatting policy to keep code consistent.
+
+## Recommended local setup
+
+We recommend using `pyenv` + `venv` to create a reproducible development environment. A helper script `dev-setup.sh` is included to automate the steps:
+
+```bash
+# Run the helper script (default Python version can be overridden)
+./dev-setup.sh 3.11.4
+source venv/bin/activate
+
+# Install pre-commit hooks
+pip install -r dev-requirements.txt
+pre-commit install
+```
+
+## Before opening a PR
+
+- Run formatting and linting: `make format` and `make ci-check`
+- Run tests: `pytest`
+- Ensure pre-commit hooks pass: `pre-commit run --all-files`
+
+## CI expectations
+
+- CI runs pre-commit checks and the full test suite on PRs
+- The project enforces Python >=3.10 in CI
+
+Please open issues or PRs against `main` and follow the branch naming conventions described in the README.

README.md

@@ -242,6 +242,32 @@ The application uses a comprehensive synthetic corpus of corporate policy docume
 - Git
 - OpenRouter API key (free tier available)
 
+#### Recommended: Create a reproducible Python environment with pyenv + venv
+
+If you used an older Python (for example 3.8) you'll hit build errors when installing modern ML packages like `tokenizers` and `sentence-transformers`. The steps below create a clean Python 3.11 environment and install project dependencies.
+
+```bash
+# Install pyenv (Homebrew) if you don't have it:
+#   brew update && brew install pyenv
+
+# Install a modern Python (example: 3.11.4)
+pyenv install 3.11.4
+
+# Use the newly installed version for this project (creates .python-version)
+pyenv local 3.11.4
+
+# Create a virtual environment and activate it
+python -m venv venv
+source venv/bin/activate
+
+# Upgrade packaging tools and install dependencies
+python -m pip install --upgrade pip setuptools wheel
+pip install -r requirements.txt
+pip install -r dev-requirements.txt || true
+```
+
+If you prefer not to use `pyenv`, install Python 3.10+ from python.org or Homebrew and create the `venv` with the system `python3`.
+
 ### 1. Repository Setup
 
 ```bash
@@ -251,6 +277,10 @@ cd msse-ai-engineering
 
 ### 2. Environment Setup
 
+Two supported flows are provided: a minimal venv-only flow and a reproducible pyenv+venv flow.
+
+Minimal (system Python 3.10+):
+
 ```bash
 # Create and activate virtual environment
 python3 -m venv venv
@@ -263,6 +293,14 @@ pip install -r requirements.txt
 pip install -r dev-requirements.txt
 ```
 
+Reproducible (recommended — uses pyenv to install a pinned Python and create a clean venv):
+
+```bash
+# Use the helper script to install pyenv Python and create a venv
+./dev-setup.sh 3.11.4
+source venv/bin/activate
+```
+
 ### 3. Configuration
 
 ```bash

app.py

@@ -1,5 +1,17 @@
 from flask import Flask, jsonify, render_template, request
 
+# Disable ChromaDB anonymized telemetry for local development so the
+# library doesn't attempt to call external PostHog telemetry endpoints.
+# This avoids noisy errors in server logs and respects developer privacy.
+try:
+    import chromadb
+
+    # Turn off anonymized telemetry (the chromadb package defaults this to True)
+    chromadb.configure(anonymized_telemetry=False)
+except Exception:
+    # If chromadb isn't installed in this environment yet, ignore silently.
+    pass
+
 app = Flask(__name__)
 
 

dev-setup.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# dev-setup.sh - create a reproducible development environment (pyenv + venv)
+# Usage: ./dev-setup.sh [python-version]
+
+set -euo pipefail
+PYTHON_VERSION=${1:-3.11.4}
+
+echo "Using python version: ${PYTHON_VERSION}"
+
+if ! command -v pyenv >/dev/null 2>&1; then
+  echo "pyenv not found. Install via Homebrew: brew install pyenv"
+  exit 1
+fi
+
+pyenv install -s "${PYTHON_VERSION}"
+pyenv local "${PYTHON_VERSION}"
+
+# Recreate venv
+rm -rf venv
+pyenv exec python -m venv venv
+
+# Activate and install
+# shellcheck source=/dev/null
+source venv/bin/activate
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install -r requirements.txt
+if [ -f dev-requirements.txt ]; then
+  python -m pip install -r dev-requirements.txt
+fi
+
+echo "Development environment ready. Activate with: source venv/bin/activate"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.black]
 line-length = 88
-target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
+target-version = ['py310', 'py311', 'py312']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
@@ -39,3 +39,15 @@ filterwarnings = [
     "ignore::DeprecationWarning",
     "ignore::PendingDeprecationWarning",
 ]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "msse-ai-engineering"
+version = "0.0.0"
+description = "MSSE AI Engineering - RAG application"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [ { name = "msse-ai-engineering" } ]

tests/conftest.py

@@ -0,0 +1,12 @@
+import os
+import sys
+
+# Ensure project root and src are on sys.path for tests
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+SRC_PATH = os.path.join(PROJECT_ROOT, "src")
+
+if PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, PROJECT_ROOT)
+
+if SRC_PATH not in sys.path:
+    sys.path.insert(0, SRC_PATH)