{"record":{"id":"2879b8cf08dc0dc9","repo":"headroomlabs-ai/headroom","slug":"strands-sdk-is-required-for-this-integration-inst-2879b8","errorCode":null,"errorMessage":"Strands SDK is required for this integration. Install with: pip install strands-agents","messagePattern":"Strands SDK is required for this integration\\. Install with: pip install strands-agents","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/strands/model.py","lineNumber":50,"sourceCode":"    ToolChoice = dict  # type: ignore[misc,assignment]\n    ToolSpec = dict  # type: ignore[misc,assignment]\n    SystemContentBlock = dict  # type: ignore[misc,assignment]\n\nT = TypeVar(\"T\")\n\nfrom headroom import HeadroomConfig  # noqa: E402\nfrom headroom.providers import OpenAIProvider  # noqa: E402\nfrom headroom.transforms import TransformPipeline  # noqa: E402\n\nfrom .providers import get_headroom_provider, get_model_name_from_strands  # noqa: E402\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_strands_available() -> None:\n    \"\"\"Raise ImportError if Strands SDK is not installed.\"\"\"\n    if not STRANDS_AVAILABLE:\n        raise ImportError(\n            \"Strands SDK is required for this integration. Install with: pip install strands-agents\"\n        )\n\n\ndef strands_available() -> bool:\n    \"\"\"Check if Strands SDK is installed.\"\"\"\n    return STRANDS_AVAILABLE\n\n\n@dataclass\nclass OptimizationMetrics:\n    \"\"\"Metrics from a single optimization pass.\"\"\"\n\n    request_id: str\n    timestamp: datetime\n    tokens_before: int\n    tokens_after: int\n    tokens_saved: int","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/strands/model.py#L32-L68","documentation":"Raised by _check_strands_available() in headroom/integrations/strands/model.py when STRANDS_AVAILABLE is False. It guards the Strands model wrapper (Headroom model class that routes through get_headroom_provider/get_model_name_from_strands and emits OptimizationMetrics per optimization pass) — the Strands equivalent of the LangChain chat model.","triggerScenarios":"Instantiating the Headroom Strands model class or using it as a Strands LLM backend when the strands-agents package is not importable; the file even uses `# noqa: E402` on imports because it sits after a large conditional import block, underlining that availability is resolved at module load.","commonSituations":"Swapping a Strands agent's model to the headroom-optimized one before installing strands-agents; version drift in strands-agents breaking the import; CI matrix cells that only install core headroom.","solutions":["Install `pip install strands-agents`","Probe with strands_available() from this module before selecting the model at runtime","Add strands-agents to the deployment lockfile"],"exampleFix":"# before\nfrom headroom.integrations.strands.model import HeadroomStrandsModel\nmodel = HeadroomStrandsModel(...)  # ImportError\n\n# after\n# pip install strands-agents\nfrom headroom.integrations.strands.model import HeadroomStrandsModel, strands_available\nif strands_available():\n    model = HeadroomStrandsModel(...)","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('strands'), 'pip install strands-agents before using the Headroom Strands model'","typeGuard":"from headroom.integrations.strands.model import strands_available\nmodel = HeadroomStrandsModel(...) if strands_available() else default_model","tryCatchPattern":"try:\n    model = HeadroomStrandsModel(...)\nexcept ImportError as e:\n    logger.warning('Falling back to plain Strands model: %s', e)\n    model = original_model","preventionTips":["Gate model selection behind strands_available() at agent construction time","Keep strands-agents pinned in the lockfile alongside headroom","Run integration tests on the exact image that ships to production"],"tags":["strands","model-wrapper","import-error","optional-dependency"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}