# Castorini Onboard

> Use when onboarding to nuggetizer, ragnarok, rank_llm, or umbrela and you need development environment setup for one repo or several repos at once, including clone-if-needed, uv or pip installation paths, shared virtualenv reuse, and smoke tests.

- **Type:** Skill
- **Install:** `agentstack add skill-castorini-castorini-skills-castorini-onboard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [castorini](https://agentstack.voostack.com/s/castorini)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [castorini](https://github.com/castorini)
- **Source:** https://github.com/castorini/castorini-skills/tree/main/skills/castorini-onboard

## Install

```sh
agentstack add skill-castorini-castorini-skills-castorini-onboard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Castorini Onboard

Unified development environment setup for the Castorini Python repos, whether the user wants one repo or several.

## Supported Repos

| Repo | PyPI Name | CLI Binary | GitHub |
|------|-----------|------------|--------|
| nuggetizer | `nuggetizer` | `nuggetizer` | `castorini/nuggetizer` |
| ragnarok | `pyragnarok` | `ragnarok` | `castorini/ragnarok` |
| rank_llm | `rank-llm` | `rank-llm` | `castorini/rank_llm` |
| umbrela | `umbrela` | `umbrela` | `castorini/umbrela` |

## Context Detection

1. If cwd is inside one of the 4 repos (check for `pyproject.toml` with matching project name) → install that one.
2. If the user explicitly asks for one repo, install only that repo.
3. If cwd is the monorepo root or elsewhere and the request is ambiguous → ask which repo(s) to install, or install all if the user says so.

## Prerequisites

- Python 3.11+
- Git (SSH access to `github.com:castorini`)

## uv Detection

```bash
command -v uv
```

If present, use uv silently. If absent, ask the user once: install uv or proceed with pip.

## Virtual Environment Preference

- Prefer a shared `.venv-shared` in the current workspace root over repo-local `.venv` directories.
- Before creating any environment, check whether `.venv-shared` already exists in the current workspace root and reuse it if present.
- Only fall back to a repo-local environment if the shared environment is unavailable or the user explicitly asks for isolation.

## Install Flow

1. Resolve which repository or repositories are in scope.
2. Clone any missing repositories with SSH access to `castorini/`.
3. Reuse `.venv-shared` when it already exists in the workspace root.
4. Prefer `uv` for sync and dependency-group support.
5. Fall back to `pip` only when `uv` is unavailable or the user explicitly asks.
6. For the common multi-repo cloud/API source install, prefer one shared editable install command:

```bash
uv pip install \
  -e './ragnarok[cloud,api]' \
  -e './nuggetizer[api]' \
  -e './umbrela[cloud,api]' \
  -e './rank_llm[openai,api]'
```

This pulls OpenAI support for all four repos and API or `uvicorn` support for each repo from its own declared extras instead of relying on an indirect transitive install from another package.

7. Run the repo CLI `doctor --output json` smoke test after install.
8. Run `pre-commit install` in each repository after a source install.

## Post-Install (all source installs)

```bash
pre-commit install
```

## Reference Files

- `references/extras.md` — Per-repo optional dependency stacks
- `references/install-recipes.md` — Per-repo clone, install, and smoke-test command sequences

## Gotchas

- `uv sync --group dev` understands dependency groups; `pip install -e .` does not. If you fall back to pip, install dev tools manually.
- `ragnarok` uses the package name `pyragnarok` on PyPI even though the repo and CLI command are `ragnarok`.
- `rank_llm` uses the package name and CLI binary `rank-llm`, while the repository and import package are spelled `rank_llm`.
- `rank_llm` supports `openai` and `api` as separate extras; use both when the user wants OpenAI-backed reranking plus HTTP serving helpers.
- `umbrela` only needs Java 21 for `pyserini` evaluation workflows, not for the default cloud-oriented development install.
- When reusing `.venv-shared`, make sure it was created with a Python version compatible with the target repo instead of blindly reusing an older interpreter.
- Run smoke tests from inside the target repository so editable installs and local entry points resolve correctly.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [castorini](https://github.com/castorini)
- **Source:** [castorini/castorini-skills](https://github.com/castorini/castorini-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-castorini-castorini-skills-castorini-onboard
- Seller: https://agentstack.voostack.com/s/castorini
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.