llmist 2.3.0 → 2.4.0

package/dist/{mock-stream-wRfUqXx4.d.ts → mock-stream-BQcC2VCP.d.ts}

@@ -1,6 +1,218 @@
 import { ZodTypeAny } from 'zod';
 import { Logger, ILogObj } from 'tslog';
 
+/**
+ * Types and interfaces for multimodal generation (image, speech).
+ *
+ * These types support non-token-based billing models where costs are calculated
+ * per-image, per-character, or per-second rather than per-token.
+ */
+/**
+ * Options for image generation requests.
+ */
+interface ImageGenerationOptions {
+    /** Model to use (e.g., "dall-e-3", "imagen-3.0-generate-002") */
+    model: string;
+    /** Text prompt describing the desired image */
+    prompt: string;
+    /**
+     * Image size/dimensions.
+     * - OpenAI: "1024x1024", "1024x1792", "1792x1024"
+     * - Gemini: "1:1", "3:4", "4:3", "9:16", "16:9"
+     */
+    size?: string;
+    /**
+     * Image quality level.
+     * - OpenAI: "standard", "hd"
+     */
+    quality?: string;
+    /**
+     * Number of images to generate.
+     * Note: DALL-E 3 only supports n=1
+     */
+    n?: number;
+    /**
+     * Response format for the generated image.
+     * - "url": Returns a URL to the image (expires after ~1 hour)
+     * - "b64_json": Returns base64-encoded image data
+     */
+    responseFormat?: "url" | "b64_json";
+}
+/**
+ * A single generated image.
+ */
+interface GeneratedImage {
+    /** URL to the generated image (if responseFormat is "url") */
+    url?: string;
+    /** Base64-encoded image data (if responseFormat is "b64_json") */
+    b64Json?: string;
+    /** Revised prompt (if the model modified the original prompt) */
+    revisedPrompt?: string;
+}
+/**
+ * Usage information for image generation.
+ */
+interface ImageUsage {
+    /** Number of images generated */
+    imagesGenerated: number;
+    /** Size of generated images */
+    size: string;
+    /** Quality level used */
+    quality: string;
+}
+/**
+ * Result of an image generation request.
+ */
+interface ImageGenerationResult {
+    /** Array of generated images */
+    images: GeneratedImage[];
+    /** Model used for generation */
+    model: string;
+    /** Usage information */
+    usage: ImageUsage;
+    /** Estimated cost in USD */
+    cost?: number;
+}
+/**
+ * Available audio formats for speech generation.
+ */
+type AudioFormat = "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
+/**
+ * Options for speech (TTS) generation requests.
+ */
+interface SpeechGenerationOptions {
+    /** Model to use (e.g., "tts-1", "tts-1-hd") */
+    model: string;
+    /** Text to convert to speech */
+    input: string;
+    /**
+     * Voice to use for generation.
+     * - OpenAI: "alloy", "echo", "fable", "onyx", "nova", "shimmer"
+     * - Gemini: "Zephyr", "Puck", "Charon", "Kore", etc.
+     */
+    voice: string;
+    /** Output audio format (default: "mp3") */
+    responseFormat?: AudioFormat;
+    /**
+     * Speed of the generated audio.
+     * Range: 0.25 to 4.0 (default: 1.0)
+     */
+    speed?: number;
+}
+/**
+ * Usage information for speech generation.
+ */
+interface SpeechUsage {
+    /** Number of characters processed */
+    characterCount: number;
+}
+/**
+ * Result of a speech generation request.
+ */
+interface SpeechGenerationResult {
+    /** Generated audio data */
+    audio: ArrayBuffer;
+    /** Model used for generation */
+    model: string;
+    /** Usage information */
+    usage: SpeechUsage;
+    /** Estimated cost in USD */
+    cost?: number;
+    /** Audio format of the result */
+    format: AudioFormat;
+}
+/**
+ * Pricing structure for image models.
+ * Maps size -> quality -> price per image.
+ */
+interface ImageModelPricing {
+    /** Simple per-image price (for models with uniform pricing) */
+    perImage?: number;
+    /**
+     * Size-based pricing.
+     * Maps size (e.g., "1024x1024") to quality-based pricing or flat price.
+     */
+    bySize?: Record<string, Record<string, number> | number>;
+}
+/**
+ * Pricing structure for speech models.
+ * Supports both character-based pricing (tts-1, tts-1-hd) and
+ * token-based pricing (gpt-4o-mini-tts).
+ */
+interface SpeechModelPricing {
+    /** Price per character (e.g., 0.000015 for $15 per 1M chars) - for tts-1, tts-1-hd */
+    perCharacter?: number;
+    /** Token-based pricing (for gpt-4o-mini-tts) */
+    perInputToken?: number;
+    perAudioOutputToken?: number;
+    /** Approximate cost per minute of generated audio (for estimation) */
+    perMinute?: number;
+}
+/**
+ * Specification for an image generation model.
+ */
+interface ImageModelSpec {
+    /** Provider identifier (e.g., "openai", "gemini") */
+    provider: string;
+    /** Model identifier */
+    modelId: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Pricing information */
+    pricing: ImageModelPricing;
+    /** Supported image sizes */
+    supportedSizes: string[];
+    /** Supported quality levels (optional) */
+    supportedQualities?: string[];
+    /** Maximum images per request */
+    maxImages: number;
+    /** Default size if not specified */
+    defaultSize?: string;
+    /** Default quality if not specified */
+    defaultQuality?: string;
+    /** Additional feature flags */
+    features?: {
+        /** Supports conversational/multi-turn image editing */
+        conversational?: boolean;
+        /** Optimized for text rendering in images */
+        textRendering?: boolean;
+        /** Supports transparency */
+        transparency?: boolean;
+    };
+}
+/**
+ * Specification for a speech generation model.
+ */
+interface SpeechModelSpec {
+    /** Provider identifier (e.g., "openai", "gemini") */
+    provider: string;
+    /** Model identifier */
+    modelId: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Pricing information */
+    pricing: SpeechModelPricing;
+    /** Available voice options */
+    voices: string[];
+    /** Supported audio formats */
+    formats: AudioFormat[];
+    /** Maximum input text length (characters) */
+    maxInputLength: number;
+    /** Default voice if not specified */
+    defaultVoice?: string;
+    /** Default format if not specified */
+    defaultFormat?: AudioFormat;
+    /** Additional feature flags */
+    features?: {
+        /** Supports multi-speaker output */
+        multiSpeaker?: boolean;
+        /** Number of supported languages */
+        languages?: number;
+        /** Supports voice instructions/steering */
+        voiceInstructions?: boolean;
+    };
+}
+
 /**
  * Model Catalog Types
  *
@@ -743,6 +955,26 @@ type TextOnlyAction = {
  * }
  * ```
  */
