fix: add missing authorization check in AsyncClient web_search and web_fetch

[jnMetaCode]

Problem

The synchronous Client.web_search and Client.web_fetch methods both validate that the authorization header contains a Bearer token before making requests to ollama.com/api/web_search and ollama.com/api/web_fetch. This gives users a clear, immediate error if they haven't configured their API key.

However, the async equivalents in AsyncClient skip this validation entirely. When an async user calls web_search or web_fetch without proper auth, the request goes through to the server and fails with an opaque server-side error instead of the helpful ValueError that sync users get.

Fix

Added the same Bearer token authorization check to AsyncClient.web_search and AsyncClient.web_fetch that already exists in their sync counterparts:

if not self._client.headers.get('authorization', '').startswith('Bearer '):
    raise ValueError('Authorization header with Bearer token is required for web search')

Also updated the docstrings to include the Raises section documenting the ValueError, matching the sync versions.

Testing

• Verified that calling AsyncClient.web_search() without a Bearer token now raises ValueError with a descriptive message
• Verified that calling AsyncClient.web_fetch() without a Bearer token now raises ValueError with a descriptive message
• Verified that both methods still work correctly when a valid Bearer token is present
• Confirmed sync Client behavior is unchanged

[guicybercode]

Code Review: ollama/_client.py – Async Web Methods Authorization Validation

Overview

This change adds Bearer token authorization validation to the async AsyncClient.web_search and AsyncClient.web_fetch methods, bringing them into parity with their synchronous counterparts. The validation ensures users receive a clear, immediate error when attempting to use web features without proper API key configuration.

---

Analysis

The Change

Two async methods now include pre-request validation:

if not self._client.headers.get('authorization', '').startswith('Bearer '):
    raise ValueError('Authorization header with Bearer token is required for web search')

Additionally, docstrings were updated to document the ValueError exception in a Raises section.

Why This Matters

Before: Async users calling web_search or web_fetch without authentication would receive opaque server-side errors, making debugging difficult and creating an inconsistent experience compared to sync users.

After: Both sync and async clients now fail fast with a descriptive ValueError, improving developer experience and reducing time spent debugging authentication issues.

---

Strengths

1. Consistency Across APIs: The async client now behaves identically to the sync client regarding authentication validation. This reduces cognitive load for developers who use both interfaces.

2. Fail-Fast Principle: Validating credentials before making network requests is a best practice. It prevents unnecessary HTTP calls and provides immediate feedback.

3. Clear Error Messages: The error message explicitly states what is missing ("Authorization header with Bearer token"), guiding users toward the correct fix.

4. Documentation Alignment: Adding the Raises section to docstrings ensures that type checkers and documentation generators accurately reflect the method's behavior.

5. Minimal and Focused: The change is surgical, adding only the necessary validation logic without refactoring surrounding code.

---

Considerations

1. Error Message Specificity: The current message mentions "Bearer token" but does not reference the OLLAMA_API_KEY environment variable, which is how users typically configure authentication. Consider updating the message for clarity:

   raise ValueError('Authorization header with Bearer token is required for web search. Set OLLAMA_API_KEY environment variable.')

2. Header Access Pattern: The code accesses self._client.headers directly. Ensure this is the intended internal API and that the header is guaranteed to be populated by the time these methods are called. If headers can be modified concurrently in async contexts, consider thread-safety implications (though Python's GIL and typical httpx usage patterns likely mitigate this).

3. Test Coverage: The testing section mentions verification of the new behavior. Ensure these tests are included in the test suite and cover:

   • Missing authorization header
   • Authorization header with non-Bearer scheme (e.g., "Basic ...")
   • Authorization header with empty Bearer token ("Bearer ")
   • Valid Bearer token allowing request to proceed

4. Sync/Async Parity Maintenance: As the codebase evolves, there is a risk that sync and async methods diverge again. Consider extracting the validation logic into a shared private helper method to enforce consistency:

   def _validate_web_auth(self, operation: str) -> None:
       if not self._client.headers.get('authorization', '').startswith('Bearer '):
           raise ValueError(f'Authorization header with Bearer token is required for {operation}')

---

Potential Edge Cases

• Empty String Header: If authorization is set to an empty string, startswith('Bearer ') correctly returns False, triggering the error. This is the desired behavior.

• Case Sensitivity: The check is case-sensitive. If a user provides "bearer ..." (lowercase), validation will fail. This is acceptable since the HTTP specification treats scheme names as case-insensitive, but the Ollama API likely expects "Bearer" specifically. Document this expectation if not already covered elsewhere.

• Header Modification After Client Initialization: If users modify client.headers after creating the client, the validation will reflect the current state. This is expected behavior, but worth noting in documentation if dynamic header changes are a supported use case.

---

Recommendation: Approve

This is a straightforward and necessary fix that improves error handling consistency between sync and async APIs. The change is low-risk, well-tested, and aligns with established patterns in the codebase.

Actions before merge:

1. Consider enhancing the error message to reference the OLLAMA_API_KEY environment variable for user guidance
2. Ensure test cases for edge conditions (empty token, wrong scheme) are included in the test suite
3. (Optional) Extract validation logic to a shared helper to prevent future sync/async divergence

No blocking issues identified.