@hiper2d/ai-agents 0.1.4 → 0.2.0

package/README.md

@@ -56,6 +56,24 @@ import { createCatalog } from '@hiper2d/ai-agents';
 const catalog = createCatalog({ glm: { temperature: 0.9 } }); // shallow per-model overrides
 ```
 
+### Voice agents
+
+Speech and transcription behind the same factory pattern. Agents are pure — no auth or
+billing — and every result reports its cost so the host decides whom to charge.
+
+```ts
+import { VoiceAgentFactory, API_KEY_CONSTANTS } from '@hiper2d/ai-agents';
+
+const voice = VoiceAgentFactory.createAgentFromKeys('google', { [API_KEY_CONSTANTS.GOOGLE]: process.env.GOOGLE_API_KEY! });
+const { audio, costUSD } = await voice.speak({ text: 'Night falls.', voice: 'Kore', voiceStyle: 'gravely' }); // WAV
+const { text } = await voice.transcribe({ audio: recording, mimeType: 'audio/webm' });
+```
+
+`openai` runs gpt-4o-mini-tts + Whisper, `google` runs Gemini 3.1 Flash TTS + Gemini 3.5
+Transcribe (`VOICE_MODEL_CONSTANTS`, prices in `VOICE_MODEL_PRICING`). The `voiceStyle`
+direction works for both providers: OpenAI takes it as instructions, Gemini gets it folded
+into the prompt ("Say gravely: …").
+
 ### Logging
 
 The library logs through an injectable sink — `setLlmLogger(fn)` — so a host app can route

package/dist/index.d.mts

@@ -801,6 +801,224 @@ interface MistralTokenUsage {
 }
 declare function extractTokenUsageFromResponse(response: any): MistralTokenUsage | null;
 
+/**
+ * Voice agents: the speech counterpart of the text agents. One agent per
+ * provider, chosen through `VoiceAgentFactory` — a caller asks for a provider
+ * and gets `speak()` / `transcribe()` without knowing which SDK or model is
+ * behind them. Agents are pure: no auth, tier or billing logic. Each result
+ * carries what the call produced and what it cost, and the host decides whom
+ * to bill.
+ */
+type VoiceProvider = 'openai' | 'google';
+interface SpeechRequest {
+    text: string;
+    /** A voice id of this provider's set (e.g. OpenAI "onyx", Gemini "Kore"). */
+    voice: string;
+    /** Delivery direction: a short adverb ("mysteriously") or a longer sentence. */
+    voiceStyle?: string;
+}
+interface SpeechUsage {
+    /** OpenAI bills speech per input character. */
+    characters?: number;
+    /** Gemini bills speech per token: text prompt in, audio out. */
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface SpeechResult {
+    /** WAV audio (24 kHz mono 16-bit from Gemini; OpenAI's default WAV). */
+    audio: ArrayBuffer;
+    costUSD: number;
+    usage: SpeechUsage;
+}
+interface TranscriptionRequest {
+    audio: ArrayBuffer;
+    /** Container of the recording, e.g. "audio/webm" (browser MediaRecorder) or "audio/wav". */
+    mimeType?: string;
+    /** Whisper reads the container from the file name's extension. */
+    fileName?: string;
+    language?: string;
+    prompt?: string;
+}
+interface TranscriptionUsage {
+    /** Whisper bills per minute of audio. */
+    audioSeconds?: number;
+    /** Gemini bills per token: audio in (~25/s), text out. */
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface TranscriptionResult {
+    text: string;
+    /** Audio length; Gemini reports none, so it is derived from audio tokens. */
+    durationSeconds: number;
+    costUSD: number;
+    usage: TranscriptionUsage;
+}
+interface VoiceAgent {
+    readonly provider: VoiceProvider;
+    readonly ttsModel: string;
+    readonly sttModel: string;
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+/** Speech and transcription models behind each voice provider. */
+declare const VOICE_MODEL_CONSTANTS: {
+    readonly OPENAI_TTS: "gpt-4o-mini-tts";
+    readonly OPENAI_STT: "whisper-1";
+    readonly GOOGLE_TTS: "gemini-3.1-flash-tts-preview";
+    readonly GOOGLE_STT: "gemini-3.5-transcribe";
+};
+declare const SUPPORTED_VOICE_PROVIDERS: readonly VoiceProvider[];
+/** Which API key (by API_KEY_CONSTANTS name) a voice provider runs on. */
+declare const VOICE_PROVIDER_API_KEY: Record<VoiceProvider, string>;
+interface VoiceModelPricing {
+    /** OpenAI TTS: USD per 1M input characters. */
+    pricePerMillionCharacters?: number;
+    /** Whisper: USD per minute of audio. */
+    pricePerMinute?: number;
+    /** Gemini TTS: text prompt in, audio tokens out. */
+    textInputPricePerM?: number;
+    audioOutputPricePerM?: number;
+    /** Gemini Transcribe: audio tokens in, text tokens out. */
+    audioInputPricePerM?: number;
+    textOutputPricePerM?: number;
+}
+/** Prices as of 2026-09 (openai.com/api/pricing, ai.google.dev/gemini-api/docs/pricing). */
+declare const VOICE_MODEL_PRICING: Record<string, VoiceModelPricing>;
+
+interface TokenPairUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** OpenAI TTS: USD for `characterCount` input characters. */
+declare function calculateOpenAiTtsCost(characterCount: number): number;
+/** Whisper: USD for `durationSeconds` of audio. */
+declare function calculateOpenAiSttCost(durationSeconds: number): number;
+/** Gemini TTS: USD for text prompt tokens in and audio tokens out. */
+declare function calculateGeminiTtsCost(usage: TokenPairUsage): number;
+/** Gemini Transcribe: USD for audio tokens in and text tokens out. */
+declare function calculateGeminiSttCost(usage: TokenPairUsage): number;
+
+/** The voice counterpart of AgentFactory: provider in, agent out. */
+declare class VoiceAgentFactory {
+    /** Build an agent from a key already resolved by the caller. */
+    static createAgent(provider: VoiceProvider, apiKey: string): VoiceAgent;
+    /**
+     * Build an agent from a key map (the shape AgentFactory takes), reading the
+     * provider's key by its API_KEY_CONSTANTS name. Throws when the key is missing
+     * so the host can report a misconfiguration before any SDK is touched.
+     */
+    static createAgentFromKeys(provider: VoiceProvider, apiKeys: ApiKeyMap): VoiceAgent;
+}
+/** Function form of `VoiceAgentFactory.createAgent`. */
+declare function createVoiceAgent(provider: VoiceProvider, apiKey: string): VoiceAgent;
+
+/** gpt-4o-mini-tts (billed per character) + Whisper (billed per minute). */
+declare class OpenAiVoiceAgent implements VoiceAgent {
+    private readonly apiKey;
+    readonly provider: "openai";
+    readonly ttsModel: "gpt-4o-mini-tts";
+    readonly sttModel: "whisper-1";
+    constructor(apiKey: string);
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+/** Gemini 3.1 Flash TTS + Gemini 3.5 Transcribe, both billed per token. */
+declare class GoogleVoiceAgent implements VoiceAgent {
+    private readonly apiKey;
+    readonly provider: "google";
+    readonly ttsModel: "gemini-3.1-flash-tts-preview";
+    readonly sttModel: "gemini-3.5-transcribe";
+    constructor(apiKey: string);
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+type OpenAiTtsVoice = 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer' | 'ash' | 'ballad' | 'coral' | 'sage';
+interface OpenAiTtsAudioOptions {
+    voice?: OpenAiTtsVoice;
+    /** Delivery direction; gpt-4o-mini-tts follows it closely. */
+    instructions?: string;
+    speed?: number;
+    format?: 'mp3' | 'wav' | 'opus' | 'aac' | 'flac' | 'pcm';
+}
+/** Core OpenAI TTS call: text + API key in, audio bytes out (WAV by default). */
+declare function generateOpenAiTtsAudio(text: string, apiKey: string, options?: OpenAiTtsAudioOptions): Promise<ArrayBuffer>;
+
+interface OpenAiSttOptions {
+    language?: string;
+    prompt?: string;
+    temperature?: number;
+    /** Whisper detects the container format from the extension. */
+    fileName?: string;
+    mimeType?: string;
+}
+interface OpenAiSttResult {
+    text: string;
+    durationSeconds: number;
+}
+/** Core Whisper call: audio + API key in, transcript + duration out. */
+declare function transcribeWithOpenAi(audioBuffer: ArrayBuffer, apiKey: string, options?: OpenAiSttOptions): Promise<OpenAiSttResult>;
+
+interface GoogleTtsAudioOptions {
+    /** e.g. "Kore", "Puck" */
+    voiceName: string;
+    /** "mysteriously", "excitedly", or a longer direction */
+    voiceStyle?: string;
+}
+interface GoogleTtsResult {
+    /** WAV, 24 kHz mono 16-bit */
+    audio: ArrayBuffer;
+    /** text prompt tokens / audio tokens — what Gemini bills */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * Gemini TTS has no instruction field: delivery is directed in the text itself
+ * ("Say cheerfully: Have a wonderful day!" in the docs). A short style (1-3
+ * words) becomes that "Say X:" prefix; a longer direction is used as written,
+ * ending in the colon that separates it from the line to read. The same style
+ * value feeds OpenAI's `instructions`, so one field serves both providers.
+ */
+declare function buildGoogleTtsPrompt(text: string, voiceStyle?: string): string;
+/** Wraps raw 16-bit mono PCM in a WAV header. */
+declare function pcmToWav(pcmData: Uint8Array, sampleRate?: number): ArrayBuffer;
+/**
+ * Core Gemini TTS call: text + API key in, WAV + token usage out.
+ *
+ * Uses generateContent rather than the newer Interactions API the docs show:
+ * both serve the 3.1 TTS model (verified 2026-09-05), and this one is typed in
+ * the SDK and reports usageMetadata, which billing needs.
+ */
+declare function generateGoogleTtsAudio(text: string, apiKey: string, options: GoogleTtsAudioOptions): Promise<GoogleTtsResult>;
+
+interface GoogleSttOptions {
+    /** Container of the recording; browsers record audio/webm. */
+    mimeType?: string;
+}
+interface GoogleSttResult {
+    text: string;
+    /** Derived from audio tokens (~25/s) — Gemini reports no duration. */
+    durationSeconds: number;
+    /** audio tokens in, text tokens out — what Gemini bills */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** From the pricing page footnote: 25 audio tokens per second of input. */
+declare const GEMINI_AUDIO_TOKENS_PER_SECOND = 25;
+/**
+ * Core Gemini transcription call: audio + API key in, transcript + usage out.
+ *
+ * Uses the Interactions API: with this model, generateContent returns the
+ * transcript as a non-text part the SDK cannot surface (verified 2026-09-05).
+ */
+declare function transcribeWithGemini(audioBuffer: ArrayBuffer, apiKey: string, options?: GoogleSttOptions): Promise<GoogleSttResult>;
+
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1202,4 +1420,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -801,6 +801,224 @@ interface MistralTokenUsage {
 }
 declare function extractTokenUsageFromResponse(response: any): MistralTokenUsage | null;
 
+/**
+ * Voice agents: the speech counterpart of the text agents. One agent per
+ * provider, chosen through `VoiceAgentFactory` — a caller asks for a provider
+ * and gets `speak()` / `transcribe()` without knowing which SDK or model is
+ * behind them. Agents are pure: no auth, tier or billing logic. Each result
+ * carries what the call produced and what it cost, and the host decides whom
+ * to bill.
+ */
+type VoiceProvider = 'openai' | 'google';
+interface SpeechRequest {
+    text: string;
+    /** A voice id of this provider's set (e.g. OpenAI "onyx", Gemini "Kore"). */
+    voice: string;
+    /** Delivery direction: a short adverb ("mysteriously") or a longer sentence. */
+    voiceStyle?: string;
+}
+interface SpeechUsage {
+    /** OpenAI bills speech per input character. */
+    characters?: number;
+    /** Gemini bills speech per token: text prompt in, audio out. */
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface SpeechResult {
+    /** WAV audio (24 kHz mono 16-bit from Gemini; OpenAI's default WAV). */
+    audio: ArrayBuffer;
+    costUSD: number;
+    usage: SpeechUsage;
+}
+interface TranscriptionRequest {
+    audio: ArrayBuffer;
+    /** Container of the recording, e.g. "audio/webm" (browser MediaRecorder) or "audio/wav". */
+    mimeType?: string;
+    /** Whisper reads the container from the file name's extension. */
+    fileName?: string;
+    language?: string;
+    prompt?: string;
+}
+interface TranscriptionUsage {
+    /** Whisper bills per minute of audio. */
+    audioSeconds?: number;
+    /** Gemini bills per token: audio in (~25/s), text out. */
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface TranscriptionResult {
+    text: string;
+    /** Audio length; Gemini reports none, so it is derived from audio tokens. */
+    durationSeconds: number;
+    costUSD: number;
+    usage: TranscriptionUsage;
+}
+interface VoiceAgent {
+    readonly provider: VoiceProvider;
+    readonly ttsModel: string;
+    readonly sttModel: string;
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+/** Speech and transcription models behind each voice provider. */
+declare const VOICE_MODEL_CONSTANTS: {
+    readonly OPENAI_TTS: "gpt-4o-mini-tts";
+    readonly OPENAI_STT: "whisper-1";
+    readonly GOOGLE_TTS: "gemini-3.1-flash-tts-preview";
+    readonly GOOGLE_STT: "gemini-3.5-transcribe";
+};
+declare const SUPPORTED_VOICE_PROVIDERS: readonly VoiceProvider[];
+/** Which API key (by API_KEY_CONSTANTS name) a voice provider runs on. */
+declare const VOICE_PROVIDER_API_KEY: Record<VoiceProvider, string>;
+interface VoiceModelPricing {
+    /** OpenAI TTS: USD per 1M input characters. */
+    pricePerMillionCharacters?: number;
+    /** Whisper: USD per minute of audio. */
+    pricePerMinute?: number;
+    /** Gemini TTS: text prompt in, audio tokens out. */
+    textInputPricePerM?: number;
+    audioOutputPricePerM?: number;
+    /** Gemini Transcribe: audio tokens in, text tokens out. */
+    audioInputPricePerM?: number;
+    textOutputPricePerM?: number;
+}
+/** Prices as of 2026-09 (openai.com/api/pricing, ai.google.dev/gemini-api/docs/pricing). */
+declare const VOICE_MODEL_PRICING: Record<string, VoiceModelPricing>;
+
+interface TokenPairUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** OpenAI TTS: USD for `characterCount` input characters. */
+declare function calculateOpenAiTtsCost(characterCount: number): number;
+/** Whisper: USD for `durationSeconds` of audio. */
+declare function calculateOpenAiSttCost(durationSeconds: number): number;
+/** Gemini TTS: USD for text prompt tokens in and audio tokens out. */
+declare function calculateGeminiTtsCost(usage: TokenPairUsage): number;
+/** Gemini Transcribe: USD for audio tokens in and text tokens out. */
+declare function calculateGeminiSttCost(usage: TokenPairUsage): number;
+
+/** The voice counterpart of AgentFactory: provider in, agent out. */
+declare class VoiceAgentFactory {
+    /** Build an agent from a key already resolved by the caller. */
+    static createAgent(provider: VoiceProvider, apiKey: string): VoiceAgent;
+    /**
+     * Build an agent from a key map (the shape AgentFactory takes), reading the
+     * provider's key by its API_KEY_CONSTANTS name. Throws when the key is missing
+     * so the host can report a misconfiguration before any SDK is touched.
+     */
+    static createAgentFromKeys(provider: VoiceProvider, apiKeys: ApiKeyMap): VoiceAgent;
+}
+/** Function form of `VoiceAgentFactory.createAgent`. */
+declare function createVoiceAgent(provider: VoiceProvider, apiKey: string): VoiceAgent;
+
+/** gpt-4o-mini-tts (billed per character) + Whisper (billed per minute). */
+declare class OpenAiVoiceAgent implements VoiceAgent {
+    private readonly apiKey;
+    readonly provider: "openai";
+    readonly ttsModel: "gpt-4o-mini-tts";
+    readonly sttModel: "whisper-1";
+    constructor(apiKey: string);
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+/** Gemini 3.1 Flash TTS + Gemini 3.5 Transcribe, both billed per token. */
+declare class GoogleVoiceAgent implements VoiceAgent {
+    private readonly apiKey;
+    readonly provider: "google";
+    readonly ttsModel: "gemini-3.1-flash-tts-preview";
+    readonly sttModel: "gemini-3.5-transcribe";
+    constructor(apiKey: string);
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+
+type OpenAiTtsVoice = 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer' | 'ash' | 'ballad' | 'coral' | 'sage';
+interface OpenAiTtsAudioOptions {
+    voice?: OpenAiTtsVoice;
+    /** Delivery direction; gpt-4o-mini-tts follows it closely. */
+    instructions?: string;
+    speed?: number;
+    format?: 'mp3' | 'wav' | 'opus' | 'aac' | 'flac' | 'pcm';
+}
+/** Core OpenAI TTS call: text + API key in, audio bytes out (WAV by default). */
+declare function generateOpenAiTtsAudio(text: string, apiKey: string, options?: OpenAiTtsAudioOptions): Promise<ArrayBuffer>;
+
+interface OpenAiSttOptions {
+    language?: string;
+    prompt?: string;
+    temperature?: number;
+    /** Whisper detects the container format from the extension. */
+    fileName?: string;
+    mimeType?: string;
+}
+interface OpenAiSttResult {
+    text: string;
+    durationSeconds: number;
+}
+/** Core Whisper call: audio + API key in, transcript + duration out. */
+declare function transcribeWithOpenAi(audioBuffer: ArrayBuffer, apiKey: string, options?: OpenAiSttOptions): Promise<OpenAiSttResult>;
+
+interface GoogleTtsAudioOptions {
+    /** e.g. "Kore", "Puck" */
+    voiceName: string;
+    /** "mysteriously", "excitedly", or a longer direction */
+    voiceStyle?: string;
+}
+interface GoogleTtsResult {
+    /** WAV, 24 kHz mono 16-bit */
+    audio: ArrayBuffer;
+    /** text prompt tokens / audio tokens — what Gemini bills */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * Gemini TTS has no instruction field: delivery is directed in the text itself
+ * ("Say cheerfully: Have a wonderful day!" in the docs). A short style (1-3
+ * words) becomes that "Say X:" prefix; a longer direction is used as written,
+ * ending in the colon that separates it from the line to read. The same style
+ * value feeds OpenAI's `instructions`, so one field serves both providers.
+ */
+declare function buildGoogleTtsPrompt(text: string, voiceStyle?: string): string;
+/** Wraps raw 16-bit mono PCM in a WAV header. */
+declare function pcmToWav(pcmData: Uint8Array, sampleRate?: number): ArrayBuffer;
+/**
+ * Core Gemini TTS call: text + API key in, WAV + token usage out.
+ *
+ * Uses generateContent rather than the newer Interactions API the docs show:
+ * both serve the 3.1 TTS model (verified 2026-09-05), and this one is typed in
+ * the SDK and reports usageMetadata, which billing needs.
+ */
+declare function generateGoogleTtsAudio(text: string, apiKey: string, options: GoogleTtsAudioOptions): Promise<GoogleTtsResult>;
+
+interface GoogleSttOptions {
+    /** Container of the recording; browsers record audio/webm. */
+    mimeType?: string;
+}
+interface GoogleSttResult {
+    text: string;
+    /** Derived from audio tokens (~25/s) — Gemini reports no duration. */
+    durationSeconds: number;
+    /** audio tokens in, text tokens out — what Gemini bills */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** From the pricing page footnote: 25 audio tokens per second of input. */
+declare const GEMINI_AUDIO_TOKENS_PER_SECOND = 25;
+/**
+ * Core Gemini transcription call: audio + API key in, transcript + usage out.
+ *
+ * Uses the Interactions API: with this model, generateContent returns the
+ * transcript as a non-text part the SDK cannot surface (verified 2026-09-05).
+ */
+declare function transcribeWithGemini(audioBuffer: ArrayBuffer, apiKey: string, options?: GoogleSttOptions): Promise<GoogleSttResult>;
+
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1202,4 +1420,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };