Skip to content

feat(web): add Serper search provider plugin - #41015

Closed
ViezeVingertjes wants to merge 2 commits into
NousResearch:mainfrom
ViezeVingertjes:feat/web-serper-provider
Closed

feat(web): add Serper search provider plugin#41015
ViezeVingertjes wants to merge 2 commits into
NousResearch:mainfrom
ViezeVingertjes:feat/web-serper-provider

Conversation

@ViezeVingertjes

Copy link
Copy Markdown

What does this PR do?

Adds a bundled serper web provider plugin so Hermes can use Serper.dev as a search backend in the existing plugin-based web provider architecture.

The provider is search-only (matching Serper’s role here) and normalizes Serper API responses into Hermes’ existing web result contract.

Type of Change

  • 🚀 New feature (non-breaking addition)

Changes Made

  • Added new bundled web plugin:
    • plugins/web/serper/plugin.yaml
    • plugins/web/serper/__init__.py
    • plugins/web/serper/provider.py
  • Provider behavior:
    • backend name: serper
    • availability gated by SERPER_API_KEY
    • search endpoint call to POST {SERPER_BASE_URL|https://google.serper.dev}/search
    • request payload includes q and num
    • response normalization from organic[]{title,url,description,position}
    • search-only capabilities (supports_search=True, supports_extract=False)
  • Wired backend selection/availability in web tools:
    • _get_backend() accepts and can auto-detect serper
    • _is_backend_available("serper")
    • check_web_api_key() recognizes configured/available serper
  • Updated registry/docs/comments to include serper in provider lists and legacy preference order.
  • Added/updated tests:
    • new tests/tools/test_web_providers_serper.py
    • updated plugin discovery/capability coverage in tests/plugins/web/test_web_search_provider_plugins.py
    • updated shared provider registration in tests/tools/conftest.py
    • updated config/backend selection coverage in tests/tools/test_web_tools_config.py

How to Test

# Focused provider + wiring coverage
scripts/run_tests.sh \
  tests/tools/test_web_providers_serper.py \
  tests/plugins/web/test_web_search_provider_plugins.py \
  tests/tools/test_web_tools_config.py \
  tests/tools/test_web_providers.py

Expected result:

  • 4 files, 130 tests passed, 0 failed.

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run tests relevant to this change and they pass
  • I've added tests for my changes
  • I've tested on my platform: Linux

Documentation & Housekeeping

  • I've updated relevant documentation/comments where provider lists are enumerated
  • No new user-facing config keys in cli-config.yaml.example required (uses existing web.backend)
  • No architecture/workflow doc changes required in CONTRIBUTING.md / AGENTS.md
  • I've considered cross-platform impact (network/env-var based provider, no OS-specific paths)

- add bundled web-serper plugin (provider, register hook, metadata)

- wire serper into backend availability + fallback selection

- extend registry/docs + web tool comments for serper

- add and update provider/config/plugin tests
@alt-glitch alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have tool/web Web search and extraction comp/plugins Plugin system and bundled plugins labels Jun 7, 2026
@ViezeVingertjes ViezeVingertjes closed this by deleting the head repository Jun 10, 2026
@haorannlp

Copy link
Copy Markdown

why closed?

@ViezeVingertjes

Copy link
Copy Markdown
Author

why closed?

Cleaned up the fork on my end; so i think that auto-closed it (would assume so).

Icather added a commit to Icather/hermes-agent that referenced this pull request Jun 26, 2026
…u-baidu, serpapi, jina, google-cse, sogou, 360-search)

v0.17 removed the Parallel free MCP fallback (NousResearch#46350), sharply reducing free search options. This adds 9 new providers as plugins following the existing brave-free/ddgs pattern, registered in backend_candidates in composite quality-score order after the existing backends.

New functional providers (search-only):
- serper      — Google SERP, 2,500 free queries, no credit card
- baidu       — Baidu AI Search, 100/day free, native Chinese content
- bocha       — Chinese market leader, 1,000 free starter queries
- qiniu-baidu — Qiniu Cloud Baidu, 3M tokens for new users
- serpapi     — Multi-engine, 100/month free
- jina        — Full-page extraction, 10M tokens free (blocked in China)
- google-cse  — Google Custom Search, 100/day (blocked in China)

Registry-only entries (no public API, listed for completeness):
- sogou, 360-search

Two prior attempts (NousResearch#41015 Serper by ViezeVingertjes, NousResearch#35690 fallback by jonathanwxh-cell) were self-closed without review. This salages their approach with a complete provider surface covering both Western and Chinese search engines.

Changes:
- plugins/web/*/ — 27 new files (provider.py, plugin.yaml, __init__.py per backend)
- tools/web_tools.py — +9 entries in _KNOWN_WEB_BACKENDS set, +9 in backend_candidates tuple, +_check_provider_available() helper, generic plugin probe in _is_backend_available()
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/plugins Plugin system and bundled plugins P3 Low — cosmetic, nice to have tool/web Web search and extraction type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants