Handle the Numpy 3.13 issue (#2282)

#### Python 3.13 on macOS ARM: NumPy fails to install (builds from
source)

- Symptom: `make install` on Python 3.13 tries to build `numpy==2.0.x`
from source on macOS ARM and fails with C/C++ errors.
- Status: Ragas CI currently targets Python 3.9–3.12; Python 3.13 is
best-effort until upstream wheels are broadly available.

Workarounds:

1) Recommended: use Python 3.12
```bash
uv python install 3.12
uv venv -p 3.12 .venv-3.12
source .venv-3.12/bin/activate
uv sync --group dev
make check
```

2) Stay on Python 3.13 (best effort):
- Minimal install first to avoid heavy transitive pins:
```bash
uv venv -p 3.13 .venv-3.13
source .venv-3.13/bin/activate
uv pip install -e ".[dev-minimal]"
make check
```
- If you need extras, add gradually:
```bash
uv pip install "ragas[tracing,gdrive,ai-frameworks]"
```
- Prefer a prebuilt NumPy wheel (if available):
```bash
uv pip install "numpy>=2.1" --only-binary=:all:
```
If the resolver still pins to 2.0.x via transitive deps, temporarily set
`numpy>=2.1` locally and re-run `uv sync --group dev`.

3) Last resort: build NumPy locally
```bash
xcode-select --install
export SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"
export CC=clang
uv pip install numpy
```

Safe alternate-venv tip:
- Keep your project `.venv` untouched and use `.venv-3.12` /
`.venv-3.13`. Avoid `make install` in alt envs; prefer `uv` commands
directly. `make check` respects the active env via `uv run --active`.

Author: Prigoistic

DEVELOPMENT.md

@@ -386,6 +386,33 @@ uv run ruff check --no-fix    # Check issues without fixing
 - **Follow existing code style** (enforced by `make format`)
 
 ---
+#### Python 3.13 on macOS ARM: NumPy fails to install (builds from source)
+
+- Symptom: `make install` attempts to build `numpy==2.0.x` from source on Python 3.13 (no prebuilt wheel), failing with C/C++ errors.
+- Status: Ragas CI supports Python 3.9–3.12. Python 3.13 is not officially supported yet.
+
+Workarounds:
+1) Recommended: use Python 3.12
+```bash
+uv python install 3.12
+rm -rf .venv
+uv venv -p 3.12
+make install
+```
+
+2) Stay on 3.13 (best effort):
+- Install minimal first, then add extras as needed:
+```bash
+rm -rf .venv
+uv venv -p 3.13
+make install-minimal
+uv pip install "ragas[tracing,gdrive,ai-frameworks]"
+```
+- Or force a newer NumPy wheel:
+```bash
+uv pip install "numpy>=2.1" --only-binary=:all:
+```
+If conflicts pin NumPy to 2.0.x, temporarily set `numpy>=2.1` in `pyproject.toml` and run `uv sync --group dev`.
 
 **Happy coding! 🚀**
 

pyproject.toml

@@ -5,7 +5,7 @@ requires-python = ">=3.9"
 license = {file = "LICENSE"}
 dependencies = [
     # Core dependencies
-    "numpy",
+    "numpy>=1.21.0,<3.0.0",
     "datasets>=4.0.0",
     "tiktoken",
     "pydantic>=2.0.0",