headroomlabs-ai/headroom · error · RuntimeError

EmbeddingScorer requires sentence-transformers. Install with

Error message

EmbeddingScorer requires sentence-transformers. Install with: pip install headroom[relevance]

What it means

Raised by create_scorer('embedding', ...) when the EmbeddingScorer reports sentence-transformers (via its is_available() probe) as unavailable. The embedding tier is an optional feature; the error tells you to install the 'relevance' extra rather than shipping the heavy dependency by default.

Source

Thrown at headroom/relevance/__init__.py:113

    Example:
        # Create default hybrid scorer (recommended)
        scorer = create_scorer()

        # Create BM25 scorer for zero-dependency environments
        scorer = create_scorer("bm25")

        # Create hybrid scorer with custom alpha
        scorer = create_scorer("hybrid", alpha=0.6, adaptive=True)
    """
    tier = tier.lower()

    if tier == "bm25":
        return BM25Scorer(**kwargs)

    elif tier == "embedding":
        if not EmbeddingScorer.is_available():
            raise RuntimeError(
                "EmbeddingScorer requires sentence-transformers. "
                "Install with: pip install headroom[relevance]"
            )
        return EmbeddingScorer(**kwargs)

    elif tier == "hybrid":
        return HybridScorer(**kwargs)

    else:
        valid_tiers = ["bm25", "embedding", "hybrid"]
        raise ValueError(f"Unknown scorer tier: {tier}. Valid tiers: {valid_tiers}")

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: pip install 'headroom[relevance]'.
2. If embeddings are optional in your app, fall back to create_scorer('bm25').
3. For Docker images, add the extra to the requirements layer that installs headroom.

Example fix

# before
scorer = create_scorer('embedding')  # RuntimeError

# after
# pip install 'headroom[relevance]' first
scorer = create_scorer('embedding')

from headroom.relevance import EmbeddingScorer, create_scorer

def build_scorer(**kw):
    if EmbeddingScorer.is_available():
        return create_scorer('embedding', **kw)
    logger.warning('embedding tier unavailable; falling back to bm25')
    return create_scorer('bm25', **kw)

from headroom.relevance import EmbeddingScorer

def embedding_available() -> bool:
    return bool(EmbeddingScorer.is_available())

try:
    scorer = create_scorer('embedding', **kwargs)
except RuntimeError as e:
    if 'sentence-transformers' in str(e):
        scorer = create_scorer('bm25', **kwargs)  # documented fallback
    else:
        raise

When it happens

Trigger: Calling create_scorer('embedding') or create_scorer('hybrid') in an environment where headroom was installed without the [relevance] extra and the embedding backend import fails.

Common situations: Base install (pip install headroom) used in a slim Docker image; CI environment without extras; upgrading headroom without reinstalling extras.

Related errors

• numpy is required for EmbeddingScorer. Install with: pip ins
• EmbeddingScorer requires fastembed. Install with: pip instal
• jinja2 is required for report generation. Install with: pip
• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/f9b6b8d78d1c77b5. Report an issue: GitHub.