Provider tiers

Librarium organizes its 24 built-in providers into four tiers based on capabilities, latency, and depth.

deep-research. Async deep research providers that take minutes to complete but produce comprehensive, multi-source reports. These providers may use a submit/poll/retrieve pattern. Best for thorough research on important topics.

ai-grounded. AI-powered search with inline citations. Returns results in seconds with good quality and source attribution. A solid middle ground between speed and depth.

raw-search. Traditional search engine results. Fast responses with many links and snippets, but no AI synthesis. Useful for broad link discovery and verifying specific facts.

llm. Ungrounded generic LLMs (Claude, OpenAI, Gemini, or anything via OpenRouter). These return the model’s direct answer to the research prompt with no web grounding and no citations, so they contribute zero sources to the deduplicated source set, sources.json, and the report tallies. They exist as an opt-in baseline/contrast layer: run them alongside grounded research to see what the model says on its own versus what grounded providers surface. Because they are ungrounded, they are excluded from every grounded default group (quick, fast, raw, deep, comprehensive, and all). Opt in explicitly via -p claude,openai-chat,..., a custom group, or --group llm. Each provider takes a cheap default model with a per-provider model config override.

Provider list

Provider	ID	Tier	API key env var
Perplexity Sonar Deep Research	`perplexity-sonar-deep`	deep-research	`PERPLEXITY_API_KEY`
Perplexity Deep Research	`perplexity-deep-research`	deep-research	`PERPLEXITY_API_KEY`
Perplexity Advanced Deep Research	`perplexity-advanced-deep`	deep-research	`PERPLEXITY_API_KEY`
OpenAI Deep Research (o4-mini)	`openai-deep`	deep-research	`OPENAI_API_KEY`
OpenAI Deep Research (o3)	`openai-deep-o3`	deep-research	`OPENAI_API_KEY`
Gemini Deep Research	`gemini-deep`	deep-research	`GEMINI_API_KEY`
Perplexity Sonar Pro	`perplexity-sonar-pro`	ai-grounded	`PERPLEXITY_API_KEY`
Gemini Grounded Search	`gemini-grounded`	ai-grounded	`GEMINI_API_KEY`
ChatGPT Search (OpenRouter)	`openrouter-online`	ai-grounded	`OPENROUTER_API_KEY`
Brave AI Answers	`brave-answers`	ai-grounded	`BRAVE_API_KEY`
Exa Search	`exa`	ai-grounded	`EXA_API_KEY`
You.com Research	`you-research`	ai-grounded	`YOU_COM_API_KEY`
Kagi FastGPT	`kagi-fastgpt`	ai-grounded	`KAGI_API_KEY`
Perplexity Search	`perplexity-search`	raw-search	`PERPLEXITY_API_KEY`
Brave Web Search	`brave-search`	raw-search	`BRAVE_API_KEY`
Jina AI Search	`jina-search`	raw-search	`JINA_AI_API_KEY`
SearchAPI	`searchapi`	raw-search	`SEARCHAPI_API_KEY`
SerpAPI	`serpapi`	raw-search	`SERPAPI_API_KEY`
Tavily Search	`tavily`	raw-search	`TAVILY_API_KEY`
Firecrawl Search	`firecrawl-search`	raw-search	`FIRECRAWL_API_KEY`
Claude	`claude`	llm	`ANTHROPIC_API_KEY`
OpenAI Chat	`openai-chat`	llm	`OPENAI_API_KEY`
Gemini Chat	`gemini-chat`	llm	`GEMINI_API_KEY`
OpenRouter Chat	`openrouter-chat`	llm	`OPENROUTER_API_KEY`

The llm tier (ungrounded baseline / contrast)

The llm tier is deliberately kept apart from the grounded tiers. Grounded providers earn their place in the source tallies by citing the web; ungrounded LLMs do not, so librarium never silently folds them into a grounded run. llm-tier rows in the live table and result output render a dim ungrounded in place of the source count, and the dedupe pipeline, sources.json, and report source totals are completely unaffected by their presence. Use the built-in llm group (--group llm) to run all four at once.

Opt-in, never auto-enabled. Several llm-tier providers share an API key with their grounded counterparts (OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY; Claude uses ANTHROPIC_API_KEY). To keep a plain librarium run — which dispatches every enabled provider — from silently calling an ungrounded model, init treats the llm tier specially:

librarium init --auto does not enable llm-tier providers, even when their key is present. It prints them as found-but-ungrounded with a hint to opt in.
Interactive librarium init lists the llm-tier providers but leaves them unchecked (with an [ungrounded] marker), so you must tick them deliberately.

As a result they stay out of the default run unless you explicitly enable them in config. Reach for them on demand via -p claude,openai-chat,..., a custom group, or --group llm regardless of your init choices.

Default models per provider (each overridable with a per-provider model config key): claude uses claude-haiku-4-5, openai-chat uses gpt-5-mini, gemini-chat uses gemini-2.5-flash, and openrouter-chat uses openai/gpt-4o-mini.

