---

name: baleen-multihop description: "Optional ColBERT Baleen multi-hop retrieval extension: HopSearcher context search, Baleen engine loops, Condenser fact selection, collectionX format, and artifact caveats. Use when tasks mention Baleen, multi-hop retrieval, condensed retrieval, HopSearcher, Condenser, collectionX, or L1/L2 condenser checkpoints." disable-model-invocation: true metadata: disco-role: operating license: MIT

Baleen Multi-hop

Use this sub-skill for ColBERT's optional Baleen multi-hop retrieval components, not for ordinary one-hop ColBERT indexing or search. Baleen composes a ColBERT Searcher variant with an Electra-based Condenser to retrieve passages, select sentence-level facts, and feed those facts as context into later hops.

Route here when

• The user asks about Baleen, multi-hop retrieval, condensed retrieval, hop-aware search, HopSearcher, Condenser, collectionX, or L1/L2 condenser checkpoints.
• The code path involves baleen.engine.Baleen, baleen.hop_searcher.HopSearcher, baleen.condenser.condense.Condenser, baleen.condenser.model.ElectraReader, or baleen.condenser.tokenization.AnswerAwareTokenizer.
• The user has, or needs to reason about, a built ColBERT index plus Baleen-specific sentence JSONL and condenser checkpoint artifacts.
• The safe answer is to inspect imports/signatures, explain prerequisites, plan an adaptation, or diagnose why a full Baleen run cannot be validated locally.

Route elsewhere when

• Use indexing-and-search for normal Indexer, Searcher, collection TSVs, one-hop search, or ranking files.
• Use training-and-distillation for training or fine-tuning ColBERT retriever checkpoints.
• Use data/evaluation guidance for non-Baleen data conversion and metrics; keep only collectionX sentence-format notes here.
• Use modeling/tokenization guidance for ColBERT checkpoint internals unless the tokenizer issue is specifically Baleen's answer-aware condenser tokenizer.

Safe operating stance

Baleen is bundled as a research-style extension. Imports and source signatures can be inspected on CPU, but end-to-end multi-hop retrieval usually needs local ColBERT index artifacts, a retrieval checkpoint, two Baleen Electra reader checkpoints, a compatible sentence-level collectionX file, and often CUDA-capable devices. Do not promise full execution from package import success alone.

Start by confirming artifacts and device constraints. If the user is CPU-only or lacks checkpoints/data, run the import inspector, explain what is available, and provide a static adaptation plan rather than attempting retrieval.

Common actions

• Use references/api-reference.md when you need source-backed class/function behavior, signatures, and composition notes.
• Use references/baleen-workflows.md when planning a safe multi-hop flow, validating artifact shape, or explaining how facts become context.
• Use references/troubleshooting.md for install/import, optional dependency, CUDA/device, checkpoint, collectionX, API misuse, and depth/hop failures.
• Use scripts/inspect_baleen_imports.py when you need deterministic import/signature diagnostics without loading checkpoints, building indexes, downloading datasets, or running retrieval.

Minimal diagnostic

From an environment where colbert-ai is installed and colbert is importable:

python scripts/inspect_baleen_imports.py --tiny-fixture

Add --json for machine-readable output. Treat a passing report as evidence that Baleen import surfaces and loader behavior are available, not as evidence that the user's checkpoints, GPU, index, or full multi-hop workflow will run.