Start Study Desk V2: remove V1 sources, add backend foundation
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>
This commit is contained in:
parent
7bd0a9aad4
commit
3e74ecd843
268 changed files with 17740 additions and 55423 deletions
180
server/ai/types.ts
Normal file
180
server/ai/types.ts
Normal file
|
|
@ -0,0 +1,180 @@
|
|||
/**
|
||||
* 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,
|
||||
};
|
||||
Loading…
Add table
Add a link
Reference in a new issue