Study/server/ai/types.ts
Elijah ccdad9728b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
- Drag-to-reorder for class materials, folders, quiz questions and deck cards. Pointer-based
  so touch works, plus keyboard (arrows/Home/End) with screen-reader announcements.
- Timed exams get a wall-clock deadline. The server refuses late answers, submits overdue
  exams with what was saved, and the countdown keeps running while the page is closed.
- Shared quiz sessions keep a frozen copy of their questions and flag later owner edits.
- Scanned PDFs are read in cached 8-page batches with real page numbers (pdf-lib), removing
  the 30 MB whole-file limit. Compatible providers now receive PDFs as file parts.
- Semantic search: embeddings for OpenAI, Gemini, Ollama and compatible servers, background
  indexing into chunk_vectors (migration 2), hybrid keyword + vector ranking for search, the
  assistant and focused generation, and a Settings -> AI section.

181 tests pass locally and in the Docker test stage on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:48:20 -07:00

197 lines
6.5 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 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<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>;
/** Text embeddings for semantic search. Absent when the provider has no embeddings API. */
embed?(cfg: ProviderConfig, req: EmbedRequest): Promise<EmbedResult>;
}
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,
};