Provider notes

Async submit/poll vs inline execution

Four providers use a true background submit/poll/retrieve pattern and return immediately in mixed or async mode:

perplexity-sonar-deep — uses Perplexity’s Async Sonar API (POST /v1/async/sonar, polled via GET /v1/async/sonar/{id}). Submits and returns a pending handle; poll with librarium status --wait --retrieve.
openai-deep and openai-deep-o3 — use OpenAI’s background deep research API. Same submit-and-poll flow.
gemini-deep — uses Google’s Interactions API (POST /v1beta/interactions with background: true). Submits and returns a pending handle; poll with librarium status --wait --retrieve.

Two Perplexity providers use the Agent API, which has no background mode. They complete inline even in mixed or async mode:

perplexity-deep-research
perplexity-advanced-deep

Usage and cost reporting

Librarium never estimates costs from pricing tables. Usage data comes only from what each provider’s API actually returns.

Provider	What the API reports
`perplexity-sonar-pro`, `perplexity-search`, `perplexity-sonar-deep`	Token counts (`prompt_tokens`, `completion_tokens`) and `cost.total_cost` (USD) when present
`openrouter-online`, `openrouter-chat`	Token counts and a flat `cost` field (USD)
`exa`	`costDollars.total` (USD); no token counts
`gemini-grounded`	`usageMetadata` token counts (`promptTokenCount`, `candidatesTokenCount`) only; no cost field
`gemini-deep`	Interactions API token counts (`total_input_tokens`, `total_output_tokens`) only; no cost field

All other providers either return no usage data or return only token counts with no cost. The reported totals in summary.md and the live table cover only the providers that reported something — the displayed cost is always sourced from the API, never calculated.

Model overrides

gemini-deep accepts a model config key to select the Deep Research agent. It defaults to the deep-research-preview-04-2026 agent; set model to deep-research-max-preview-04-2026 for the heavier (and more expensive) variant:

{
  "providers": {
    "gemini-deep": {
      "apiKey": "$GEMINI_API_KEY",
      "enabled": true,
      "model": "deep-research-max-preview-04-2026"
    }
  }
}

The four llm-tier providers (claude, openai-chat, gemini-chat, openrouter-chat) also accept a per-provider model config override; see the llm tier for their defaults. No other built-in provider currently exposes a model override via config. The OpenRouter and Perplexity Agent-based grounded providers use fixed model identifiers in their adapter code.

Provider	Env var	Get a key
Anthropic (Claude)	`ANTHROPIC_API_KEY`	platform.claude.com/docs/en/api/overview
Perplexity	`PERPLEXITY_API_KEY`	docs.perplexity.ai/home
OpenAI	`OPENAI_API_KEY`	platform.openai.com
Google Gemini	`GEMINI_API_KEY`	ai.google.dev
Brave	`BRAVE_API_KEY`	brave.com/search/api
Exa	`EXA_API_KEY`	exa.ai
You.com	`YOU_COM_API_KEY`	you.com/docs/welcome
Kagi	`KAGI_API_KEY`	help.kagi.com
Jina AI	`JINA_AI_API_KEY`	jina.ai
SearchAPI	`SEARCHAPI_API_KEY`	searchapi.io
SerpAPI	`SERPAPI_API_KEY`	serpapi.com
Tavily	`TAVILY_API_KEY`	docs.tavily.com
Firecrawl	`FIRECRAWL_API_KEY`	docs.firecrawl.dev
OpenRouter	`OPENROUTER_API_KEY`	openrouter.ai

Run librarium init --auto to discover which keys are already present in your environment and enable their matching providers automatically. Note that init never auto-enables llm-tier providers, even when their key is present — see the llm tier.

Async behavior notes

perplexity-sonar-deep uses Perplexity’s Async Sonar API (POST /v1/async/sonar, polled via GET /v1/async/sonar/{id}). In mixed and async modes it submits and returns immediately; librarium status --wait --retrieve polls and retrieves results like openai-deep tasks.

gemini-deep uses Google’s Interactions API (POST /v1beta/interactions with background: true). In mixed and async modes it submits and returns immediately; poll with librarium status --wait --retrieve.

perplexity-deep-research and perplexity-advanced-deep use Perplexity’s Agent API, which has no background mode. They complete inline even in mixed mode.

Legacy provider ID aliases

Perplexity provider IDs were renamed to match current product names:

perplexity-sonar renamed to perplexity-sonar-pro
perplexity-deep renamed to perplexity-sonar-deep

For backward compatibility, librarium still accepts legacy IDs in:

run --providers
provider config keys in ~/.config/librarium/config.json
custom group members
fallback targets

Legacy IDs are normalized to canonical IDs and emit a warning. Output files and run.json always use canonical IDs.

Custom providers

You can also add custom providers (npm modules or local scripts) via config. See Custom providers for the full implementation guide.

Providers