+/**
+ * Image generation namespace with automatic cost reporting.
+ */
+interface CostReportingImageNamespace {
+    /**
+     * Generate images from a text prompt.
+     * Costs are automatically reported to the execution context.
+     */
+    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
+}
+/**
+ * Speech generation namespace with automatic cost reporting.
+ */
+interface CostReportingSpeechNamespace {
+    /**
+     * Generate speech audio from text.
+     * Costs are automatically reported to the execution context.
+     */
+    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+}
 interface CostReportingLLMist {
     /**
      * Quick completion - returns final text response.
@@ -763,6 +995,16 @@ interface CostReportingLLMist {
      * Access to model registry for cost estimation.
      */
     readonly modelRegistry: ModelRegistry;
+    /**
+     * Image generation with automatic cost reporting.
+     * Costs are reported based on model and generation parameters.
+     */
+    readonly image: CostReportingImageNamespace;
+    /**
+     * Speech generation with automatic cost reporting.
+     * Costs are reported based on input length and model pricing.
+     */
+    readonly speech: CostReportingSpeechNamespace;
 }
 /**
  * Execution context provided to gadgets during execution.
@@ -1283,6 +1525,167 @@ interface ProviderAdapter {
      * @returns Promise resolving to the number of input tokens
      */
     countTokens?(messages: LLMMessage[], descriptor: ModelDescriptor, spec?: ModelSpec): Promise<number>;
+    /**
+     * Get image model specifications for this provider.
+     * Returns undefined if the provider doesn't support image generation.
+     */
+    getImageModelSpecs?(): ImageModelSpec[];
+    /**
+     * Check if this provider supports image generation for a given model.
+     * @param modelId - Model identifier (e.g., "dall-e-3")
+     */
+    supportsImageGeneration?(modelId: string): boolean;
+    /**
+     * Generate images from a text prompt.
+     * @param options - Image generation options
+     * @returns Promise resolving to the generation result with images and cost
+     */
+    generateImage?(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
+    /**
+     * Get speech model specifications for this provider.
+     * Returns undefined if the provider doesn't support speech generation.
+     */
+    getSpeechModelSpecs?(): SpeechModelSpec[];
+    /**
+     * Check if this provider supports speech generation for a given model.
+     * @param modelId - Model identifier (e.g., "tts-1", "tts-1-hd")
+     */
+    supportsSpeechGeneration?(modelId: string): boolean;
+    /**
+     * Generate speech audio from text.
+     * @param options - Speech generation options
+     * @returns Promise resolving to the generation result with audio and cost
+     */
+    generateSpeech?(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+}
+
+/**
+ * Image Generation Namespace
+ *
+ * Provides image generation methods.
+ *
+ * @example
+ * ```typescript
+ * const llmist = new LLMist();
+ *
+ * const result = await llmist.image.generate({
+ *   model: "dall-e-3",
+ *   prompt: "A cat in space",
+ *   size: "1024x1024",
+ *   quality: "hd",
+ * });
+ *
+ * console.log(result.images[0].url);
+ * console.log("Cost:", result.cost);
+ * ```
+ */
+
+declare class ImageNamespace {
+    private readonly adapters;
+    private readonly defaultProvider;
+    constructor(adapters: ProviderAdapter[], defaultProvider: string);
+    /**
+     * Generate images from a text prompt.
+     *
+     * @param options - Image generation options
+     * @returns Promise resolving to the generation result with images and cost
+     * @throws Error if the provider doesn't support image generation
+     */
+    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
+    /**
+     * List all available image generation models.
+     */
+    listModels(): ImageModelSpec[];
+    /**
+     * Check if a model is supported for image generation.
+     */
+    supportsModel(modelId: string): boolean;
+    private findImageAdapter;
+}
+
+/**
+ * Speech Generation Namespace
+ *
+ * Provides text-to-speech generation methods.
+ *
+ * @example
+ * ```typescript
+ * const llmist = new LLMist();
+ *
+ * const result = await llmist.speech.generate({
+ *   model: "tts-1-hd",
+ *   input: "Hello, world!",
+ *   voice: "nova",
+ * });
+ *
+ * // Save the audio
+ * fs.writeFileSync("output.mp3", Buffer.from(result.audio));
+ * console.log("Cost:", result.cost);
+ * ```
+ */
+
+declare class SpeechNamespace {
+    private readonly adapters;
+    private readonly defaultProvider;
+    constructor(adapters: ProviderAdapter[], defaultProvider: string);
+    /**
+     * Generate speech audio from text.
+     *
+     * @param options - Speech generation options
+     * @returns Promise resolving to the generation result with audio and cost
+     * @throws Error if the provider doesn't support speech generation
+     */
+    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+    /**
+     * List all available speech generation models.
+     */
+    listModels(): SpeechModelSpec[];
+    /**
+     * Check if a model is supported for speech generation.
+     */
+    supportsModel(modelId: string): boolean;
+    private findSpeechAdapter;
+}
+
+/**
+ * Text Generation Namespace
+ *
+ * Provides text completion and streaming methods.
+ * Replaces the deprecated llmist.complete() and llmist.stream() methods.
+ *
+ * @example
+ * ```typescript
+ * const llmist = new LLMist();
+ *
+ * // Complete
+ * const answer = await llmist.text.complete("What is 2+2?");
+ *
+ * // Stream
+ * for await (const chunk of llmist.text.stream("Tell me a story")) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+
+declare class TextNamespace {
+    private readonly client;
+    constructor(client: LLMist);
+    /**
+     * Generate a complete text response.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Complete text response
+     */
+    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    /**
+     * Stream text chunks.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Async generator yielding text chunks
+     */
+    stream(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
 }
 
 interface LLMistOptions {
@@ -1326,8 +1729,12 @@ interface LLMistOptions {
 }
 declare class LLMist {
     private readonly parser;
+    private readonly defaultProvider;
     readonly modelRegistry: ModelRegistry;
     private readonly adapters;
+    readonly text: TextNamespace;
+    readonly image: ImageNamespace;
+    readonly speech: SpeechNamespace;
     constructor();
     constructor(adapters: ProviderAdapter[]);
     constructor(adapters: ProviderAdapter[], defaultProvider: string);
@@ -3609,4 +4016,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type AfterLLMCallAction as $, type AgentHooks as A, BaseGadget as B, type CompactionStrategy as C, type ProviderAdapter as D, type ExecutionContext as E, type ModelDescriptor as F, GadgetRegistry as G, type HintTemplate as H, type IConversationManager as I, type ModelSpec as J, type LLMGenerationOptions as K, type LLMStream as L, MockProviderAdapter as M, type HistoryMessage as N, type TrailingMessage as O, type ParsedGadgetCall as P, type TrailingMessageContext as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, AgentBuilder as U, type EventHandlers as V, collectEvents as W, collectText as X, runWithHandlers as Y, type AfterGadgetExecutionAction as Z, type AfterGadgetExecutionControllerContext as _, type LLMStreamChunk as a, type AfterLLMCallControllerContext as a0, type AfterLLMErrorAction as a1, type AgentOptions as a2, type BeforeGadgetExecutionAction as a3, type BeforeLLMCallAction as a4, type ChunkInterceptorContext as a5, type Controllers as a6, type GadgetExecutionControllerContext as a7, type GadgetParameterInterceptorContext as a8, type GadgetResultInterceptorContext as a9, type PromptContext as aA, type PromptTemplate as aB, DEFAULT_HINTS as aC, DEFAULT_PROMPTS as aD, resolveHintTemplate as aE, resolvePromptTemplate as aF, resolveRulesTemplate as aG, type QuickOptions as aH, complete as aI, stream as aJ, type GadgetClass as aK, type GadgetOrClass as aL, type CostReportingLLMist as aM, type GadgetExecuteResult as aN, type TextOnlyAction as aO, type TextOnlyContext as aP, type TextOnlyCustomHandler as aQ, type TextOnlyGadgetConfig as aR, type TextOnlyHandler as aS, type TextOnlyStrategy as aT, type Interceptors as aa, type LLMCallControllerContext as ab, type LLMErrorControllerContext as ac, type MessageInterceptorContext as ad, type ObserveChunkContext as ae, type ObserveGadgetCompleteContext as af, type ObserveGadgetStartContext as ag, type ObserveLLMCallContext as ah, type ObserveLLMCompleteContext as ai, type ObserveLLMErrorContext as aj, type Observers as ak, type MessageTurn as al, type ObserveCompactionContext as am, DEFAULT_COMPACTION_CONFIG as an, DEFAULT_SUMMARIZATION_PROMPT as ao, type LLMistOptions as ap, type LLMRole as aq, LLMMessageBuilder as ar, type CostEstimate as as, type ModelFeatures as at, type ModelLimits as au, type ModelPricing as av, type ProviderIdentifier as aw, ModelIdentifierParser as ax, type HintContext as ay, type PromptConfig as az, type LLMMessage as b, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockMatcher as j, type MockMatcherContext as k, type MockOptions as l, mockLLM as m, type MockRegistration as n, type MockResponse as o, type MockStats as p, ModelRegistry as q, LLMist as r, type CompactionContext as s, type CompactionResult as t, type CompactionConfig as u, type CompactionEvent as v, type CompactionStats as w, type GadgetExecuteReturn as x, type GadgetExample as y, type GadgetExecutionResult as z };
+export { type EventHandlers as $, type AgentHooks as A, BaseGadget as B, type CompactionStrategy as C, type ProviderAdapter as D, type ExecutionContext as E, type ModelDescriptor as F, GadgetRegistry as G, type HintTemplate as H, type IConversationManager as I, type ModelSpec as J, type LLMGenerationOptions as K, type LLMStream as L, MockProviderAdapter as M, type ImageModelSpec as N, type ImageGenerationOptions as O, type ParsedGadgetCall as P, type ImageGenerationResult as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type SpeechModelSpec as U, type SpeechGenerationOptions as V, type SpeechGenerationResult as W, type HistoryMessage as X, type TrailingMessage as Y, type TrailingMessageContext as Z, AgentBuilder as _, type LLMStreamChunk as a, collectEvents as a0, collectText as a1, runWithHandlers as a2, type AfterGadgetExecutionAction as a3, type AfterGadgetExecutionControllerContext as a4, type AfterLLMCallAction as a5, type AfterLLMCallControllerContext as a6, type AfterLLMErrorAction as a7, type AgentOptions as a8, type BeforeGadgetExecutionAction as a9, type ModelLimits as aA, type ModelPricing as aB, type ProviderIdentifier as aC, ModelIdentifierParser as aD, type HintContext as aE, type PromptConfig as aF, type PromptContext as aG, type PromptTemplate as aH, DEFAULT_HINTS as aI, DEFAULT_PROMPTS as aJ, resolveHintTemplate as aK, resolvePromptTemplate as aL, resolveRulesTemplate as aM, type QuickOptions as aN, complete as aO, stream as aP, type GadgetClass as aQ, type GadgetOrClass as aR, type CostReportingLLMist as aS, type GadgetExecuteResult as aT, type TextOnlyAction as aU, type TextOnlyContext as aV, type TextOnlyCustomHandler as aW, type TextOnlyGadgetConfig as aX, type TextOnlyHandler as aY, type TextOnlyStrategy as aZ, type BeforeLLMCallAction as aa, type ChunkInterceptorContext as ab, type Controllers as ac, type GadgetExecutionControllerContext as ad, type GadgetParameterInterceptorContext as ae, type GadgetResultInterceptorContext as af, type Interceptors as ag, type LLMCallControllerContext as ah, type LLMErrorControllerContext as ai, type MessageInterceptorContext as aj, type ObserveChunkContext as ak, type ObserveGadgetCompleteContext as al, type ObserveGadgetStartContext as am, type ObserveLLMCallContext as an, type ObserveLLMCompleteContext as ao, type ObserveLLMErrorContext as ap, type Observers as aq, type MessageTurn as ar, type ObserveCompactionContext as as, DEFAULT_COMPACTION_CONFIG as at, DEFAULT_SUMMARIZATION_PROMPT as au, type LLMistOptions as av, type LLMRole as aw, LLMMessageBuilder as ax, type CostEstimate as ay, type ModelFeatures as az, type LLMMessage as b, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockMatcher as j, type MockMatcherContext as k, type MockOptions as l, mockLLM as m, type MockRegistration as n, type MockResponse as o, type MockStats as p, ModelRegistry as q, LLMist as r, type CompactionContext as s, type CompactionResult as t, type CompactionConfig as u, type CompactionEvent as v, type CompactionStats as w, type GadgetExecuteReturn as x, type GadgetExample as y, type GadgetExecutionResult as z };