SearchProvider

Interface#

import type {
  ProviderResponse, ValidatedSearchRequest,
} from '@belweave/search-sdk';

interface SearchProvider {
  readonly id: string;
  readonly capabilities: {
    readonly domainFilters: boolean;
    readonly mutuallyExclusiveDomainFilters?: boolean;
    readonly maxIncludeDomains: number;
    readonly maxExcludeDomains: number;
    readonly maxQueryLength?: number;
  };
  search(
    request: ValidatedSearchRequest,
    options: { signal: AbortSignal },
  ): Promise<ProviderResponse>;
}

Declare capabilities truthfully#

The orchestrator checks capabilities across the entire fallback chain before dispatch. Capacities are nonnegative integers. An optional maxQueryLength must be a positive integer and is measured in UTF-16 code units. Context declares a ceiling of 500. IDs must be 1–64 ASCII letters, digits, hyphens, or underscores.

Custom implementations are trusted code#

A custom provider must return the normalized response shape, assign truthful provenance, honor its advertised capabilities, and observe the signal where possible. The orchestrator validates response fields and applies deadlines, fallback policy, and result ceilings. It cannot verify the truth of supplied attribution.

Most hosted adapter options are { apiKey, fetch? }; Valyu adds typed search settings, and SearXNG uses an operator-selected instance. Injected fetch has the shape (input: string | URL, init?: RequestInit) => Promise<Response> and is useful for controlled fixtures and server networking policy.