Skip to content

[Feature]: add Serply as a web-search provider #1479

Description

@googio

Problem or Motivation

OpenMAIC's web-search layer currently offers Tavily, Exa, Bocha, Brave, Baidu, SearXNG, MiniMax, Claude and Doubao. Users who already hold a Serply API key (a Google SERP API at https://serply.io) have no way to plug it into classroom generation without standing up a SearXNG instance or buying a second search subscription. The provider registry in lib/web-search/constants.ts and the adapter switch in lib/web-search/index.ts are designed for exactly this kind of addition, and the recent Exa provider (#1342) shows the accepted shape.

Disclosure: I am affiliated with Serply. This is a bring-your-own-key integration; nothing in OpenMAIC changes for users who do not configure it.

Proposed Solution

Add serply as a new API-key web-search provider, mirroring the Exa integration end to end:

  • lib/web-search/serply.ts: searchWithSerply calling GET https://api.serply.io/v1/search/?q=...&num=N with the X-Api-Key header via proxyFetch, mapping results[] (title, link, description) to WebSearchSource entries and dropping results without a URL.
  • Registry entry in WEB_SEARCH_PROVIDERS, 'serply' in WebSearchProviderId, dispatch case in searchWeb, env key name in the web-search route, SERPLY_API_KEY / SERPLY_BASE_URL / SERPLY_ENABLED in the server provider config, official base URL allowlist entry, default client settings + migration in lib/store/settings.ts.
  • settings.providerNames.serply in all 12 locales, .env.example, configuration.mdx + supported-models.mdx in all 6 doc locales, and skills/openmaic/references/provider-keys.md.
  • Vitest coverage: adapter unit tests, dispatch, route, server config, constants, and the provider-neutrality guard debt table.

Acceptance Criteria

  • A user can pick "Serply" under Settings > Web Search, enter an API key, and classroom generation uses it for web research.
  • A self-hoster can configure it server-side with SERPLY_API_KEY (plus optional SERPLY_BASE_URL, SERPLY_ENABLED=false) and the client shows it as server-managed.
  • The system returns a clear error naming SERPLY_API_KEY when the provider is selected without credentials.
  • Existing providers continue to work; pnpm format, pnpm lint, npx tsc --noEmit and pnpm test stay green.

Alternatives Considered

  • Pointing users at SearXNG with a Serply engine: requires self-hosting a second service and loses the key-based server-managed flow OpenMAIC already supports.
  • A generic "custom HTTP search" provider: larger design change, and the neutrality guard intentionally keeps vendor knowledge inside per-provider adapters.

Area

Model / provider integration

Additional Context

I have the implementation ready and can open the PR right after this issue is acknowledged. It will be marked AI-assisted per CONTRIBUTING and includes Settings screenshots.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions