Skip to content

Sources Catalog ​

nb-search ships with 18 search lanes and 9 fetch pipelines. Use the standalone nb-extract tool for local document conversion and Markdown/resource saving. These sources are grouped by use case, cost structure, latency characteristics, and output channel.

About the dimensions

The relative cost (free / cheap / expensive) and relative latency (fast / medium / slow) in the tables are qualitative metadata labels declared strictly by the runtime configuration. They help an upper-layer orchestrator make coarse-grained choices; they are not actual billing data or benchmark scores.

Use-case groups and configuration guidance ​

The official built-in usage guidance (src/lane-guidance.ts) divides capabilities into three main groups. These groups describe use cases and integration paths, not a quality ranking:

  1. Onboarding: general discovery and reading (onboarding):
    • Configuration guidance: In 0.5.0 and later, the default is the keyless duckduckgo.search lane for general web search. Public HTML pages may trigger challenges or rate limits; the tool reports those errors as they are instead of pretending the result set is empty. Repository search and documentation context can be selected explicitly with github.repositories and context7.docs. You can also configure tavily.search, brave.search, exa.search, and other sources and set one as defaults.search_lane; an explicit default or selection takes precedence, and a failure does not silently switch sources. Fetching uses the built-in ordered URL routing package kiki-common-direct@1 (known GitHub Raw/API, npm, and PyPI metadata use direct.fetch only). Other public URLs try direct.fetch (Defuddle) first and then the keyless jina.reader if that fails.
    • Typical sources: duckduckgo.search, brave.search, exa.search, tavily.search, parallel.search, searxng.search, and zhipu.search; fetch pipelines include direct.fetch and jina.reader.
  2. Specialist capabilities (specialist):
    • Configuration guidance: Select these explicitly for particular data types, page extraction, or controlled environments. Usually specify them directly with --lane, --lanes, or --pipeline rather than using them as a fallback for the entire web.
    • Typical sources:
      • Code and engineering: github.repositories (repository search), context7.docs (framework documentation context).
      • Deep web/social search: firecrawl.search (search with extracted content), grok.x-synthesis (synthesis of discussions on X).
      • Dedicated fetchers: exa.contents, tavily.extract, firecrawl.scrape, direct.local (compatible local files and inline content without network egress), wayback.fetch (historical snapshots), browser.render (headless Chromium rendering), and oac.fetch (model-based extraction and summarization).
  3. Synthesis and deep research (research):
    • Configuration guidance: Use these when a model must perform multi-step reasoning, produce a synthesis, or generate a structured report. They have comparatively higher cost and latency and must be invoked as a single explicit lane; they cannot be placed in a multi-source Results preset.
    • Typical sources: exa.synthesis, tavily.synthesis, grok.synthesis, gma.research, and oac.synthesis.

Diagnostics and capability inspection

Run node scripts/nb-search.mjs --doctor locally to print a readiness summary with the use-case groups. Call capabilities to inspect each source's live port activation and supported modes. The "supported modes" listed below apply to the standard local runtime when no custom http_transport is injected; an explicitly injected custom transport disables all async modes. readiness reflects local configuration completeness only, not whether an external upstream is online.

18 search lanes ​

The 18 built-in search lanes use different underlying providers and operations:

