Documentation
¶
Overview ¶
Package search turns a question into candidate URLs.
Two providers ship: Brave and Tavily. They are not interchangeable in one respect that matters more than price — Tavily returns extracted page content alongside each result, so a result that arrives with usable text skips the fetch entirely. §10.4 lists that as the first thing to try before adding any fetch capability, because it removes latency, failure modes, and rate-limit pressure all at once.
Index ¶
Constants ¶
const ( DefaultBraveCostMicros = 5_000 // ~$5 / 1000 queries DefaultTavilyCostMicros = 8_000 // ~$8 / 1000 queries )
Default per-query prices, in micro-dollars, from each provider's entry paid tier. Verify against the current plan before trusting a budget built on them.
Variables ¶
var ( // ErrRateLimited is a 429. The executor's error policy treats it as // transient and retries with backoff (§9.5). ErrRateLimited = errors.New("search: rate limited") // it just burns the budget on a configuration mistake. ErrUnauthorized = errors.New("search: unauthorized") // ErrQuotaExceeded means the plan's allowance is gone. Also fatal. ErrQuotaExceeded = errors.New("search: quota exceeded") )
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
Provider Kind
Status int
Body string
// contains filtered or unexported fields
}
APIError carries provider detail alongside a sentinel.
type Config ¶
type Config struct {
// Provider is which backend to use. Required.
Provider Kind
// APIKey for the selected provider.
APIKey string
// BaseURL overrides the provider endpoint, for tests and proxies.
BaseURL string
// CostPerQueryMicros prices one search in micro-dollars. Defaults come from
// each provider's published entry tier, but plans differ enough that this
// is configuration rather than a constant — an unpriced call would make the
// budget ceiling unenforceable for the search half of a session.
CostPerQueryMicros int64
// RateLimit throttles calls to the provider. Defaults are the documented
// free-tier ceilings, which are low enough that exceeding them is the
// common failure rather than an edge case.
RateLimit limiter.Limit
Timeout time.Duration
}
Config selects and configures a provider.
type Options ¶
type Options struct {
MaxResults int
// IncludeContent asks the provider for page text. Ignored by providers that
// cannot supply it.
IncludeContent bool
// Deep requests a more thorough (and more expensive) search where the
// provider offers the choice.
Deep bool
// IncludeDomains / ExcludeDomains restrict the result set where supported.
IncludeDomains []string
ExcludeDomains []string
}
Options tune a single search.
type Provider ¶
type Provider interface {
// Search returns ranked results. Cost is reported on the Response so the
// ledger can settle against the reservation that covered this lead.
Search(ctx context.Context, query string, opts Options) (*Response, error)
Kind() Kind
}
Provider is a search backend.
type Response ¶
type Response struct {
Query string
Provider Kind
Results []Result
Cost core.Cost
Elapsed time.Duration
}
Response is one search call.
type Result ¶
type Result struct {
URL string
Title string
Snippet string
// Content is the provider's own extraction of the page.
//
// Brave never populates it. Tavily does when asked, and when it is present
// and long enough the WebActor can skip the fetch — which is the single
// biggest efficiency difference between the two providers.
Content string
// PublishedAt feeds Claim.PublishedAt, which §11.2 needs to tell staleness
// apart from genuine disagreement. Providers report it unevenly.
PublishedAt *time.Time
Score float64
Rank int
}
Result is one search hit.
func (Result) HasUsableContent ¶
HasUsableContent reports whether the provider handed back enough text to work with directly. The floor mirrors the fetcher's own minimum for usable text.
Source Files