@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/LLMService.typedefs.d.ts

@@ -0,0 +1,655 @@
+import type { OpenAIClient, OpenAIClientOptions, OpenAIModelConfigOverrides, OpenAIModelNames, OpenAISpeechOptions } from './providers/OpenAI/OpenAI.typedefs';
+import type { GoogleGenerativeAIClient, GoogleGenerativeAIClientOptions, GoogleGenerativeAIModelNames, GoogleGenerativeAISpeechOptions, GoogleGenerativeAIModelConfigOverrides } from './providers/GoogleGenerativeAI/GoogleGenerativeAI.typedefs';
+import type { LLMAPIClient, LLMAPIClientOptions, LLMAPIModelNames, LLMAPIModelConfigOverrides, LLMAPISpeechOptions } from './providers/LLMAPI/LLMAPI.typedefs';
+import type { LLMCompletionService, LLMAssistanceService, LLMSpeechToTextService, LLMTextToSpeechService } from './services';
+import type { LLMLoggerInterface } from './utilities/logger';
+import type { LLMReporterInterface } from './utilities/reporter';
+import type { LLMSchemaInterface, InferSchema } from './utilities/schema';
+import type { LLMTracedPrompt } from './utilities/llmTracing/llmTracing.typedefs';
+/**
+ * Enum of supported LLM providers.
+ */
+export declare enum LLMProviders {
+    OpenAI = "OpenAI",
+    GoogleGenerativeAI = "GoogleGenerativeAI",
+    LLMAPI = "LLMAPI"
+}
+/**
+ * Maps each LLM provider to its corresponding instance type.
+ */
+export type LLMInstances = {
+    [LLMProviders.OpenAI]: OpenAIClient;
+    [LLMProviders.GoogleGenerativeAI]: GoogleGenerativeAIClient;
+    [LLMProviders.LLMAPI]: LLMAPIClient;
+};
+/**
+ * Configuration options for initializing each LLM provider's client.
+ */
+export type LLMInstanceOptions = {
+    [LLMProviders.OpenAI]: OpenAIClientOptions;
+    [LLMProviders.GoogleGenerativeAI]: GoogleGenerativeAIClientOptions;
+    [LLMProviders.LLMAPI]: LLMAPIClientOptions;
+};
+/**
+ * Supported service purposes/types that the LLM gateway provides.
+ */
+export declare enum LLMPurposes {
+    Completion = "completion",
+    Assistance = "assistance",
+    SpeechToText = "speech_to_text",
+    TextToSpeech = "text_to_speech"
+}
+/**
+ * Maps each LLM purpose to its corresponding service implementation for a specific provider.
+ * @template Provider - The LLM provider type
+ * @template Reporter - The reporter interface type
+ */
+export type LLMServiceByPurpose<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = {
+    [LLMPurposes.Completion]: LLMCompletionService<Provider, Reporter>;
+    [LLMPurposes.Assistance]: LLMAssistanceService<Provider, Reporter>;
+    [LLMPurposes.SpeechToText]: LLMSpeechToTextService<Provider, Reporter>;
+    [LLMPurposes.TextToSpeech]: LLMTextToSpeechService<Provider, Reporter>;
+};
+/**
+ * Function type for building an LLM service instance for a specific provider and purpose.
+ * @template Provider - The LLM provider type
+ * @template Purpose - The service purpose type
+ * @template Reporter - Reporter interface type (optional)
+ * @param logger - Optional LLMLogger instance for service logging
+ * @param reporter - Optional reporter instance for metrics collection
+ * @param options - Provider-specific configuration options
+ * @returns An instance of the requested LLM service
+ */
+export type LLMServiceBuilder<Provider extends LLMProviders, Purpose extends LLMPurposes, Reporter extends LLMReporterInterface<any> | undefined> = (logger: LLMLoggerInterface | undefined, reporter: Reporter, options?: LLMInstanceOptions[Provider]) => LLMServiceByPurpose<Provider, Reporter>[Purpose];
+/**
+ * Defines token limits for LLM models.
+ */
+export interface LLMLimits {
+    maxInputTokens: number;
+    maxOutputTokens: number;
+}
+/**
+ * Describes which capabilities an LLM model supports.
+ */
+export interface LLMModelCapabilities {
+    vision: boolean;
+    tools: boolean;
+    reasoning: boolean;
+    webSearch: boolean;
+    jsonOutput?: boolean;
+    structuredOutputs?: boolean;
+    tts?: boolean;
+    stt?: boolean;
+    /**
+     * Whether the model's tool/function-result message can natively carry
+     * images. When absent or false, providers surface tool-returned images
+     * through a separate user message instead.
+     */
+    multimodalToolResults?: boolean;
+}
+/**
+ * Configuration parameters that control LLM generation behavior.
+ */
+export type LLMConfig<Provider extends LLMProviders = any, ModelName extends LLMModelName[Provider] = any> = Partial<{
+    temperature: number;
+    top_p: number | null;
+}> & (Provider extends LLMProviders.OpenAI ? OpenAIModelConfigOverrides<ModelName> : Provider extends LLMProviders.GoogleGenerativeAI ? GoogleGenerativeAIModelConfigOverrides<ModelName> : Provider extends LLMProviders.LLMAPI ? LLMAPIModelConfigOverrides<ModelName> : {});
+/**
+ * Maps a provider to all available models it can access.
+ * @template Provider - The LLM provider type
+ */
+export type LLMProviderAvailableModels<Provider extends LLMProviders> = {
+    [ModelName in LLMModelName[Provider]]: LLMModel<Provider, ModelName>;
+};
+/**
+ * Maps service purposes to the available models for a specific provider.
+ * @template Purpose - The service purpose type
+ * @template Provider - The LLM provider type
+ */
+export type LLMProviderModelsByPurpose<Purpose extends LLMPurposes, Provider extends LLMProviders> = Record<Purpose, Partial<LLMProviderAvailableModels<Provider>>>;
+/**
+ * Maps each provider to its supported model names.
+ */
+export type LLMModelName = {
+    [LLMProviders.OpenAI]: OpenAIModelNames;
+    [LLMProviders.GoogleGenerativeAI]: GoogleGenerativeAIModelNames;
+    [LLMProviders.LLMAPI]: LLMAPIModelNames;
+};
+/**
+ * Represents an LLM model with its configuration and limitations.
+ * @template Provider - The LLM provider type
+ * @template ModelName - The specific model name for the provider
+ */
+export interface LLMModel<Provider extends LLMProviders, ModelName extends LLMModelName[Provider] = LLMModelName[Provider]> {
+    name: ModelName;
+    limits: LLMLimits;
+    config: LLMConfig<Provider, ModelName>;
+    pricing: LLMModelPricing;
+    capabilities?: LLMModelCapabilities;
+}
+/**
+ * Pricing information for LLM models
+ */
+export interface LLMModelPricing {
+    /**
+     * Pricing calculation for text input
+     */
+    getPriceForTextInput: (tokens: number) => number;
+    /**
+     * Pricing calculation for text output
+     */
+    getPriceForTextOutput: (tokens: number) => number;
+    /**
+     * Pricing calculation for audio input
+     */
+    getPriceForAudioInput: (audio_tokens: number) => number;
+    /**
+     * Pricing calculation for audio output
+     */
+    getPriceForAudioOutput: (audio_tokens: number) => number;
+    /**
+     * Pricing calculation for cached text input (optional)
+     * If not provided, cached tokens will be charged at regular text input rate
+     * OpenAI: 50% discount on cached tokens
+     * Google: 75-90% discount depending on model
+     */
+    getPriceForCachedTextInput?: (tokens: number) => number;
+    /**
+     * Pricing calculation for cached audio input (optional)
+     * If not provided, cached tokens will be charged at regular audio input rate
+     */
+    getPriceForCachedAudioInput?: (audio_tokens: number) => number;
+    /**
+     * Currency code for the pricing
+     */
+    currency: 'USD';
+}
+/**
+ * Roles that can be assigned to messages in an LLM conversation.
+ */
+export declare enum LLMRoles {
+    User = "user",
+    Assistant = "assistant"
+}
+/**
+ * Possible content types for messages in an LLM conversation.
+ */
+export declare enum LLMMessageContentType {
+    TEXT = "text",
+    IMAGE_URL = "image_url",
+    AUDIO_FILE = "audio_file"
+}
+/**
+ * Represents a text part in a message in an LLM conversation.
+ */
+export interface LLMMessageTextContent {
+    type: LLMMessageContentType.TEXT;
+    text: string;
+}
+/**
+ * Represents an image part (by url) in a message in an LLM conversation.
+ */
+export interface LLMMessageImageUrlContent {
+    type: LLMMessageContentType.IMAGE_URL;
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/**
+ * Union type for all possible message content types in an LLM completion.
+ */
+export type LLMCompletionsMessageContent = LLMMessageTextContent | LLMMessageImageUrlContent;
+/**
+ * Union type for all possible message content types in an LLM assistance.
+ */
+export type LLMAssistanceMessageContent = LLMMessageTextContent | LLMMessageImageUrlContent;
+/**
+ * Represents an audio file buffer
+ */
+export type LLMAudioContent = {
+    type: LLMMessageContentType.AUDIO_FILE;
+    buffer: Buffer<ArrayBuffer>;
+};
+/**
+ * Represents a message in an LLM completion request.
+ */
+export interface LLMCompletionMessage {
+    role: LLMRoles;
+    content: LLMCompletionsMessageContent[];
+}
+/**
+ * Represents a message in an LLM assistance request.
+ */
+export interface LLMAssistanceMessage {
+    role: LLMRoles;
+    content: LLMAssistanceMessageContent[];
+}
+/**
+ * Represents an error that occurred during an LLM request.
+ */
+export type LLMRequestError = Error;
+/**
+ * Token usage reported by an LLM provider for a single call.
+ */
+export interface LLMModelUsage {
+    inputTextTokens?: number;
+    outputTextTokens?: number;
+    inputAudioTokens?: number;
+    outputAudioTokens?: number;
+    inputCachedTextTokens?: number;
+    inputCachedAudioTokens?: number;
+    outputReasoningTokens?: number;
+}
+/**
+ * Absolute USD cost for a single LLM call, derived from usage and model pricing.
+ */
+export interface LLMCostsResult {
+    input: number;
+    output: number;
+    total: number;
+    currency: string;
+}
+/**
+ * Generic result type for LLM requests that can either succeed or fail.
+ * @template ResponseType - The type of the successful result
+ */
+export type LLMRequestResult<ResponseType> = ResponseType | {
+    error: LLMRequestError;
+};
+/**
+ * Result type for LLM completion requests.
+ */
+export type LLMCompletionResult = LLMRequestResult<{
+    text: string;
+    usage?: LLMModelUsage;
+    cost?: LLMCostsResult;
+}>;
+/**
+ * Base options for LLM methods that can be extended by specific method options.
+ * Contains common properties like abort signal for cancellation.
+ * @template Reporter - Reporter interface type
+ */
+export type LLMMethodBaseOptions<Reporter extends LLMReporterInterface<any> | undefined> = {
+    abortSignal?: AbortSignal;
+    traceContext?: LLMCallTraceContext;
+} & (Reporter extends LLMReporterInterface<infer R> ? R extends undefined ? {
+    reporterContext?: never;
+} : {
+    reporterContext: R;
+} : {
+    reporterContext?: never;
+});
+/**
+ * Per-call trace context threaded into a single gateway call. When a prompt is
+ * present it names the observation instead of `<service>/<method>` and links
+ * the observation to its managed prompt version.
+ */
+export type LLMCallTraceContext = {
+    prompt?: LLMTracedPrompt;
+    /**
+     * Names the observation. Wins over every other source, and is the only way to
+     * name a call that has no managed prompt to borrow a name from - speech-to-text
+     * and text-to-speech, which would otherwise read as `<service>/<method>` and
+     * lose the domain operation they belong to.
+     */
+    name?: string;
+    /**
+     * @deprecated Use `prompt`. Kept on 7.8 for compatibility; still names the
+     * observation when `prompt` is absent.
+     */
+    promptName?: string;
+    /**
+     * The user this call was made for, as a typed trace attribute. Travels beside
+     * the metadata bag rather than inside it, because the tracer promotes it to
+     * the trace's own user field.
+     */
+    userId?: string;
+    /**
+     * Groups every trace of one conversation, review, or agent run under a single
+     * Langfuse session. A typed trace attribute, never a metadata key.
+     */
+    sessionId?: string;
+    /** Langfuse trace tags. A typed trace attribute, never a metadata key. */
+    tags?: string[];
+    metadata?: Record<string, string | number | boolean>;
+};
+/**
+ * Options for sending a message to an LLM service.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMSendMessageOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    message: LLMCompletionMessage;
+    model: LLMModel<Provider>;
+    history?: LLMCompletionMessage[];
+    instructions?: string;
+};
+/**
+ * Result type for structured output from LLM providers.
+ * @template T - The type of the structured data
+ */
+export type LLMStructuredResult<T = any> = LLMRequestResult<{
+    text: string;
+    data?: T;
+    parseError?: string;
+    toolIterationsUsed?: number;
+    toolIterationsExhausted?: true;
+    stopReason?: LLMToolLoopStopReasons;
+    terminalTool?: LLMTerminalToolOutcome;
+    usage?: LLMModelUsage;
+    cost?: LLMCostsResult;
+}>;
+/**
+ * Limits for files that can be uploaded to LLM services.
+ */
+export type LLMFileLimits = {
+    maxFileSize: number;
+    supportedMimeTypes: LLMUploadFileMimeTypes[];
+};
+/**
+ * Supported MIME types for files that can be uploaded to LLM services.
+ */
+export declare enum LLMUploadFileMimeTypes {
+    IMAGE_PNG = "image/png",
+    IMAGE_JPEG = "image/jpeg",
+    IMAGE_JPG = "image/jpg",
+    IMAGE_GIF = "image/gif",
+    IMAGE_WEBP = "image/webp",
+    IMAGE_SVG_XML = "image/svg+xml",
+    IMAGE_BMP = "image/bmp",
+    PLAIN_TEXT = "text/plain",
+    MARKDOWN = "text/markdown",
+    AUDIO_MP3 = "audio/mp3",
+    AUDIO_MPEG = "audio/mpeg",
+    AUDIO_WAV = "audio/wav",
+    AUDIO_WEBM = "audio/webm",
+    AUDIO_OGG = "audio/ogg"
+}
+/**
+ * Represents the MIME types for images that can be uploaded to LLM services.
+ */
+export type LLMImageMimeType = LLMUploadFileMimeTypes.IMAGE_PNG | LLMUploadFileMimeTypes.IMAGE_JPEG | LLMUploadFileMimeTypes.IMAGE_JPG | LLMUploadFileMimeTypes.IMAGE_GIF | LLMUploadFileMimeTypes.IMAGE_WEBP | LLMUploadFileMimeTypes.IMAGE_SVG_XML | LLMUploadFileMimeTypes.IMAGE_BMP;
+/**
+ * Represents the MIME types for audio files that can be uploaded to LLM services.
+ */
+export type LLMAudioMimeType = LLMUploadFileMimeTypes.AUDIO_MP3 | LLMUploadFileMimeTypes.AUDIO_MPEG | LLMUploadFileMimeTypes.AUDIO_WAV | LLMUploadFileMimeTypes.AUDIO_WEBM | LLMUploadFileMimeTypes.AUDIO_OGG;
+/**
+ * Represents a file to be uploaded to an LLM service.
+ * @template Reporter - Reporter interface type
+ */
+export type LLMUploadFileOptions<Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    mimeType: LLMUploadFileMimeTypes;
+    name: string;
+    path: string;
+};
+/**
+ * Represents a file that has been successfully uploaded to an LLM service.
+ */
+export interface LLMUploadedFile extends Omit<LLMUploadFileOptions<any>, 'reporterContext' | 'abortSignal'> {
+    fileId: string;
+}
+/**
+ * Result type for file upload operations.
+ */
+export type LLMUploadFileResult = LLMRequestResult<LLMUploadedFile>;
+/**
+ * Options for creating a file storage for a specific LLM provider.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMCreateFileStorageOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    uploadedFiles: LLMUploadedFile[];
+    model: LLMModel<Provider>;
+    instructions?: string;
+};
+/**
+ * Represents a created file storage in an LLM service.
+ */
+export interface LLMCreatedFileStorage {
+    storageId: string;
+}
+/**
+ * Result type for file storage creation operations.
+ */
+export type LLMCreateFileStorageResult = LLMRequestResult<LLMCreatedFileStorage>;
+/**
+ * Options for creating a chat session with a specific LLM provider.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMCreateChatOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    model: LLMModel<Provider>;
+    instructions?: string;
+    history?: LLMAssistanceMessage[];
+    storageId?: string;
+    files?: LLMUploadedFile[];
+};
+/**
+ * Represents a created chat session in an LLM service.
+ */
+export interface LLMCreatedChat {
+    chatId: string;
+}
+/**
+ * Result type for chat creation operations.
+ */
+export type LLMCreateChatResult = LLMRequestResult<LLMCreatedChat>;
+/**
+ * Options for chat assistance with a specific LLM provider.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMAssistanceOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    model: LLMModel<Provider>;
+    message: LLMAssistanceMessage;
+    chatId: string;
+    storageId?: string;
+    tools?: LLMToolDefinition[];
+    maxToolIterations?: number;
+    /** Groups this legacy tool loop under one agent trace observation. */
+    agentName?: string;
+    /**
+     * Invoked with the model's visible assistant text from a tool-calling round
+     * that will continue the loop (narration emitted alongside tool calls),
+     * before that round's tools execute. Never carries the final round's answer
+     * or reasoning/thinking content; the text may be empty when the round
+     * produced only tool calls, so the consumer skips empty/whitespace-only text.
+     * Observability-only: the callback must not throw — the tool loop does not
+     * guard the call.
+     */
+    onAssistantNarration?: (text: string) => void;
+};
+/**
+ * Result type for assistance requests.
+ */
+export type LLMAssistanceResult = LLMRequestResult<{
+    text: string;
+    toolIterationsUsed?: number;
+    toolIterationsExhausted?: true;
+    stopReason?: LLMToolLoopStopReasons;
+    terminalTool?: LLMTerminalToolOutcome;
+}>;
+/**
+ * Options for a one-shot prompt in a newly created chat.
+ * Combines chat creation options with message sending options.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMAssistInNewChatOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMCreateChatOptions<Provider, Reporter> & {
+    prompt: string;
+    tools?: LLMToolDefinition[];
+    maxToolIterations?: number;
+};
+/**
+ * An image returned by a tool's `execute` for the model to see.
+ */
+export interface LLMToolResultImage {
+    /** Image location. An https URL, or a data URL for inline bytes. */
+    url: string;
+    /** Vision detail hint passed to providers that accept it. */
+    detail?: 'auto' | 'low' | 'high';
+    /**
+     * MIME type of the image. Defaults to `image/png`. Used by providers that
+     * require raw bytes (Gemini) when fetching and re-encoding the image.
+     */
+    mimeType?: string;
+    /** Optional caption rendered next to the image for the model. */
+    label?: string;
+}
+/**
+ * Structured result a tool's `execute` may return when it needs to surface
+ * images alongside text. The `content` string always becomes the
+ * tool/function-result message; `images` are surfaced to the model the way
+ * each provider's API allows.
+ */
+export interface LLMStructuredToolResult {
+    content: string;
+    images?: LLMToolResultImage[];
+}
+/**
+ * What a tool's `execute` may return. A plain `string` keeps the legacy
+ * text-only behaviour; an `LLMStructuredToolResult` additionally carries
+ * images.
+ */
+export type LLMToolResult = string | LLMStructuredToolResult;
+/**
+ * The verdict of a tool's `canExecute` precondition. A refusal carries the
+ * `reason` the model is told, which is why it is required: a denial the model
+ * cannot explain to itself is a denial it will retry blindly.
+ */
+export type LLMToolGateResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+export interface LLMToolDefinition<Schema extends LLMSchemaInterface = LLMSchemaInterface> {
+    name: string;
+    description: string;
+    parameters: Schema;
+    execute: (args: InferSchema<Schema>) => Promise<LLMToolResult> | LLMToolResult;
+    /**
+     * Decides whether this call may run, on the arguments the model supplied.
+     * Checked before `execute`, so a refused call never has its side effect. A
+     * refusal is ordinary control flow, not an error: the model is told the
+     * `reason` as the call's result and the run continues with its iteration
+     * budget untouched. Use it for permission, quota, and state preconditions
+     * that depend on the arguments rather than on the tool being present at all.
+     */
+    canExecute?: (args: InferSchema<Schema>) => Promise<LLMToolGateResult> | LLMToolGateResult;
+    /**
+     * Ends the turn once this tool runs. The round executes in full (every call
+     * of that round, including parallel ones), but its results are not fed back
+     * and no further model round starts — the loop stops with
+     * `LLMToolLoopStopReasons.TerminalTool` and this tool's output as the turn
+     * outcome. Use for tools that hand control back to the application, such as
+     * an `ask_user` tool that needs a human reply before the agent can continue.
+     */
+    terminal?: boolean;
+}
+/**
+ * Why a provider's model⇄tool loop stopped. `Completed` is the ordinary end
+ * (a model round returned no tool calls), `MaxIterations` means the loop hit
+ * `maxToolIterations` with tool calls still pending, and `TerminalTool` means
+ * a tool declaring `terminal` ran and ended the turn.
+ */
+export declare enum LLMToolLoopStopReasons {
+    Completed = "completed",
+    MaxIterations = "max_iterations",
+    TerminalTool = "terminal_tool"
+}
+/**
+ * The terminal tool call that ended a turn: the tool's name and the output it
+ * returned, which the application handles instead of a model answer. When more
+ * than one terminal call lands in the same round, the first in the round's
+ * order is reported (all of them still execute).
+ */
+export interface LLMTerminalToolOutcome {
+    name: string;
+    output: LLMToolResult;
+}
+/**
+ * Function type for counting tokens in messages for a specific provider's model.
+ * @template Provider - The LLM provider type
+ * @template ContentType - The type of the message content
+ * @param messages - Array of message strings to count tokens for
+ * @param model - The LLM model to use for token counting
+ * @returns Promise resolving to the number of tokens
+ */
+export type LLMCountTokensFunction<Provider extends LLMProviders, ContentType> = (messagesContents: ContentType, model: LLMModel<Provider>) => Promise<number>;
+/**
+ * Options for combining messages with a limit on the number of tokens.
+ * @template Provider - The LLM provider type
+ * @template TokenCountFunction - Function type for counting tokens
+ */
+export interface CombineMessagesOptions<Provider extends LLMProviders, TokenCountFunction extends LLMCountTokensFunction<Provider, any[]>> {
+    history?: LLMCompletionMessage[];
+    message: LLMCompletionMessage;
+    model: LLMModel<Provider>;
+    instance: LLMInstances[Provider];
+    logger: LLMLoggerInterface | undefined;
+    countTokensFn: TokenCountFunction;
+}
+/**
+ * Options for transcribing audio to text using an LLM service.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMTranscribeOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    pathToAudio: string;
+    mimeType?: LLMAudioMimeType;
+    model: LLMModel<Provider>;
+    instructions?: string;
+    language?: string;
+};
+/**
+ * Result type for LLM transcription requests.
+ */
+export type LLMTranscribeResult = LLMRequestResult<{
+    text: string;
+    usage?: LLMModelUsage;
+    cost?: LLMCostsResult;
+}>;
+/**
+ * Provider-specific options for creating speech from text.
+ */
+export type LLMSpeechOptions = {
+    [LLMProviders.OpenAI]: OpenAISpeechOptions;
+    [LLMProviders.GoogleGenerativeAI]: GoogleGenerativeAISpeechOptions;
+    [LLMProviders.LLMAPI]: LLMAPISpeechOptions;
+};
+/**
+ * Options for creating speech from text using an LLM service.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export type LLMCreateSpeechOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> = LLMMethodBaseOptions<Reporter> & {
+    text: string;
+    model: LLMModel<Provider>;
+    instructions?: string;
+    speechOptions?: LLMSpeechOptions[Provider];
+};
+/**
+ * Result type for LLM speech creation requests.
+ * Contains the generated audio buffer and its MIME type.
+ */
+export type LLMCreateSpeechResult = LLMRequestResult<{
+    audio: Buffer<ArrayBuffer>;
+    mimeType: string | null;
+}>;
+/**
+ * Options for creating LLM services.
+ * @template Provider - The LLM provider type
+ * @template Reporter - Reporter interface type
+ */
+export interface LLMServiceOptions<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> {
+    /** The LLM provider (OpenAI, GoogleGenerativeAI) */
+    provider: Provider;
+    /** Provider-specific configuration options */
+    options?: LLMInstanceOptions[Provider];
+    /** Logger instance (optional, no logging if not provided) */
+    logger?: LLMLoggerInterface;
+    /** Reporter instance (optional, no reporting if not provided) */
+    reporter?: Reporter;
+}