search

Documentation

Index

• Variables
• type BackendError
• type Brave
  • func NewBrave(apiKey string) *Brave
  • func (b *Brave) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type DDG
  • func NewDDG() *DDG
  • func (d *DDG) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type EXA
  • func NewEXA(apiKey *string) *EXA
  • func (e *EXA) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type Firecrawl
  • func NewFirecrawl(apiKey string) *Firecrawl
  • func (f *Firecrawl) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type Keenable
  • func NewKeenable(apiKey *string) *Keenable
  • func (k *Keenable) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type Multi
  • func NewMultiFromConfig(cfg *config.Config, names []string, searxngURL string) (*Multi, error)
  • func (m *Multi) Names() []string
  • func (m *Multi) Search(ctx context.Context, query string, limit int) ([]Result, []BackendError, error)
• type Random
  • func NewRandomFromConfig(cfg *config.Config, names []string, searxngURL string) (*Random, error)
  • func (r *Random) Names() []string
  • func (r *Random) Search(ctx context.Context, query string, limit int) ([]Result, string, []BackendError, error)
• type Result
• type SearXNG
  • func NewSearXNG(baseURL string) *SearXNG
  • func (s *SearXNG) Search(ctx context.Context, query string, limit int) ([]Result, error)
• type Searcher
  • func NewFromConfig(cfg *config.Config, backend, searxngURL string) (Searcher, error)

Variables

var ErrUnknownBackend = errors.New("unknown search backend")

ErrUnknownBackend reports a backend name that is not a known search backend. Callers classify errors wrapping it as validation failures (bad input); any other NewFromConfig error is a missing precondition (e.g. API key).

Types

type BackendError

type BackendError struct {
	Backend string
	Err     error
}

BackendError records a single backend's failure during multi or random provider search. The caller can report partial/fallback failures without hiding which providers were attempted.

type Brave

type Brave struct {
	// contains filtered or unexported fields
}

Brave searches via the Brave Search API.

func NewBrave

func NewBrave(apiKey string) *Brave

NewBrave creates a new Brave search backend.

func (*Brave) Search

func (b *Brave) Search(ctx context.Context, query string, limit int) ([]Result, error)

Search queries Brave and returns up to limit results.

type DDG

type DDG struct {
	// contains filtered or unexported fields
}

DDG searches DuckDuckGo's HTML interface.

func NewDDG

func NewDDG() *DDG

NewDDG creates a new DuckDuckGo search backend.

func (*DDG) Search

func (d *DDG) Search(ctx context.Context, query string, limit int) ([]Result, error)

Search queries DuckDuckGo and returns up to limit results.

type EXA

type EXA struct {
	// contains filtered or unexported fields
}

func NewEXA

func NewEXA(apiKey *string) *EXA

func (*EXA) Search

func (e *EXA) Search(ctx context.Context, query string, limit int) ([]Result, error)

type Firecrawl

type Firecrawl struct {
	// contains filtered or unexported fields
}

Firecrawl searches the web via the Firecrawl v2 search API.

func NewFirecrawl

func NewFirecrawl(apiKey string) *Firecrawl

NewFirecrawl creates a new Firecrawl search backend.

func (*Firecrawl) Search

func (f *Firecrawl) Search(ctx context.Context, query string, limit int) ([]Result, error)

Search queries Firecrawl and returns up to limit web results.

type Keenable

type Keenable struct {
	// contains filtered or unexported fields
}

Keenable searches via the Keenable web search API, a search index built for AI agents. It is keyless by default (rate-limited); an optional API key lifts the hourly cap and switches to the authenticated endpoint.

func NewKeenable

func NewKeenable(apiKey *string) *Keenable

NewKeenable creates a new Keenable search backend. A nil or blank apiKey uses the keyless public endpoint.

func (*Keenable) Search

func (k *Keenable) Search(ctx context.Context, query string, limit int) ([]Result, error)

Search queries Keenable and returns up to limit results.

type Multi

type Multi struct {
	// contains filtered or unexported fields
}

Multi fans a query out across several backends and fuses their ranked results with Reciprocal Rank Fusion. Construct it with NewMultiFromConfig.

func NewMultiFromConfig

func NewMultiFromConfig(cfg *config.Config, names []string, searxngURL string) (*Multi, error)

NewMultiFromConfig resolves a federated backend set. names is either the single sentinel []string{"all"} (every usable backend, in AvailableBackends order) or an explicit ordered list. Resolution reuses NewFromConfig, so "usable" means exactly what it means everywhere else in ketch (config/key presence). For the "all" set, unconfigured backends are silently skipped; for an explicit list, an unusable name fails loudly (unknown → wraps ErrUnknownBackend; unconfigured → the constructor's precondition error), so callers can classify with backendErr/backendErrf just like NewFromConfig.

func (*Multi) Names

func (m *Multi) Names() []string

Names returns the resolved backend names in fan-out order.

func (*Multi) Search

func (m *Multi) Search(ctx context.Context, query string, limit int) ([]Result, []BackendError, error)

Search fans out to every resolved backend concurrently (each bounded by multiBackendTimeout), fuses the successful lists with RRF (k=60), dedups by canonical URL, and cuts the fused list to limit. errs carries per-backend failures (timeouts and errors); a backend that succeeds with zero results is a success, not a failure. The returned error is non-nil only when every backend failed.

type Random

type Random struct {
	// contains filtered or unexported fields
}

Random tries a freshly shuffled sequence of search providers and returns the first successful response. Unlike Multi it is sequential and never fuses results or calls providers after one succeeds.

func NewRandomFromConfig

func NewRandomFromConfig(cfg *config.Config, names []string, searxngURL string) (*Random, error)

NewRandomFromConfig resolves the candidate providers using the same "all"/explicit-name rules as NewMultiFromConfig.

func (*Random) Names

func (r *Random) Names() []string

Names returns a copy of the resolved provider names.

func (*Random) Search

func (r *Random) Search(ctx context.Context, query string, limit int) ([]Result, string, []BackendError, error)

Search shuffles providers for this call, then tries each once with a 10s timeout. A response with zero results is still success. It falls back only after an error and returns the selected provider plus prior failures.

type Result

type Result struct {
	Title       string `json:"title"`
	URL         string `json:"url"`
	FetchedURL  string `json:"fetched_url,omitempty"`
	Description string `json:"description,omitempty"`
	Content     string `json:"content,omitempty"`
	// Backends lists the backends that returned this result under federated
	// (--multi) search. Empty (and omitted) for single-backend results, so
	// every existing single-backend output stays byte-identical.
	Backends []string `json:"backends,omitempty"`
}

Result represents a single search result.

type SearXNG

type SearXNG struct {
	// contains filtered or unexported fields
}

SearXNG searches a SearXNG instance via its JSON API.

func NewSearXNG

func NewSearXNG(baseURL string) *SearXNG

NewSearXNG creates a new SearXNG search backend.

func (*SearXNG) Search

func (s *SearXNG) Search(ctx context.Context, query string, limit int) ([]Result, error)

Search queries SearXNG and returns up to limit results.

type Searcher

type Searcher interface {
	Search(ctx context.Context, query string, limit int) ([]Result, error)
}

Searcher is the interface for search backends.

func NewFromConfig

func NewFromConfig(cfg *config.Config, backend, searxngURL string) (Searcher, error)

NewFromConfig builds the Searcher for backend, resolving API keys and instance URLs from cfg exactly as the `ketch search` CLI does. searxngURL overrides cfg.SearxngURL when non-empty (the --searxng-url flag / MCP searxng_url param). Both the CLI and the MCP server call this — it is the single owner of the backend switch.