| name | umbrela-install |
| description | Set up an umbrela development environment — checks Python 3.11+, installs via uv or pip with cloud extras, and verifies with doctor. Use when someone is onboarding, setting up a fresh clone, or troubleshooting their environment. |
umbrela Install
Development environment setup for umbrela — LLM-based relevance assessment of query-passage pairs.
Prerequisites
- Python 3.11+
- Git (SSH access to
github.com:castorini)
Verify Runtime
python3 --version
command -v uv
If uv is on PATH, use it silently. If not, ask the user once: install uv or proceed with pip.
Clone (if needed)
If no pyproject.toml in cwd:
git clone git@github.com:castorini/umbrela.git && cd umbrela
Install (source — preferred)
uv path
uv venv --python 3.11
source .venv/bin/activate
uv sync --group dev --extra cloud
pip path
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[cloud]"
pip install pre-commit pytest mypy ruff
PyPI alternative (mention but don't default to)
pip install umbrela
Smoke Test
umbrela doctor --output json
umbrela --help
Pre-commit (source installs)
pre-commit install
Reference Files
references/extras.md — Optional dependency stacks (cloud, hf, fastchat, pyserini)
Gotchas
- Java 21 is only needed if installing
--extra pyserini for evaluation workflows. The core umbrela package does not require Java.
- Dev dependencies use PEP 735
[dependency-groups] — only uv sync --group dev resolves them natively. With pip, install each package manually.
- MyPy is strict:
disallow_untyped_defs = true. All new functions need type annotations.
- Test directory is
tests/ (with an s).
