{"record":{"id":"171b7b6b58a63d19","repo":"headroomlabs-ai/headroom","slug":"numpy-is-required-for-embeddingscorer-install-wit","errorCode":null,"errorMessage":"numpy is required for EmbeddingScorer. Install with: pip install headroom[relevance]","messagePattern":"numpy is required for EmbeddingScorer\\. Install with: pip install headroom\\[relevance\\]","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/relevance/embedding.py","lineNumber":48,"sourceCode":"import os\nfrom typing import TYPE_CHECKING\n\nfrom .base import RelevanceScore, RelevanceScorer\n\n# numpy is an optional dependency - import lazily\n_numpy = None\n\n\ndef _get_numpy():\n    \"\"\"Lazily import numpy.\"\"\"\n    global _numpy\n    if _numpy is None:\n        try:\n            import numpy as np\n\n            _numpy = np\n        except ImportError as e:\n            raise ImportError(\n                \"numpy is required for EmbeddingScorer. \"\n                \"Install with: pip install headroom[relevance]\"\n            ) from e\n    return _numpy\n\n\nif TYPE_CHECKING:\n    from fastembed import TextEmbedding\n\nlogger = logging.getLogger(__name__)\n\n# Default model name. Same string used by the Rust embedding scorer.\nDEFAULT_MODEL_NAME = \"BAAI/bge-small-en-v1.5\"\n\n# Pinned revision of fastembed's underlying HF repo for the default model\n# (fastembed resolves \"BAAI/bge-small-en-v1.5\" -> \"qdrant/bge-small-en-v1.5-onnx-q\").\n# fastembed's TextEmbedding signature omits ``revision`` but forwards **kwargs to\n# huggingface_hub.snapshot_download, so passing it pins the download for","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/relevance/embedding.py#L30-L66","documentation":"Raised lazily by _get_numpy() in the embedding module the first time numpy is needed and the import fails. numpy is part of the optional [relevance] extra; the error surfaces only at use time because the import is deferred to keep base installs light.","triggerScenarios":"Calling any EmbeddingScorer scoring/embedding method in an environment where numpy is not installed, after having satisfied the fastembed availability probe.","commonSituations":"Partial installs where fastembed is present but numpy is missing or broken (wrong ABI for another package); slim containers; downgrading numpy-breaking environments.","solutions":["Install the extra: pip install 'headroom[relevance]' (pulls a compatible numpy).","Verify with 'python -c \"import numpy\"' in the same interpreter/venv your app runs in.","If numpy conflicts with another package, pin a version compatible with both or isolate headroom in its own venv."],"exampleFix":"# before\nscorer.score(query, docs)  # ImportError: numpy required\n\n# after\n# pip install 'headroom[relevance]'\nscorer.score(query, docs)","handlingStrategy":"fallback","validationCode":"def numpy_available() -> bool:\n    try:\n        import numpy  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not numpy_available():\n    scorer = create_scorer('bm25')  # avoid failing mid-request","typeGuard":"def numpy_available() -> bool:\n    try:\n        import numpy  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    score = scorer.score(query, docs)\nexcept ImportError as e:\n    if 'numpy' in str(e):\n        scorer = create_scorer('bm25')\n        score = scorer.score(query, docs)\n    else:\n        raise","preventionTips":["Smoke-test optional imports at startup: python -c 'import numpy, fastembed' in the app venv.","Install extras as one unit ('headroom[relevance]') so numpy and fastembed stay in sync.","Run dependency checks in the same interpreter the service uses, not the system one."],"tags":["dependencies","optional-feature","numpy","lazy-import"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}