Skip to content

Build your personal knowledge base with Trilium Notes

11.1 KB
Raw Blame
/**
 * Shared LLM types for chat integration.
 * Used by both client and server for API communication.
 */

/**
 * Plain-text segment of a multimodal message.
 */
export interface LlmTextPart {
    type: "text";
    text: string;
}

/**
 * Image segment of a multimodal message. The image is referenced by its
 * Trilium attachment ID — the server loads the bytes from Becca before
 * forwarding to the provider, so the wire stays small and we don't store
 * base64 in chat history.
 */
export interface LlmImagePart {
    type: "image";
    attachmentId: string;
    /** IANA media type (e.g. "image/png"). */
    mime: string;
}

/**
 * File segment of a multimodal message (e.g. a PDF). Like image parts, the
 * file is referenced by its Trilium attachment ID and resolved to bytes
 * server-side. Provider support varies by MIME type — PDFs (`application/pdf`)
 * are handled natively by Anthropic, OpenAI, and Google.
 */
export interface LlmFilePart {
    type: "file";
    attachmentId: string;
    mime: string;
    filename: string;
}

/**
 * Text-file segment of a multimodal message (e.g. a `.md`, `.json`, source
 * code). Unlike `LlmFilePart`, the server inlines the decoded UTF-8 content
 * as a plain `TextPart` so it works with every provider regardless of file
 * upload support — the trade-off is that large files inflate token usage.
 */
export interface LlmTextAttachmentPart {
    type: "text_attachment";
    attachmentId: string;
    filename: string;
}

export type LlmMessagePart = LlmTextPart | LlmImagePart | LlmFilePart | LlmTextAttachmentPart;

/**
 * A chat message in the conversation. `content` may be a plain string (the
 * common case) or an ordered array of parts when the message includes images.
 */
export interface LlmMessage {
    role: "user" | "assistant" | "system";
    content: string | LlmMessagePart[];
}

/**
 * Citation information extracted from LLM responses.
 * May include URL (for web search) or document metadata (for document citations).
 */
export interface LlmCitation {
    /** Source URL (typically from web search) */
    url?: string;
    /** Document or page title */
    title?: string;
    /** The text that was cited */
    citedText?: string;
}

/**
 * How much a model reasons before it answers, weakest first. The names are the
 * AI SDK's `reasoning` call option, plus Anthropic's `max`.
 */
export const LLM_REASONING_EFFORTS = [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] as const;

export type LlmReasoningEffort = (typeof LLM_REASONING_EFFORTS)[number];

/**
 * Configuration for LLM chat requests.
 */
export interface LlmChatConfig {
    /** Provider type (e.g. "anthropic"). Kept for chats saved before {@link providerId} existed. */
    provider?: string;
    /**
     * ID of the provider configuration to route through. Preferred over
     * {@link provider} — it disambiguates multiple configs of the same type
     * (e.g. a real OpenAI key plus a self-hosted Ollama endpoint).
     */
    providerId?: string;
    model?: string;
    systemPrompt?: string;
    /** Enable web search tool */
    enableWebSearch?: boolean;
    /**
     * The config id of the search provider that answers {@link enableWebSearch}, in place of the
     * model's built-in search. Absent, or naming no configured search provider, means built-in.
     */
    webSearchProviderId?: string;
    /** Enable note tools (search and read notes) */
    enableNoteTools?: boolean;
    /** Enable extended thinking for deeper reasoning */
    enableExtendedThinking?: boolean;
    /** Token budget for extended thinking (default: 10000) */
    thinkingBudget?: number;
    /**
     * Reasoning effort for a model that lists {@link LlmModelInfo.reasoningEfforts}. Takes the
     * place of {@link enableExtendedThinking} for such a model; absent means the model's
     * {@link LlmModelInfo.defaultReasoningEffort}.
     */
    reasoningEffort?: LlmReasoningEffort;
    /** Current note context (note ID the user is viewing) */
    contextNoteId?: string;
    /** The note ID of the chat note (used for auto-renaming on first message) */
    chatNoteId?: string;
    /** The tools the user allowed for the whole chat, whose calls run without asking. */
    allowedTools?: string[];
    /** Which tool calls wait for the user. Absent means `"always_ask"`. */
    permissionMode?: LlmPermissionMode;
}

/**
 * Which tool calls of a chat wait for the user: all of them, only those that change notes, or none.
 * A tool the chat allowed (`allowedTools`) runs without asking in every mode.
 */
export const LLM_PERMISSION_MODES = [ "always_ask", "ask_before_changes", "dont_ask" ] as const;

export type LlmPermissionMode = (typeof LLM_PERMISSION_MODES)[number];

/**
 * Pricing per million tokens for a model.
 */
export interface LlmModelPricing {
    /** Cost per million input tokens in USD */
    input: number;
    /** Cost per million output tokens in USD */
    output: number;
}

/**
 * What a configuration in the `llmProviders` option provides: chat models (`"llm"`) or web
 * search (`"search"`). A configuration without a `kind` is `"llm"`.
 */
export type LlmProviderKind = "llm" | "search";

/** Whether a stored provider configuration is of `kind`, treating a missing `kind` as `"llm"`. */
export function isProviderOfKind(config: { kind?: LlmProviderKind }, kind: LlmProviderKind): boolean {
    return (config.kind ?? "llm") === kind;
}

/**
 * Information about an available LLM model.
 */
