Study/server/ai/providers/common.ts
2026-11-11 18:32:46 -07:00

138 lines
5.6 KiB
TypeScript

/**
* Helpers shared by the adapters that are about our neutral contract rather
* than about HTTP: tool-argument parsing, model-list post-processing, the
* connection-test wrapper.
*/
import { jsonrepair } from 'jsonrepair';
import { AIError, type DiscoveredModel, type ProviderKind, type TestResult, type Usage } from '../types.ts';
import { lookupModelDefaults } from './catalog.ts';
import { isRecord } from './http.ts';
/** Strict parse of tool-call arguments; `undefined` when they are not a JSON object. */
export function parseArgsStrict(raw: string): Record<string, unknown> | undefined {
const text = raw.trim();
if (text === '') return {};
try {
const value: unknown = JSON.parse(text);
return isRecord(value) ? value : undefined;
} catch {
return undefined;
}
}
/**
* Parses the JSON arguments of a completed tool call. Models occasionally emit
* slightly broken JSON (trailing commas, unescaped newlines); `jsonrepair`
* fixes those. Anything still unparseable is an `invalid_response`.
*
* Do NOT use this on a call that was cut off by the output-token limit —
* repairing a truncated call would silently invent a shorter input.
*/
export function parseToolArguments(raw: unknown, provider: string, toolName: string): Record<string, unknown> {
if (isRecord(raw)) return raw; // some servers send an object instead of a JSON string
const text = typeof raw === 'string' ? raw : raw == null ? '' : String(raw);
const strict = parseArgsStrict(text);
if (strict) return strict;
try {
const repaired: unknown = JSON.parse(jsonrepair(text));
if (isRecord(repaired)) return repaired;
} catch {
/* fall through */
}
throw new AIError('invalid_response', `${provider} produced a tool call for "${toolName}" with arguments that are not valid JSON.`, {
providerMessage: text.length > 300 ? `${text.slice(0, 300)}…` : text,
});
}
/** Stable id for providers that do not issue tool-call ids themselves. */
export function newToolCallId(prefix: string): string {
return `${prefix}_${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
}
export function dataUrl(mime: string, base64: string): string {
return `data:${mime};base64,${base64}`;
}
export function num(v: unknown): number {
return typeof v === 'number' && Number.isFinite(v) ? v : 0;
}
export function str(v: unknown): string {
return typeof v === 'string' ? v : '';
}
/**
* Usage convention used by every adapter:
* inputTokens = ALL prompt tokens, including cached ones
* cacheRead/cacheWriteTokens = the cached subsets of inputTokens
* outputTokens = ALL generated tokens, including reasoning
* reasoningTokens = the reasoning subset of outputTokens
*/
export function makeUsage(u: { input: number; output: number; cacheRead?: number; cacheWrite?: number; reasoning?: number }): Usage {
const usage: Usage = { inputTokens: u.input, outputTokens: u.output };
if (u.cacheRead) usage.cacheReadTokens = u.cacheRead;
if (u.cacheWrite) usage.cacheWriteTokens = u.cacheWrite;
if (u.reasoning) usage.reasoningTokens = u.reasoning;
return usage;
}
/**
* Ids that are obviously not text-chat models: embeddings, speech, image and
* video generation, moderation, realtime/audio-only, rerankers, legacy
* completion-only models.
*/
const NON_CHAT_RE = new RegExp(
[
'embed', // text-embedding-3-large, gemini-embedding-001, nomic-embed-text
'\\btts\\b|whisper|transcri|speech|\\baudio\\b|realtime|\\blive\\b',
'dall-e|gpt-image|image-generation|imagen|-image\\b|image-preview|\\bsora\\b|\\bveo\\b|lyria|stable-diffusion',
'moderation|-guard\\b|rerank|\\baqa\\b',
'computer-use|robotics|deep-research',
'^(babbage|davinci|curie|ada)\\b|^text-|turbo-instruct',
].join('|'),
'i',
);
export function isChatModelId(id: string): boolean {
return !NON_CHAT_RE.test(id);
}
/** Merges discovery results with catalog defaults; values the provider reported always win. */
export function withCatalogDefaults(kind: ProviderKind, models: DiscoveredModel[]): DiscoveredModel[] {
const seen = new Set<string>();
const out: DiscoveredModel[] = [];
for (const m of models) {
if (!m.id || seen.has(m.id)) continue;
seen.add(m.id);
const d = lookupModelDefaults(kind, m.id);
const merged: DiscoveredModel = { ...d, ...stripUndefined(m), id: m.id };
if (d.capabilities || m.capabilities) merged.capabilities = { ...d.capabilities, ...stripUndefined(m.capabilities ?? {}) };
out.push(merged);
}
return out;
}
function stripUndefined<T extends object>(obj: T): T {
const out = {} as Record<string, unknown>;
for (const [k, v] of Object.entries(obj)) if (v !== undefined && v !== null) out[k] = v;
return out as T;
}
/** Shared implementation of `ProviderAdapter.test()`: never throws, always friendly. */
export async function runTest(label: string, check: () => Promise<{ modelCount?: number; note?: string }>): Promise<TestResult> {
const started = Date.now();
try {
const { modelCount, note } = await check();
const latencyMs = Date.now() - started;
const message =
note ?? (modelCount !== undefined ? `Connected to ${label}: ${modelCount} model${modelCount === 1 ? '' : 's'} available.` : `Connected to ${label}.`);
return modelCount !== undefined ? { ok: true, message, latencyMs, modelCount } : { ok: true, message, latencyMs };
} catch (err) {
const latencyMs = Date.now() - started;
const message = err instanceof AIError ? err.message : `Could not connect to ${label}.`;
return { ok: false, message, latencyMs };
}
}
/** Timeout used by `test()` so a dead endpoint fails fast instead of hanging the settings page. */
export const TEST_TIMEOUT_MS = 20_000;