Study/server/ai/providers/openai.ts
Elijah 3e74ecd843 Start Study Desk V2: remove V1 sources, add backend foundation
V1 remains intact on main and in history. This branch replaces it with a new
application: node:sqlite storage with migrations, scrypt auth and sessions,
content/SRS/attempt/stats services, document extraction and chunking, a
provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible,
Ollama), the generation pipeline and the tool-using assistant.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 08:16:41 -07:00

313 lines
13 KiB
TypeScript

/**
* OpenAI — Responses API (`POST /v1/responses`, SSE).
* https://platform.openai.com/docs/api-reference/responses
* https://platform.openai.com/docs/guides/function-calling
* https://platform.openai.com/docs/guides/reasoning
*
* Quirks handled here:
* - Requests are stateless (`store: false`). Reasoning models need their reasoning
* items passed back between tool calls, so encrypted reasoning is requested via
* `include: ["reasoning.encrypted_content"]` and every turn's raw output items are
* kept in `providerData` and replayed verbatim.
* - Reasoning models reject `temperature`; classic models reject `reasoning`.
* - The accepted `reasoning.effort` values differ by model generation. When a model
* rejects the chosen value the request is retried once with a safe one.
* - Tool-call arguments arrive as deltas keyed by output item.
*/
import {
AIError,
type ChatMessage,
type ChatRequest,
type ContentPart,
type DiscoveredModel,
type ModelCapabilities,
type ProviderAdapter,
type ProviderConfig,
type StopReason,
type StreamEvent,
type TestResult,
} from '../types.ts';
import { lookupModelDefaults } from './catalog.ts';
import { dataUrl, isChatModelId, makeUsage, num, parseArgsStrict, parseToolArguments, runTest, str, TEST_TIMEOUT_MS, withCatalogDefaults } from './common.ts';
import { ensureOk, errorFromProvider, httpRequest, isRecord, requestJson, sseJson, trimBaseUrl, type ErrorContext, type HttpResponse } from './http.ts';
type Json = Record<string, unknown>;
const LABEL = 'OpenAI';
const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
function base(cfg: ProviderConfig): string {
const url = trimBaseUrl(cfg.baseUrl || DEFAULT_BASE_URL);
return /\/v\d+$/.test(url) ? url : `${url}/v1`;
}
function errorContext(cfg: ProviderConfig): ErrorContext {
return { provider: LABEL, secrets: [cfg.apiKey, ...Object.values(cfg.headers ?? {})] };
}
function headers(cfg: ProviderConfig): Record<string, string> {
if (!cfg.apiKey) throw new AIError('not_configured', 'Add an OpenAI API key in Settings to use OpenAI models.');
return { ...cfg.headers, Authorization: `Bearer ${cfg.apiKey}` };
}
/** Whether a model is a reasoning model, when the caller did not say. */
function isReasoningModel(req: ChatRequest): boolean {
if (req.capabilities?.reasoning !== undefined) return req.capabilities.reasoning;
const known = lookupModelDefaults('openai', req.model).capabilities?.reasoning;
if (known !== undefined) return known;
return /^(o\d|gpt-[5-9]|gpt-\d{2})/.test(req.model) && !/chat/.test(req.model);
}
function userContent(parts: ContentPart[], caps: Partial<ModelCapabilities>): Json[] {
const out: Json[] = [];
for (const p of parts) {
if (p.type === 'text' && p.text) out.push({ type: 'input_text', text: p.text });
else if (p.type === 'image') {
if (caps.vision === false) out.push({ type: 'input_text', text: '[An image was attached, but this model cannot read images.]' });
else out.push({ type: 'input_image', image_url: dataUrl(p.mime, p.data) });
} else if (p.type === 'file') {
if (p.mime === 'application/pdf' && caps.pdf !== false) out.push({ type: 'input_file', filename: p.filename ?? 'document.pdf', file_data: dataUrl(p.mime, p.data) });
else if (p.mime.startsWith('text/')) out.push({ type: 'input_text', text: Buffer.from(p.data, 'base64').toString('utf8') });
else out.push({ type: 'input_text', text: `[The file "${p.filename ?? 'attachment'}" was attached, but this model cannot read it directly.]` });
}
}
return out;
}
function toInput(messages: ChatMessage[], caps: Partial<ModelCapabilities>, dropReasoning: boolean): Json[] {
const input: Json[] = [];
for (const msg of messages) {
if (msg.role === 'assistant') {
const pd = msg.providerData;
if (pd?.kind === 'openai' && isRecord(pd.data) && Array.isArray(pd.data.output)) {
// Same provider: replay the output items exactly (reasoning items included).
for (const item of pd.data.output.filter(isRecord)) {
if (item.type === 'reasoning' && (dropReasoning || !item.encrypted_content)) continue;
input.push(item);
}
continue;
}
const text = msg.content.filter((p) => p.type === 'text').map((p) => (p as { text: string }).text).join('');
if (text) input.push({ role: 'assistant', content: [{ type: 'output_text', text }] });
for (const p of msg.content) {
if (p.type === 'tool_call') input.push({ type: 'function_call', call_id: p.id, name: p.name, arguments: JSON.stringify(p.input ?? {}) });
}
continue;
}
for (const p of msg.content) {
if (p.type === 'tool_result') input.push({ type: 'function_call_output', call_id: p.toolCallId, output: p.output || '(no output)' });
}
const content = userContent(msg.content.filter((p) => p.type !== 'tool_result'), caps);
if (content.length > 0) input.push({ role: 'user', content });
}
return input;
}
interface Flags {
/** Value sent as reasoning.effort, or null to omit the field. */
effort: string | null;
summary: boolean;
temperature: boolean;
dropReasoning: boolean;
include: boolean;
}
function buildBody(req: ChatRequest, flags: Flags): Json {
const caps = req.capabilities ?? {};
const body: Json = { model: req.model, input: toInput(req.messages, caps, flags.dropReasoning), stream: true, store: false };
if (req.system?.trim()) body.instructions = req.system.trim();
if (req.maxOutputTokens) body.max_output_tokens = Math.max(16, req.maxOutputTokens);
if (caps.tools !== false && req.tools?.length) {
body.tools = req.tools.map((t) => ({ type: 'function', name: t.name, description: t.description, parameters: { type: 'object', ...t.parameters }, strict: false }));
const choice = req.toolChoice;
if (choice === 'none' || choice === 'required' || choice === 'auto') body.tool_choice = choice;
else if (isRecord(choice)) body.tool_choice = { type: 'function', name: choice.name };
}
if (isReasoningModel(req)) {
const reasoning: Json = {};
if (flags.effort) reasoning.effort = flags.effort;
if (flags.summary) reasoning.summary = 'auto';
if (Object.keys(reasoning).length > 0) body.reasoning = reasoning;
if (flags.include) body.include = ['reasoning.encrypted_content'];
} else if (flags.temperature && req.temperature !== undefined && caps.temperature !== false) {
body.temperature = req.temperature;
}
if (req.jsonMode) body.text = { format: { type: 'json_object' } };
return body;
}
async function* stream(cfg: ProviderConfig, req: ChatRequest): AsyncGenerator<StreamEvent> {
const ctx = errorContext(cfg);
const flags: Flags = {
// "none" is only understood by recent models; if it is rejected we fall back to "low".
effort: req.reasoningEffort ?? null,
summary: true,
temperature: true,
dropReasoning: false,
include: true,
};
let http: HttpResponse;
for (let attempt = 0; ; attempt += 1) {
http = await httpRequest(`${base(cfg)}/responses`, { ...ctx, headers: headers(cfg), body: buildBody(req, flags), signal: req.signal });
try {
await ensureOk(http);
break;
} catch (err) {
if (!(err instanceof AIError) || err.status !== 400 || attempt >= 5) throw err;
const detail = (err.providerMessage ?? '').toLowerCase();
if (flags.effort && /reasoning\.effort|reasoning_effort|effort/.test(detail)) flags.effort = flags.effort === 'none' ? 'minimal' : flags.effort === 'minimal' ? 'low' : null;
else if (flags.summary && /summary/.test(detail)) flags.summary = false;
else if (flags.include && /include|encrypted_content/.test(detail)) flags.include = false;
else if (flags.temperature && /temperature/.test(detail)) flags.temperature = false;
else if (!flags.dropReasoning && /reasoning/.test(detail) && /item|input/.test(detail)) flags.dropReasoning = true;
else throw err;
}
}
const args = new Map<string, string>();
let final: Json | null = null;
let reasoningEmitted = false;
let streamedText = '';
for await (const { data } of sseJson(http)) {
if (!isRecord(data)) continue;
switch (data.type) {
case 'response.output_text.delta': {
const delta = str(data.delta);
if (delta) {
streamedText += delta;
yield { type: 'text', delta };
}
break;
}
case 'response.refusal.delta': {
const delta = str(data.delta);
if (delta) yield { type: 'text', delta };
break;
}
case 'response.reasoning_summary_part.added':
if (reasoningEmitted) yield { type: 'reasoning', delta: '\n\n' };
break;
case 'response.reasoning_summary_text.delta':
case 'response.reasoning_text.delta': {
const delta = str(data.delta);
if (delta) {
reasoningEmitted = true;
yield { type: 'reasoning', delta };
}
break;
}
case 'response.function_call_arguments.delta':
args.set(str(data.item_id), (args.get(str(data.item_id)) ?? '') + str(data.delta));
break;
case 'response.completed':
case 'response.incomplete':
if (isRecord(data.response)) final = data.response;
break;
case 'response.failed':
throw errorFromProvider(ctx, undefined, isRecord(data.response) && isRecord(data.response.error) ? { error: data.response.error } : data);
case 'error':
throw errorFromProvider(ctx, undefined, isRecord(data.error) ? data : { error: data });
default:
break;
}
}
if (!final) throw new AIError('network', 'The connection to OpenAI closed before the response finished.', { retryable: true });
const incomplete = isRecord(final.incomplete_details) ? str(final.incomplete_details.reason) : '';
const truncated = incomplete === 'max_output_tokens';
const output = Array.isArray(final.output) ? final.output.filter(isRecord) : [];
const content: ContentPart[] = [];
const replay: Json[] = [];
const calls: { id: string; name: string; input: Record<string, unknown> }[] = [];
let refused = false;
let text = '';
for (const item of output) {
if (item.type === 'message') {
for (const part of Array.isArray(item.content) ? item.content.filter(isRecord) : []) {
if (part.type === 'output_text') text += str(part.text);
else if (part.type === 'refusal') {
refused = true;
text += str(part.refusal);
}
}
replay.push(item);
} else if (item.type === 'function_call') {
const name = str(item.name);
const raw = str(item.arguments) || args.get(str(item.id)) || '';
let input = parseArgsStrict(raw);
if (!input) {
if (truncated) continue;
input = parseToolArguments(raw, LABEL, name);
}
calls.push({ id: str(item.call_id) || str(item.id), name, input });
replay.push(item);
} else if (item.type === 'reasoning') {
replay.push(item);
}
}
if (!text && streamedText) text = streamedText;
if (text) content.push({ type: 'text', text });
for (const call of calls) {
content.push({ type: 'tool_call', ...call });
yield { type: 'tool_call', call };
}
let stopReason: StopReason = 'end';
if (calls.length > 0) stopReason = 'tool_use';
else if (refused || incomplete === 'content_filter') stopReason = 'refusal';
else if (truncated) stopReason = 'max_tokens';
else if (incomplete) stopReason = 'other';
const u = isRecord(final.usage) ? final.usage : {};
const message: ChatMessage = { role: 'assistant', content };
if (replay.length > 0) message.providerData = { kind: 'openai', data: { output: replay } };
yield {
type: 'done',
message,
stopReason,
usage: makeUsage({
input: num(u.input_tokens),
output: num(u.output_tokens),
cacheRead: isRecord(u.input_tokens_details) ? num(u.input_tokens_details.cached_tokens) : 0,
reasoning: isRecord(u.output_tokens_details) ? num(u.output_tokens_details.reasoning_tokens) : 0,
}),
};
}
async function listModels(cfg: ProviderConfig, signal?: AbortSignal, timeoutMs?: number): Promise<DiscoveredModel[]> {
const res = await requestJson<Json>(`${base(cfg)}/models`, { ...errorContext(cfg), headers: headers(cfg), signal, firstByteTimeoutMs: timeoutMs, totalTimeoutMs: timeoutMs });
const data = Array.isArray(res.data) ? res.data.filter(isRecord) : [];
const found: DiscoveredModel[] = [];
for (const m of data) {
const id = str(m.id);
// Fine-tunes ("ft:...") are chat models too; search/codex-only variants are not useful here.
if (!id || !isChatModelId(id) || /search|^codex-|-codex-max/.test(id)) continue;
if (!/^(gpt|o\d|chat|ft:)/.test(id)) continue;
found.push({ id });
}
found.sort((a, b) => b.id.localeCompare(a.id, undefined, { numeric: true }));
return withCatalogDefaults('openai', found);
}
async function test(cfg: ProviderConfig): Promise<TestResult> {
return runTest(LABEL, async () => ({ modelCount: (await listModels(cfg, undefined, TEST_TIMEOUT_MS)).length }));
}
export const openaiAdapter: ProviderAdapter = {
kind: 'openai',
meta: {
label: LABEL,
defaultBaseUrl: DEFAULT_BASE_URL,
requiresApiKey: true,
requiresBaseUrl: false,
supportsDiscovery: true,
docsUrl: 'https://platform.openai.com/api-keys',
keyHint: 'sk-…',
},
stream,
listModels: (cfg, signal) => listModels(cfg, signal),
test,
};