Overview
Provider-neutral web evidence with a Brave Web Search / LLM Context adapter.
Search
@absolutejs/searchv0.2.0betaAIUse web search as a replaceable evidence provider.
Provider-neutral web evidence with a Brave Web Search and LLM Context adapter. Search returns normalized sources, excerpts, availability and attempt accounting. Compose it with the RAG research runtime for primary-page reads, structured extraction, field review and monitoring.
#Installation
BASH
bun add @absolutejs/search@0.2.0#Capabilities
Overview
Provider-neutral web evidence with a Brave Web Search / LLM Context adapter.
Successful empty results, partial evidence, provider outages, quota failures and cancellation remain distinct. Every network attempt carries billing disposition; unknown cost remains null. A 200 response remains fulfilled if its body cannot be parsed. The host owns retry/admission, prices, credentials and accounting. No hidden model calls or fallback providers.
Source excerpts are untrusted evidence. Publication and retrieval timestamps do not establish an event date. sourceSupportsQuote checks quotation presence, not entailment. withSearchCache requires an explicit scope, isolates provider/options/version, uses shorter empty-result retention, never caches failures, and optionally persists through a host store. Requests with caller-owned cancellation are not coalesced.
Capabilities and agent setup
Providers may declare capabilities with supported modes, filters and content views. SearchRequest.filters carries domain/date/category constraints. assertSearchCapabilities and withSearchCapabilities reject unsupported constraints before provider work. Brave advertises web/context excerpts and freshness/country/language; unsupported domain/date/category filters are rejected, never silently ignored. Existing providers without metadata remain compatible with existing request fields, but must declare support before accepting the new filters.
The manifest exports a guarded search_web agent tool and a Brave configuration recipe using BRAVE_SEARCH_API_KEY. Bind the configured provider and host enforcer through the existing manifest AI/MCP bridges. Search spending and tenant authorization remain host-controlled. For complete research, extraction, monitoring and framework flows, compose with @absolutejs/rag/research.
Brave Web Search and LLM Context
createBraveSearch supports web and context modes, source excerpts, context limits and freshness/country/language constraints. The adapter makes no hidden model calls or fallback-provider requests.
Availability and provenance
Successful empty, partial evidence, provider failure, quota failure and cancellation remain distinct. Sources retain their URLs and publication/retrieval information. Retrieval time does not establish an event date.
Explicit capabilities
Providers declare supported modes, filters and content views. assertSearchCapabilities and withSearchCapabilities reject unsupported constraints before provider work. The Brave adapter does not advertise domain/date/category filters.
Scoped caching
withSearchCache requires an explicit scope, separates provider/options/version, retains empty results briefly and never caches failures. A host store can persist entries. Caller-owned cancellation prevents coalescing those requests.
Accounting and agent tools
observe receives each network attempt with billing disposition. The host owns prices, credentials, retry and admission; unknown cost stays null. The manifest exposes a guarded search_web tool and a Brave configuration recipe for the existing AI/MCP bridges.
Outcomes
What you can build
Capabilities and agent setup
Providers may declare capabilities with supported modes, filters and content views. SearchRequest.filters carries domain/date/category constraints. assertSearchCapabilities and withSearchCapabilities reject unsupported constraints before provider work. Brave advertises web/context excerpts and freshness/country/language; unsupported domain/date/category filters are rejected, never silently ignored. Existing providers without metadata remain compatible with existing request fields, but must declare support before accepting the new filters.
Hardening checklist
Production guidance
Make every external boundary explicitPin the deployed @absolutejs/search version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.
Follow in order
Troubleshooting path
1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/search example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.
#@absolutejs/search quick start
Partial snippet# @absolutejs/search
TS
import { createBraveSearch } from '@absolutejs/search/brave';
const search = createBraveSearch({ apiKey, observe: recordAttempt });
const result = await search.search({ query: 'company partnership program', mode: 'context', maxTokens: 4096 });#Query Brave context
Partial snippetSet BRAVE_SEARCH_API_KEY on the server. Handle status and limitations alongside sources; an unavailable response is not evidence that a company or fact does not exist.
TS
import { createBraveSearch } from '@absolutejs/search/brave';
const apiKey = process.env.BRAVE_SEARCH_API_KEY;
if (!apiKey) throw new Error('Set BRAVE_SEARCH_API_KEY');
const search = createBraveSearch({ apiKey });
const result = await search.search({
query: 'company partnership program',
mode: 'context',
maxTokens: 4096
});
console.log(result.status, result.sources, result.limitations);#Compose with research
Partial snippetInstall @absolutejs/rag and @absolutejs/ai. provider and model are your configured model adapter and extraction model. Any compatible SearchProvider, including index.provider, can occupy this slot.
TS
import { createResearch } from '@absolutejs/rag/research';
const research = createResearch({ search, provider, model });
const result = await research.run({ query: 'Company partnership eligibility' });#API reference
Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.
20 symbols
TS
type SearchStatus = "ok" | "empty" | "partial" | "unavailable" | "rate_limited" | "quota_exceeded" | "cancelled" | "error";@absolutejs/searchCurrent package surface
What ships today
Import surface · click to copy