@quilltap/plugin-types 1.18.0 → 2.0.1

package/dist/llm/index.d.ts

@@ -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 };

package/dist/llm/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// src/llm/embeddings.ts
+// src/providers/embedding.ts
 function isLocalEmbeddingProvider(provider) {
   return "fitCorpus" in provider && "loadState" in provider && "getState" in provider;
 }

package/dist/llm/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/llm/embeddings.ts"],"names":[],"mappings":";;;AAyLO,SAAS,yBACd,QAAA,EACoC;AACpC,EAAA,OAAO,WAAA,IAAe,QAAA,IAAY,WAAA,IAAe,QAAA,IAAY,UAAA,IAAc,QAAA;AAC7E","file":"index.js","sourcesContent":["/**\n * Embedding Provider Types for Quilltap plugin development\n *\n * Defines interfaces for embedding providers that can be implemented\n * by plugins to provide text-to-vector embedding functionality.\n *\n * @module @quilltap/plugin-types/llm/embeddings\n */\n\n/**\n * Result of an embedding operation\n */\nexport interface EmbeddingResult {\n  /** The embedding vector (array of floating point numbers) */\n  embedding: number[];\n  /** The model used to generate the embedding */\n  model: string;\n  /** Number of dimensions in the embedding vector */\n  dimensions: number;\n  /** Token usage information (if available) */\n  usage?: {\n    promptTokens: number;\n    totalTokens: number;\n    cost?: number;\n  };\n}\n\n/**\n * Options for embedding generation\n */\nexport interface EmbeddingOptions {\n  /** Desired dimensions for the embedding (if model supports variable dimensions) */\n  dimensions?: number;\n}\n\n/**\n * Standard embedding provider interface\n *\n * This is the base interface for all embedding providers that use\n * external APIs (OpenAI, Ollama, OpenRouter, etc.)\n */\nexport interface EmbeddingProvider {\n  /**\n   * Generate an embedding for a single text\n   *\n   * @param text The text to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns The embedding result\n   */\n  generateEmbedding(\n    text: string,\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult>;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings?(\n    texts: string[],\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult[]>;\n\n  /**\n   * Get available embedding models\n   *\n   * @param apiKey The API key for authentication\n   * @returns Array of model IDs\n   */\n  getAvailableModels?(apiKey: string): Promise<string[]>;\n\n  /**\n   * Check if the provider is available and properly configured\n   *\n   * @param apiKey Optional API key to validate\n   * @returns True if the provider is ready to use\n   */\n  isAvailable?(apiKey?: string): Promise<boolean>;\n}\n\n/**\n * Serializable state for local embedding providers\n *\n * Used by providers like TF-IDF that maintain vocabulary state\n */\nexport interface LocalEmbeddingProviderState {\n  /** The vocabulary as an array of [term, index] pairs */\n  vocabulary: [string, number][];\n  /** The IDF (Inverse Document Frequency) weights */\n  idf: number[];\n  /** Average document length across the corpus */\n  avgDocLength: number;\n  /** Size of the vocabulary */\n  vocabularySize: number;\n  /** Whether bigrams are included in the vocabulary */\n  includeBigrams: boolean;\n  /** Timestamp when the vocabulary was fitted */\n  fittedAt: string;\n}\n\n/**\n * Local embedding provider interface\n *\n * Extended interface for local/offline embedding providers that\n * maintain vocabulary state (like TF-IDF). These providers don't\n * require API keys and can work entirely offline.\n */\nexport interface LocalEmbeddingProvider extends Omit<EmbeddingProvider, 'generateEmbedding' | 'generateBatchEmbeddings'> {\n  /**\n   * Generate an embedding for a single text\n   * Local providers don't need apiKey parameter\n   *\n   * @param text The text to embed\n   * @returns The embedding result\n   */\n  generateEmbedding(text: string): EmbeddingResult;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings(texts: string[]): EmbeddingResult[];\n\n  /**\n   * Fit the vocabulary on a corpus of documents\n   *\n   * This method analyzes the corpus to build vocabulary, calculate IDF weights,\n   * and other statistics needed for embedding generation.\n   *\n   * @param documents Array of text documents to analyze\n   */\n  fitCorpus(documents: string[]): void;\n\n  /**\n   * Check if the vocabulary has been fitted\n   *\n   * @returns True if fitCorpus has been called with documents\n   */\n  isFitted(): boolean;\n\n  /**\n   * Load state from a serialized representation\n   *\n   * @param state The serialized provider state\n   */\n  loadState(state: LocalEmbeddingProviderState): void;\n\n  /**\n   * Get the current state for serialization\n   *\n   * @returns The provider state, or null if not fitted\n   */\n  getState(): LocalEmbeddingProviderState | null;\n\n  /**\n   * Get the vocabulary size\n   *\n   * @returns Number of terms in the vocabulary\n   */\n  getVocabularySize(): number;\n\n  /**\n   * Get the embedding dimensions\n   *\n   * @returns Number of dimensions in generated embeddings\n   */\n  getDimensions(): number;\n}\n\n/**\n * Type guard to check if a provider is a local embedding provider\n */\nexport function isLocalEmbeddingProvider(\n  provider: EmbeddingProvider | LocalEmbeddingProvider\n): provider is LocalEmbeddingProvider {\n  return 'fitCorpus' in provider && 'loadState' in provider && 'getState' in provider;\n}\n"]}
+{"version":3,"sources":["../../src/providers/embedding.ts"],"names":[],"mappings":";;;AAyLO,SAAS,yBACd,QAAA,EACoC;AACpC,EAAA,OAAO,WAAA,IAAe,QAAA,IAAY,WAAA,IAAe,QAAA,IAAY,UAAA,IAAc,QAAA;AAC7E","file":"index.js","sourcesContent":["/**\n * Embedding Provider — Shape 3: Text -> Vector\n *\n * Send text to an embedding model, receive a numeric vector representation.\n * Used for semantic search, RAG, and similarity matching.\n *\n * @module @quilltap/plugin-types/providers/embedding\n */\n\n/**\n * Result of an embedding operation\n */\nexport interface EmbeddingResult {\n  /** The embedding vector (array of floating point numbers) */\n  embedding: number[];\n  /** The model used to generate the embedding */\n  model: string;\n  /** Number of dimensions in the embedding vector */\n  dimensions: number;\n  /** Token usage information (if available) */\n  usage?: {\n    promptTokens: number;\n    totalTokens: number;\n    cost?: number;\n  };\n}\n\n/**\n * Options for embedding generation\n */\nexport interface EmbeddingOptions {\n  /** Desired dimensions for the embedding (if model supports variable dimensions) */\n  dimensions?: number;\n}\n\n/**\n * Embedding provider interface — Shape 3: Text -> Vector\n *\n * Sends text to an embedding model and receives a numeric vector\n * representation for use in semantic search, RAG, and similarity matching.\n */\nexport interface EmbeddingProvider {\n  /**\n   * Generate an embedding for a single text\n   *\n   * @param text The text to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns The embedding result\n   */\n  generateEmbedding(\n    text: string,\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult>;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings?(\n    texts: string[],\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult[]>;\n\n  /**\n   * Get available embedding models\n   *\n   * @param apiKey The API key for authentication\n   * @returns Array of model IDs\n   */\n  getAvailableModels?(apiKey: string): Promise<string[]>;\n\n  /**\n   * Check if the provider is available and properly configured\n   *\n   * @param apiKey Optional API key to validate\n   * @returns True if the provider is ready to use\n   */\n  isAvailable?(apiKey?: string): Promise<boolean>;\n}\n\n/**\n * Serializable state for local embedding providers\n *\n * Used by providers like TF-IDF that maintain vocabulary state\n */\nexport interface LocalEmbeddingProviderState {\n  /** The vocabulary as an array of [term, index] pairs */\n  vocabulary: [string, number][];\n  /** The IDF (Inverse Document Frequency) weights */\n  idf: number[];\n  /** Average document length across the corpus */\n  avgDocLength: number;\n  /** Size of the vocabulary */\n  vocabularySize: number;\n  /** Whether bigrams are included in the vocabulary */\n  includeBigrams: boolean;\n  /** Timestamp when the vocabulary was fitted */\n  fittedAt: string;\n}\n\n/**\n * Local embedding provider interface\n *\n * Extended interface for local/offline embedding providers that\n * maintain vocabulary state (like TF-IDF). These providers don't\n * require API keys and can work entirely offline.\n */\nexport interface LocalEmbeddingProvider extends Omit<EmbeddingProvider, 'generateEmbedding' | 'generateBatchEmbeddings'> {\n  /**\n   * Generate an embedding for a single text\n   * Local providers don't need apiKey parameter\n   *\n   * @param text The text to embed\n   * @returns The embedding result\n   */\n  generateEmbedding(text: string): EmbeddingResult;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings(texts: string[]): EmbeddingResult[];\n\n  /**\n   * Fit the vocabulary on a corpus of documents\n   *\n   * This method analyzes the corpus to build vocabulary, calculate IDF weights,\n   * and other statistics needed for embedding generation.\n   *\n   * @param documents Array of text documents to analyze\n   */\n  fitCorpus(documents: string[]): void;\n\n  /**\n   * Check if the vocabulary has been fitted\n   *\n   * @returns True if fitCorpus has been called with documents\n   */\n  isFitted(): boolean;\n\n  /**\n   * Load state from a serialized representation\n   *\n   * @param state The serialized provider state\n   */\n  loadState(state: LocalEmbeddingProviderState): void;\n\n  /**\n   * Get the current state for serialization\n   *\n   * @returns The provider state, or null if not fitted\n   */\n  getState(): LocalEmbeddingProviderState | null;\n\n  /**\n   * Get the vocabulary size\n   *\n   * @returns Number of terms in the vocabulary\n   */\n  getVocabularySize(): number;\n\n  /**\n   * Get the embedding dimensions\n   *\n   * @returns Number of dimensions in generated embeddings\n   */\n  getDimensions(): number;\n}\n\n/**\n * Type guard to check if a provider is a local embedding provider\n */\nexport function isLocalEmbeddingProvider(\n  provider: EmbeddingProvider | LocalEmbeddingProvider\n): provider is LocalEmbeddingProvider {\n  return 'fitCorpus' in provider && 'loadState' in provider && 'getState' in provider;\n}\n"]}

package/dist/llm/index.mjs

@@ -1,4 +1,4 @@
-// src/llm/embeddings.ts
+// src/providers/embedding.ts
 function isLocalEmbeddingProvider(provider) {
   return "fitCorpus" in provider && "loadState" in provider && "getState" in provider;
 }

package/dist/llm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/llm/embeddings.ts"],"names":[],"mappings":";AAyLO,SAAS,yBACd,QAAA,EACoC;AACpC,EAAA,OAAO,WAAA,IAAe,QAAA,IAAY,WAAA,IAAe,QAAA,IAAY,UAAA,IAAc,QAAA;AAC7E","file":"index.mjs","sourcesContent":["/**\n * Embedding Provider Types for Quilltap plugin development\n *\n * Defines interfaces for embedding providers that can be implemented\n * by plugins to provide text-to-vector embedding functionality.\n *\n * @module @quilltap/plugin-types/llm/embeddings\n */\n\n/**\n * Result of an embedding operation\n */\nexport interface EmbeddingResult {\n  /** The embedding vector (array of floating point numbers) */\n  embedding: number[];\n  /** The model used to generate the embedding */\n  model: string;\n  /** Number of dimensions in the embedding vector */\n  dimensions: number;\n  /** Token usage information (if available) */\n  usage?: {\n    promptTokens: number;\n    totalTokens: number;\n    cost?: number;\n  };\n}\n\n/**\n * Options for embedding generation\n */\nexport interface EmbeddingOptions {\n  /** Desired dimensions for the embedding (if model supports variable dimensions) */\n  dimensions?: number;\n}\n\n/**\n * Standard embedding provider interface\n *\n * This is the base interface for all embedding providers that use\n * external APIs (OpenAI, Ollama, OpenRouter, etc.)\n */\nexport interface EmbeddingProvider {\n  /**\n   * Generate an embedding for a single text\n   *\n   * @param text The text to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns The embedding result\n   */\n  generateEmbedding(\n    text: string,\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult>;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings?(\n    texts: string[],\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult[]>;\n\n  /**\n   * Get available embedding models\n   *\n   * @param apiKey The API key for authentication\n   * @returns Array of model IDs\n   */\n  getAvailableModels?(apiKey: string): Promise<string[]>;\n\n  /**\n   * Check if the provider is available and properly configured\n   *\n   * @param apiKey Optional API key to validate\n   * @returns True if the provider is ready to use\n   */\n  isAvailable?(apiKey?: string): Promise<boolean>;\n}\n\n/**\n * Serializable state for local embedding providers\n *\n * Used by providers like TF-IDF that maintain vocabulary state\n */\nexport interface LocalEmbeddingProviderState {\n  /** The vocabulary as an array of [term, index] pairs */\n  vocabulary: [string, number][];\n  /** The IDF (Inverse Document Frequency) weights */\n  idf: number[];\n  /** Average document length across the corpus */\n  avgDocLength: number;\n  /** Size of the vocabulary */\n  vocabularySize: number;\n  /** Whether bigrams are included in the vocabulary */\n  includeBigrams: boolean;\n  /** Timestamp when the vocabulary was fitted */\n  fittedAt: string;\n}\n\n/**\n * Local embedding provider interface\n *\n * Extended interface for local/offline embedding providers that\n * maintain vocabulary state (like TF-IDF). These providers don't\n * require API keys and can work entirely offline.\n */\nexport interface LocalEmbeddingProvider extends Omit<EmbeddingProvider, 'generateEmbedding' | 'generateBatchEmbeddings'> {\n  /**\n   * Generate an embedding for a single text\n   * Local providers don't need apiKey parameter\n   *\n   * @param text The text to embed\n   * @returns The embedding result\n   */\n  generateEmbedding(text: string): EmbeddingResult;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings(texts: string[]): EmbeddingResult[];\n\n  /**\n   * Fit the vocabulary on a corpus of documents\n   *\n   * This method analyzes the corpus to build vocabulary, calculate IDF weights,\n   * and other statistics needed for embedding generation.\n   *\n   * @param documents Array of text documents to analyze\n   */\n  fitCorpus(documents: string[]): void;\n\n  /**\n   * Check if the vocabulary has been fitted\n   *\n   * @returns True if fitCorpus has been called with documents\n   */\n  isFitted(): boolean;\n\n  /**\n   * Load state from a serialized representation\n   *\n   * @param state The serialized provider state\n   */\n  loadState(state: LocalEmbeddingProviderState): void;\n\n  /**\n   * Get the current state for serialization\n   *\n   * @returns The provider state, or null if not fitted\n   */\n  getState(): LocalEmbeddingProviderState | null;\n\n  /**\n   * Get the vocabulary size\n   *\n   * @returns Number of terms in the vocabulary\n   */\n  getVocabularySize(): number;\n\n  /**\n   * Get the embedding dimensions\n   *\n   * @returns Number of dimensions in generated embeddings\n   */\n  getDimensions(): number;\n}\n\n/**\n * Type guard to check if a provider is a local embedding provider\n */\nexport function isLocalEmbeddingProvider(\n  provider: EmbeddingProvider | LocalEmbeddingProvider\n): provider is LocalEmbeddingProvider {\n  return 'fitCorpus' in provider && 'loadState' in provider && 'getState' in provider;\n}\n"]}
+{"version":3,"sources":["../../src/providers/embedding.ts"],"names":[],"mappings":";AAyLO,SAAS,yBACd,QAAA,EACoC;AACpC,EAAA,OAAO,WAAA,IAAe,QAAA,IAAY,WAAA,IAAe,QAAA,IAAY,UAAA,IAAc,QAAA;AAC7E","file":"index.mjs","sourcesContent":["/**\n * Embedding Provider — Shape 3: Text -> Vector\n *\n * Send text to an embedding model, receive a numeric vector representation.\n * Used for semantic search, RAG, and similarity matching.\n *\n * @module @quilltap/plugin-types/providers/embedding\n */\n\n/**\n * Result of an embedding operation\n */\nexport interface EmbeddingResult {\n  /** The embedding vector (array of floating point numbers) */\n  embedding: number[];\n  /** The model used to generate the embedding */\n  model: string;\n  /** Number of dimensions in the embedding vector */\n  dimensions: number;\n  /** Token usage information (if available) */\n  usage?: {\n    promptTokens: number;\n    totalTokens: number;\n    cost?: number;\n  };\n}\n\n/**\n * Options for embedding generation\n */\nexport interface EmbeddingOptions {\n  /** Desired dimensions for the embedding (if model supports variable dimensions) */\n  dimensions?: number;\n}\n\n/**\n * Embedding provider interface — Shape 3: Text -> Vector\n *\n * Sends text to an embedding model and receives a numeric vector\n * representation for use in semantic search, RAG, and similarity matching.\n */\nexport interface EmbeddingProvider {\n  /**\n   * Generate an embedding for a single text\n   *\n   * @param text The text to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns The embedding result\n   */\n  generateEmbedding(\n    text: string,\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult>;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @param model The model to use\n   * @param apiKey The API key for authentication\n   * @param options Optional configuration\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings?(\n    texts: string[],\n    model: string,\n    apiKey: string,\n    options?: EmbeddingOptions\n  ): Promise<EmbeddingResult[]>;\n\n  /**\n   * Get available embedding models\n   *\n   * @param apiKey The API key for authentication\n   * @returns Array of model IDs\n   */\n  getAvailableModels?(apiKey: string): Promise<string[]>;\n\n  /**\n   * Check if the provider is available and properly configured\n   *\n   * @param apiKey Optional API key to validate\n   * @returns True if the provider is ready to use\n   */\n  isAvailable?(apiKey?: string): Promise<boolean>;\n}\n\n/**\n * Serializable state for local embedding providers\n *\n * Used by providers like TF-IDF that maintain vocabulary state\n */\nexport interface LocalEmbeddingProviderState {\n  /** The vocabulary as an array of [term, index] pairs */\n  vocabulary: [string, number][];\n  /** The IDF (Inverse Document Frequency) weights */\n  idf: number[];\n  /** Average document length across the corpus */\n  avgDocLength: number;\n  /** Size of the vocabulary */\n  vocabularySize: number;\n  /** Whether bigrams are included in the vocabulary */\n  includeBigrams: boolean;\n  /** Timestamp when the vocabulary was fitted */\n  fittedAt: string;\n}\n\n/**\n * Local embedding provider interface\n *\n * Extended interface for local/offline embedding providers that\n * maintain vocabulary state (like TF-IDF). These providers don't\n * require API keys and can work entirely offline.\n */\nexport interface LocalEmbeddingProvider extends Omit<EmbeddingProvider, 'generateEmbedding' | 'generateBatchEmbeddings'> {\n  /**\n   * Generate an embedding for a single text\n   * Local providers don't need apiKey parameter\n   *\n   * @param text The text to embed\n   * @returns The embedding result\n   */\n  generateEmbedding(text: string): EmbeddingResult;\n\n  /**\n   * Generate embeddings for multiple texts in a batch\n   *\n   * @param texts Array of texts to embed\n   * @returns Array of embedding results\n   */\n  generateBatchEmbeddings(texts: string[]): EmbeddingResult[];\n\n  /**\n   * Fit the vocabulary on a corpus of documents\n   *\n   * This method analyzes the corpus to build vocabulary, calculate IDF weights,\n   * and other statistics needed for embedding generation.\n   *\n   * @param documents Array of text documents to analyze\n   */\n  fitCorpus(documents: string[]): void;\n\n  /**\n   * Check if the vocabulary has been fitted\n   *\n   * @returns True if fitCorpus has been called with documents\n   */\n  isFitted(): boolean;\n\n  /**\n   * Load state from a serialized representation\n   *\n   * @param state The serialized provider state\n   */\n  loadState(state: LocalEmbeddingProviderState): void;\n\n  /**\n   * Get the current state for serialization\n   *\n   * @returns The provider state, or null if not fitted\n   */\n  getState(): LocalEmbeddingProviderState | null;\n\n  /**\n   * Get the vocabulary size\n   *\n   * @returns Number of terms in the vocabulary\n   */\n  getVocabularySize(): number;\n\n  /**\n   * Get the embedding dimensions\n   *\n   * @returns Number of dimensions in generated embeddings\n   */\n  getDimensions(): number;\n}\n\n/**\n * Type guard to check if a provider is a local embedding provider\n */\nexport function isLocalEmbeddingProvider(\n  provider: EmbeddingProvider | LocalEmbeddingProvider\n): provider is LocalEmbeddingProvider {\n  return 'fitCorpus' in provider && 'loadState' in provider && 'getState' in provider;\n}\n"]}

package/dist/plugins/index.d.mts

@@ -1,2 +1,3 @@
-export { $ as AnnotationButton, A as AttachmentSupport, a as ColorPalette, a0 as DialogueDetection, E as Effects, b as EmbeddedFont, c as EmbeddingModelInfo, F as FontDefinition, I as IconProps, d as ImageGenerationModelInfo, e as ImageProviderConstraints, g as InstalledPluginInfo, L as LLMProviderPlugin, h as ModelInfo, i as ModerationCategoryResult, a1 as ModerationProviderConfig, j as ModerationProviderConfigRequirements, k as ModerationProviderMetadata, l as ModerationProviderPlugin, m as ModerationProviderPluginExport, n as ModerationResult, P as PluginAuthor, o as PluginCapability, p as PluginCategory, q as PluginCompatibility, s as PluginManifest, t as PluginPermissions, u as PluginStatus, v as ProviderCapabilities, w as ProviderConfig, x as ProviderConfigRequirements, y as ProviderMetadata, z as ProviderPluginExport, a2 as RenderingPattern, R as RoleplayTemplateConfig, B as RoleplayTemplateMetadata, D as RoleplayTemplatePlugin, G as RoleplayTemplatePluginExport, S as SearchOutput, H as SearchProviderConfig, J as SearchProviderConfigRequirements, K as SearchProviderMetadata, N as SearchProviderPlugin, O as SearchProviderPluginExport, Q as SearchResult, T as Spacing, V as ThemeMetadata, W as ThemePlugin, X as ThemePluginExport, Y as ThemeTokens, _ as Typography } from '../index-QQUNtK0j.mjs';
+export { a4 as AnnotationButton, A as AttachmentSupport, a as ColorPalette, a5 as DialogueDetection, E as Effects, b as EmbeddedFont, c as EmbeddingModelInfo, F as FontDefinition, I as IconProps, d as ImageGenerationModelInfo, e as ImageProviderConstraints, g as InstalledPluginInfo, L as LLMProviderPlugin, h as ModelInfo, i as ModerationCategoryResult, a6 as ModerationProviderConfig, j as ModerationProviderConfigRequirements, k as ModerationProviderMetadata, l as ModerationProviderPlugin, m as ModerationProviderPluginExport, n as ModerationResult, P as PluginAuthor, o as PluginCapability, p as PluginCategory, q as PluginCompatibility, s as PluginManifest, t as PluginPermissions, u as PluginStatus, v as ProviderCapabilities, w as ProviderConfig, x as ProviderConfigRequirements, y as ProviderMetadata, z as ProviderPluginExport, a7 as RenderingPattern, R as RoleplayTemplateConfig, B as RoleplayTemplateMetadata, D as RoleplayTemplatePlugin, G as RoleplayTemplatePluginExport, S as ScoringProviderConfigRequirements, H as ScoringProviderMetadata, J as ScoringProviderPlugin, K as ScoringProviderPluginExport, N as SearchOutput, O as SearchProviderConfig, Q as SearchProviderConfigRequirements, T as SearchProviderMetadata, U as SearchProviderPlugin, V as SearchProviderPluginExport, W as SearchResult, X as Spacing, Z as TextProviderPlugin, _ as ThemeMetadata, $ as ThemePlugin, a0 as ThemePluginExport, a1 as ThemeTokens, a3 as Typography } from '../index-DtW7izgw.mjs';
 import '../llm/index.mjs';
+import '../providers/index.mjs';

package/dist/plugins/index.d.ts

@@ -1,2 +1,3 @@
-export { $ as AnnotationButton, A as AttachmentSupport, a as ColorPalette, a0 as DialogueDetection, E as Effects, b as EmbeddedFont, c as EmbeddingModelInfo, F as FontDefinition, I as IconProps, d as ImageGenerationModelInfo, e as ImageProviderConstraints, g as InstalledPluginInfo, L as LLMProviderPlugin, h as ModelInfo, i as ModerationCategoryResult, a1 as ModerationProviderConfig, j as ModerationProviderConfigRequirements, k as ModerationProviderMetadata, l as ModerationProviderPlugin, m as ModerationProviderPluginExport, n as ModerationResult, P as PluginAuthor, o as PluginCapability, p as PluginCategory, q as PluginCompatibility, s as PluginManifest, t as PluginPermissions, u as PluginStatus, v as ProviderCapabilities, w as ProviderConfig, x as ProviderConfigRequirements, y as ProviderMetadata, z as ProviderPluginExport, a2 as RenderingPattern, R as RoleplayTemplateConfig, B as RoleplayTemplateMetadata, D as RoleplayTemplatePlugin, G as RoleplayTemplatePluginExport, S as SearchOutput, H as SearchProviderConfig, J as SearchProviderConfigRequirements, K as SearchProviderMetadata, N as SearchProviderPlugin, O as SearchProviderPluginExport, Q as SearchResult, T as Spacing, V as ThemeMetadata, W as ThemePlugin, X as ThemePluginExport, Y as ThemeTokens, _ as Typography } from '../index-FCJXfnL_.js';
+export { a4 as AnnotationButton, A as AttachmentSupport, a as ColorPalette, a5 as DialogueDetection, E as Effects, b as EmbeddedFont, c as EmbeddingModelInfo, F as FontDefinition, I as IconProps, d as ImageGenerationModelInfo, e as ImageProviderConstraints, g as InstalledPluginInfo, L as LLMProviderPlugin, h as ModelInfo, i as ModerationCategoryResult, a6 as ModerationProviderConfig, j as ModerationProviderConfigRequirements, k as ModerationProviderMetadata, l as ModerationProviderPlugin, m as ModerationProviderPluginExport, n as ModerationResult, P as PluginAuthor, o as PluginCapability, p as PluginCategory, q as PluginCompatibility, s as PluginManifest, t as PluginPermissions, u as PluginStatus, v as ProviderCapabilities, w as ProviderConfig, x as ProviderConfigRequirements, y as ProviderMetadata, z as ProviderPluginExport, a7 as RenderingPattern, R as RoleplayTemplateConfig, B as RoleplayTemplateMetadata, D as RoleplayTemplatePlugin, G as RoleplayTemplatePluginExport, S as ScoringProviderConfigRequirements, H as ScoringProviderMetadata, J as ScoringProviderPlugin, K as ScoringProviderPluginExport, N as SearchOutput, O as SearchProviderConfig, Q as SearchProviderConfigRequirements, T as SearchProviderMetadata, U as SearchProviderPlugin, V as SearchProviderPluginExport, W as SearchResult, X as Spacing, Z as TextProviderPlugin, _ as ThemeMetadata, $ as ThemePlugin, a0 as ThemePluginExport, a1 as ThemeTokens, a3 as Typography } from '../index-BXJLgAuZ.js';
 import '../llm/index.js';
+import '../providers/index.js';

package/dist/providers/index.d.mts

@@ -0,0 +1,132 @@
+export { AttachmentResults, CacheUsage, EmbeddingOptions, EmbeddingProvider, EmbeddingResult, FileAttachment, GeneratedImage, ImageGenParams, ImageGenResponse, ImageGenProvider as ImageProvider, JSONSchemaDefinition, LLMMessage, LLMParams, LLMResponse, LocalEmbeddingProvider, LocalEmbeddingProviderState, ModelMetadata, ModelWarning, ModelWarningLevel, ResponseFormat, StreamChunk, LLMProvider as TextProvider, TokenUsage, isLocalEmbeddingProvider } from '../llm/index.mjs';
+
+/**
+ * Scoring Provider — Shape 4: Text + Candidates -> Scores
+ *
+ * Send content (and optionally candidates or labels) to a scoring model,
+ * receive scored categories or ranked results. This generalizes content
+ * moderation, reranking, and classification into a single interface shape.
+ *
+ * ## Supported Tasks
+ *
+ * ### Moderation (implemented)
+ * Score content against safety categories. The provider returns per-category
+ * flagged/score pairs (e.g., "violence": 0.95, "hate": 0.02).
+ *
+ * ```typescript
+ * const result = await provider.score({
+ *   content: 'some user message',
+ *   task: 'moderation',
+ * }, apiKey);
+ * // result.flagged = true, result.categories = [{ category: 'violence', flagged: true, score: 0.95 }, ...]
+ * ```
+ *
+ * ### Reranking (future)
+ * Given a query and candidate passages, score each passage by relevance.
+ * Uses `candidates` field to pass the passages to rank.
+ *
+ * ```typescript
+ * const result = await provider.score({
+ *   content: 'What is the capital of France?',
+ *   task: 'reranking',
+ *   candidates: ['Paris is the capital of France.', 'London is in England.', ...],
+ * }, apiKey);
+ * // result.categories = [{ category: '0', score: 0.98 }, { category: '1', score: 0.12 }, ...]
+ * ```
+ *
+ * ### Classification (future)
+ * Classify content into one or more predefined labels.
+ * Uses `labels` field to define the classification categories.
+ *
+ * ```typescript
+ * const result = await provider.score({
+ *   content: 'I love this product!',
+ *   task: 'classification',
+ *   labels: ['positive', 'negative', 'neutral'],
+ * }, apiKey);
+ * // result.categories = [{ category: 'positive', flagged: true, score: 0.92 }, ...]
+ * ```
+ *
+ * @module @quilltap/plugin-types/providers/scoring
+ */
+/**
+ * The type of scoring task to perform
+ */
+type ScoringTask = 'moderation' | 'reranking' | 'classification';
+/**
+ * Input for a scoring operation
+ */
+interface ScoringInput {
+    /** The primary text to score */
+    content: string;
+    /** The scoring task type */
+    task: ScoringTask;
+    /**
+     * Candidate passages for reranking.
+     * Each candidate is scored against the content (used as query).
+     */
+    candidates?: string[];
+    /**
+     * Label set for classification.
+     * Content is classified into these categories.
+     */
+    labels?: string[];
+    /** Task-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * A single category/label score
+ */
+interface CategoryScore {
+    /** Category or label name (e.g., 'violence', 'positive', or candidate index) */
+    category: string;
+    /** Whether this category was triggered/flagged */
+    flagged: boolean;
+    /** Confidence score (0-1) */
+    score: number;
+}
+/**
+ * Result from a scoring operation
+ */
+interface ScoringResult {
+    /** Overall flagged status (for moderation) or top match (for classification) */
+    flagged: boolean;
+    /** Per-category/label breakdown with scores */
+    categories: CategoryScore[];
+    /** Which task produced this result */
+    task: ScoringTask;
+}
+/**
+ * Scoring provider interface — Shape 4: Text + Candidates -> Scores
+ *
+ * Sends content to a scoring model and receives scored categories,
+ * ranked results, or classification labels. Generalizes moderation,
+ * reranking, and classification into a single provider shape.
+ */
+interface ScoringProvider {
+    /**
+     * Score content according to the specified task
+     *
+     * @param input The scoring input with content, task type, and optional candidates/labels
+     * @param apiKey The API key for authentication
+     * @param baseUrl Optional base URL for the scoring API
+     * @returns Scored results with per-category breakdown
+     */
+    score(input: ScoringInput, apiKey: string, baseUrl?: string): Promise<ScoringResult>;
+    /**
+     * Get the scoring tasks this provider supports
+     *
+     * @returns Array of supported task types
+     */
+    getSupportedTasks(): ScoringTask[];
+    /**
+     * Validate an API key for this provider (optional)
+     *
+     * @param apiKey The API key to validate
+     * @param baseUrl Optional base URL
+     * @returns True if valid
+     */
+    validateApiKey?(apiKey: string, baseUrl?: string): Promise<boolean>;
+}
+
+export type { CategoryScore, ScoringInput, ScoringProvider, ScoringResult, ScoringTask };