All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
- 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>
204 lines
6.9 KiB
TypeScript
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,
|
|
};
|