/** * 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, REASONING_EFFORTS, type DiscoveredModel, type ProviderKind, type ReasoningEffort, 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 | 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 { 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)}`; } /** Parses an OpenAI-style `/embeddings` response ({ data: [{ index, embedding }], usage }). */ export function parseEmbeddings(res: unknown, expected: number, label: string): { vectors: number[][]; inputTokens: number } { const body = res as { data?: { index?: number; embedding?: unknown }[]; usage?: { prompt_tokens?: number; total_tokens?: number } }; const rows = Array.isArray(body?.data) ? body.data : []; const vectors: number[][] = new Array(expected); rows.forEach((row, i) => { const at = typeof row.index === 'number' ? row.index : i; if (Array.isArray(row.embedding)) vectors[at] = row.embedding.map(Number); }); if (rows.length !== expected || vectors.some((v) => !v || v.length === 0)) { throw new AIError('invalid_response', `${label} returned ${rows.length} embeddings for ${expected} inputs.`); } return { vectors, inputTokens: num(body?.usage?.prompt_tokens ?? body?.usage?.total_tokens) }; } 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(); 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(obj: T): T { const out = {} as Record; 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 { 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; /** * Maps a requested effort onto the closest level a provider accepts. Ties go to the higher * level, so "medium" on a low/high-only API becomes "high" rather than silently weaker. */ export function nearestEffort(effort: ReasoningEffort, allowed: readonly T[]): T { const rank = (e: string) => REASONING_EFFORTS.indexOf(e as ReasoningEffort); const want = rank(effort); let best = allowed[0]; let bestDistance = Number.POSITIVE_INFINITY; for (const level of allowed) { const d = Math.abs(rank(level) - want); if (d < bestDistance || (d === bestDistance && rank(level) > rank(best))) { best = level; bestDistance = d; } } return best; }