{"record":{"id":"05bb768927b6ef0f","repo":"headroomlabs-ai/headroom","slug":"sentence-transformers-is-required-for-localembedde","errorCode":null,"errorMessage":"sentence-transformers is required for LocalEmbedder. Install it with: pip install sentence-transformers","messagePattern":"sentence-transformers is required for LocalEmbedder\\. Install it with: pip install sentence-transformers","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/memory/adapters/embedders.py","lineNumber":234,"sourceCode":"            ImportError: If sentence-transformers is not installed.\n        \"\"\"\n        self._model_name = model_name or ML_MODEL_DEFAULTS.sentence_transformer\n        self._requested_device = device\n        self._model: SentenceTransformer | None = None\n        self._device: str | None = None\n        self._dimension: int | None = None\n        self._lock = asyncio.Lock()\n        # Dedicated single-worker executor, created only when the resolved device\n        # is MPS (see _load_model). torch-MPS is not thread-safe, so every encode()\n        # must run on one thread. Stays None for CPU/CUDA → default shared executor.\n        self._executor: ThreadPoolExecutor | None = None\n\n    def _check_dependencies(self) -> None:\n        \"\"\"Check that required dependencies are installed.\"\"\"\n        try:\n            import sentence_transformers  # noqa: F401\n        except ImportError as e:\n            raise ImportError(\n                \"sentence-transformers is required for LocalEmbedder. \"\n                \"Install it with: pip install sentence-transformers\"\n            ) from e\n\n    def _detect_device(self) -> str:\n        \"\"\"Auto-detect the best available device.\n\n        Returns:\n            Device string: \"cuda\", \"mps\", or \"cpu\".\n        \"\"\"\n        import torch\n\n        if torch.cuda.is_available():\n            logger.info(\"CUDA device detected, using GPU\")\n            return \"cuda\"\n        elif torch.backends.mps.is_available():\n            logger.info(\"MPS device detected, using Apple Silicon GPU\")\n            return \"mps\"","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/adapters/embedders.py#L216-L252","documentation":"LocalEmbedder (sentence-transformers based) checks for the sentence_transformers import in __init__ via _check_dependencies and raises this ImportError when the optional dependency is absent. The original ImportError is chained. Note: even with the package installed, a missing torch or a broken install can surface here first since sentence_transformers imports torch transitively.","triggerScenarios":"Instantiating LocalEmbedder() in an environment where sentence-transformers (or its torch dependency) is not installed — e.g. base headroom install without the [local-embeddings] extra, fresh venv, or a Docker image trimmed of ML deps.","commonSituations":"pip install headroom without extras then using the local embedding path; CI slim images; dependency resolver dropping sentence-transformers during a conflicting upgrade; Apple Silicon wheels missing causing import failure that masquerades as absence.","solutions":["pip install sentence-transformers (as the message says) in the active environment.","Prefer the headroom extra if provided (e.g. pip install 'headroom[local]') so the whole set stays consistent.","Verify with python -c \"import sentence_transformers\" — if that fails with a different error (e.g. torch/MPS), fix that underlying install.","If you don't need local embeddings, switch to OpenAIEmbedder or OllamaEmbedder instead."],"exampleFix":"# before\nfrom headroom.memory.adapters.embedders import LocalEmbedder\nemb = LocalEmbedder()  # ImportError: sentence-transformers is required\n\n# after (shell)\npip install sentence-transformers\nemb = LocalEmbedder()","handlingStrategy":"validation","validationCode":"def local_embedder_available() -> bool:\n    try:\n        import sentence_transformers  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not local_embedder_available():\n    raise SystemExit(\"pip install sentence-transformers before using LocalEmbedder\")","typeGuard":null,"tryCatchPattern":"try:\n    emb = LocalEmbedder()\nexcept ImportError as e:\n    if \"sentence-transformers\" in str(e):\n        raise SystemExit(\"Missing optional dep; run: pip install sentence-transformers\") from e\n    raise","preventionTips":["Declare the local-embeddings extra in your project's dependencies if you use LocalEmbedder.","Probe importability in a startup preflight (one cheap import check) instead of failing mid-request.","Bake sentence-transformers + torch into deployment images; both are heavy and slow to install at runtime."],"tags":["dependencies","import","embeddings","memory","optional-extra"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}