@quilltap/plugin-types 1.17.3 → 2.0.0

package/dist/providers/index.d.ts

@@ -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.js';
+
+/**
+ * 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 };

package/dist/providers/index.js

@@ -0,0 +1,10 @@
+'use strict';
+
+// src/providers/embedding.ts
+function isLocalEmbeddingProvider(provider) {
+  return "fitCorpus" in provider && "loadState" in provider && "getState" in provider;
+}
+
+exports.isLocalEmbeddingProvider = isLocalEmbeddingProvider;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -0,0 +1 @@
+{"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/providers/index.mjs

@@ -0,0 +1,8 @@
+// src/providers/embedding.ts
+function isLocalEmbeddingProvider(provider) {
+  return "fitCorpus" in provider && "loadState" in provider && "getState" in provider;
+}
+
+export { isLocalEmbeddingProvider };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/providers/index.mjs.map

@@ -0,0 +1 @@
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quilltap/plugin-types",
-  "version": "1.17.3",
+  "version": "2.0.0",
   "description": "Type definitions for Quilltap plugin development",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,11 @@
       "types": "./dist/common/index.d.ts",
       "import": "./dist/common/index.mjs",
       "require": "./dist/common/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.mjs",
+      "require": "./dist/providers/index.js"
     }
   },
   "files": [