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>
180 lines
6 KiB
TypeScript
180 lines
6 KiB
TypeScript
/**
|
|
* 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' | 'openai_compatible' | 'ollama';
|
|
|
|
export const PROVIDER_KINDS: ProviderKind[] = ['openai', 'anthropic', 'gemini', '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<string, string>;
|
|
}
|
|
|
|
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<string, unknown> }
|
|
| { 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<string, unknown>;
|
|
}
|
|
|
|
export type ReasoningEffort = 'none' | 'low' | 'medium' | 'high';
|
|
|
|
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<ModelCapabilities>;
|
|
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<string, unknown> } }
|
|
/** 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<ModelCapabilities>;
|
|
/** USD per million tokens, when known. */
|
|
priceIn?: number;
|
|
priceOut?: number;
|
|
}
|
|
|
|
export interface TestResult {
|
|
ok: boolean;
|
|
message: string;
|
|
latencyMs: number;
|
|
/** Number of models visible to the key, when discovery works. */
|
|
modelCount?: 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<StreamEvent>;
|
|
/** Lists chat-capable models. Throws AIError('unsupported') when a provider has no listing API. */
|
|
listModels(cfg: ProviderConfig, signal?: AbortSignal): Promise<DiscoveredModel[]>;
|
|
/** Cheap credential / connectivity check. Never throws. */
|
|
test(cfg: ProviderConfig, model?: string): Promise<TestResult>;
|
|
}
|
|
|
|
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,
|
|
};
|