@quilltap/plugin-types 1.0.0

package/dist/llm/index.d.mts

@@ -0,0 +1,468 @@
+/**
+ * Tool/Function calling types for Quilltap plugin development
+ *
+ * @module @quilltap/plugin-types/llm/tools
+ */
+/**
+ * OpenAI-format tool definition
+ * Used as the universal baseline format for tool definitions
+ */
+interface OpenAIToolDefinition {
+    /** Tool type - always 'function' for function calling */
+    type: 'function';
+    function: {
+        /** Name of the function */
+        name: string;
+        /** Description of what the function does */
+        description?: string;
+        /** Parameters schema in JSON Schema format */
+        parameters?: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required?: string[];
+            additionalProperties?: boolean;
+        };
+        /** Whether to use strict mode for parameters */
+        strict?: boolean;
+    };
+}
+/**
+ * Universal tool format (alias for OpenAI format)
+ * Used as the standard format across all providers
+ */
+interface UniversalTool {
+    /** Tool type - always 'function' */
+    type: 'function';
+    function: {
+        /** Name of the tool/function */
+        name: string;
+        /** Description of what the tool does */
+        description: string;
+        /** Parameters schema in JSON Schema format */
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+/**
+ * Anthropic-format tool definition
+ * Tool use format expected by Anthropic Claude models
+ */
+interface AnthropicToolDefinition {
+    /** Name of the tool */
+    name: string;
+    /** Description of what the tool does */
+    description?: string;
+    /** Input schema in JSON Schema format */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Google-format tool definition
+ * Function calling format expected by Google Gemini models
+ */
+interface GoogleToolDefinition {
+    /** Name of the function */
+    name: string;
+    /** Description of what the function does */
+    description: string;
+    /** Parameters schema in JSON Schema format */
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/**
+ * Tool call from assistant response
+ * Represents a tool call made by the model
+ */
+interface ToolCall {
+    /** Unique ID for this tool call */
+    id: string;
+    /** Type of tool call - always 'function' */
+    type: 'function';
+    function: {
+        /** Name of the function to call */
+        name: string;
+        /** Arguments as a JSON string */
+        arguments: string;
+    };
+}
+/**
+ * Parsed tool call request
+ * Used consistently across all providers after parsing
+ */
+interface ToolCallRequest {
+    /** Name of the tool being called */
+    name: string;
+    /** Parsed arguments object */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Tool result to send back to the model
+ */
+interface ToolResult {
+    /** ID of the tool call this is responding to */
+    toolCallId: string;
+    /** Result content */
+    content: string;
+    /** Whether this result represents an error */
+    isError?: boolean;
+}
+/**
+ * Options for tool formatting operations
+ */
+interface ToolFormatOptions {
+    /** Image provider type for context-aware formatting */
+    imageProviderType?: string;
+    /** Additional custom options */
+    [key: string]: unknown;
+}
+
+/**
+ * Core LLM types for Quilltap plugin development
+ *
+ * @module @quilltap/plugin-types/llm
+ */
+
+/**
+ * File attachment for multimodal messages
+ */
+interface FileAttachment {
+    /** Unique identifier for the attachment */
+    id: string;
+    /** Path to the file on disk (internal use) */
+    filepath?: string;
+    /** Original filename */
+    filename: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Base64 encoded data (loaded at send time) */
+    data?: string;
+    /** URL to fetch the file (alternative to data) */
+    url?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Message in a conversation
+ */
+interface LLMMessage {
+    /** Role of the message sender */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Message content */
+    content: string;
+    /** Optional name for multi-character chats */
+    name?: string;
+    /** File attachments for this message */
+    attachments?: FileAttachment[];
+    /** Tool call ID (for tool role messages) */
+    toolCallId?: string;
+    /** Tool calls made by assistant */
+    toolCalls?: ToolCall[];
+    /** Cache control for prompt caching (Anthropic, Google) */
+    cacheControl?: {
+        type: 'ephemeral';
+    };
+    /** Google Gemini thought signature for thinking models */
+    thoughtSignature?: string;
+}
+/**
+ * JSON Schema definition for structured outputs
+ */
+interface JSONSchemaDefinition {
+    /** Name of the schema */
+    name: string;
+    /** Whether to use strict mode */
+    strict?: boolean;
+    /** The JSON schema object */
+    schema: Record<string, unknown>;
+}
+/**
+ * Response format for structured outputs
+ */
+interface ResponseFormat {
+    /** Output type */
+    type: 'text' | 'json_object' | 'json_schema';
+    /** JSON schema definition (when type is 'json_schema') */
+    jsonSchema?: JSONSchemaDefinition;
+}
+/**
+ * Parameters for LLM requests
+ */
+interface LLMParams {
+    /** Array of messages in the conversation */
+    messages: LLMMessage[];
+    /** Model identifier */
+    model: string;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+    /** Stop sequences */
+    stop?: string | string[];
+    /** Tool definitions (provider-specific format) */
+    tools?: unknown[];
+    /** Tool choice configuration */
+    toolChoice?: 'auto' | 'none' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    /** Response format for structured outputs */
+    responseFormat?: ResponseFormat;
+    /** Seed for deterministic generation */
+    seed?: number;
+    /** User identifier for tracking */
+    user?: string;
+    /** Enable native web search capability */
+    webSearchEnabled?: boolean;
+    /** Provider-specific parameters from profile */
+    profileParameters?: Record<string, unknown>;
+}
+/**
+ * Token usage statistics
+ */
+interface TokenUsage {
+    /** Tokens used for the prompt */
+    promptTokens: number;
+    /** Tokens used for the completion */
+    completionTokens: number;
+    /** Total tokens used */
+    totalTokens: number;
+}
+/**
+ * Cache usage statistics (OpenRouter, Anthropic)
+ */
+interface CacheUsage {
+    /** Number of cached tokens */
+    cachedTokens?: number;
+    /** Cache discount amount */
+    cacheDiscount?: number;
+    /** Tokens used for cache creation */
+    cacheCreationInputTokens?: number;
+    /** Tokens read from cache */
+    cacheReadInputTokens?: number;
+}
+/**
+ * Attachment processing results
+ */
+interface AttachmentResults {
+    /** IDs of attachments sent successfully */
+    sent: string[];
+    /** Attachments that failed with error details */
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+/**
+ * Response from LLM
+ */
+interface LLMResponse {
+    /** Generated content */
+    content: string;
+    /** Reason generation stopped */
+    finishReason: string | null;
+    /** Token usage statistics */
+    usage: TokenUsage;
+    /** Provider-specific raw response */
+    raw?: unknown;
+    /** Tool calls made by the model */
+    toolCalls?: ToolCall[];
+    /** Results of attachment processing */
+    attachmentResults?: AttachmentResults;
+    /** Google Gemini thought signature */
+    thoughtSignature?: string;
+    /** Cache usage statistics */
+    cacheUsage?: CacheUsage;
+}
+/**
+ * Streaming chunk from LLM
+ */
+interface StreamChunk {
+    /** Content in this chunk */
+    content: string;
+    /** Whether this is the final chunk */
+    done: boolean;
+    /** Token usage (typically on final chunk) */
+    usage?: TokenUsage;
+    /** Tool calls (typically on final chunk) */
+    toolCalls?: ToolCall[];
+    /** Attachment results (typically on final chunk) */
+    attachmentResults?: AttachmentResults;
+    /** Raw response for tool call detection */
+    rawResponse?: unknown;
+    /** Google Gemini thought signature */
+    thoughtSignature?: string;
+    /** Cache usage statistics */
+    cacheUsage?: CacheUsage;
+}
+/**
+ * Image generation parameters
+ */
+interface ImageGenParams {
+    /** Image generation prompt */
+    prompt: string;
+    /** Negative prompt (what to avoid) */
+    negativePrompt?: string;
+    /** Model identifier */
+    model?: string;
+    /** Image size (e.g., '1024x1024') */
+    size?: string;
+    /** Aspect ratio (e.g., '16:9') */
+    aspectRatio?: string;
+    /** Image quality */
+    quality?: 'standard' | 'hd';
+    /** Image style */
+    style?: 'vivid' | 'natural';
+    /** Number of images to generate */
+    n?: number;
+    /** Response format */
+    responseFormat?: 'url' | 'b64_json';
+    /** Seed for reproducibility */
+    seed?: number;
+    /** Guidance scale for diffusion models */
+    guidanceScale?: number;
+    /** Inference steps for diffusion models */
+    steps?: number;
+}
+/**
+ * Generated image result
+ */
+interface GeneratedImage {
+    /** Base64 encoded image data */
+    data?: string;
+    /** URL to the generated image */
+    url?: string;
+    /** Deprecated: use 'data' instead */
+    b64Json?: string;
+    /** Image MIME type */
+    mimeType?: string;
+    /** Revised prompt (some providers modify the prompt) */
+    revisedPrompt?: string;
+    /** Seed used for generation */
+    seed?: number;
+}
+/**
+ * Image generation response
+ */
+interface ImageGenResponse {
+    /** Array of generated images */
+    images: GeneratedImage[];
+    /** Provider-specific raw response */
+    raw?: unknown;
+}
+/**
+ * Model warning level
+ */
+type ModelWarningLevel = 'info' | 'warning' | 'error';
+/**
+ * Model warning information
+ */
+interface ModelWarning {
+    /** Warning severity level */
+    level: ModelWarningLevel;
+    /** Warning message */
+    message: string;
+    /** Optional link to documentation */
+    documentationUrl?: string;
+}
+/**
+ * Model metadata with warnings and capabilities
+ */
+interface ModelMetadata {
+    /** Model identifier */
+    id: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Warnings or recommendations */
+    warnings?: ModelWarning[];
+    /** Whether the model is deprecated */
+    deprecated?: boolean;
+    /** Whether the model is experimental/preview */
+    experimental?: boolean;
+    /** Capabilities this model lacks */
+    missingCapabilities?: string[];
+    /** Maximum output tokens */
+    maxOutputTokens?: number;
+    /** Context window size */
+    contextWindow?: number;
+}
+/**
+ * Core LLM provider interface
+ *
+ * Plugins can implement this interface to provide LLM functionality.
+ */
+interface LLMProvider {
+    /** Whether this provider supports file attachments */
+    readonly supportsFileAttachments: boolean;
+    /** Supported MIME types for file attachments */
+    readonly supportedMimeTypes: string[];
+    /** Whether this provider supports image generation */
+    readonly supportsImageGeneration: boolean;
+    /** Whether this provider supports web search */
+    readonly supportsWebSearch: boolean;
+    /**
+     * Send a message and get a complete response
+     */
+    sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse>;
+    /**
+     * Send a message and stream the response
+     */
+    streamMessage(params: LLMParams, apiKey: string): AsyncGenerator<StreamChunk>;
+    /**
+     * Validate an API key
+     */
+    validateApiKey(apiKey: string): Promise<boolean>;
+    /**
+     * Get available models from the provider
+     */
+    getAvailableModels(apiKey: string): Promise<string[]>;
+    /**
+     * Generate an image (optional)
+     */
+    generateImage?(params: ImageGenParams, apiKey: string): Promise<ImageGenResponse>;
+    /**
+     * Get metadata for a specific model (optional)
+     */
+    getModelMetadata?(modelId: string): ModelMetadata | undefined;
+    /**
+     * Get metadata for all models with warnings (optional)
+     */
+    getModelsWithMetadata?(apiKey: string): Promise<ModelMetadata[]>;
+}
+/**
+ * Image generation provider interface
+ */
+interface ImageGenProvider {
+    /** Provider identifier */
+    readonly provider: string;
+    /** Models supported by this provider */
+    readonly supportedModels: string[];
+    /**
+     * Generate an image
+     */
+    generateImage(params: ImageGenParams, apiKey: string): Promise<ImageGenResponse>;
+    /**
+     * Validate an API key
+     */
+    validateApiKey(apiKey: string): Promise<boolean>;
+    /**
+     * Get available models
+     */
+    getAvailableModels(apiKey?: string): Promise<string[]>;
+}
+
+export type { AnthropicToolDefinition, AttachmentResults, CacheUsage, FileAttachment, GeneratedImage, GoogleToolDefinition, ImageGenParams, ImageGenProvider, ImageGenResponse, JSONSchemaDefinition, LLMMessage, LLMParams, LLMProvider, LLMResponse, ModelMetadata, ModelWarning, ModelWarningLevel, OpenAIToolDefinition, ResponseFormat, StreamChunk, TokenUsage, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool };