stanford-oval/storm · error · ImportError

AzureAISearch requires `pip install azure-search-documents`.

Error message

AzureAISearch requires `pip install azure-search-documents`.

What it means

Raised by AzureAISearchRM.__init__ when the optional Azure SDK packages (azure-core, azure-search-documents) are not installed. STORM treats Azure AI Search retrieval as an optional extra, so it only imports the SDK lazily inside the constructor and converts the ImportError into a clearer message with install instructions.

Source

Thrown at knowledge_storm/rm.py:1141

        """
        Params:
            azure_ai_search_api_key: Azure AI Search API key. Check out https://learn.microsoft.com/en-us/azure/search/search-security-api-keys?tabs=rest-use%2Cportal-find%2Cportal-query
                "API key" section
            azure_ai_search_url: Custom Azure AI Search Endpoint URL. Check out https://learn.microsoft.com/en-us/azure/search/search-create-service-portal#name-the-service
            azure_ai_search_index_name: Custom Azure AI Search Index Name. Check out https://learn.microsoft.com/en-us/azure/search/search-how-to-create-search-index?tabs=portal
            k: Number of top results to retrieve.
            is_valid_source: Optional function to filter valid sources.
            min_char_count: Minimum character count for the article to be considered valid.
            snippet_chunk_size: Maximum character count for each snippet.
            webpage_helper_max_threads: Maximum number of threads to use for webpage helper.
        """
        super().__init__(k=k)

        try:
            from azure.core.credentials import AzureKeyCredential
            from azure.search.documents import SearchClient
        except ImportError as err:
            raise ImportError(
                "AzureAISearch requires `pip install azure-search-documents`."
            ) from err

        if not azure_ai_search_api_key and not os.environ.get(
            "AZURE_AI_SEARCH_API_KEY"
        ):
            raise RuntimeError(
                "You must supply azure_ai_search_api_key or set environment variable AZURE_AI_SEARCH_API_KEY"
            )
        elif azure_ai_search_api_key:
            self.azure_ai_search_api_key = azure_ai_search_api_key
        else:
            self.azure_ai_search_api_key = os.environ["AZURE_AI_SEARCH_API_KEY"]

        if not azure_ai_search_url and not os.environ.get("AZURE_AI_SEARCH_URL"):
            raise RuntimeError(
                "You must supply azure_ai_search_url or set environment variable AZURE_AI_SEARCH_URL"
            )

View on GitHub (pinned to fb951af774)

Solutions

pip install azure-search-documents
Verify you're in the right environment: python -c "import azure.search.documents"
If it still fails, reinstall cleanly: pip install --force-reinstall azure-search-documents azure-core

Example fix

# before
rm = AzureAISearchRM(azure_ai_search_api_key=..., azure_ai_search_url=..., azure_ai_search_index_name=...)

# after
pip install azure-search-documents
rm = AzureAISearchRM(azure_ai_search_api_key=..., azure_ai_search_url=..., azure_ai_search_index_name=...)

Defensive patterns

Strategy: validation

Validate before calling

def azure_search_sdk_available():
    try:
        import azure.search.documents  # noqa: F401
        import azure.core.credentials  # noqa: F401
        return True
    except ImportError:
        return False

if not azure_search_sdk_available():
    raise SystemExit("Install with: pip install azure-search-documents")

Try / catch

try:
    from knowledge_storm.rm import AzureAISearchRM
    rm = AzureAISearchRM(azure_ai_search_api_key=K, azure_ai_search_url=U, azure_ai_search_index_name=I)
except ImportError as e:
    if "azure-search-documents" in str(e):
        # fall back to another retriever or prompt the user to install
        rm = YouRM(...)
    else:
        raise

Prevention

Declare azure-search-documents in your project's requirements when using AzureAISearchRM
Pin optional extras in setup/pyproject extras_require so CI installs them
Add a smoke test that imports the SDK in the deployment environment

When it happens

Trigger: Instantiating AzureAISearchRM on an environment where `import azure.search.documents` or `import azure.core.credentials` fails — i.e., azure-search-documents (and its azure-core dependency) were never installed or were removed from the virtualenv.

Common situations: Installing the storm/knowledge-storm package without optional extras; using a different virtualenv/conda env than the one where the Azure SDK was installed; a broken or partially uninstalled azure namespace package causing ImportError even though some azure-* packages exist.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of stanford-oval/storm@fb951af774 (2026-08-28). Data as JSON: /api/errors/a15815297674e14c. Report an issue: GitHub.