Lane IDProvider / operationOutput channel and schemaSupported modes (when ready)Required credentials and endpoint configurationRelative cost / latencyCharacteristics and endpoint conventions
brave.searchbrave/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_BRAVE_API_KEY required; Base URL optionalcheap / fastIndependent web search index; appends /res/v1/web/search to the endpoint
exa.searchexa/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_EXA_API_KEY required; Base URL optionalcheap / fastNeural search; appends /search to the endpoint
exa.synthesisexa/synthesisTyped (nb-search.synthesis@1)sync, asyncNB_SEARCH_EXA_API_KEY required; Base URL optionalexpensive / mediumSynthesis-oriented search that returns paragraphs and citations
tavily.searchtavily/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_TAVILY_API_KEY required; Base URL optionalcheap / fastAgent-optimized search; appends /search to the endpoint
tavily.synthesistavily/synthesisTyped (nb-search.synthesis@1)sync, asyncNB_SEARCH_TAVILY_API_KEY required; Base URL optionalcheap / mediumSynthesis-oriented results with a direct answer
tavily.crawltavily/crawlTyped (nb-search.crawl@1)sync, asyncNB_SEARCH_TAVILY_API_KEY required; Base URL optionalcheap / slowOfficial Crawl POST; returns a bounded Markdown document set
tavily.researchtavily/researchTyped (nb-search.research@1)sync, asyncNB_SEARCH_TAVILY_API_KEY required; Base URL optionalexpensive / slowOfficial Research Task POST/GET polling; returns content and sources
firecrawl.searchfirecrawl/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_FIRECRAWL_API_KEY required; Base URL optionalcheap / fastSearch endpoint; appends /v2/search to the endpoint
searxng.searchsearxng/searchResults (nb-search.results@1)sync, asyncNo key; NB_SEARCH_SEARXNG_BASE_URL requiredfree / mediumSelf-hosted or private aggregated search instance; appends /search to the endpoint
zhipu.searchzhipu/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_ZHIPU_API_KEY required; Base URL optionalcheap / fastZhipu Web Search; appends /paas/v4/web_search to the endpoint
parallel.searchparallel/searchResults (nb-search.results@1)sync, asyncNB_SEARCH_PARALLEL_API_KEY requiredcheap / fastFixed endpoint: https://api.parallel.ai/v1/search
github.repositoriesgithub/repositoriesResults (nb-search.results@1)sync, asyncNB_SEARCH_GITHUB_TOKEN optionalfree / fastOn-demand repository search; anonymous requests are more vulnerable to rate limits
duckduckgo.searchduckduckgo/searchResults (nb-search.results@1)sync, asyncNo credentials or self-hosted endpoint requiredfree / mediumZero-key default general web search; public HTML search reports challenges or rate limits directly
context7.docscontext7/docsTyped (nb-search.docs-context@1)sync, asyncNB_SEARCH_CONTEXT7_API_KEY optionalcheap / mediumFramework and code-library documentation context extraction; uses public mode without a key
grok.synthesisgrok/synthesisTyped (nb-search.synthesis@1)sync, asyncNB_SEARCH_GROK_API_KEY required; Base/Model optionalexpensive / slowBased on the xAI Grok Responses API with the web_search tool enabled
grok.x-synthesisgrok/x-synthesisTyped (nb-search.synthesis@1)sync, asyncNB_SEARCH_GROK_API_KEY required; Base/Model optionalexpensive / slowBased on the xAI Grok Responses API with the x_search tool enabled
gma.researchgrok-multi-agent/researchTyped (nb-search.multi-agent-research@1)sync, asyncNB_SEARCH_GROK_API_KEY and NB_SEARCH_GROK_MULTI_AGENT_BASE_URL requiredexpensive / slowDeep multi-agent reasoning; supports chat_completions and messages modes
oac.synthesisopenai-compatible/synthesisTyped (nb-search.synthesis@1)sync, asyncNB_SEARCH_OAC_API_KEY, NB_SEARCH_OAC_BASE_URL, and NB_SEARCH_OAC_MODEL requiredexpensive / slowStructured synthesis through an OpenAI-compatible Chat Completions endpoint

9 fetch pipelines ​

Pipeline IDProvider / operationSupported input and outputSupported modes (when ready)Credential and dependency requirementsRelative cost / latencyDefault fetch-chain position and description
direct.fetchdirect-http/fetchURL -> nb-search.fetch@1sync, asyncNo credentials; direct HTTP requestfree / fastFirst in the default URL fetch chain; Defuddle extracts static HTML, JSON, and GitHub API text
jina.readerjina-reader/readerURL -> nb-search.fetch@1syncNB_SEARCH_JINA_API_KEY optionalfree / mediumSecond in the default URL fetch chain; extracts page text and converts it to Markdown
direct.localdirect-http/localinline / file -> nb-search.fetch@1sync, asyncNo credentials; file_scopes required for filesfree / fastOnly item in the default inline/file fetch chain; no network egress (egress: none)
exa.contentsexa/contentsURL -> nb-search.fetch@1syncNB_SEARCH_EXA_API_KEY requiredcheap / fastRequires explicit selection or a custom chain; calls Exa's /contents extraction endpoint
tavily.extracttavily/extractURL -> nb-search.fetch@1syncNB_SEARCH_TAVILY_API_KEY requiredcheap / fastRequires explicit selection or a custom chain; calls Tavily's /extract page-extraction endpoint
firecrawl.scrapefirecrawl/scrapeURL -> nb-search.fetch@1syncNB_SEARCH_FIRECRAWL_API_KEY requiredcheap / mediumRequires explicit selection or a custom chain; calls Firecrawl's /v2/scrape endpoint
wayback.fetchwayback/fetchURL -> nb-search.fetch@1syncNo credentials; automatically queries Wayback archive snapshotsfree / mediumRequires explicit selection or a custom chain; useful for pages that are offline or require historical snapshots
browser.renderbrowser-render/renderURL -> nb-search.fetch@1asyncPlaywright + Chromium required; async onlyfree / slowRequires explicit selection or a custom chain; renders client-side JavaScript pages through a browser engine
oac.fetchopenai-compatible/fetchURL -> nb-search.fetch@1syncOAC key, Base URL, and Model requiredexpensive / slowRequires explicit selection or a custom chain; uses a compatible model to summarize and extract page content

Explicit opt-in and custom sources ​

The built-in adapters below do not create default instances or lanes automatically. Declare them explicitly in config.json or host code before enabling them:

  • Built-in Zhihu source (provider_id: "zhihu"): Supports community Q&A and column search (zhihu.search), Chinese web-wide search (zhihu.global), and direct synthesis (zhihu.synthesis). It includes a free-quota gate through GET /api/v1/quota (default allow_paid: false) and a local keyUsage() metric. See the complete Schema v4 configuration in Web & Regional Search: opt-in Zhihu.
  • Local script source (provider_id: "script") and SDK custom registration: Bind trusted local .js/.mjs/.ts/.mts modules to standard search lanes that support sync and detached async, or inject a custom adapter into the host process through ProviderRegistration. See Custom Sources and Script Lanes.

Released under the MIT License · AI Index: /nb-search/llms.txt