Python Environment Rules

Required Python Version

• Windows: Python 3.11.9
• Linux: Python 3.11.9 (or python3.11 from package manager)
• macOS: Python 3.11.9 (or python3.11 via Homebrew)

Virtual Environment Setup

Before running any Python command, ensure the virtual environment exists and is activated.

Creating the environment (if .venv/ does not exist)

# Windows
py -3.11 -m venv .venv

# Linux / macOS
python3.11 -m venv .venv

Activating the environment

Always activate before running Python:

# Windows (Git Bash / MSYS2)
source .venv/Scripts/activate

# Linux / macOS
source .venv/bin/activate

Installing dependencies

After activation, install required packages:

pip install --upgrade pip
pip install matplotlib numpy tiktoken

Rules for All Python Execution

1. Never use the system Python. Always run Python inside the .venv environment.
2. Call the venv Python directly by path — no activation needed, works regardless of shell state, and survives subshell boundaries. Resolve the OS-correct path with:

   PYTHON="$([ -f .venv/Scripts/python ] && echo .venv/Scripts/python || echo .venv/bin/python)"
   $PYTHON benchmark/charts.py benchmark/results

   Use the same pattern for pip:

   PIP="$([ -f .venv/Scripts/pip ] && echo .venv/Scripts/pip || echo .venv/bin/pip)"
   $PIP install matplotlib

   • .venv/Scripts/python — Windows (Git Bash / MSYS2 / PowerShell)
   • .venv/bin/python — Linux / macOS
3. If .venv/ does not exist, create it before proceeding. Do not skip this step.
4. If a package is missing, install it via the venv pip (see rule 2).
5. Do not add .venv/ to version control. It should be in .gitignore.