feat(anthropic): add native web search support

[TimeToBuildBob]

Summary

Implements Anthropic Claude native web search to address issue #492 (broken search due to bot detection on Google/DuckDuckGo).

Fixes #492

Changes

Features

• Environment variable configuration (GPTME_ANTHROPIC_WEB_SEARCH)
• Configurable max_uses parameter (GPTME_ANTHROPIC_WEB_SEARCH_MAX_USES, default: 5)
• Seamless integration with existing tools
• Automatic web search - Claude decides when to use it based on the query
• Backward compatible (disabled by default)

Implementation Details

Modified Files:

1. gptme/llm/llm_anthropic.py:

   • Added _create_web_search_tool() function to create Anthropic web search tool definition
   • Modified _prepare_messages_for_api() to conditionally include web search tool
   • Added environment variable checks
   • Logs info message when web search is enabled

2. gptme/tools/browser.py:

   • Updated docstring to document provider native search feature
   • Added configuration examples

3. tests/test_llm_anthropic.py:

   • Added 3 comprehensive tests for web search functionality
   • Tests cover: enabled, disabled, combined with other tools
   • All tests pass ✅

Usage

# Enable Anthropic native web search
export GPTME_ANTHROPIC_WEB_SEARCH=true
export GPTME_ANTHROPIC_WEB_SEARCH_MAX_USES=3  # Optional, default is 5

# Start gptme with Anthropic model
gptme -m anthropic/claude-sonnet-4-5

# Ask questions that require web search
> What's the current weather in Tokyo?

Claude will automatically use its native web search capability to find current information.

Testing

All tests pass:

tests/test_llm_anthropic.py::test_web_search_tool_enabled PASSED
tests/test_llm_anthropic.py::test_web_search_tool_disabled PASSED
tests/test_llm_anthropic.py::test_web_search_tool_with_other_tools PASSED

Future Work

This PR focuses on Anthropic's native search. Future enhancements could include:

• OpenAI Responses API web search support (requires different API)
• OpenRouter :online suffix support
• Domain filtering configuration
• User location parameter for geographic refinement

Notes

• Requires organization admin to enable web search in Anthropic Console
• Web search results are automatically cited by Claude
• The feature is opt-in via environment variable
• Compatible with all Claude models that support tools

---

[!IMPORTANT] Adds native web search support for Anthropic Claude models, configurable via environment variables, with tests and documentation updates.

• Features:
  • Adds native web search support for Anthropic Claude models, controlled by GPTME_ANTHROPIC_WEB_SEARCH and GPTME_ANTHROPIC_WEB_SEARCH_MAX_USES environment variables.
  • Web search is automatically used based on query, backward compatible, and disabled by default.
• Implementation:
  • In llm_anthropic.py, adds _create_web_search_tool() and modifies _prepare_messages_for_api() to include web search tool if enabled.
  • Updates browser.py docstring to document native search feature and configuration.
• Testing:
  • Adds tests in test_llm_anthropic.py for web search tool functionality, covering enabled, disabled, and combined tool scenarios.

^{This description was created by for de6bc882274bcca4ecac4bd5c8c6dfb37654ab4f. You can customize this summary. It will automatically update as commits are pushed.}

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: All tests successful. No failed tests found.

:loudspeaker: Thoughts on this report? Let us know!

[TimeToBuildBob]

Improvements Added (2025-10-17)

Addressed the automated review feedback from Ellipsis:

Changes

1. **Error Handling for **

   • Added try/except around integer conversion
   • Falls back to default value of 5 if invalid value provided
   • Logs warning when fallback occurs

2. Duplicate Tool Prevention

   • Checks if web search tool already present in tools_dict before adding
   • Prevents multiple web_search_20250305 tools
   • Logs debug message when duplicate detected

Testing

Added two new test cases:

• test_web_search_invalid_max_uses: Verifies fallback to default when env var is invalid
• test_web_search_no_duplicate_tools: Verifies duplicate prevention logic

All 5 web search tests passing:

• test_web_search_tool_enabled ✅
• test_web_search_tool_disabled ✅
• test_web_search_invalid_max_uses ✅ (new)
• test_web_search_no_duplicate_tools ✅ (new)
• test_web_search_tool_with_other_tools ✅

Ready for Review

This PR is now ready for human review with:

• Improved error handling
• Duplicate prevention
• Comprehensive test coverage
• All CI checks expected to pass