/** * Provider-neutral AI contract. * * Every provider adapter (OpenAI, Anthropic, Gemini, OpenAI-compatible, Ollama) * translates between this shape and the provider's wire format. Nothing outside * `server/ai/providers/` may depend on a provider-specific request or response. */ export type ProviderKind = 'openai' | 'anthropic' | 'gemini' | 'deepseek' | 'openai_compatible' | 'ollama'; export const PROVIDER_KINDS: ProviderKind[] = ['openai', 'anthropic', 'gemini', 'deepseek', 'openai_compatible', 'ollama']; /** Decrypted provider connection, only ever held server-side. */ export interface ProviderConfig { id: string; kind: ProviderKind; name: string; /** Null means "use the provider's official default endpoint". */ baseUrl: string | null; apiKey: string | null; /** Extra HTTP headers (e.g. OpenRouter attribution, org ids). */ headers?: Record; } export type ContentPart = | { type: 'text'; text: string } /** Base64 image data (no data: prefix). */ | { type: 'image'; mime: string; data: string } /** Base64 file, used for native PDF input where a provider supports it. */ | { type: 'file'; mime: string; data: string; filename?: string } | { type: 'tool_call'; id: string; name: string; input: Record } | { type: 'tool_result'; toolCallId: string; name: string; output: string; isError?: boolean }; export interface ChatMessage { /** Tool results travel as `tool_result` parts inside a `user` message. */ role: 'user' | 'assistant'; content: ContentPart[]; /** * Opaque provider state for an assistant turn (thinking blocks + signatures, * Gemini thought signatures, OpenAI reasoning items...). An adapter writes it * on the `done` event and, when the next request goes to the same provider * kind, replays it verbatim instead of rebuilding the turn from `content`. */ providerData?: { kind: ProviderKind; data: unknown }; } export interface ToolDef { name: string; description: string; /** JSON Schema (object). Adapters down-convert for providers with a restricted dialect. */ parameters: Record; } /** * Reasoning effort, from "off" to the most a provider offers. Adapters map each level onto * the nearest value their API accepts (see `nearestEffort`). */ export const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const; export type ReasoningEffort = (typeof REASONING_EFFORTS)[number]; export interface ModelCapabilities { tools: boolean; vision: boolean; /** Accepts PDF files directly as input. */ pdf: boolean; /** Has a configurable reasoning / thinking effort. */ reasoning: boolean; /** Accepts a custom temperature (some reasoning models reject it). */ temperature: boolean; } export interface ChatRequest { model: string; system?: string; messages: ChatMessage[]; tools?: ToolDef[]; toolChoice?: 'auto' | 'none' | 'required' | { name: string }; temperature?: number; maxOutputTokens?: number; reasoningEffort?: ReasoningEffort; /** Ask for a JSON object as the text output when the provider has a JSON mode. */ jsonMode?: boolean; /** Known capabilities of the model, when the caller has them. Adapters must not send unsupported params. */ capabilities?: Partial; signal?: AbortSignal; } export interface Usage { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number; reasoningTokens?: number; } export type StopReason = 'end' | 'tool_use' | 'max_tokens' | 'refusal' | 'other'; export type StreamEvent = | { type: 'text'; delta: string } | { type: 'reasoning'; delta: string } /** Emitted once per tool call, after its arguments are complete and parsed. */ | { type: 'tool_call'; call: { id: string; name: string; input: Record } } /** Always the final event of a successful stream. */ | { type: 'done'; message: ChatMessage; stopReason: StopReason; usage: Usage }; export interface DiscoveredModel { /** Identifier sent to the API. */ id: string; label?: string; contextWindow?: number; maxOutput?: number; capabilities?: Partial; /** USD per million tokens, when known. */ priceIn?: number; priceOut?: number; /** USD per million cached (cache-hit) input tokens, when the provider prices them separately. */ priceCachedIn?: number; } export interface TestResult { ok: boolean; message: string; latencyMs: number; /** Number of models visible to the key, when discovery works. */ modelCount?: number; } export interface EmbedRequest { model: string; inputs: string[]; /** Some providers embed search queries and stored passages differently. */ purpose: 'document' | 'query'; /** Requested vector size, for models that can shorten their output (OpenAI v3, Gemini). */ dimensions?: number; signal?: AbortSignal; } export interface EmbedResult { vectors: number[][]; inputTokens: number; } export interface ProviderAdapter { kind: ProviderKind; /** Human label and defaults used by the settings UI. */ meta: { label: string; defaultBaseUrl: string | null; requiresApiKey: boolean; requiresBaseUrl: boolean; supportsDiscovery: boolean; docsUrl: string; keyHint: string; }; /** Streams one model turn. Throws AIError; never yields after `done`. */ stream(cfg: ProviderConfig, req: ChatRequest): AsyncIterable; /** Lists chat-capable models. Throws AIError('unsupported') when a provider has no listing API. */ listModels(cfg: ProviderConfig, signal?: AbortSignal): Promise; /** Cheap credential / connectivity check. Never throws. */ test(cfg: ProviderConfig, model?: string): Promise; /** Text embeddings for semantic search. Absent when the provider has no embeddings API. */ embed?(cfg: ProviderConfig, req: EmbedRequest): Promise; } export type AIErrorCode = | 'auth' | 'rate_limit' | 'quota' | 'context_length' | 'not_found' | 'bad_request' | 'content_filter' | 'server' | 'network' | 'timeout' | 'aborted' | 'unsupported' | 'invalid_response' | 'not_configured'; export class AIError extends Error { code: AIErrorCode; status?: number; retryable: boolean; /** Raw (already secret-scrubbed) provider message, for the details disclosure in the UI. */ providerMessage?: string; constructor(code: AIErrorCode, message: string, opts: { status?: number; retryable?: boolean; providerMessage?: string; cause?: unknown } = {}) { super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined); this.name = 'AIError'; this.code = code; this.status = opts.status; this.retryable = opts.retryable ?? (code === 'rate_limit' || code === 'server' || code === 'network' || code === 'timeout'); this.providerMessage = opts.providerMessage; } } export const DEFAULT_CAPABILITIES: ModelCapabilities = { tools: true, vision: false, pdf: false, reasoning: false, temperature: true, };