feat(brave): add BraveWebSearch integration by SyedShahmeerAli12 · Pull Request #3237 · deepset-ai/haystack-core-integrations

SyedShahmeerAli12 · 2026-04-27T11:50:35Z

Related Issues

part of Add new integration for Brave Search #3236

Proposed Changes:

Adds BraveWebSearch, a new Haystack component that wraps the Brave Search API.

Follows the same structure as the existing TavilyWebSearch integration:

run() for sync usage, run_async() for async usage (both via httpx)
Returns documents (content = result description) and links (result URLs)
top_k, country, search_lang, and extra_params configurable at init time
Per-run top_k override supported

API response mapping:
Brave Search returns results under web.results. Each result's description becomes the Document content, with title and url stored in meta.

How did you test it?

11 unit tests covering:

Default and custom init parameters
Serialization round-trip (to_dict / from_dict)
run() returns correct documents and links
Correct query parameters forwarded to the API (count, country, search_lang)
Per-run top_k override
Async run_async() returns correct results
Empty results and missing web key handled gracefully
HTTP errors propagated correctly

2 integration tests skipped unless BRAVE_API_KEY is set.

Notes for the reviewer

Uses httpx (sync Client for run(), AsyncClient for run_async()) rather than a dedicated SDK, since Brave Search has no official Python client. httpx is a well-maintained library already used widely in the Python ecosystem.

Checklist

I have read the contributors guidelines and the code of conduct
I have updated the related issue with new insights and changes
I added unit tests and updated the docstrings
I've used one of the conventional commit types for my PR title: feat:

Implements BraveWebSearch component for Haystack using the Brave Search API. Follows the same structure as TavilyWebSearch. - sync run() and async run_async() via httpx - top_k, country, search_lang, extra_params configuration - per-run top_k override - returns documents (content = description) and links - 11 unit tests, 2 integration tests (skipped without API key) Closes deepset-ai#3236

SyedShahmeerAli12 · 2026-04-27T13:15:52Z

Hey @anakin87 all CI checks are now passing (including the API reference build). Whenever you have a chance to review, that would be great!

anakin87

Left two initial comments.

Have you run yourself tests using the Brave API key?

SyedShahmeerAli12 · 2026-04-27T14:04:12Z

Left two initial comments.

Have you run yourself tests using the Brave API key?

umm no let me address the comments then check via Brave Api key , would you refer me the documention so it would be easy for me too..

SyedShahmeerAli12 · 2026-04-28T10:10:10Z

Hey @anakin87 I tried to get a Brave API key for testing, but Brave has removed their free tier as of late 2025 and now requires a credit card for the $5/month metered plan. Would it be possible to verify the integration tests via a CI secret, or would you like me to proceed another way? The integration tests are already gated with @pytest.mark.skipif(not os.environ.get("BRAVE_API_KEY"), ...) so they won't affect CI.

anakin87 · 2026-04-28T12:41:05Z

Hey @anakin87 I tried to get a Brave API key for testing, but Brave has removed their free tier as of late 2025 and now requires a credit card for the $5/month metered plan. Would it be possible to verify the integration tests via a CI secret, or would you like me to proceed another way? The integration tests are already gated with @pytest.mark.skipif(not os.environ.get("BRAVE_API_KEY"), ...) so they won't affect CI.

I'll proceed with review and testing when I have some time.

For the future, I'd like to invite you to only contribute to integrations you can test completely locally.

anakin87

Tests pass but:

.github/workflows/brave.yml - no CI workflow exists
.github/labeler.yml - no integration:brave label rule
.github/workflows/CI_coverage_comment.yml - brave isn't registered. Add it.
Root README.md - brave isn't listed in the integrations table.

- Add .github/workflows/brave.yml CI workflow - Register 'Test / brave' in CI_coverage_comment.yml - Add integration:brave label rule to labeler.yml - Fix README.md: remove stale CHANGELOG link - Add brave-search-haystack row to root README table

- Fix broken doc links: api.search.brave.com -> api-dashboard.search.brave.com - Add timeout and max_retries params to BraveWebSearch.__init__() - Replace httpx.Client/AsyncClient with request_with_retry/async_request_with_retry - Update tests to mock request_with_retry instead of httpx directly - Restore CHANGELOG link in README.md (keep this) - Fix alphabetical order of brave row in root README.md

anakin87

Two final comments.

I'd invite you, if you use code agents, to review their outputs yourself before committing.

…strings

anakin87

I added license.

Merging now

SyedShahmeerAli12 requested a review from a team as a code owner April 27, 2026 11:50

SyedShahmeerAli12 requested review from anakin87 and removed request for a team April 27, 2026 11:50

github-actions Bot added the type:documentation Improvements or additions to documentation label Apr 27, 2026

Add pydoc config for Brave Search API reference generation

6315297

Merge branch 'main' into feat/brave-search-integration

c524397

anakin87 requested changes Apr 27, 2026

View reviewed changes

Comment thread integrations/brave/CHANGELOG.md Outdated

Comment thread integrations/brave/README.md

fix(brave): remove auto-generated CHANGELOG and simplify README

51dd431

anakin87 requested changes Apr 30, 2026

View reviewed changes

github-actions Bot added the topic:CI label Apr 30, 2026

anakin87 requested changes Apr 30, 2026

View reviewed changes

Comment thread README.md Outdated

Comment thread integrations/brave/README.md Outdated

anakin87 reviewed Apr 30, 2026

View reviewed changes

Comment thread integrations/brave/src/haystack_integrations/components/websearch/brave/brave_websearch.py Outdated

anakin87 reviewed Apr 30, 2026

View reviewed changes

Comment thread integrations/brave/src/haystack_integrations/components/websearch/brave/brave_websearch.py Outdated

anakin87 reviewed Apr 30, 2026

View reviewed changes

Comment thread integrations/brave/src/haystack_integrations/components/websearch/brave/brave_websearch.py

anakin87 requested changes May 6, 2026

View reviewed changes

Comment thread integrations/brave/src/haystack_integrations/components/websearch/brave/brave_websearch.py Outdated

Comment thread integrations/brave/src/haystack_integrations/components/websearch/brave/brave_websearch.py Outdated

SyedShahmeerAli12 and others added 2 commits May 6, 2026 15:18

fix(brave): remove broken doc links from country and extra_params doc…

13654ba

…strings

license

f338e10

anakin87 approved these changes May 6, 2026

View reviewed changes

anakin87 merged commit 9d93d0f into deepset-ai:main May 6, 2026
18 checks passed

Conversation

SyedShahmeerAli12 commented Apr 27, 2026 • edited by anakin87 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issues

Proposed Changes:

How did you test it?

Notes for the reviewer

Checklist

Uh oh!

SyedShahmeerAli12 commented Apr 27, 2026

Uh oh!

anakin87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

SyedShahmeerAli12 commented Apr 27, 2026

Uh oh!

SyedShahmeerAli12 commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anakin87 commented Apr 28, 2026

Uh oh!

anakin87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anakin87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

anakin87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SyedShahmeerAli12 commented Apr 27, 2026 •

edited by anakin87

Loading

SyedShahmeerAli12 commented Apr 28, 2026 •

edited

Loading