@nijaru/pi-search 0.0.4 → 0.0.5

package/README.md

@@ -32,8 +32,12 @@ Pi tools:
   automatically.
 - Other/local models use configured Exa automatically only when metered search
   is allowed; Exa returns semantic results with excerpts and reported usage.
+  Configured DeepSeek is the cheaper second metered path (structured dates and
+  excerpts through `site:`/`after:`/`before:` operators), selected after Exa
+  under metered routing.
 - In free-only mode, configured Brave is the conservative paced keyword/fresh
-  path. Set `PI_SEARCH_PREFER_FREE=1` to prefer it before metered Exa.
+  path. Set `PI_SEARCH_PREFER_FREE=1` to prefer it before metered providers,
+  with one metered fallback after a safe Brave failure.
   Parallel, Cloudflare Web Search, and the official X API remain explicit providers.
 - Automatic routing permits at most one visible fallback after a safe
   authentication, rate-limit, or unavailable failure. Network, timeout, and
@@ -55,11 +59,14 @@ registered only when their key is present at construction, an unset
 variable simply leaves that provider disabled.
 
 ```bash
-# Optional metered semantic search for non-native/local models
+# Optional metered search for non-native/local models
 export EXA_API_KEY=...
-# Allow Exa (and deliberate metered fallback) in automatic routing:
+# Cheaper second metered path; selected after Exa when metered routing is allowed.
+export DEEPSEEK_API_KEY=...            # $0.75 per 1K successful requests
+# Allow metered providers (Exa, DeepSeek) in automatic routing:
 # export PI_SEARCH_ALLOW_METERED=1
-# Prefer admitted free-mode Brave before Exa, but allow Exa if Brave is absent:
+# Prefer admitted free-mode Brave before metered providers, with one metered
+# fallback after a safe Brave failure:
 # export PI_SEARCH_PREFER_FREE=1
 
 # Optional last-resort keyword/fresh search
@@ -70,7 +77,7 @@ export BRAVE_API_KEY=...
 # metered Brave with the opt-in below.
 export PI_SEARCH_BRAVE_FREE_ONLY=1
 # Free mode does not inspect account billing or guarantee no paid overage.
-# Explicit `provider: "exa"` remains an intentional per-call opt-in.
+# Explicit `provider: "exa"` or `"deepseek"` remains an intentional per-call opt-in.
 
 # Explicit secondary providers
 export PARALLEL_API_KEY=...
@@ -99,9 +106,11 @@ model alias rather than full Flash/Pro or legacy model IDs. Explicit
 compatible registry model with `executionModel` even when another model is
 active; this makes model and billing choice visible. Pi's `/login xai` subscription flow is supported by the
 registry for Grok web/X search. A provider hint such as `provider: "exa"`,
-`"parallel"`, or `"x"` is strict and never falls through to another provider.
+`"deepseek"`, `"parallel"`, or `"x"` is strict and never falls through to
+another provider.
 Without a hint, the router selects available native search first, then Exa,
-then Brave when the corresponding credentials and hard constraints permit it.
+then DeepSeek, then Brave when the corresponding credentials and hard
+constraints permit it.
 Set `includeContent: true` on `web_search` only when bounded excerpts from
 selected source pages are needed; this reuses the safe local fetch path. For
 `web_research`, use `executionModel` with an explicit model-mediated `provider`
@@ -141,6 +150,26 @@ with saved/exportable Pi transcripts unless contractually permitted. Clarify
 those rights before using Ceramic. Zero Data Retention describes provider
 handling, not permission to retain results yourself.
 
+### DeepSeek Search
+
+DeepSeek Search is a direct metered provider (`provider: "deepseek"`). The
+adapter composes domain and inclusive publication-date filters into DeepSeek's
+documented `site:`, `-site:`, `after:`, and `before:` query operators, and
+requests the model-oriented summary rather than full page content; readable
+pages remain `web_fetch`'s job. DeepSeek caps queries at 128 characters
+including those operators, so a long filtered query is rejected before
+dispatch instead of being truncated. Requests that need social, media,
+location, context-size, token-budget, or live-access controls are rejected
+rather than degraded. Date operators have day granularity, so the provider
+window is widened to whole days and a warning is reported; time-of-day bounds
+are then enforced locally on results that report a date. Results with a known
+publication date are filtered to the requested inclusive range; undated
+results remain visible with an explicit warning.
+
+The adapter reads `DEEPSEEK_API_KEY` from the environment, like the other
+direct providers. A DeepSeek login stored only in Pi's model registry does not
+register it.
+
 ### Local and virtual models
 
 Research queries retain the 2,000-character runtime limit. The tool schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nijaru/pi-search",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Provider-neutral web search and fetching tools for Pi",
   "type": "module",
   "license": "MIT",
@@ -41,9 +41,9 @@
     "live:smoke": "bun scripts/live-smoke.ts"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.2.0",
-    "@earendil-works/pi-coding-agent": "1.2.0",
-    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/bun": "1.3.14",
     "@types/turndown": "^5.0.6",
     "typebox": "1.3.10",

package/src/contracts.ts

@@ -566,6 +566,7 @@ export type ProviderId =
 	| "gemini"
 	| "brave"
 	| "exa"
+	| "deepseek"
 	| "cloudflare"
 	| "parallel"
 	| "parallel-responses"
@@ -584,6 +585,7 @@ export const SEARCH_PROVIDER_HINT_IDS = [
 	"gemini",
 	"brave",
 	"exa",
+	"deepseek",
 	"cloudflare",
 	"parallel",
 	"parallel-responses",

package/src/deepseek.ts

@@ -0,0 +1,308 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderProfile,
+	ProviderRateLimitInfo,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { httpSource, objectValue, optionalString, optionalTimestamp, postJson, requireApiKey, type SearchHttpFetch } from "./provider-http";
+import { validateSearchRequest } from "./search";
+
+export const DEEPSEEK_SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search";
+export const DEFAULT_DEEPSEEK_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** Current published price for one successful Search API request. */
+export const DEEPSEEK_ESTIMATED_SEARCH_COST_USD = 0.00075;
+/** DeepSeek counts query characters, including any operator clauses. */
+export const DEEPSEEK_MAX_QUERY_LENGTH = 128;
+const DEEPSEEK_MAX_SCORE = 3;
+
+export interface DeepSeekAdapterOptions {
+	readonly apiKey?: string;
+	readonly endpoint?: string;
+	readonly fetchImpl?: SearchHttpFetch;
+	readonly maxResponseBytes?: number;
+}
+
+// DeepSeek's search index is a general web index with its own authority and
+// freshness ranking. It exposes no dedicated social, media, context, or
+// location controls, so those requests are rejected rather than degraded.
+const capabilities: ProviderCapabilities = {
+	keyword: true,
+	freshness: true,
+	excerpts: true,
+	domainFilter: true,
+	dateFilter: true,
+};
+
+const profile: ProviderProfile = {
+	auth: "environment",
+	costModel: "per-request",
+	estimatedCostUsd: DEEPSEEK_ESTIMATED_SEARCH_COST_USD,
+};
+
+function unsupported(message: string): never {
+	throw createProviderError({ provider: "deepseek", kind: "unsupported", message, retryable: false });
+}
+
+function acceptRequestOptions(request: SearchRequest): void {
+	if (request.social !== undefined) unsupported("DeepSeek search does not provide dedicated social/X constraints");
+	if (request.executionModel !== undefined) unsupported("DeepSeek search is a direct provider and does not accept an execution model");
+	if (request.searchContextSize !== undefined) unsupported("DeepSeek search does not expose provider-native search context sizing");
+	if (request.returnTokenBudget !== undefined) unsupported("DeepSeek search does not expose a returned-token budget");
+	if (request.externalWebAccess !== undefined) unsupported("DeepSeek search does not expose live/cache-only selection");
+	if (request.userLocation !== undefined) unsupported("DeepSeek search does not expose a user location contract");
+	if (request.imageSettings !== undefined) unsupported("DeepSeek search does not expose image result settings");
+	if (request.searchContentTypes !== undefined) unsupported("DeepSeek search does not expose content-type selection");
+}
+
+/** The UTC calendar day for an ISO-8601 date or instant; operators are day-based. */
+function utcDatePart(value: string): string {
+	return new Date(Date.parse(value)).toISOString().slice(0, 10);
+}
+
+/** Shift a YYYY-MM-DD date in UTC. */
+function shiftDate(day: string, deltaDays: number): string {
+	const [year, month, date] = day.split("-").map(Number);
+	return new Date(Date.UTC(year!, month! - 1, date! + deltaDays)).toISOString().slice(0, 10);
+}
+
+/**
+ * DeepSeek's `after:`/`before:` operators are date boundaries, while the
+ * request contract uses inclusive bounds. Widen each boundary by one day so
+ * the provider window cannot exclude the requested boundary days; the exact
+ * inclusive range is then enforced locally for results that report a date.
+ */
+function dateOperators(request: SearchRequest): { readonly operators: string[]; readonly widened: boolean } {
+	const operators: string[] = [];
+	let widened = false;
+	const from = request.dateRange?.from;
+	const to = request.dateRange?.to;
+	if (from !== undefined) {
+		if (from.includes("T")) widened = true;
+		operators.push(`after:${shiftDate(utcDatePart(from), -1)}`);
+	}
+	if (to !== undefined) {
+		if (to.includes("T")) widened = true;
+		operators.push(`before:${shiftDate(utcDatePart(to), 1)}`);
+	}
+	return { operators, widened };
+}
+
+function domainClauses(request: SearchRequest): string[] {
+	const include = request.domains?.include ?? [];
+	const exclude = request.domains?.exclude ?? [];
+	const clauses: string[] = [];
+	// DeepSeek documents multiple allowed sites as `site:a OR site:b` clauses
+	// joined by OR rather than a parenthesized group.
+	if (include.length > 0) clauses.push(include.map((domain) => `site:${domain}`).join(" OR "));
+	clauses.push(...exclude.map((domain) => `-site:${domain}`));
+	return clauses;
+}
+
+export interface DeepSeekRequestPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+export function buildDeepSeekRequest(request: SearchRequest): DeepSeekRequestPlan {
+	const normalized = validateSearchRequest(request);
+	acceptRequestOptions(normalized);
+
+	const appliedOptions: SearchOption[] = ["maxResults", "mode"];
+	const warnings: SearchWarning[] = [];
+	if (normalized.domains?.include !== undefined || normalized.domains?.exclude !== undefined) appliedOptions.push("domains");
+	if (normalized.dateRange !== undefined) appliedOptions.push("dateRange");
+
+	if (normalized.mode === "keyword") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "DeepSeek search reranks by its own relevance and authority signals; keyword-only ranking is not guaranteed" });
+	}
+	if (normalized.mode === "fresh" && normalized.dateRange?.from === undefined) {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "DeepSeek search can return recent sources but this request does not impose a recent-date floor" });
+	}
+
+	const dates = dateOperators(normalized);
+	if (dates.widened) {
+		warnings.push({ code: "unsupported-option", option: "dateRange", message: "DeepSeek date operators have day granularity; time-of-day bounds are enforced locally on results that report a date" });
+	}
+
+	const query = [normalized.query, ...domainClauses(normalized), ...dates.operators].filter((part) => part.length > 0).join(" ");
+	// Count Unicode code points, matching DeepSeek's own limit rather than
+	// JavaScript's UTF-16 length.
+	if ([...query].length > DEEPSEEK_MAX_QUERY_LENGTH) {
+		throw createProviderError({
+			provider: "deepseek",
+			kind: "unsupported",
+			fallbackSafe: true,
+			message: `DeepSeek limits queries to ${DEEPSEEK_MAX_QUERY_LENGTH} characters including site/date operators; the composed query is ${[...query].length} characters`,
+			retryable: false,
+		});
+	}
+
+	return {
+		body: {
+			query,
+			count: normalized.maxResults ?? 10,
+			// DeepSeek returns a model-oriented summary regardless; full page
+			// content stays the job of the local web_fetch path.
+			need_content: false,
+		},
+		appliedOptions,
+		warnings,
+	};
+}
+
+function malformed(message: string): never {
+	throw createProviderError({ provider: "deepseek", kind: "malformed", message: `DeepSeek returned a malformed response (${message})`, retryable: false });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function scoreFromResult(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return Math.max(0, Math.min(1, value / DEEPSEEK_MAX_SCORE));
+}
+
+function excerptFromRecord(record: Record<string, unknown>): string | undefined {
+	// `summary` is the 600-800 character text DeepSeek intends models to read;
+	// `snippet` is the shorter display string.
+	return optionalString(record.summary, 4_000) ?? optionalString(record.snippet, 4_000);
+}
+
+/** Inclusive UTC day boundaries for date-only bounds; exact instants otherwise. */
+function boundaryMs(value: string, endOfDay: boolean): number | undefined {
+	const milliseconds = Date.parse(value);
+	if (!Number.isFinite(milliseconds)) return undefined;
+	return endOfDay && !value.includes("T") ? milliseconds + 86_400_000 - 1 : milliseconds;
+}
+
+/**
+ * The date operators widen the provider window to protect inclusive boundary
+ * days, so enforce the exact inclusive range on results whose date is known.
+ * Results without a date cannot be checked and remain visible with a warning.
+ */
+function filterByDateRange(
+	results: readonly SearchResult[],
+	request: SearchRequest,
+): { readonly results: readonly SearchResult[]; readonly removed: number; readonly unverified: number } {
+	const fromMs = request.dateRange?.from === undefined ? undefined : boundaryMs(request.dateRange.from, false);
+	const toMs = request.dateRange?.to === undefined ? undefined : boundaryMs(request.dateRange.to, true);
+	if (fromMs === undefined && toMs === undefined) return { results, removed: 0, unverified: 0 };
+	const kept: SearchResult[] = [];
+	let removed = 0;
+	let unverified = 0;
+	for (const result of results) {
+		const publishedMs = result.publishedAt === undefined ? Number.NaN : Date.parse(result.publishedAt);
+		if (!Number.isFinite(publishedMs)) {
+			unverified += 1;
+			kept.push(result);
+			continue;
+		}
+		if ((fromMs !== undefined && publishedMs < fromMs) || (toMs !== undefined && publishedMs > toMs)) {
+			removed += 1;
+			continue;
+		}
+		kept.push(result);
+	}
+	return { results: kept, removed, unverified };
+}
+
+export function normalizeDeepSeekResponse(
+	payload: unknown,
+	request: SearchRequest,
+	options: { readonly requestId?: string; readonly rateLimits?: ProviderRateLimitInfo } = {},
+): SearchResponse {
+	const normalized = validateSearchRequest(request);
+	const root = objectValue(payload, "response", "deepseek");
+	if (!Array.isArray(root.results)) return malformed("results is not an array");
+	const results: SearchResult[] = [];
+	let discarded = 0;
+	for (const value of root.results) {
+		// A single malformed entry should not hide otherwise usable evidence.
+		if (!isRecord(value)) {
+			discarded += 1;
+			continue;
+		}
+		const parsed = httpSource(value.url, "deepseek");
+		if (parsed === undefined) {
+			discarded += 1;
+			continue;
+		}
+		results.push({
+			url: parsed.url,
+			title: optionalString(value.title, 500),
+			domain: parsed.domain,
+			publishedAt: optionalTimestamp(value.date),
+			excerpt: excerptFromRecord(value),
+			provider: "deepseek",
+			searchQuery: normalized.query,
+			score: scoreFromResult(value.rerank_score),
+		});
+	}
+	if (discarded > 0 && results.length === 0) return malformed("results contained no parseable HTTP URLs");
+	const dateFiltered = filterByDateRange(results, normalized);
+	const warnings: SearchWarning[] = [];
+	if (discarded > 0) {
+		warnings.push({ code: "partial-results", message: `DeepSeek discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}` });
+	}
+	if (dateFiltered.removed > 0) {
+		warnings.push({ code: "partial-results", message: `DeepSeek removed ${dateFiltered.removed} result entr${dateFiltered.removed === 1 ? "y" : "ies"} outside the requested date range` });
+	}
+	if (dateFiltered.unverified > 0) {
+		warnings.push({ code: "partial-results", message: `DeepSeek could not verify the publication date of ${dateFiltered.unverified} result entr${dateFiltered.unverified === 1 ? "y" : "ies"} against the requested date range` });
+	}
+	return {
+		query: normalized.query,
+		results: dateFiltered.results.slice(0, normalized.maxResults ?? 10),
+		provider: "deepseek",
+		appliedOptions: [],
+		warnings,
+		...(options.requestId === undefined ? {} : { requestId: options.requestId }),
+		...(options.rateLimits === undefined ? {} : { usage: { rateLimits: options.rateLimits } }),
+	};
+}
+
+export class DeepSeekProvider implements Provider {
+	readonly id = "deepseek" as const;
+	readonly capabilities = capabilities;
+	readonly profile = profile;
+	private readonly apiKey?: string;
+	private readonly endpoint: string;
+	private readonly fetchImpl: SearchHttpFetch;
+	private readonly maxResponseBytes: number;
+
+	constructor(options: DeepSeekAdapterOptions) {
+		this.apiKey = options.apiKey;
+		this.endpoint = options.endpoint ?? DEEPSEEK_SEARCH_ENDPOINT;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_DEEPSEEK_RESPONSE_BYTES;
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, _context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		const plan = buildDeepSeekRequest(normalized);
+		const result = await postJson({
+			provider: this.id,
+			url: this.endpoint,
+			headers: { authorization: `Bearer ${requireApiKey(this.id, this.apiKey)}` },
+			body: plan.body,
+			signal,
+			fetchImpl: this.fetchImpl,
+			maxResponseBytes: this.maxResponseBytes,
+		});
+		const response = normalizeDeepSeekResponse(result.payload, normalized, result);
+		return { ...response, appliedOptions: plan.appliedOptions, warnings: [...plan.warnings, ...response.warnings] };
+	}
+}
+
+export function createDeepSeekProvider(options: DeepSeekAdapterOptions): DeepSeekProvider {
+	return new DeepSeekProvider(options);
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import { createAnthropicProvider } from "./anthropic";
 import { createBraveProvider, BraveQuotaTracker } from "./brave";
 import { createBraveAnswersProvider } from "./brave-answers";
 import { createCodexProvider } from "./codex";
+import { createDeepSeekProvider } from "./deepseek";
 import { createExaProvider } from "./exa";
 import { createCloudflareProvider, type CloudflareUpstream } from "./cloudflare";
 import { createGeminiProvider } from "./gemini";
@@ -20,9 +21,9 @@ import { registerWebSearch } from "./search-tool";
 
 /**
  * Native grounding is selected for supported active models. Exa is the
- * metered non-native default only when explicitly allowed; Brave is the paced
- * last-resort keyword path. Automatic availability failures may use one
- * visible fallback.
+ * metered non-native default only when explicitly allowed, DeepSeek is the
+ * cheaper second metered path, and Brave is the paced last-resort keyword
+ * path. Automatic availability failures may use one visible fallback.
  */
 export default function (pi: ExtensionAPI): void {
 	const braveKey = process.env.BRAVE_API_KEY;
@@ -40,9 +41,11 @@ export default function (pi: ExtensionAPI): void {
 	const anthropic = createAnthropicProvider();
 	const meta = createMetaProvider();
 	const exaKey = process.env.EXA_API_KEY;
+	const deepseekKey = process.env.DEEPSEEK_API_KEY;
 	const parallelKey = process.env.PARALLEL_API_KEY;
 	const xToken = process.env.X_API_BEARER_TOKEN;
 	const exa = createExaProvider({ apiKey: exaKey });
+	const deepseek = createDeepSeekProvider({ apiKey: deepseekKey });
 	const cloudflareUpstream = process.env.PI_SEARCH_CLOUDFLARE_PROVIDER;
 	const cloudflareAccount = process.env.CLOUDFLARE_ACCOUNT_ID;
 	const cloudflareToken = process.env.CLOUDFLARE_API_TOKEN;
@@ -79,6 +82,7 @@ export default function (pi: ExtensionAPI): void {
 		anthropic,
 		meta,
 		exa,
+		deepseek,
 		cloudflare,
 		cloudflareConfigured,
 		parallel,
@@ -88,6 +92,7 @@ export default function (pi: ExtensionAPI): void {
 		brave,
 		braveConfigured: braveKey !== undefined && braveKey.trim().length > 0,
 		exaConfigured: exaKey !== undefined && exaKey.trim().length > 0,
+		deepseekConfigured: deepseekKey !== undefined && deepseekKey.trim().length > 0,
 		parallelConfigured: parallelKey !== undefined && parallelKey.trim().length > 0,
 		parallelResponsesConfigured: parallelResponsesEnabled,
 		braveAnswersConfigured: braveAnswersEnabled,
@@ -102,6 +107,7 @@ export default function (pi: ExtensionAPI): void {
 		brave: braveKey !== undefined && braveKey.trim().length > 0,
 		braveAnswers: braveAnswersEnabled,
 		exa: exaKey !== undefined && exaKey.trim().length > 0,
+		deepseek: deepseekKey !== undefined && deepseekKey.trim().length > 0,
 		cloudflare: cloudflareConfigured,
 		parallel: parallelKey !== undefined && parallelKey.trim().length > 0,
 		parallelResponses: parallelResponsesEnabled,

package/src/provider-availability.ts

@@ -13,6 +13,7 @@ export interface ProviderHintAvailability {
 	readonly brave?: boolean;
 	readonly braveAnswers?: boolean;
 	readonly exa?: boolean;
+	readonly deepseek?: boolean;
 	readonly cloudflare?: boolean;
 	readonly parallel?: boolean;
 	readonly parallelResponses?: boolean;
@@ -30,6 +31,7 @@ export function availableProviderHints(availability: ProviderHintAvailability):
 		|| (id === "brave" && availability.brave === true)
 		|| (id === "brave-answers" && availability.braveAnswers === true)
 		|| (id === "exa" && availability.exa === true)
+		|| (id === "deepseek" && availability.deepseek === true)
 		|| (id === "cloudflare" && availability.cloudflare === true)
 		|| (id === "parallel" && availability.parallel === true)
 		|| (id === "parallel-responses" && availability.parallelResponses === true)

package/src/router.ts

@@ -17,6 +17,7 @@ export interface SearchRouterOptions {
 	readonly meta?: Provider;
 	readonly brave?: Provider;
 	readonly exa?: Provider;
+	readonly deepseek?: Provider;
 	readonly cloudflare?: Provider;
 	readonly parallel?: Provider;
 	readonly parallelResponses?: Provider;
@@ -25,6 +26,7 @@ export interface SearchRouterOptions {
 	/** Credential presence is supplied by the construction boundary. */
 	readonly braveConfigured?: boolean;
 	readonly exaConfigured?: boolean;
+	readonly deepseekConfigured?: boolean;
 	readonly cloudflareConfigured?: boolean;
 	readonly parallelConfigured?: boolean;
 	readonly parallelResponsesConfigured?: boolean;
@@ -129,16 +131,41 @@ function selection(provider: Provider, automatic: boolean, fallbacks: readonly P
 	return { provider, automatic, fallbacks: fallbacks.slice(0, 1) };
 }
 
+/**
+ * Metered direct providers in selection order, gated by the billing policy.
+ * Exa comes first because it has current independent quality evidence;
+ * DeepSeek is the cheaper second candidate.
+ */
+function meteredCandidates(request: SearchRequest, options: SearchRouterOptions, policy: SearchBillingPolicy): readonly Provider[] {
+	if (policy === "free-only") return [];
+	const candidates: Provider[] = [];
+	if (options.exaConfigured === true && options.exa !== undefined && canServe(options.exa, request)) candidates.push(options.exa);
+	if (options.deepseekConfigured === true && options.deepseek !== undefined && canServe(options.deepseek, request)) candidates.push(options.deepseek);
+	return candidates;
+}
+
+/** A Brave path this request and policy permit, ignoring any quota window. */
+function braveCandidate(request: SearchRequest, options: SearchRouterOptions, policy: SearchBillingPolicy): Provider | undefined {
+	const braveAllowed = policy === "allow-configured-metered" || options.braveFreeCapacityConfigured === true;
+	if (options.braveConfigured !== true || options.brave === undefined || !braveAllowed) return undefined;
+	return canServe(options.brave, request) ? options.brave : undefined;
+}
+
+function directCandidates(request: SearchRequest, options: SearchRouterOptions, policy: SearchBillingPolicy): readonly Provider[] {
+	const brave = braveCandidate(request, options, policy);
+	return [
+		...meteredCandidates(request, options, policy),
+		...(brave !== undefined && options.braveCapacity?.canAttempt() !== false ? [brave] : []),
+	];
+}
+
 function directFallback(
 	primary: Provider,
 	request: SearchRequest,
 	options: SearchRouterOptions,
 	policy: SearchBillingPolicy,
 ): readonly Provider[] {
-	if (policy !== "free-only" && primary.id !== "exa" && options.exaConfigured === true && options.exa !== undefined && canServe(options.exa, request)) return [options.exa];
-	const braveAllowed = policy === "allow-configured-metered" || options.braveFreeCapacityConfigured === true;
-	if (primary.id !== "brave" && options.braveConfigured === true && options.brave !== undefined && braveAllowed && options.braveCapacity?.canAttempt() !== false && canServe(options.brave, request)) return [options.brave];
-	return [];
+	return directCandidates(request, options, policy).filter((provider) => provider.id !== primary.id).slice(0, 1);
 }
 
 function checkBraveCapacity(options: SearchRouterOptions): void {
@@ -191,6 +218,11 @@ function explicitProvider(
 		if (!canServe(options.exa, request)) return unavailable("Exa cannot satisfy the requested search constraints", provider);
 		return selection(options.exa, false);
 	}
+	if (provider === "deepseek") {
+		if (options.deepseek === undefined || options.deepseekConfigured !== true) return unavailable("DeepSeek search is not configured; set DEEPSEEK_API_KEY", provider);
+		if (!canServe(options.deepseek, request)) return unavailable("DeepSeek cannot satisfy the requested search constraints", provider);
+		return selection(options.deepseek, false);
+	}
 	if (provider === "cloudflare") {
 		if (options.cloudflare === undefined || options.cloudflareConfigured !== true) return unavailable("Cloudflare search is not configured; set its account ID, API token, and explicit upstream", provider);
 		if (!canServe(options.cloudflare, request)) return unavailable("Cloudflare cannot satisfy the requested search constraints", provider);
@@ -277,29 +309,47 @@ export function createSearchRouter(options: SearchRouterOptions): SearchProvider
 		}
 
 		const exaConfigured = options.exaConfigured === true;
-		const exaAllowed = policy !== "free-only";
-		const exaCanMatchMode = exaAllowed && options.exa !== undefined && canServe(options.exa, normalized);
-
-		const braveCanMatchMode = options.brave !== undefined && canServe(options.brave, normalized);
+		const meteredAllowed = policy !== "free-only";
+		const deepseekConfigured = options.deepseekConfigured === true;
 		const braveConfigured = options.braveConfigured === true;
 		const braveAllowed = policy === "allow-configured-metered" || options.braveFreeCapacityConfigured === true;
-		// prefer-free chooses the admitted Brave path before a metered Exa call.
-		if (policy === "prefer-free" && braveCanMatchMode && braveConfigured && braveAllowed && options.braveCapacity?.canAttempt() !== false) {
+		const brave = braveCandidate(normalized, options, policy);
+		// prefer-free chooses the admitted Brave path before any metered call, but
+		// a safe Brave failure may still use the same single metered fallback.
+		if (policy === "prefer-free" && brave !== undefined && options.braveCapacity?.canAttempt() !== false) {
 			checkBraveCapacity(options);
-			return selection(options.brave!, true);
+			return selection(brave, true, meteredCandidates(normalized, options, policy).slice(0, 1));
+		}
+		const metered = meteredCandidates(normalized, options, policy);
+		if (metered[0] !== undefined) {
+			const fallback = metered[1] ?? (brave !== undefined && options.braveCapacity?.canAttempt() !== false ? brave : undefined);
+			return selection(metered[0], true, fallback === undefined ? [] : [fallback]);
 		}
-		if (exaConfigured && exaCanMatchMode) return selection(options.exa!, true, directFallback(options.exa!, normalized, options, policy));
-		if (braveCanMatchMode && braveConfigured && braveAllowed) {
+		if (brave !== undefined) {
 			checkBraveCapacity(options);
-			return selection(options.brave!, true);
+			return selection(brave, true);
 		}
 		// No direct provider was eligible; name the hard constraints the
 		// configured providers could not honor instead of blaming the retrieval
 		// mode, which never blocks selection on its own.
-		if (exaAllowed && exaConfigured && options.exa !== undefined) {
+		if (meteredAllowed && exaConfigured && options.exa !== undefined) {
 			const unmet = unmetConstraintNames(normalized);
 			return unavailable(`Exa cannot satisfy the requested ${unmet.join(", ") || "search constraints"}`, "exa");
 		}
+		if (meteredAllowed && deepseekConfigured && options.deepseek !== undefined) {
+			const unmet = unmetConstraintNames(normalized);
+			return unavailable(`DeepSeek cannot satisfy the requested ${unmet.join(", ") || "search constraints"}`, "deepseek");
+		}
+		if (!meteredAllowed) {
+			const eligible = [
+				exaConfigured && options.exa !== undefined && canServe(options.exa, normalized) ? "Exa" : undefined,
+				deepseekConfigured && options.deepseek !== undefined && canServe(options.deepseek, normalized) ? "DeepSeek" : undefined,
+			].filter((name): name is string => name !== undefined);
+			if (eligible.length > 0) {
+				const names = eligible.join(" and ");
+				return unavailable(`${names} ${eligible.length === 1 ? "is" : "are"} configured and could serve this request, but metered automatic routing is disabled; set PI_SEARCH_ALLOW_METERED=1 or use an explicit provider hint`, "router");
+			}
+		}
 		if (braveConfigured && !braveAllowed) return unavailable("Brave is configured but free-mode admission is disabled; set PI_SEARCH_BRAVE_FREE_ONLY=1 or PI_SEARCH_ALLOW_METERED=1", "router");
 		if (braveConfigured && options.brave !== undefined) {
 			const unmet = unmetConstraintNames(normalized);