@quilltap/plugin-types 1.18.0 → 2.0.1

package/dist/llm/index.d.mts

@@ -1,3 +1,105 @@
+/**
+ * Common types shared across all provider interfaces
+ *
+ * These types are used by multiple provider shapes (text, image, embedding, scoring)
+ * and are extracted here to avoid duplication.
+ *
+ * @module @quilltap/plugin-types/providers/common
+ */
+/**
+ * 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>;
+}
+/**
+ * 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;
+    }>;
+}
+/**
+ * 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;
+}
+
 /**
  * Tool/Function calling types for Quilltap plugin development
  *
@@ -128,32 +230,15 @@ interface ToolFormatOptions {
 }
 
 /**
- * Core LLM types for Quilltap plugin development
+ * Text Provider — Shape 1: Text -> Text
  *
- * @module @quilltap/plugin-types/llm
+ * Send instructions + data (with optional attachments) to an LLM,
+ * receive a text response. This is the fundamental text completion shape,
+ * covering both standard and "cheap" model calls.
+ *
+ * @module @quilltap/plugin-types/providers/text
  */
 
-/**
- * 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
  */
@@ -198,7 +283,7 @@ interface ResponseFormat {
     jsonSchema?: JSONSchemaDefinition;
 }
 /**
- * Parameters for LLM requests
+ * Parameters for text completion requests
  */
 interface LLMParams {
     /** Array of messages in the conversation */
@@ -209,6 +294,12 @@ interface LLMParams {
     temperature?: number;
     /** Maximum tokens to generate */
     maxTokens?: number;
+    /**
+     * When true, the provider MUST respect the exact maxTokens value without
+     * applying model-specific overrides (e.g. reasoning model minimums).
+     * Used by background tasks (cheap LLM) that need strict output limits.
+     */
+    strictMaxTokens?: boolean;
     /** Nucleus sampling parameter */
     topP?: number;
     /** Stop sequences */
@@ -236,43 +327,7 @@ interface LLMParams {
     previousResponseId?: string;
 }
 /**
- * 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
+ * Response from a text completion
  */
 interface LLMResponse {
     /** Generated content */
@@ -293,7 +348,7 @@ interface LLMResponse {
     cacheUsage?: CacheUsage;
 }
 /**
- * Streaming chunk from LLM
+ * Streaming chunk from a text completion
  */
 interface StreamChunk {
     /** Content in this chunk */
@@ -313,6 +368,56 @@ interface StreamChunk {
     /** Cache usage statistics */
     cacheUsage?: CacheUsage;
 }
+/**
+ * Text completion provider interface — Shape 1: Text -> Text
+ *
+ * Sends instructions and data to an LLM and receives text responses,
+ * either as a complete response or as a stream of chunks.
+ *
+ * This covers both standard and "cheap" model calls — the difference
+ * is in model selection and parameters, not the interface shape.
+ */
+interface TextProvider {
+    /** Whether this provider supports file attachments */
+    readonly supportsFileAttachments: boolean;
+    /** Supported MIME types for file attachments */
+    readonly supportedMimeTypes: string[];
+    /** 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[]>;
+    /**
+     * 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 Provider — Shape 2: Text -> Image
+ *
+ * Send instructions (a prompt) to an image generation model,
+ * receive one or more generated images.
+ *
+ * @module @quilltap/plugin-types/providers/image
+ */
 /**
  * Image generation parameters
  */
@@ -369,94 +474,18 @@ interface ImageGenResponse {
     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
+ * Image generation provider interface — Shape 2: Text -> Image
  *
- * 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
+ * Sends a text prompt to an image generation model and receives
+ * one or more generated images.
  */
-interface ImageGenProvider {
+interface ImageProvider {
     /** Provider identifier */
     readonly provider: string;
     /** Models supported by this provider */
     readonly supportedModels: string[];
     /**
-     * Generate an image
+     * Generate an image from a text prompt
      */
     generateImage(params: ImageGenParams, apiKey: string): Promise<ImageGenResponse>;
     /**
@@ -470,12 +499,12 @@ interface ImageGenProvider {
 }
 
 /**
- * Embedding Provider Types for Quilltap plugin development
+ * Embedding Provider — Shape 3: Text -> Vector
  *
- * Defines interfaces for embedding providers that can be implemented
- * by plugins to provide text-to-vector embedding functionality.
+ * Send text to an embedding model, receive a numeric vector representation.
+ * Used for semantic search, RAG, and similarity matching.
  *
- * @module @quilltap/plugin-types/llm/embeddings
+ * @module @quilltap/plugin-types/providers/embedding
  */
 /**
  * Result of an embedding operation
@@ -502,10 +531,10 @@ interface EmbeddingOptions {
     dimensions?: number;
 }
 /**
- * Standard embedding provider interface
+ * Embedding provider interface — Shape 3: Text -> Vector
  *
- * This is the base interface for all embedding providers that use
- * external APIs (OpenAI, Ollama, OpenRouter, etc.)
+ * Sends text to an embedding model and receives a numeric vector
+ * representation for use in semantic search, RAG, and similarity matching.
  */
 interface EmbeddingProvider {
     /**
@@ -630,4 +659,4 @@ interface LocalEmbeddingProvider extends Omit<EmbeddingProvider, 'generateEmbedd
  */
 declare function isLocalEmbeddingProvider(provider: EmbeddingProvider | LocalEmbeddingProvider): provider is LocalEmbeddingProvider;
 
-export { type AnthropicToolDefinition, type AttachmentResults, type CacheUsage, type EmbeddingOptions, type EmbeddingProvider, type EmbeddingResult, type FileAttachment, type GeneratedImage, type GoogleToolDefinition, type ImageGenParams, type ImageGenProvider, type ImageGenResponse, type JSONSchemaDefinition, type LLMMessage, type LLMParams, type LLMProvider, type LLMResponse, type LocalEmbeddingProvider, type LocalEmbeddingProviderState, type ModelMetadata, type ModelWarning, type ModelWarningLevel, type OpenAIToolDefinition, type ResponseFormat, type StreamChunk, type TokenUsage, type ToolCall, type ToolCallRequest, type ToolFormatOptions, type ToolResult, type UniversalTool, isLocalEmbeddingProvider };
+export { type AnthropicToolDefinition, type AttachmentResults, type CacheUsage, type EmbeddingOptions, type EmbeddingProvider, type EmbeddingResult, type FileAttachment, type GeneratedImage, type GoogleToolDefinition, type ImageGenParams, type ImageProvider as ImageGenProvider, type ImageGenResponse, type ImageProvider, type JSONSchemaDefinition, type LLMMessage, type LLMParams, type TextProvider as LLMProvider, type LLMResponse, type LocalEmbeddingProvider, type LocalEmbeddingProviderState, type ModelMetadata, type ModelWarning, type ModelWarningLevel, type OpenAIToolDefinition, type ResponseFormat, type StreamChunk, type TextProvider, type TokenUsage, type ToolCall, type ToolCallRequest, type ToolFormatOptions, type ToolResult, type UniversalTool, isLocalEmbeddingProvider };