search

type BackendAttempt ¶ added in v2026.909.0

type BackendAttempt struct {
	Backend    string `json:"backend"`
	Success    bool   `json:"success"`
	Error      string `json:"error,omitempty"`
	DurationMs int64  `json:"durationMs,omitempty"`
}

type BalanceState ¶ added in v2026.909.0

type BalanceState struct {
	Month  string           `json:"month"`
	Counts map[string]int64 `json:"counts"`
	Next   string           `json:"next,omitempty"`
}

BalanceState is the persisted scheduler state for the MCP-backed search adapters. Counts represent backend attempts, including attempts that later fail and cause a fallback.

type BalanceStore ¶ added in v2026.909.0

type BalanceStore interface {
	Update(func(*BalanceState) error) (BalanceState, error)
}

BalanceStore provides an atomic read-modify-write operation. The file implementation uses a process lock as well as an OS file lock so two Solomon processes do not lose increments made in the same month.

func DefaultBalanceStore() BalanceStore

type Engine ¶

type Engine interface {
	Search(ctx context.Context, req Request) (Response, error)
}

func Lookup(name string) (Engine, error)

type ExaAdapter ¶ added in v2026.909.0

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

ExaAdapter translates Solomon's neutral search request into Exa's hosted MCP search tool. The hosted tool intentionally exposes only query and numResults, so provider-specific search settings are not guessed or sent as unsupported MCP arguments.

func NewExaAdapter(caller MCPToolCaller, serverName string) (*ExaAdapter, error)

func (a *ExaAdapter) Search(ctx context.Context, req Request) (Response, error)

type FileBalanceStore ¶ added in v2026.909.0

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

func NewFileBalanceStore(path string) (*FileBalanceStore, error)

func (s *FileBalanceStore) Update(fn func(*BalanceState) error) (BalanceState, error)

type Hit ¶

type Hit struct {
	Title       string         `json:"title"`
	URL         string         `json:"url"`
	Snippet     string         `json:"snippet,omitempty"`
	Content     string         `json:"content,omitempty"`
	Author      string         `json:"author,omitempty"`
	PublishedAt string         `json:"publishedAt,omitempty"`
	Score       *float64       `json:"score,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type MCPAdapterServer ¶ added in v2026.909.0

type MCPAdapterServer struct {
	ServerName string
	Adapter    string
}

MCPAdapterServer identifies one internal MCP server without exposing its transport, headers, environment, or other configuration secrets.

type MCPToolCaller ¶ added in v2026.909.0

type MCPToolCaller interface {
	CallInternalTool(ctx context.Context, serverName, toolName, intent string, args map[string]any) (any, error)
}

MCPToolCaller is the narrow host-side surface needed by MCP-backed search adapters. The concrete MCP manager remains outside this package so the adapter can be unit-tested without a live remote server.

type MemoryBalanceStore ¶ added in v2026.909.0

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

func NewMemoryBalanceStore(initial BalanceState) *MemoryBalanceStore

func (s *MemoryBalanceStore) Snapshot() BalanceState

func (s *MemoryBalanceStore) Update(fn func(*BalanceState) error) (BalanceState, error)

type NativeCloakAdapter ¶ added in v2026.909.0

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

NativeCloakAdapter is Solomon's local CloakBrowser fallback. The browser process is owned by internal/cloak; this adapter only turns a rendered search page into the provider-neutral search response.

func NewNativeCloakAdapter(browser cloak.Browser) (*NativeCloakAdapter, error)

func (a *NativeCloakAdapter) Search(ctx context.Context, req Request) (Response, error)

type ParallelAdapter ¶ added in v2026.909.0

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

ParallelAdapter translates Solomon's neutral request into the current Parallel Search MCP contract. The MCP tool accepts an objective and one or more search queries; max-results and advanced settings are connection-level settings on the public MCP endpoint, so the adapter trims the returned list locally instead of sending unsupported per-call arguments.

func NewParallelAdapter(caller MCPToolCaller, serverName string) (*ParallelAdapter, error)

func (a *ParallelAdapter) Search(ctx context.Context, req Request) (Response, error)

type Request ¶

type Request struct {
	Query      string
	MaxResults int
	Intent     string
	Extras     map[string]any
}

type Response ¶

type Response struct {
	Engine       string            `json:"engine"`
	Hits         []Hit             `json:"hits"`
	HasMore      bool              `json:"hasMore,omitempty"`
	SearxBaseURL string            `json:"searxBaseURL,omitempty"`
	Metadata     *ResponseMetadata `json:"metadata,omitempty"`
}

func Run(ctx context.Context, engineKey string, req Request) (Response, error)

func RunEngine(ctx context.Context, engineKey string, e Engine, req Request) (Response, error)

type ResponseMetadata ¶ added in v2026.909.0

type ResponseMetadata struct {
	Provider          string           `json:"provider,omitempty"`
	Adapter           string           `json:"adapter,omitempty"`
	SessionID         string           `json:"sessionId,omitempty"`
	ProviderRequestID string           `json:"providerRequestId,omitempty"`
	Warnings          []string         `json:"warnings,omitempty"`
	Fallback          bool             `json:"fallback,omitempty"`
	Partial           bool             `json:"partial,omitempty"`
	Attempts          []BackendAttempt `json:"attempts,omitempty"`
	ProviderData      map[string]any   `json:"providerData,omitempty"`
}

type Router ¶ added in v2026.909.0

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

Router balances requests among configured web-search adapters. A backend attempt is reserved before the call, so failures are counted just like successful requests and the monthly usage stays balanced across fallbacks.

func NewMCPRouter(caller MCPToolCaller, servers []MCPAdapterServer, options RouterOptions) (*Router, error)

func NewRouter(adapters map[string]Engine, options RouterOptions) *Router

func (r *Router) Search(ctx context.Context, req Request) (Response, error)

type RouterError ¶ added in v2026.909.0

type RouterError struct {
	Attempts []BackendAttempt
	Err      error
}

RouterError reports that every selected backend failed. Its Unwrap method preserves errors.Is checks such as errors.Is(err, ErrNoResults).

func (e *RouterError) Error() string

func (e *RouterError) Unwrap() error

type RouterOptions ¶ added in v2026.909.0

type RouterOptions struct {
	Store    BalanceStore
	Now      func() time.Time
	Fallback Engine
}