@opengeni/config 1.3.0 → 1.4.0

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.
@@ -0,0 +1,83 @@
1
+ import { z } from "zod";
2
+
3
+ /**
4
+ * Credit pricing for deployment-funded live (speech-to-speech) voice.
5
+ *
6
+ * Live voice is metered by server-observed connection time, billed per started
7
+ * minute. Prices are deployment configuration, never code defaults: when credit
8
+ * billing is active, a deployment-funded voice model without a configured price
9
+ * is not offered and cannot be started.
10
+ */
11
+ export type RealtimeVoicePricing = {
12
+ /** Upstream cost of one minute of live voice, in USD micros. */
13
+ microsPerMinute: number;
14
+ /** Opengeni margin in basis points added on top of the upstream cost. */
15
+ marginBps?: number | undefined;
16
+ };
17
+
18
+ const RealtimeVoicePricingSchema = z
19
+ .object({
20
+ microsPerMinute: z.number().int().positive().max(100_000_000),
21
+ marginBps: z.number().int().min(0).max(100_000).optional(),
22
+ })
23
+ .strict();
24
+
25
+ /** Model id of the deployment-hosted Azure GPT Live voice. */
26
+ export const AZURE_LIVE_REALTIME_MODEL_ID = "opengeni-azure/gpt-live-1" as const;
27
+
28
+ function parseJson(raw: string, env: string): unknown {
29
+ try {
30
+ return JSON.parse(raw);
31
+ } catch {
32
+ throw new Error(`${env} must be valid JSON`);
33
+ }
34
+ }
35
+
36
+ function issues(error: z.ZodError): string {
37
+ return error.issues
38
+ .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
39
+ .join("; ");
40
+ }
41
+
42
+ /** One live-voice price, e.g. `{"microsPerMinute":50000,"marginBps":500}`. */
43
+ export function parseRealtimeVoicePricingJson(
44
+ raw: string | undefined,
45
+ env = "live voice pricing JSON",
46
+ ): RealtimeVoicePricing | null {
47
+ if (raw === undefined || raw.trim() === "") return null;
48
+ const result = RealtimeVoicePricingSchema.safeParse(parseJson(raw, env));
49
+ if (!result.success) throw new Error(`${env} is invalid: ${issues(result.error)}`);
50
+ return result.data;
51
+ }
52
+
53
+ /**
54
+ * Prices keyed by upstream AI Gateway realtime model id, e.g.
55
+ * `{"openai/gpt-realtime-2.1":{"microsPerMinute":120000,"marginBps":500}}`.
56
+ */
57
+ export function parseRealtimeVoicePricingTableJson(
58
+ raw: string | undefined,
59
+ env = "live voice pricing table JSON",
60
+ ): Record<string, RealtimeVoicePricing> {
61
+ if (raw === undefined || raw.trim() === "") return {};
62
+ const result = z
63
+ .record(z.string().min(1).max(256), RealtimeVoicePricingSchema)
64
+ .safeParse(parseJson(raw, env));
65
+ if (!result.success) throw new Error(`${env} is invalid: ${issues(result.error)}`);
66
+ return result.data;
67
+ }
68
+
69
+ /** Credit price of one started minute, after margin, rounded up to whole micros. */
70
+ export function realtimeVoiceMinuteCreditMicros(pricing: RealtimeVoicePricing): {
71
+ providerCostMicros: number;
72
+ creditCostMicros: number;
73
+ } {
74
+ const provider = BigInt(pricing.microsPerMinute);
75
+ const credit = (provider * BigInt(10_000 + (pricing.marginBps ?? 0)) + 9_999n) / 10_000n;
76
+ return { providerCostMicros: Number(provider), creditCostMicros: Number(credit) };
77
+ }
78
+
79
+ /** Billed minutes for a server-observed interval: every started minute, at least one. */
80
+ export function realtimeVoiceStartedMinutes(startedAt: Date, observedUntil: Date): number {
81
+ const elapsed = Math.max(0, observedUntil.getTime() - startedAt.getTime());
82
+ return Math.max(1, Math.ceil(elapsed / 60_000));
83
+ }
@@ -0,0 +1,353 @@
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 OpenAI, Azure,
8
+ * Codex and SuperGrok) follows the model catalog. Provider search is a
9
+ * separate, deployment-configured HTTP provider that Opengeni calls from the
10
+ * worker. It is inert until `OPENGENI_WEB_SEARCH_PROVIDER` names a provider
11
+ * with its credentials, and it is offered only where the turn has no hosted
12
+ * search unless the operator selects `replace`.
13
+ */
14
+
15
+ export const WEB_SEARCH_PROVIDER_IDS = [
16
+ "tinyfish",
17
+ "exa",
18
+ "tavily",
19
+ "firecrawl",
20
+ "brave",
21
+ "jina",
22
+ "searxng",
23
+ ] as const;
24
+ export type WebSearchProviderId = (typeof WEB_SEARCH_PROVIDER_IDS)[number];
25
+
26
+ /** Model-visible names of the provider tools. */
27
+ export const WEB_SEARCH_TOOL_NAME = "web_search";
28
+ export const WEB_FETCH_TOOL_NAME = "web_fetch";
29
+ export type WebSearchProviderToolName = typeof WEB_SEARCH_TOOL_NAME | typeof WEB_FETCH_TOOL_NAME;
30
+
31
+ /**
32
+ * `fallback` (default): offer provider tools only to turns without hosted
33
+ * search. `replace`: offer them to every turn and withhold the SDK-hosted
34
+ * `web_search` tool. SuperGrok keeps its transport-level native search in
35
+ * both modes because Opengeni does not attach it as an agent tool.
36
+ */
37
+ export const WebSearchProviderMode = z.enum(["fallback", "replace"]);
38
+ export type WebSearchProviderMode = z.infer<typeof WebSearchProviderMode>;
39
+
40
+ type ProviderTraits = {
41
+ search: boolean;
42
+ fetch: boolean;
43
+ /** Needs an API key for this operation. */
44
+ searchKey: boolean;
45
+ fetchKey: boolean;
46
+ /** Needs an explicit base URL (self-hosted). */
47
+ baseUrl: boolean;
48
+ };
49
+
50
+ /** What each adapter can do. Jina fetch works keyless at a low rate limit. */
51
+ export const WEB_SEARCH_PROVIDER_TRAITS: Readonly<Record<WebSearchProviderId, ProviderTraits>> = {
52
+ tinyfish: { search: true, fetch: true, searchKey: true, fetchKey: true, baseUrl: false },
53
+ exa: { search: true, fetch: true, searchKey: true, fetchKey: true, baseUrl: false },
54
+ tavily: { search: true, fetch: true, searchKey: true, fetchKey: true, baseUrl: false },
55
+ firecrawl: { search: true, fetch: true, searchKey: true, fetchKey: true, baseUrl: false },
56
+ brave: { search: true, fetch: false, searchKey: true, fetchKey: false, baseUrl: false },
57
+ jina: { search: true, fetch: true, searchKey: true, fetchKey: false, baseUrl: false },
58
+ searxng: { search: true, fetch: false, searchKey: false, fetchKey: false, baseUrl: true },
59
+ };
60
+
61
+ /**
62
+ * Upstream list price of one call in integer USD micros, plus the Opengeni
63
+ * margin in basis points (500 = +5%, as for model pricing). Credit billing
64
+ * charges `ceil(providerCost * (10000 + marginBps) / 10000)` per call.
65
+ */
66
+ export type WebSearchPricing = {
67
+ searchMicros: number;
68
+ fetchMicros: number;
69
+ marginBps?: number | undefined;
70
+ };
71
+
72
+ const WebSearchPricingSchema = z
73
+ .object({
74
+ searchMicros: z.number().int().nonnegative().max(10_000_000),
75
+ fetchMicros: z.number().int().nonnegative().max(10_000_000),
76
+ marginBps: z.number().int().min(0).max(100_000).optional(),
77
+ })
78
+ .strict();
79
+
80
+ /**
81
+ * Built-in pay-as-you-go list prices (checked 2026-10). A provider response
82
+ * that reports its own dollar cost (Exa `costDollars`, Tavily `usage.credits`)
83
+ * bills that cost instead; an explicit `OPENGENI_WEB_SEARCH_PRICING_JSON`
84
+ * overrides both. Plan-dependent providers (Firecrawl) should set the JSON.
85
+ */
86
+ export const DEFAULT_WEB_SEARCH_PRICING: Readonly<Record<WebSearchProviderId, WebSearchPricing>> = {
87
+ // Search and Fetch are free at any wallet balance.
88
+ tinyfish: { searchMicros: 0, fetchMicros: 0, marginBps: 500 },
89
+ // Auto search $7/1k + highlights $1/1k; contents text $1/1k pages.
90
+ exa: { searchMicros: 8_000, fetchMicros: 1_000, marginBps: 500 },
91
+ // Basic search 1 credit, basic extract 1 credit per 5 URLs; $0.008/credit.
92
+ tavily: { searchMicros: 8_000, fetchMicros: 1_600, marginBps: 500 },
93
+ // 2 credits per 10 results, 1 credit per scrape, at Hobby-plan credit cost.
94
+ firecrawl: { searchMicros: 6_400, fetchMicros: 3_200, marginBps: 500 },
95
+ // $5 per 1k requests.
96
+ brave: { searchMicros: 5_000, fetchMicros: 0, marginBps: 500 },
97
+ // At least 10k tokens per search at $0.05/1M; reader billed per token.
98
+ jina: { searchMicros: 500, fetchMicros: 250, marginBps: 500 },
99
+ // Self-hosted.
100
+ searxng: { searchMicros: 0, fetchMicros: 0, marginBps: 500 },
101
+ };
102
+
103
+ /** Tavily's pay-as-you-go price of one credit, used for reported usage. */
104
+ export const TAVILY_CREDIT_MICROS = 8_000;
105
+
106
+ export type WebSearchProviderEndpoint = {
107
+ provider: WebSearchProviderId;
108
+ apiKey: string | null;
109
+ baseUrl: string | null;
110
+ };
111
+
112
+ export type WebSearchProviderConfig = {
113
+ mode: WebSearchProviderMode;
114
+ search: WebSearchProviderEndpoint;
115
+ /** Null when no configured provider can fetch pages. */
116
+ fetch: WebSearchProviderEndpoint | null;
117
+ /** Explicit operator price, else null (built-in or provider-reported). */
118
+ pricingOverride: WebSearchPricing | null;
119
+ timeoutMs: number;
120
+ };
121
+
122
+ export type WebSearchSettings = {
123
+ webSearchEnabled: boolean;
124
+ webSearchProvider?: string | undefined;
125
+ webSearchApiKey?: string | undefined;
126
+ webSearchBaseUrl?: string | undefined;
127
+ webFetchProvider?: string | undefined;
128
+ webFetchApiKey?: string | undefined;
129
+ webFetchBaseUrl?: string | undefined;
130
+ webSearchProviderMode?: string | undefined;
131
+ webSearchPricingJson?: string | undefined;
132
+ webSearchRequestTimeoutMs?: number | undefined;
133
+ };
134
+
135
+ export type WebSearchProviderResolution =
136
+ | { status: "off" }
137
+ | { status: "invalid"; reason: string }
138
+ | { status: "configured"; config: WebSearchProviderConfig };
139
+
140
+ function usableSecret(value: string | undefined): string | null {
141
+ const trimmed = value?.trim();
142
+ if (!trimmed) return null;
143
+ // `.env.example` placeholders must never advertise a dead tool.
144
+ if (/^(your[-_ ]|<|changeme|replace[-_ ]?me|xxx)/iu.test(trimmed)) return null;
145
+ return trimmed;
146
+ }
147
+
148
+ function normalizedBaseUrl(value: string | undefined): string | null {
149
+ const trimmed = value?.trim();
150
+ if (!trimmed) return null;
151
+ let url: URL;
152
+ try {
153
+ url = new URL(trimmed);
154
+ } catch (error) {
155
+ throw new Error("must be an absolute http(s) URL", { cause: error });
156
+ }
157
+ if (url.protocol !== "https:" && url.protocol !== "http:") {
158
+ throw new Error("must be an absolute http(s) URL");
159
+ }
160
+ if (url.username || url.password) throw new Error("must not embed credentials");
161
+ return url.toString().replace(/\/+$/u, "");
162
+ }
163
+
164
+ function providerId(value: string): WebSearchProviderId | null {
165
+ const normalized = value.trim().toLowerCase();
166
+ return (WEB_SEARCH_PROVIDER_IDS as readonly string[]).includes(normalized)
167
+ ? (normalized as WebSearchProviderId)
168
+ : null;
169
+ }
170
+
171
+ /**
172
+ * Resolve the deployment's provider search. `off` is the default and also
173
+ * applies when `OPENGENI_WEB_SEARCH_ENABLED=false` (the server-wide web search
174
+ * switch). `invalid` means an operator named a provider but the configuration
175
+ * cannot work; the tools stay unoffered and the worker logs the reason.
176
+ */
177
+ export function resolveWebSearchProvider(settings: WebSearchSettings): WebSearchProviderResolution {
178
+ const raw = settings.webSearchProvider?.trim() ?? "";
179
+ if (!settings.webSearchEnabled || raw === "" || raw.toLowerCase() === "none") {
180
+ return { status: "off" };
181
+ }
182
+ try {
183
+ const search = providerId(raw);
184
+ if (!search) {
185
+ throw new Error(
186
+ `OPENGENI_WEB_SEARCH_PROVIDER must be one of none, ${WEB_SEARCH_PROVIDER_IDS.join(", ")}`,
187
+ );
188
+ }
189
+ const modeResult = WebSearchProviderMode.safeParse(
190
+ settings.webSearchProviderMode?.trim().toLowerCase() || "fallback",
191
+ );
192
+ if (!modeResult.success) {
193
+ throw new Error("OPENGENI_WEB_SEARCH_PROVIDER_MODE must be fallback or replace");
194
+ }
195
+ let searchBaseUrl: string | null;
196
+ try {
197
+ searchBaseUrl = normalizedBaseUrl(settings.webSearchBaseUrl);
198
+ } catch (error) {
199
+ throw new Error(`OPENGENI_WEB_SEARCH_BASE_URL ${(error as Error).message}`, {
200
+ cause: error,
201
+ });
202
+ }
203
+ const searchTraits = WEB_SEARCH_PROVIDER_TRAITS[search];
204
+ const searchKey = usableSecret(settings.webSearchApiKey);
205
+ if (searchTraits.searchKey && !searchKey) {
206
+ throw new Error(`${search} search needs OPENGENI_WEB_SEARCH_API_KEY`);
207
+ }
208
+ if (searchTraits.baseUrl && !searchBaseUrl) {
209
+ throw new Error(`${search} search needs OPENGENI_WEB_SEARCH_BASE_URL`);
210
+ }
211
+ const searchEndpoint: WebSearchProviderEndpoint = {
212
+ provider: search,
213
+ apiKey: searchKey,
214
+ baseUrl: searchBaseUrl,
215
+ };
216
+
217
+ const fetchRaw = settings.webFetchProvider?.trim() ?? "";
218
+ let fetch: WebSearchProviderEndpoint | null = null;
219
+ if (fetchRaw === "") {
220
+ // The search provider fetches too when it can.
221
+ if (searchTraits.fetch) fetch = searchEndpoint;
222
+ } else if (fetchRaw.toLowerCase() !== "none") {
223
+ const fetchProvider = providerId(fetchRaw);
224
+ if (!fetchProvider || !WEB_SEARCH_PROVIDER_TRAITS[fetchProvider].fetch) {
225
+ throw new Error(
226
+ `OPENGENI_WEB_FETCH_PROVIDER must be none or one of ${WEB_SEARCH_PROVIDER_IDS.filter(
227
+ (id) => WEB_SEARCH_PROVIDER_TRAITS[id].fetch,
228
+ ).join(", ")}`,
229
+ );
230
+ }
231
+ let fetchBaseUrl: string | null;
232
+ try {
233
+ fetchBaseUrl = normalizedBaseUrl(settings.webFetchBaseUrl);
234
+ } catch (error) {
235
+ throw new Error(`OPENGENI_WEB_FETCH_BASE_URL ${(error as Error).message}`, {
236
+ cause: error,
237
+ });
238
+ }
239
+ const sameProvider = fetchProvider === search;
240
+ const fetchKey = usableSecret(settings.webFetchApiKey) ?? (sameProvider ? searchKey : null);
241
+ if (WEB_SEARCH_PROVIDER_TRAITS[fetchProvider].fetchKey && !fetchKey) {
242
+ throw new Error(`${fetchProvider} fetch needs OPENGENI_WEB_FETCH_API_KEY`);
243
+ }
244
+ fetch = {
245
+ provider: fetchProvider,
246
+ apiKey: fetchKey,
247
+ baseUrl: fetchBaseUrl ?? (sameProvider ? searchBaseUrl : null),
248
+ };
249
+ }
250
+
251
+ let pricingOverride: WebSearchPricing | null = null;
252
+ const pricingRaw = settings.webSearchPricingJson?.trim();
253
+ if (pricingRaw) {
254
+ let parsed: unknown;
255
+ try {
256
+ parsed = JSON.parse(pricingRaw);
257
+ } catch (error) {
258
+ throw new Error("OPENGENI_WEB_SEARCH_PRICING_JSON must be valid JSON", { cause: error });
259
+ }
260
+ const result = WebSearchPricingSchema.safeParse(parsed);
261
+ if (!result.success) {
262
+ throw new Error(
263
+ `OPENGENI_WEB_SEARCH_PRICING_JSON is invalid: ${result.error.issues
264
+ .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
265
+ .join("; ")}`,
266
+ );
267
+ }
268
+ pricingOverride = result.data;
269
+ }
270
+ return {
271
+ status: "configured",
272
+ config: {
273
+ mode: modeResult.data,
274
+ search: searchEndpoint,
275
+ fetch,
276
+ pricingOverride,
277
+ timeoutMs: settings.webSearchRequestTimeoutMs ?? 20_000,
278
+ },
279
+ };
280
+ } catch (error) {
281
+ return { status: "invalid", reason: (error as Error).message };
282
+ }
283
+ }
284
+
285
+ /** The configured provider, or null when off or invalid. */
286
+ export function webSearchProviderConfig(
287
+ settings: WebSearchSettings,
288
+ ): WebSearchProviderConfig | null {
289
+ const resolution = resolveWebSearchProvider(settings);
290
+ return resolution.status === "configured" ? resolution.config : null;
291
+ }
292
+
293
+ /**
294
+ * The single web-search plan for one turn, shared by the worker (which tools
295
+ * it attaches) and the API's effective-tools projection (what it reports).
296
+ *
297
+ * `hostedWebSearch` is whether the resolved model attaches the SDK-hosted
298
+ * `web_search` tool. `transportHostedSearch` is true for providers whose native
299
+ * search is added by the transport rather than as an agent tool (SuperGrok).
300
+ */
301
+ export function webSearchToolPlan(
302
+ settings: WebSearchSettings,
303
+ turn: { hostedWebSearch: boolean; transportHostedSearch?: boolean },
304
+ ): { hostedWebSearch: boolean; providerTools: WebSearchProviderToolName[] } {
305
+ const config = webSearchProviderConfig(settings);
306
+ if (!config || turn.transportHostedSearch) {
307
+ return { hostedWebSearch: turn.hostedWebSearch, providerTools: [] };
308
+ }
309
+ if (config.mode === "fallback" && turn.hostedWebSearch) {
310
+ return { hostedWebSearch: true, providerTools: [] };
311
+ }
312
+ return {
313
+ hostedWebSearch: false,
314
+ providerTools: config.fetch
315
+ ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME]
316
+ : [WEB_SEARCH_TOOL_NAME],
317
+ };
318
+ }
319
+
320
+ /** Upstream price for one call before any provider-reported cost. */
321
+ export function webSearchCallPricing(
322
+ config: WebSearchProviderConfig,
323
+ operation: "search" | "fetch",
324
+ ): { providerMicros: number; marginBps: number; explicit: boolean } {
325
+ const endpoint = operation === "search" ? config.search : config.fetch;
326
+ const provider = endpoint?.provider ?? config.search.provider;
327
+ if (config.pricingOverride) {
328
+ return {
329
+ providerMicros:
330
+ operation === "search"
331
+ ? config.pricingOverride.searchMicros
332
+ : config.pricingOverride.fetchMicros,
333
+ marginBps: config.pricingOverride.marginBps ?? 500,
334
+ explicit: true,
335
+ };
336
+ }
337
+ const builtin = DEFAULT_WEB_SEARCH_PRICING[provider];
338
+ // A keyless call (Jina reader, self-hosted SearXNG) costs nothing.
339
+ const free = !endpoint?.apiKey;
340
+ return {
341
+ providerMicros: free ? 0 : operation === "search" ? builtin.searchMicros : builtin.fetchMicros,
342
+ marginBps: builtin.marginBps ?? 500,
343
+ explicit: false,
344
+ };
345
+ }
346
+
347
+ /** Credit cost of a provider cost after margin, rounded up to whole micros. */
348
+ export function webSearchCreditMicros(providerMicros: number, marginBps: number): number {
349
+ if (!Number.isSafeInteger(providerMicros) || providerMicros < 0) {
350
+ throw new Error("web search provider cost must be a non-negative safe integer");
351
+ }
352
+ return Number((BigInt(providerMicros) * BigInt(10_000 + marginBps) + 9_999n) / 10_000n);
353
+ }