{"record":{"id":"f9b6b8d78d1c77b5","repo":"headroomlabs-ai/headroom","slug":"embeddingscorer-requires-sentence-transformers-in","errorCode":null,"errorMessage":"EmbeddingScorer requires sentence-transformers. Install with: pip install headroom[relevance]","messagePattern":"EmbeddingScorer requires sentence-transformers\\. Install with: pip install headroom\\[relevance\\]","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"headroom/relevance/__init__.py","lineNumber":113,"sourceCode":"\n    Example:\n        # Create default hybrid scorer (recommended)\n        scorer = create_scorer()\n\n        # Create BM25 scorer for zero-dependency environments\n        scorer = create_scorer(\"bm25\")\n\n        # Create hybrid scorer with custom alpha\n        scorer = create_scorer(\"hybrid\", alpha=0.6, adaptive=True)\n    \"\"\"\n    tier = tier.lower()\n\n    if tier == \"bm25\":\n        return BM25Scorer(**kwargs)\n\n    elif tier == \"embedding\":\n        if not EmbeddingScorer.is_available():\n            raise RuntimeError(\n                \"EmbeddingScorer requires sentence-transformers. \"\n                \"Install with: pip install headroom[relevance]\"\n            )\n        return EmbeddingScorer(**kwargs)\n\n    elif tier == \"hybrid\":\n        return HybridScorer(**kwargs)\n\n    else:\n        valid_tiers = [\"bm25\", \"embedding\", \"hybrid\"]\n        raise ValueError(f\"Unknown scorer tier: {tier}. Valid tiers: {valid_tiers}\")\n","sourceCodeStart":95,"sourceCodeEnd":125,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/relevance/__init__.py#L95-L125","documentation":"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.","triggerScenarios":"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.","commonSituations":"Base install (pip install headroom) used in a slim Docker image; CI environment without extras; upgrading headroom without reinstalling extras.","solutions":["Install the extra: pip install 'headroom[relevance]'.","If embeddings are optional in your app, fall back to create_scorer('bm25').","For Docker images, add the extra to the requirements layer that installs headroom."],"exampleFix":"# before\nscorer = create_scorer('embedding')  # RuntimeError\n\n# after\n# pip install 'headroom[relevance]' first\nscorer = create_scorer('embedding')","handlingStrategy":"fallback","validationCode":"from headroom.relevance import EmbeddingScorer, create_scorer\n\ndef build_scorer(**kw):\n    if EmbeddingScorer.is_available():\n        return create_scorer('embedding', **kw)\n    logger.warning('embedding tier unavailable; falling back to bm25')\n    return create_scorer('bm25', **kw)","typeGuard":"from headroom.relevance import EmbeddingScorer\n\ndef embedding_available() -> bool:\n    return bool(EmbeddingScorer.is_available())","tryCatchPattern":"try:\n    scorer = create_scorer('embedding', **kwargs)\nexcept RuntimeError as e:\n    if 'sentence-transformers' in str(e):\n        scorer = create_scorer('bm25', **kwargs)  # documented fallback\n    else:\n        raise","preventionTips":["Install the [relevance] extra in every environment that selects the embedding tier.","Probe EmbeddingScorer.is_available() at startup and degrade to bm25 with a log line.","Record installed extras in your deployment manifest so slim images are caught before runtime."],"tags":["dependencies","optional-feature","relevance","installation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}