Study/server/ai/types.ts
Elijah 25bc03ea75
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
Fourth revision: OpenRouter, live tool stages, Explain layout, share sections
- Interactive blocks are encouraged by default; Explain gets a reduced library
  and never writes practice questions.
- Assistant tool steps breathe while running, show live stages from generation
  and the Python check, and read in the past tense when done.
- The assistant asks before searching the web when class materials do not
  cover a question; clarifying questions list every class's exams and never
  ask about format (always NCLEX).
- Explain opens beside the question from 900px wide, moving the question left
  while open and back on the next one.
- Generate dialog drops the practice set/exam switch (presets cover it) and the
  Generate buttons lose their icon.
- Python check notes are green when every check passed, applied fixes neutral.
- Share pages group by exam, then Quizzes, Flashcards, Notes, Class Materials,
  hiding empty groups; the class page uses the same order. "Documents" is now
  "Class Materials".
- OpenRouter provider replaces the Ollama type; migration 6 turns Ollama
  connections into OpenAI-compatible ones at /v1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 21:54:39 -07:00

204 lines
6.9 KiB
TypeScript

/**
* Provider-neutral AI contract.
*
* Every provider adapter (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, OpenAI-compatible)
* 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' | 'openrouter' | 'openai_compatible';
export const PROVIDER_KINDS: ProviderKind[] = ['openai', 'anthropic', 'gemini', 'deepseek', 'openrouter', 'openai_compatible'];
/** 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>;
}
/**
* 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<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;
/** 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<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,
};