Installation

ESML targets Python ≥ 3.14 and R ≥ 4.3. Both languages are supported independently; you do not need both unless you are running the full dual-language pipeline. Python 3.15 is the recommended primary version.

Python

From PyPI (forthcoming public release):

pip install esml

Editable install from source (development):

git clone <repo>
cd esml/dev/sphinx/project

# Primary: Python 3.15 (recommended)
python3.15 -m venv .venv
PKG_CONFIG_PATH="/opt/homebrew/opt/openblas/lib/pkgconfig" \
    .venv/bin/pip install -e ".[test,docs]"

# Secondary: Python 3.14 (adds codecarbon with pydantic support)
python3.14 -m venv .venv-314
.venv-314/bin/pip install -e ".[test,docs,carbon]"

Note

On macOS with Apple Silicon, scipy requires OpenBLAS. Set PKG_CONFIG_PATH="/opt/homebrew/opt/openblas/lib/pkgconfig" before pip install.

The [carbon] extra (CodeCarbon emissions tracking) requires Python ≤ 3.14 due to pydantic-core Rust dependencies. On Python 3.15+, ESML uses the built-in esml.emissions tracker instead.

Bootstrap script (creates .venv, installs Python + R deps):

libexec/config/tests/rtests/bootstrap_esml.sh

R

Install from local source:

install.packages("r-package/esml", repos = NULL, type = "source")

Required R packages (installed automatically):

install.packages(c("survey", "testthat"), repos = "https://cloud.r-project.org/")

Note

On Apple Silicon, use CRAN R (not Homebrew R) to avoid RSQLite segfaults. Download from https://cran.r-project.org. Run brew unlink r if needed. Current recommended: R 4.5.3 (CRAN).

macOS

# Install CRAN R (not brew R — see note above)
curl -O https://cran.r-project.org/bin/macosx/big-sur-arm64/base/R-4.5.3-arm64.pkg
sudo installer -pkg R-4.5.3-arm64.pkg -target /
brew unlink r 2>/dev/null

# Python 3.15
brew install python@3.15
pip install esml

Linux

# Debian/Ubuntu
sudo apt-get install r-base python3 python3-pip
pip3 install esml

Windows

winget install -e --id RProject.R
winget install -e --id Python.Python.3.14
pip install esml

Verifying the install

esml list-modules          # prints the 21 CPADS analysis modules
esml doctor                # checks LLM providers, datasets, R, Docker
esml --help

library(esml)
list_esml_modules()

LLM provider setup

ESML supports LLM providers tried in priority order. The FreeAPI client is vendored (esml.freeapi) — no external SDK or API key required.

Priority	Provider	How to enable
1	Ollama (local, private)	curl -fsSL https://ollama.com/install.sh | sh && ollama pull qwen2.5:7b
2	OllamaFreeAPI (free, no key)	Built-in. No setup needed. Uses gpt-oss:20b (Gemma3) by default.
3	Gemini (free tier)	export GEMINI_API_KEY=... (free key at aistudio.google.com)
4	Local fallback	Automatic. Keyword-matched help text, no network required.

If no provider is configured, esml ask returns a static help response. Run esml doctor to see which providers are currently available.