headroomlabs-ai/headroom · error · ImportError

any-llm-sdk is required for AnyLLMBackend. Install with: pip

Error message

any-llm-sdk is required for AnyLLMBackend. Install with: pip install 'any-llm-sdk[all]'

What it means

AnyLLMBackend.__init__ raises ImportError when the optional any-llm-sdk dependency is not installed (ANYLLM_AVAILABLE is falsy at import time of the module). The constructor fails fast instead of deferring to a confusing ModuleNotFoundError at first request. The message includes the exact pip extra needed.

Source

Thrown at headroom/backends/anyllm.py:76

            return "auto"
        if choice_type == "any":
            return "required"
        if choice_type == "tool":
            return {"type": "function", "function": {"name": choice.get("name", "")}}
    return "auto"


class AnyLLMBackend(Backend):
    """Backend using any-llm for multi-provider support."""

    def __init__(
        self,
        provider: str = "openai",
        api_key: str | None = None,
        api_base: str | None = None,
    ):
        if not ANYLLM_AVAILABLE:
            raise ImportError(
                "any-llm-sdk is required for AnyLLMBackend. "
                "Install with: pip install 'any-llm-sdk[all]'"
            )

        self.provider = provider.lower()
        # Normalize empty-string overrides (e.g. an env var set to "") to None
        # so provider defaults stay active instead of forwarding a blank value.
        self.api_key = api_key or None
        self.api_base = api_base or None

        # Create the AnyLLM instance once and reuse. api_key/api_base are only
        # forwarded when set so providers keep their own env-var defaults
        # (e.g. OPENAI_API_KEY / OPENAI_BASE_URL) otherwise.
        create_kwargs: dict[str, Any] = {}
        if self.api_key is not None:
            create_kwargs["api_key"] = self.api_key
        if self.api_base is not None:
            create_kwargs["api_base"] = self.api_base

View on GitHub (pinned to 322425c43b)

Solutions

Install the SDK with all provider extras: pip install 'any-llm-sdk[all]'.
If you know the single provider you need, install its narrower extra (e.g. 'any-llm-sdk[anthropic]') to keep images slim.
In Dockerfiles, add the install to the same layer as headroom-ai so the dependency is not stripped by a later slim stage.
Verify before constructing: python -c "import any_llm" should succeed.

Example fix

# before
backend = AnyLLMBackend(provider="anthropic")  # ImportError in slim env

# after
# requirements.txt:
#   any-llm-sdk[all]
backend = AnyLLMBackend(provider="anthropic")

Defensive patterns

Strategy: validation

Validate before calling

def anyllm_available() -> bool:
    try:
        import any_llm  # noqa: F401
        return True
    except ImportError:
        return False

if not anyllm_available():
    raise SystemExit("AnyLLMBackend requires: pip install 'any-llm-sdk[all]'")

Try / catch

try:
    backend = AnyLLMBackend(provider="openai")
except ImportError as e:
    raise SystemExit(f"missing optional dependency: {e}; add any-llm-sdk[all] to the image") from e

Prevention

Pin optional backend deps in the same lockfile/requirements set as headroom-ai.
Add a container healthcheck that instantiates each configured backend at startup.
Distinguish ImportError for missing optional deps from real code bugs by checking the message.

When it happens

Trigger: Instantiating AnyLLMBackend(provider=..., api_key=..., api_base=...) in an environment where 'import any_llm' failed — headroom-ai installed without the any-llm extra, or a slim Docker image.

Common situations: Using the multi-provider backend in the default slim Docker image, a venv where only 'headroom-ai' base deps were installed, or a lockfile that dropped the optional dependency after a refactor.

Related errors

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