@opengeni/config 3.1.1 → 3.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/claude-subscription-capacity.d.ts +9 -0
- package/dist/claude-subscription-oauth.d.ts +17 -0
- package/dist/claude-subscription-usage.d.ts +4 -2
- package/dist/credit-promotions.d.ts +25 -0
- package/dist/index.d.ts +1564 -56
- package/dist/index.js +3524 -614
- package/dist/index.js.map +1 -1
- package/dist/realtime-voice-pricing.d.ts +30 -0
- package/dist/subscription-account-selection.d.ts +17 -0
- package/dist/web-search.d.ts +174 -0
- package/package.json +5 -5
- package/src/claude-subscription-capacity.ts +129 -0
- package/src/claude-subscription-oauth.ts +33 -0
- package/src/claude-subscription-usage.ts +225 -5
- package/src/credit-promotions.ts +68 -0
- package/src/index.ts +3406 -178
- package/src/realtime-voice-pricing.ts +83 -0
- package/src/subscription-account-selection.ts +36 -0
- package/src/web-search.ts +600 -0
|
@@ -0,0 +1,600 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Provider-agnostic web search: the deployment-funded `web_search` and
|
|
5
|
+
* `web_fetch` agent tools.
|
|
6
|
+
*
|
|
7
|
+
* Hosted search (the provider-executed `web_search` tool of the model's own
|
|
8
|
+
* API) follows the model catalog. Provider search is a separate,
|
|
9
|
+
* deployment-configured HTTP provider that Opengeni calls from the worker.
|
|
10
|
+
* Search and page reading are separate slots; each slot holds an ordered
|
|
11
|
+
* list of providers, and a call moves to the next provider when one fails.
|
|
12
|
+
* By default the provider tools are offered only where the turn has no
|
|
13
|
+
* hosted search (`OPENGENI_WEB_SEARCH_PREFER=native`).
|
|
14
|
+
*
|
|
15
|
+
* Adding a provider means one catalog entry here plus one adapter in
|
|
16
|
+
* `@opengeni/runtime/web-search`.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
export const WEB_SEARCH_PROVIDER_IDS = [
|
|
20
|
+
"tinyfish",
|
|
21
|
+
"parallel",
|
|
22
|
+
"perplexity",
|
|
23
|
+
"exa",
|
|
24
|
+
"tavily",
|
|
25
|
+
"firecrawl",
|
|
26
|
+
"brave",
|
|
27
|
+
"jina",
|
|
28
|
+
"searxng",
|
|
29
|
+
] as const;
|
|
30
|
+
export type WebSearchProviderId = (typeof WEB_SEARCH_PROVIDER_IDS)[number];
|
|
31
|
+
|
|
32
|
+
/** Used when `OPENGENI_WEB_SEARCH_PROVIDER` is unset: free with an account key. */
|
|
33
|
+
export const DEFAULT_WEB_SEARCH_PROVIDER: WebSearchProviderId = "tinyfish";
|
|
34
|
+
|
|
35
|
+
/** Model-visible names of the provider tools. */
|
|
36
|
+
export const WEB_SEARCH_TOOL_NAME = "web_search";
|
|
37
|
+
export const WEB_FETCH_TOOL_NAME = "web_fetch";
|
|
38
|
+
export type WebSearchProviderToolName = typeof WEB_SEARCH_TOOL_NAME | typeof WEB_FETCH_TOOL_NAME;
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* `native` (default): offer provider tools only to turns without hosted
|
|
42
|
+
* search. `provider`: offer them to every turn and withhold the SDK-hosted
|
|
43
|
+
* `web_search` tool. SuperGrok keeps its transport-level native search either
|
|
44
|
+
* way because Opengeni does not attach it as an agent tool.
|
|
45
|
+
*/
|
|
46
|
+
export const WebSearchPreference = z.enum(["native", "provider"]);
|
|
47
|
+
export type WebSearchPreference = z.infer<typeof WebSearchPreference>;
|
|
48
|
+
|
|
49
|
+
/** One operation (search or page fetch) a provider offers. */
|
|
50
|
+
export type WebSearchProviderOperation = {
|
|
51
|
+
/** Pay-as-you-go list price of one successful call, in USD micros. */
|
|
52
|
+
listPriceMicros: number;
|
|
53
|
+
/** The operation needs an API key; keyless calls are billed as free. */
|
|
54
|
+
keyRequired: boolean;
|
|
55
|
+
/** Default API base URL; null when the operator must supply one. */
|
|
56
|
+
defaultBaseUrl: string | null;
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
export type WebSearchProviderCatalogEntry = {
|
|
60
|
+
id: WebSearchProviderId;
|
|
61
|
+
label: string;
|
|
62
|
+
search: WebSearchProviderOperation | null;
|
|
63
|
+
fetch: WebSearchProviderOperation | null;
|
|
64
|
+
/** Where the list price comes from (checked 2026-10). */
|
|
65
|
+
pricingUrl: string;
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Every supported provider with its capabilities, default endpoints and
|
|
70
|
+
* list prices. A provider response that reports its own dollar cost (Exa
|
|
71
|
+
* `costDollars`, Tavily `usage.credits`) bills that cost instead, and
|
|
72
|
+
* `OPENGENI_WEB_SEARCH_PRICING_JSON` overrides both.
|
|
73
|
+
*/
|
|
74
|
+
export const WEB_SEARCH_PROVIDER_CATALOG: Readonly<
|
|
75
|
+
Record<WebSearchProviderId, WebSearchProviderCatalogEntry>
|
|
76
|
+
> = {
|
|
77
|
+
tinyfish: {
|
|
78
|
+
id: "tinyfish",
|
|
79
|
+
label: "TinyFish",
|
|
80
|
+
// Search and Fetch are free at any wallet balance, within account rate limits.
|
|
81
|
+
search: {
|
|
82
|
+
listPriceMicros: 0,
|
|
83
|
+
keyRequired: true,
|
|
84
|
+
defaultBaseUrl: "https://api.search.tinyfish.ai",
|
|
85
|
+
},
|
|
86
|
+
fetch: {
|
|
87
|
+
listPriceMicros: 0,
|
|
88
|
+
keyRequired: true,
|
|
89
|
+
defaultBaseUrl: "https://api.fetch.tinyfish.ai",
|
|
90
|
+
},
|
|
91
|
+
pricingUrl: "https://www.tinyfish.ai/pricing",
|
|
92
|
+
},
|
|
93
|
+
parallel: {
|
|
94
|
+
id: "parallel",
|
|
95
|
+
label: "Parallel",
|
|
96
|
+
// Search in `fast` mode $1/1k requests; Extract $1/1k URLs.
|
|
97
|
+
search: {
|
|
98
|
+
listPriceMicros: 1_000,
|
|
99
|
+
keyRequired: true,
|
|
100
|
+
defaultBaseUrl: "https://api.parallel.ai",
|
|
101
|
+
},
|
|
102
|
+
fetch: { listPriceMicros: 1_000, keyRequired: true, defaultBaseUrl: "https://api.parallel.ai" },
|
|
103
|
+
pricingUrl: "https://parallel.ai/pricing",
|
|
104
|
+
},
|
|
105
|
+
perplexity: {
|
|
106
|
+
id: "perplexity",
|
|
107
|
+
label: "Perplexity",
|
|
108
|
+
// Search API with `search_type: "fast"`: $1/1k requests.
|
|
109
|
+
search: {
|
|
110
|
+
listPriceMicros: 1_000,
|
|
111
|
+
keyRequired: true,
|
|
112
|
+
defaultBaseUrl: "https://api.perplexity.ai",
|
|
113
|
+
},
|
|
114
|
+
fetch: null,
|
|
115
|
+
pricingUrl: "https://docs.perplexity.ai/getting-started/pricing",
|
|
116
|
+
},
|
|
117
|
+
exa: {
|
|
118
|
+
id: "exa",
|
|
119
|
+
label: "Exa",
|
|
120
|
+
// Auto search $7/1k + highlights $1/1k; contents text $1/1k pages.
|
|
121
|
+
search: { listPriceMicros: 8_000, keyRequired: true, defaultBaseUrl: "https://api.exa.ai" },
|
|
122
|
+
fetch: { listPriceMicros: 1_000, keyRequired: true, defaultBaseUrl: "https://api.exa.ai" },
|
|
123
|
+
pricingUrl: "https://exa.ai/pricing",
|
|
124
|
+
},
|
|
125
|
+
tavily: {
|
|
126
|
+
id: "tavily",
|
|
127
|
+
label: "Tavily",
|
|
128
|
+
// Basic search 1 credit, basic extract 1 credit per 5 URLs; $0.008/credit.
|
|
129
|
+
search: { listPriceMicros: 8_000, keyRequired: true, defaultBaseUrl: "https://api.tavily.com" },
|
|
130
|
+
fetch: { listPriceMicros: 1_600, keyRequired: true, defaultBaseUrl: "https://api.tavily.com" },
|
|
131
|
+
pricingUrl: "https://docs.tavily.com/documentation/api-credits",
|
|
132
|
+
},
|
|
133
|
+
firecrawl: {
|
|
134
|
+
id: "firecrawl",
|
|
135
|
+
label: "Firecrawl",
|
|
136
|
+
// 2 credits per 10 results, 1 credit per scrape, at Hobby-plan credit cost.
|
|
137
|
+
search: {
|
|
138
|
+
listPriceMicros: 6_400,
|
|
139
|
+
keyRequired: true,
|
|
140
|
+
defaultBaseUrl: "https://api.firecrawl.dev",
|
|
141
|
+
},
|
|
142
|
+
fetch: {
|
|
143
|
+
listPriceMicros: 3_200,
|
|
144
|
+
keyRequired: true,
|
|
145
|
+
defaultBaseUrl: "https://api.firecrawl.dev",
|
|
146
|
+
},
|
|
147
|
+
pricingUrl: "https://www.firecrawl.dev/pricing",
|
|
148
|
+
},
|
|
149
|
+
brave: {
|
|
150
|
+
id: "brave",
|
|
151
|
+
label: "Brave Search",
|
|
152
|
+
// $5 per 1k requests.
|
|
153
|
+
search: {
|
|
154
|
+
listPriceMicros: 5_000,
|
|
155
|
+
keyRequired: true,
|
|
156
|
+
defaultBaseUrl: "https://api.search.brave.com",
|
|
157
|
+
},
|
|
158
|
+
fetch: null,
|
|
159
|
+
pricingUrl: "https://brave.com/search/api/",
|
|
160
|
+
},
|
|
161
|
+
jina: {
|
|
162
|
+
id: "jina",
|
|
163
|
+
label: "Jina",
|
|
164
|
+
// At least 10k tokens per search at $0.05/1M; the reader works keyless at
|
|
165
|
+
// a low per-IP rate and can be self-hosted (set its base URL).
|
|
166
|
+
search: { listPriceMicros: 500, keyRequired: true, defaultBaseUrl: "https://s.jina.ai" },
|
|
167
|
+
fetch: { listPriceMicros: 250, keyRequired: false, defaultBaseUrl: "https://r.jina.ai" },
|
|
168
|
+
pricingUrl: "https://jina.ai/reader/",
|
|
169
|
+
},
|
|
170
|
+
searxng: {
|
|
171
|
+
id: "searxng",
|
|
172
|
+
label: "SearXNG",
|
|
173
|
+
// Self-hosted metasearch; needs the operator's base URL.
|
|
174
|
+
search: { listPriceMicros: 0, keyRequired: false, defaultBaseUrl: null },
|
|
175
|
+
fetch: null,
|
|
176
|
+
pricingUrl: "https://docs.searxng.org/",
|
|
177
|
+
},
|
|
178
|
+
};
|
|
179
|
+
|
|
180
|
+
function envProviderName(id: WebSearchProviderId): string {
|
|
181
|
+
return id.toUpperCase();
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** Per-provider API key variable, e.g. `OPENGENI_WEB_TINYFISH_API_KEY`. */
|
|
185
|
+
export function webSearchProviderApiKeyEnv(id: WebSearchProviderId): string {
|
|
186
|
+
return `OPENGENI_WEB_${envProviderName(id)}_API_KEY`;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Per-provider base URL variable, e.g. `OPENGENI_WEB_SEARXNG_BASE_URL`. */
|
|
190
|
+
export function webSearchProviderBaseUrlEnv(id: WebSearchProviderId): string {
|
|
191
|
+
return `OPENGENI_WEB_${envProviderName(id)}_BASE_URL`;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** Every environment variable that configures provider web search. */
|
|
195
|
+
export function webSearchEnvironmentVariables(): string[] {
|
|
196
|
+
return [
|
|
197
|
+
"OPENGENI_WEB_SEARCH_PROVIDER",
|
|
198
|
+
"OPENGENI_WEB_FETCH_PROVIDER",
|
|
199
|
+
"OPENGENI_WEB_SEARCH_PREFER",
|
|
200
|
+
"OPENGENI_WEB_SEARCH_PRICING_JSON",
|
|
201
|
+
"OPENGENI_WEB_SEARCH_REQUEST_TIMEOUT_MS",
|
|
202
|
+
...WEB_SEARCH_PROVIDER_IDS.flatMap((id) => [
|
|
203
|
+
webSearchProviderApiKeyEnv(id),
|
|
204
|
+
webSearchProviderBaseUrlEnv(id),
|
|
205
|
+
]),
|
|
206
|
+
// Earlier single-provider names, still honoured.
|
|
207
|
+
"OPENGENI_WEB_SEARCH_API_KEY",
|
|
208
|
+
"OPENGENI_WEB_SEARCH_BASE_URL",
|
|
209
|
+
"OPENGENI_WEB_FETCH_API_KEY",
|
|
210
|
+
"OPENGENI_WEB_FETCH_BASE_URL",
|
|
211
|
+
"OPENGENI_WEB_SEARCH_PROVIDER_MODE",
|
|
212
|
+
];
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
export type WebSearchProviderCredentials = Partial<
|
|
216
|
+
Record<string, { apiKey?: string | undefined; baseUrl?: string | undefined }>
|
|
217
|
+
>;
|
|
218
|
+
|
|
219
|
+
export const WebSearchProviderCredentialsSchema = z
|
|
220
|
+
.record(
|
|
221
|
+
z.string(),
|
|
222
|
+
z.object({ apiKey: z.string().optional(), baseUrl: z.string().optional() }).strict(),
|
|
223
|
+
)
|
|
224
|
+
.default({});
|
|
225
|
+
|
|
226
|
+
/** Per-provider keys and base URLs from the environment. */
|
|
227
|
+
export function webSearchProviderCredentialsFromEnv(
|
|
228
|
+
source: Record<string, string | undefined>,
|
|
229
|
+
): WebSearchProviderCredentials {
|
|
230
|
+
const credentials: WebSearchProviderCredentials = {};
|
|
231
|
+
for (const id of WEB_SEARCH_PROVIDER_IDS) {
|
|
232
|
+
const apiKey = source[webSearchProviderApiKeyEnv(id)]?.trim();
|
|
233
|
+
const baseUrl = source[webSearchProviderBaseUrlEnv(id)]?.trim();
|
|
234
|
+
if (apiKey || baseUrl) {
|
|
235
|
+
credentials[id] = { ...(apiKey ? { apiKey } : {}), ...(baseUrl ? { baseUrl } : {}) };
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
return credentials;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* Upstream price of one call in integer USD micros, plus the Opengeni
|
|
243
|
+
* margin in basis points (500 = +5%, as for model pricing). Credit billing
|
|
244
|
+
* charges `ceil(providerCost * (10000 + marginBps) / 10000)` per call.
|
|
245
|
+
*/
|
|
246
|
+
export type WebSearchPricing = {
|
|
247
|
+
searchMicros: number;
|
|
248
|
+
fetchMicros: number;
|
|
249
|
+
marginBps?: number | undefined;
|
|
250
|
+
};
|
|
251
|
+
|
|
252
|
+
const WebSearchPricingSchema = z
|
|
253
|
+
.object({
|
|
254
|
+
searchMicros: z.number().int().nonnegative().max(10_000_000),
|
|
255
|
+
fetchMicros: z.number().int().nonnegative().max(10_000_000),
|
|
256
|
+
marginBps: z.number().int().min(0).max(100_000).optional(),
|
|
257
|
+
})
|
|
258
|
+
.strict();
|
|
259
|
+
|
|
260
|
+
const DEFAULT_MARGIN_BPS = 500;
|
|
261
|
+
|
|
262
|
+
/** Tavily's pay-as-you-go price of one credit, used for reported usage. */
|
|
263
|
+
export const TAVILY_CREDIT_MICROS = 8_000;
|
|
264
|
+
|
|
265
|
+
export type WebSearchProviderEndpoint = {
|
|
266
|
+
provider: WebSearchProviderId;
|
|
267
|
+
apiKey: string | null;
|
|
268
|
+
baseUrl: string | null;
|
|
269
|
+
};
|
|
270
|
+
|
|
271
|
+
export type WebSearchProviderConfig = {
|
|
272
|
+
preference: WebSearchPreference;
|
|
273
|
+
/** Search providers in failover order; never empty. */
|
|
274
|
+
search: WebSearchProviderEndpoint[];
|
|
275
|
+
/** Page readers in failover order; empty when pages cannot be fetched. */
|
|
276
|
+
fetch: WebSearchProviderEndpoint[];
|
|
277
|
+
/** Explicit operator prices by provider, overriding list prices. */
|
|
278
|
+
pricingOverrides: Partial<Record<WebSearchProviderId, WebSearchPricing>>;
|
|
279
|
+
timeoutMs: number;
|
|
280
|
+
};
|
|
281
|
+
|
|
282
|
+
export type WebSearchSettings = {
|
|
283
|
+
webSearchEnabled: boolean;
|
|
284
|
+
webSearchProvider?: string | undefined;
|
|
285
|
+
webFetchProvider?: string | undefined;
|
|
286
|
+
webSearchPrefer?: string | undefined;
|
|
287
|
+
/** Per-provider keys and base URLs (`OPENGENI_WEB_<PROVIDER>_API_KEY` / `_BASE_URL`). */
|
|
288
|
+
webSearchProviderCredentials?: WebSearchProviderCredentials | undefined;
|
|
289
|
+
/** Earlier single-provider settings: apply to the first provider of their slot. */
|
|
290
|
+
webSearchApiKey?: string | undefined;
|
|
291
|
+
webSearchBaseUrl?: string | undefined;
|
|
292
|
+
webFetchApiKey?: string | undefined;
|
|
293
|
+
webFetchBaseUrl?: string | undefined;
|
|
294
|
+
webSearchProviderMode?: string | undefined;
|
|
295
|
+
webSearchPricingJson?: string | undefined;
|
|
296
|
+
webSearchRequestTimeoutMs?: number | undefined;
|
|
297
|
+
/** Credit billing is active for this deployment (see webSearchCreditBillingActive). */
|
|
298
|
+
billingMode?: string | undefined;
|
|
299
|
+
usageLimitsMode?: string | undefined;
|
|
300
|
+
};
|
|
301
|
+
|
|
302
|
+
export type WebSearchProviderResolution =
|
|
303
|
+
| { status: "off" }
|
|
304
|
+
| { status: "invalid"; reason: string }
|
|
305
|
+
| { status: "configured"; config: WebSearchProviderConfig };
|
|
306
|
+
|
|
307
|
+
function usableSecret(value: string | undefined): string | null {
|
|
308
|
+
const trimmed = value?.trim();
|
|
309
|
+
if (!trimmed) return null;
|
|
310
|
+
// `.env.example` placeholders must never advertise a dead tool.
|
|
311
|
+
if (/^(your[-_ ]|<|changeme|replace[-_ ]?me|xxx)/iu.test(trimmed)) return null;
|
|
312
|
+
return trimmed;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function normalizedBaseUrl(value: string | undefined, name: string): string | null {
|
|
316
|
+
const trimmed = value?.trim();
|
|
317
|
+
if (!trimmed) return null;
|
|
318
|
+
let url: URL;
|
|
319
|
+
try {
|
|
320
|
+
url = new URL(trimmed);
|
|
321
|
+
} catch (error) {
|
|
322
|
+
throw new Error(`${name} must be an absolute http(s) URL`, { cause: error });
|
|
323
|
+
}
|
|
324
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
325
|
+
throw new Error(`${name} must be an absolute http(s) URL`);
|
|
326
|
+
}
|
|
327
|
+
if (url.username || url.password) throw new Error(`${name} must not embed credentials`);
|
|
328
|
+
return url.toString().replace(/\/+$/u, "");
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
function providerList(raw: string, variable: string, operation: "search" | "fetch") {
|
|
332
|
+
const ids: WebSearchProviderId[] = [];
|
|
333
|
+
for (const part of raw.split(",")) {
|
|
334
|
+
const normalized = part.trim().toLowerCase();
|
|
335
|
+
if (!normalized) continue;
|
|
336
|
+
const capable = WEB_SEARCH_PROVIDER_IDS.filter(
|
|
337
|
+
(id) => WEB_SEARCH_PROVIDER_CATALOG[id][operation],
|
|
338
|
+
);
|
|
339
|
+
if (!(capable as readonly string[]).includes(normalized)) {
|
|
340
|
+
throw new Error(
|
|
341
|
+
`${variable} must be none or a comma-separated list of ${capable.join(", ")}`,
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
if (!ids.includes(normalized as WebSearchProviderId))
|
|
345
|
+
ids.push(normalized as WebSearchProviderId);
|
|
346
|
+
}
|
|
347
|
+
if (ids.length === 0) throw new Error(`${variable} names no provider`);
|
|
348
|
+
return ids;
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
function preference(settings: WebSearchSettings): WebSearchPreference {
|
|
352
|
+
const prefer = settings.webSearchPrefer?.trim().toLowerCase();
|
|
353
|
+
if (prefer) {
|
|
354
|
+
const parsed = WebSearchPreference.safeParse(prefer);
|
|
355
|
+
if (!parsed.success) throw new Error("OPENGENI_WEB_SEARCH_PREFER must be native or provider");
|
|
356
|
+
return parsed.data;
|
|
357
|
+
}
|
|
358
|
+
const legacy = settings.webSearchProviderMode?.trim().toLowerCase();
|
|
359
|
+
if (!legacy || legacy === "fallback") return "native";
|
|
360
|
+
if (legacy === "replace") return "provider";
|
|
361
|
+
throw new Error("OPENGENI_WEB_SEARCH_PROVIDER_MODE must be fallback or replace");
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
function pricingOverrides(raw: string | undefined): WebSearchProviderConfig["pricingOverrides"] {
|
|
365
|
+
const trimmed = raw?.trim();
|
|
366
|
+
if (!trimmed) return {};
|
|
367
|
+
let parsed: unknown;
|
|
368
|
+
try {
|
|
369
|
+
parsed = JSON.parse(trimmed);
|
|
370
|
+
} catch (error) {
|
|
371
|
+
throw new Error("OPENGENI_WEB_SEARCH_PRICING_JSON must be valid JSON", { cause: error });
|
|
372
|
+
}
|
|
373
|
+
const describe = (error: z.ZodError) =>
|
|
374
|
+
`OPENGENI_WEB_SEARCH_PRICING_JSON is invalid: ${error.issues
|
|
375
|
+
.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
|
|
376
|
+
.join("; ")}`;
|
|
377
|
+
// One flat price applies to every configured provider.
|
|
378
|
+
if (parsed && typeof parsed === "object" && "searchMicros" in parsed) {
|
|
379
|
+
const flat = WebSearchPricingSchema.safeParse(parsed);
|
|
380
|
+
if (!flat.success) throw new Error(describe(flat.error));
|
|
381
|
+
return Object.fromEntries(WEB_SEARCH_PROVIDER_IDS.map((id) => [id, flat.data]));
|
|
382
|
+
}
|
|
383
|
+
const byProvider = z
|
|
384
|
+
.record(z.string(), WebSearchPricingSchema)
|
|
385
|
+
.superRefine((value, context) => {
|
|
386
|
+
for (const key of Object.keys(value)) {
|
|
387
|
+
if (!(WEB_SEARCH_PROVIDER_IDS as readonly string[]).includes(key)) {
|
|
388
|
+
context.addIssue({ code: "custom", path: [key], message: "unknown provider" });
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
})
|
|
392
|
+
.safeParse(parsed);
|
|
393
|
+
if (!byProvider.success) throw new Error(describe(byProvider.error));
|
|
394
|
+
return byProvider.data as WebSearchProviderConfig["pricingOverrides"];
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* Resolve the deployment's provider search. `off` applies when
|
|
399
|
+
* `OPENGENI_WEB_SEARCH_ENABLED=false` (the server-wide web search switch),
|
|
400
|
+
* when the provider is `none`, and when the provider is left at its default
|
|
401
|
+
* (TinyFish) without that provider's key. `invalid` means an operator named
|
|
402
|
+
* providers but the configuration cannot work; the tools stay unoffered and
|
|
403
|
+
* the worker logs the reason.
|
|
404
|
+
*/
|
|
405
|
+
export function resolveWebSearchProvider(settings: WebSearchSettings): WebSearchProviderResolution {
|
|
406
|
+
const named = settings.webSearchProvider?.trim() ?? "";
|
|
407
|
+
if (!settings.webSearchEnabled || named.toLowerCase() === "none") return { status: "off" };
|
|
408
|
+
const credentials = settings.webSearchProviderCredentials ?? {};
|
|
409
|
+
if (named === "") {
|
|
410
|
+
// The default provider turns on only once its own key is set.
|
|
411
|
+
if (!usableSecret(credentials[DEFAULT_WEB_SEARCH_PROVIDER]?.apiKey)) return { status: "off" };
|
|
412
|
+
}
|
|
413
|
+
try {
|
|
414
|
+
const searchIds = providerList(
|
|
415
|
+
named || DEFAULT_WEB_SEARCH_PROVIDER,
|
|
416
|
+
"OPENGENI_WEB_SEARCH_PROVIDER",
|
|
417
|
+
"search",
|
|
418
|
+
);
|
|
419
|
+
const endpoint = (
|
|
420
|
+
id: WebSearchProviderId,
|
|
421
|
+
operation: "search" | "fetch",
|
|
422
|
+
legacy: { apiKey: string | undefined; baseUrl: string | undefined; name: string } | null,
|
|
423
|
+
sameProvider: WebSearchProviderEndpoint | undefined,
|
|
424
|
+
): WebSearchProviderEndpoint => {
|
|
425
|
+
const own = credentials[id];
|
|
426
|
+
const apiKey =
|
|
427
|
+
usableSecret(own?.apiKey) ??
|
|
428
|
+
(legacy ? usableSecret(legacy.apiKey) : null) ??
|
|
429
|
+
sameProvider?.apiKey ??
|
|
430
|
+
null;
|
|
431
|
+
const baseUrl =
|
|
432
|
+
normalizedBaseUrl(own?.baseUrl, webSearchProviderBaseUrlEnv(id)) ??
|
|
433
|
+
(legacy ? normalizedBaseUrl(legacy.baseUrl, `${legacy.name}_BASE_URL`) : null) ??
|
|
434
|
+
sameProvider?.baseUrl ??
|
|
435
|
+
null;
|
|
436
|
+
const spec = WEB_SEARCH_PROVIDER_CATALOG[id][operation]!;
|
|
437
|
+
if (spec.keyRequired && !apiKey) {
|
|
438
|
+
throw new Error(`${id} ${operation} needs ${webSearchProviderApiKeyEnv(id)}`);
|
|
439
|
+
}
|
|
440
|
+
if (!spec.defaultBaseUrl && !baseUrl) {
|
|
441
|
+
throw new Error(`${id} ${operation} needs ${webSearchProviderBaseUrlEnv(id)}`);
|
|
442
|
+
}
|
|
443
|
+
return { provider: id, apiKey, baseUrl };
|
|
444
|
+
};
|
|
445
|
+
const search = searchIds.map((id, index) =>
|
|
446
|
+
endpoint(
|
|
447
|
+
id,
|
|
448
|
+
"search",
|
|
449
|
+
index === 0 && named
|
|
450
|
+
? {
|
|
451
|
+
apiKey: settings.webSearchApiKey,
|
|
452
|
+
baseUrl: settings.webSearchBaseUrl,
|
|
453
|
+
name: "OPENGENI_WEB_SEARCH",
|
|
454
|
+
}
|
|
455
|
+
: null,
|
|
456
|
+
undefined,
|
|
457
|
+
),
|
|
458
|
+
);
|
|
459
|
+
|
|
460
|
+
const fetchNamed = settings.webFetchProvider?.trim() ?? "";
|
|
461
|
+
let fetch: WebSearchProviderEndpoint[];
|
|
462
|
+
if (fetchNamed === "") {
|
|
463
|
+
// Search providers that can also read pages do so, in the same order.
|
|
464
|
+
fetch = search.flatMap((entry) =>
|
|
465
|
+
WEB_SEARCH_PROVIDER_CATALOG[entry.provider].fetch ? [entry] : [],
|
|
466
|
+
);
|
|
467
|
+
} else if (fetchNamed.toLowerCase() === "none") {
|
|
468
|
+
fetch = [];
|
|
469
|
+
} else {
|
|
470
|
+
fetch = providerList(fetchNamed, "OPENGENI_WEB_FETCH_PROVIDER", "fetch").map((id, index) =>
|
|
471
|
+
endpoint(
|
|
472
|
+
id,
|
|
473
|
+
"fetch",
|
|
474
|
+
index === 0
|
|
475
|
+
? {
|
|
476
|
+
apiKey: settings.webFetchApiKey,
|
|
477
|
+
baseUrl: settings.webFetchBaseUrl,
|
|
478
|
+
name: "OPENGENI_WEB_FETCH",
|
|
479
|
+
}
|
|
480
|
+
: null,
|
|
481
|
+
search.find((entry) => entry.provider === id),
|
|
482
|
+
),
|
|
483
|
+
);
|
|
484
|
+
}
|
|
485
|
+
return {
|
|
486
|
+
status: "configured",
|
|
487
|
+
config: {
|
|
488
|
+
preference: preference(settings),
|
|
489
|
+
search,
|
|
490
|
+
fetch,
|
|
491
|
+
pricingOverrides: pricingOverrides(settings.webSearchPricingJson),
|
|
492
|
+
timeoutMs: settings.webSearchRequestTimeoutMs ?? 20_000,
|
|
493
|
+
},
|
|
494
|
+
};
|
|
495
|
+
} catch (error) {
|
|
496
|
+
return { status: "invalid", reason: (error as Error).message };
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/** The configured provider, or null when off or invalid. */
|
|
501
|
+
export function webSearchProviderConfig(
|
|
502
|
+
settings: WebSearchSettings,
|
|
503
|
+
): WebSearchProviderConfig | null {
|
|
504
|
+
const resolution = resolveWebSearchProvider(settings);
|
|
505
|
+
return resolution.status === "configured" ? resolution.config : null;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* The single web-search plan for one turn, shared by the worker (which tools
|
|
510
|
+
* it attaches) and the API's effective-tools projection (what it reports).
|
|
511
|
+
*
|
|
512
|
+
* `hostedWebSearch` is whether the resolved model attaches the SDK-hosted
|
|
513
|
+
* `web_search` tool. `transportHostedSearch` is true for providers whose native
|
|
514
|
+
* search is added by the transport rather than as an agent tool (SuperGrok).
|
|
515
|
+
*/
|
|
516
|
+
export function webSearchToolPlan(
|
|
517
|
+
settings: WebSearchSettings,
|
|
518
|
+
turn: {
|
|
519
|
+
hostedWebSearch: boolean;
|
|
520
|
+
transportHostedSearch?: boolean;
|
|
521
|
+
/**
|
|
522
|
+
* The workspace turned Opengeni credits off: a provider tool is offered
|
|
523
|
+
* only when one of its providers is free (admission still refuses paid
|
|
524
|
+
* calls if the switch flips mid-turn).
|
|
525
|
+
*/
|
|
526
|
+
creditsDisabled?: boolean;
|
|
527
|
+
},
|
|
528
|
+
): { hostedWebSearch: boolean; providerTools: WebSearchProviderToolName[] } {
|
|
529
|
+
const config = webSearchProviderConfig(settings);
|
|
530
|
+
if (!config || turn.transportHostedSearch) {
|
|
531
|
+
return { hostedWebSearch: turn.hostedWebSearch, providerTools: [] };
|
|
532
|
+
}
|
|
533
|
+
if (config.preference === "native" && turn.hostedWebSearch) {
|
|
534
|
+
return { hostedWebSearch: true, providerTools: [] };
|
|
535
|
+
}
|
|
536
|
+
const offered: WebSearchProviderToolName[] =
|
|
537
|
+
config.fetch.length > 0 ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : [WEB_SEARCH_TOOL_NAME];
|
|
538
|
+
const providerTools = turn.creditsDisabled
|
|
539
|
+
? offered.filter((tool) => !webSearchToolSpendsCredits(settings, config, tool))
|
|
540
|
+
: offered;
|
|
541
|
+
return {
|
|
542
|
+
// `provider` withholds hosted search only in favour of a provider tool the
|
|
543
|
+
// turn actually gets.
|
|
544
|
+
hostedWebSearch: turn.hostedWebSearch && !providerTools.includes(WEB_SEARCH_TOOL_NAME),
|
|
545
|
+
providerTools,
|
|
546
|
+
};
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
/** Whether this deployment bills web search and fetch in Opengeni credits. */
|
|
550
|
+
export function webSearchCreditBillingActive(
|
|
551
|
+
settings: Pick<WebSearchSettings, "billingMode" | "usageLimitsMode">,
|
|
552
|
+
): boolean {
|
|
553
|
+
return settings.billingMode === "stripe" || settings.usageLimitsMode === "managed";
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
/** Whether every provider of this tool would spend Opengeni credits per call. */
|
|
557
|
+
export function webSearchToolSpendsCredits(
|
|
558
|
+
settings: WebSearchSettings,
|
|
559
|
+
config: WebSearchProviderConfig,
|
|
560
|
+
tool: WebSearchProviderToolName,
|
|
561
|
+
): boolean {
|
|
562
|
+
const operation = tool === WEB_SEARCH_TOOL_NAME ? "search" : "fetch";
|
|
563
|
+
return (
|
|
564
|
+
webSearchCreditBillingActive(settings) &&
|
|
565
|
+
config[operation].every(
|
|
566
|
+
(endpoint) => webSearchCallPricing(config, endpoint, operation).providerMicros > 0,
|
|
567
|
+
)
|
|
568
|
+
);
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
/** Upstream price for one call to one provider, before any provider-reported cost. */
|
|
572
|
+
export function webSearchCallPricing(
|
|
573
|
+
config: Pick<WebSearchProviderConfig, "pricingOverrides">,
|
|
574
|
+
endpoint: WebSearchProviderEndpoint,
|
|
575
|
+
operation: "search" | "fetch",
|
|
576
|
+
): { providerMicros: number; marginBps: number; explicit: boolean } {
|
|
577
|
+
const override = config.pricingOverrides[endpoint.provider];
|
|
578
|
+
if (override) {
|
|
579
|
+
return {
|
|
580
|
+
providerMicros: operation === "search" ? override.searchMicros : override.fetchMicros,
|
|
581
|
+
marginBps: override.marginBps ?? DEFAULT_MARGIN_BPS,
|
|
582
|
+
explicit: true,
|
|
583
|
+
};
|
|
584
|
+
}
|
|
585
|
+
const spec = WEB_SEARCH_PROVIDER_CATALOG[endpoint.provider][operation];
|
|
586
|
+
// A keyless call (Jina reader, self-hosted SearXNG) costs nothing.
|
|
587
|
+
return {
|
|
588
|
+
providerMicros: spec && endpoint.apiKey ? spec.listPriceMicros : 0,
|
|
589
|
+
marginBps: DEFAULT_MARGIN_BPS,
|
|
590
|
+
explicit: false,
|
|
591
|
+
};
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
/** Credit cost of a provider cost after margin, rounded up to whole micros. */
|
|
595
|
+
export function webSearchCreditMicros(providerMicros: number, marginBps: number): number {
|
|
596
|
+
if (!Number.isSafeInteger(providerMicros) || providerMicros < 0) {
|
|
597
|
+
throw new Error("web search provider cost must be a non-negative safe integer");
|
|
598
|
+
}
|
|
599
|
+
return Number((BigInt(providerMicros) * BigInt(10_000 + marginBps) + 9_999n) / 10_000n);
|
|
600
|
+
}
|