export interface LlmModelInfo {
    /** Model identifier (e.g., "claude-sonnet-4-20250514") */
    id: string;
    /** Human-readable name (e.g., "Claude Sonnet 4") */
    name: string;
    /** Provider type that owns this model (e.g., "anthropic", "openai") */
    provider?: string;
    /** ID of the provider configuration this model was listed from */
    providerId?: string;
    /** User-given name of the provider configuration (e.g. "My Ollama") */
    providerName?: string;
    /** Pricing per million tokens. Absent for dynamically discovered models with unknown pricing. */
    pricing?: LlmModelPricing;
    /** Whether this is the default model */
    isDefault?: boolean;
    /** Whether this is a legacy/older model */
    isLegacy?: boolean;
    /** Whether this model is pre-selected by default when adding a provider (e.g. excludes legacy and, for Gemini, preview models) */
    recommended?: boolean;
    /** Maximum context window size in tokens */
    contextWindow?: number;
    /** Whether usage is covered by a subscription plan rather than metered per token */
    isSubscription?: boolean;
    /**
     * The reasoning efforts the model can be run at, weakest first. Absent for a model with no
     * graded setting, which keeps the on/off extended thinking switch instead.
     */
    reasoningEfforts?: LlmReasoningEffort[];
    /** The effort used when a chat has not chosen one. One of {@link reasoningEfforts}. */
    defaultReasoningEffort?: LlmReasoningEffort;
    /**
     * The attachment kinds the model reads natively. Absent means every kind; text attachments
     * are inlined as text for every model and never listed.
     */
    attachmentKinds?: LlmAttachmentKind[];
}

/** An attachment a model reads natively: an image, or a file such as a PDF. */
export const LLM_ATTACHMENT_KINDS = [ "image", "file" ] as const;

export type LlmAttachmentKind = (typeof LLM_ATTACHMENT_KINDS)[number];

/**
 * Token usage information from the LLM response.
 */
export interface LlmUsage {
    /** The token counts are absent when the provider reports none, as the ACP agents (Copilot, Antigravity) do. */
    promptTokens?: number;
    completionTokens?: number;
    totalTokens?: number;
    /** Estimated cost in USD (if available) */
    cost?: number;
    /** Model identifier used for this response */
    model?: string;
    /**
     * Provider *type* that served the response ("anthropic", "deepseek", …), not the id of a
     * particular configuration. Recorded alongside the model so the client can abbreviate the
     * name for display: which vendor word is safe to drop depends on the vendor. The full
     * name is what gets stored — shortening is applied at render time only.
     */
    provider?: string;
}

/**
 * Machine-readable context for a failed provider call, carried alongside the
 * human-readable error message of an `error` chunk.
 *
 * Kept as separate fields rather than pre-formatted into the message so the client
 * can title the failure ("API error (HTTP 400)"), collapse the noisy parts behind a
 * "show details" toggle, and drop a response body that only repeats the message.
 * Absent for failures that never reached a provider (connection errors, aborted
 * streams) and for chats saved before this field existed.
 */
export interface LlmErrorDetails {
    /** HTTP status returned by the provider. */
    statusCode?: number;
    /** Endpoint the failed request was sent to. */
    url?: string;
    /** Raw response body, truncated by the server to a display-safe length. */
    responseBody?: string;
}

/**
 * What a turn is waiting on before its reply starts. The client names it in
 * the chat until the first content of the reply arrives.
 *   - `starting_agent`: a subscription agent's CLI is being started.
 */
export type LlmStreamStatus = "starting_agent";

/**
 * Whether a tool result is the `{ error }` object the note tools return on failure. Takes the object
 * itself or its JSON, as a `tool_result` chunk carries it.
 */
export function isToolErrorResult(result: unknown): boolean {
    let value = result;
    if (typeof value === "string") {
        try {
            value = JSON.parse(value);
        } catch {
            return false;
        }
    }
    return typeof value === "object" && value !== null && !Array.isArray(value) && "error" in value;
}

/** A tool call that waits for the user to allow or deny it. */
export interface LlmToolApprovalRequest {
    toolCallId: string;
    toolName: string;
    toolInput: Record<string, unknown>;
}

/** The user's answer to a {@link LlmToolApprovalRequest}, posted to `/api/llm-chat/tool-approval`. */
export interface LlmToolApprovalAnswer {
    /** The id the client gave the turn when it started it. */
    streamId: string;
    toolCallId: string;
    approved: boolean;
    /**
     * `"chat"` allows the call's tool for the rest of the chat: its other calls in the turn run
     * without asking. Ignored for a denial.
     */
    scope?: "chat";
}

/**
 * Stream chunk types for real-time SSE updates.
 * Defines the protocol between server and client.
 */
export type LlmStreamChunk =
    | { type: "status"; status: LlmStreamStatus }
    | { type: "text"; content: string }
    | { type: "thinking"; content: string }
    | { type: "tool_input_start"; toolCallId: string; toolName: string }
    | { type: "tool_input_delta"; toolCallId: string; delta: string }
    | { type: "tool_use"; toolCallId: string; toolName: string; toolInput: Record<string, unknown> }
    | ({ type: "tool_approval_request" } & LlmToolApprovalRequest)
    | { type: "tool_result"; toolCallId: string; toolName: string; result: string; isError?: boolean }
    | { type: "citation"; citation: LlmCitation }
    | { type: "usage"; usage: LlmUsage }
    | { type: "error"; error: string; errorDetails?: LlmErrorDetails }
    | { type: "done" };