@stacksjs/ai 0.75.37 → 0.75.40

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export * from './context';
 export * from './text';
 // Image generation & vision
 export * from './image';
+// Text-to-speech & speech-to-text (stacksjs/stacks#306)
+export * from './speech';
 // Semantic search, embeddings & RAG
 export * from './search';
 // Personalization, sentiment & classification

package/dist/index.js

@@ -1 +1 @@
-export*from"./types";export*from"./drivers";export*from"./client";export*from"./agents";export*from"./buddy";export*from"./context";export*from"./text";export*from"./image";export*from"./search";export*from"./personalization";export*from"./mcp";export*from"./utils/client-bedrock";export*from"./utils/client-bedrock-runtime";export{buildMessageWithImages,normalizeMessagesForProvider}from"./utils/vision";export{fetchWithRetry}from"./utils/retry";export{clearUsageReporters,listUsageReporters,onUsage,recordUsage}from"./utils/usage";export{estimateMessageTokens,estimateTokens,sanitizePrompt}from"./utils/tokens";export*from"./utils/model-access";
+export*from"./types";export*from"./drivers";export*from"./client";export*from"./agents";export*from"./buddy";export*from"./context";export*from"./text";export*from"./image";export*from"./speech";export*from"./search";export*from"./personalization";export*from"./mcp";export*from"./utils/client-bedrock";export*from"./utils/client-bedrock-runtime";export{buildMessageWithImages,normalizeMessagesForProvider}from"./utils/vision";export{fetchWithRetry}from"./utils/retry";export{clearUsageReporters,listUsageReporters,onUsage,recordUsage}from"./utils/usage";export{estimateMessageTokens,estimateTokens,sanitizePrompt}from"./utils/tokens";export*from"./utils/model-access";

package/dist/speech.d.ts

@@ -0,0 +1,87 @@
+import type { AIProvider } from './types';
+/** The MIME type for a speech format. */
+export declare function speechMimeType(format: SpeechFormat): string;
+/**
+ * Synthesize speech from text.
+ *
+ * @example
+ * ```ts
+ * const speech = await textToSpeech('Your order has shipped.', { voice: 'nova' })
+ * return new Response(speech.audio, { headers: { 'Content-Type': speech.mimeType } })
+ * ```
+ */
+export declare function textToSpeech(text: string, options?: TextToSpeechOptions): Promise<SpeechResult>;
+/**
+ * Write synthesized speech to a Stacks storage disk.
+ *
+ * @example
+ * ```ts
+ * const speech = await textToSpeech('Welcome back!')
+ * await storeSpeech(speech, 'audio/welcome.mp3', { disk: 'public' })
+ * ```
+ */
+export declare function storeSpeech(speech: Pick<SpeechResult, 'audio' | 'mimeType'>, path: string, options?: StoreSpeechOptions): Promise<StoredSpeech>;
+/**
+ * Transcribe audio to text.
+ *
+ * @example
+ * ```ts
+ * const { text } = await speechToText(Bun.file('memo.m4a'), { language: 'en' })
+ * ```
+ */
+export declare function speechToText(audio: SpeechInput, options?: SpeechToTextOptions): Promise<TranscriptionResult>;
+/** Drivers that implement text-to-speech / speech-to-text. */
+export declare const SPEECH_DRIVERS: readonly AIProvider[];
+declare interface SpeechRequestOptions {
+  driver?: SpeechDriver
+  config?: ConfiguredAIOptions
+  retry?: RetryConfig
+  signal?: AbortSignal
+}
+export declare interface TextToSpeechOptions extends SpeechRequestOptions {
+  model?: string
+  voice?: OpenAISpeechVoice | (string & {})
+  format?: SpeechFormat
+  speed?: number
+  instructions?: string
+}
+export declare interface SpeechResult {
+  audio: Uint8Array
+  mimeType: string
+  format: SpeechFormat
+  driver: AIProvider
+  model: string
+  voice: string
+}
+export declare interface SpeechToTextOptions extends SpeechRequestOptions {
+  model?: string
+  language?: string
+  prompt?: string
+  temperature?: number
+  filename?: string
+}
+export declare interface TranscriptionResult {
+  text: string
+  driver: AIProvider
+  model: string
+}
+/** Anything with a Stacks `StorageAdapter`-compatible `write()`. */
+export declare interface SpeechStorageDisk {
+  write: (path: string, contents: Uint8Array) => Promise<{ path: string, size: number, contentType?: string }>
+}
+export declare interface StoreSpeechOptions {
+  disk?: string | SpeechStorageDisk
+}
+export declare interface StoredSpeech {
+  path: string
+  size: number
+  mimeType: string
+}
+/** A driver name: one of the built-in providers, or anything `config/ai.ts` holds. */
+export type SpeechDriver = AIProvider | (string & {});
+/** Audio container/codec the provider should return. */
+export type SpeechFormat = 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
+/** OpenAI's built-in voices. Any other string is passed through (custom voice ids). */
+export type OpenAISpeechVoice = | 'alloy' | 'ash' | 'ballad' | 'cedar' | 'coral' | 'echo' | 'fable'
+  | 'marin' | 'nova' | 'onyx' | 'sage' | 'shimmer' | 'verse';
+export type SpeechInput = Blob | Uint8Array | ArrayBuffer;

package/dist/speech.js

@@ -0,0 +1 @@
+import{resolveAIProvider}from"./client";import{fetchWithRetry}from"./utils/retry";export const SPEECH_DRIVERS=["openai"];const OPENAI_BASE_URL="https://api.openai.com/v1",MAX_OPENAI_INPUT=4096;async function loadConfig(config){if(config)return config;try{const{ai}=await import("@stacksjs/config");return ai??{}}catch{return{}}}function unsupported(feature,driver){return Error(`${feature} is not supported by the "${driver}" AI driver. Drivers that support it: ${SPEECH_DRIVERS.join(", ")}. Pass { driver: '${SPEECH_DRIVERS[0]}' } or set \`default\` in config/ai.ts.`)}function resolveSpeechDriver(feature,config,override){const requested=String(override||config.default||"").trim();if(!requested)throw Error(`${feature} needs an AI driver. Pass { driver: '${SPEECH_DRIVERS[0]}' } or set \`default\` in config/ai.ts.`);let provider;try{provider=resolveAIProvider({default:requested})}catch{throw unsupported(feature,requested)}if(!SPEECH_DRIVERS.includes(provider))throw unsupported(feature,provider);return provider}function openAICredentials(config){const driver=config.drivers?.openai??{},apiKey=driver.apiKey?.trim()||process.env.OPENAI_API_KEY?.trim()||"",customBase=driver.baseUrl?.trim();if(!apiKey&&!customBase)throw Error("OpenAI API key not set. Set OPENAI_API_KEY or `drivers.openai.apiKey` in config/ai.ts.");return{apiKey,baseUrl:(customBase||OPENAI_BASE_URL).replace(/\/+$/,"")}}async function failure(provider,operation,response){let body="";try{body=(await response.text()).trim()}catch{}const snippet=body.length>500?`${body.slice(0,500)}...`:body;return Error(`${provider} ${operation} failed with HTTP ${response.status}${snippet?`: ${snippet}`:""}`)}const MIME_TYPES={mp3:"audio/mpeg",opus:"audio/ogg",aac:"audio/aac",flac:"audio/flac",wav:"audio/wav",pcm:"audio/pcm"};export function speechMimeType(format){return MIME_TYPES[format]}export async function textToSpeech(text,options={}){if(typeof text!=="string"||!text.trim())throw Error("textToSpeech() needs non-empty text.");const format=options.format??"mp3";if(!(format in MIME_TYPES))throw Error(`Unsupported speech format "${format}". Use one of: ${Object.keys(MIME_TYPES).join(", ")}.`);if(options.speed!==void 0&&!(options.speed>=0.25&&options.speed<=4))throw Error(`Speech speed must be between 0.25 and 4.0, got ${options.speed}.`);const config=await loadConfig(options.config),driver=resolveSpeechDriver("Text-to-speech",config,options.driver);return openAITextToSpeech(text,format,options,config,driver)}async function openAITextToSpeech(text,format,options,config,driver){if(text.length>MAX_OPENAI_INPUT)throw Error(`OpenAI text-to-speech accepts at most ${MAX_OPENAI_INPUT} characters per request, got ${text.length}. Split the text into chunks.`);const model=options.model??"gpt-4o-mini-tts",voice=options.voice??"alloy";if(options.instructions&&/^tts-1(?:-hd)?$/.test(model))throw Error(`OpenAI model "${model}" does not support \`instructions\`. Use gpt-4o-mini-tts.`);const{apiKey,baseUrl}=openAICredentials(config),body={model,input:text,voice,response_format:format};if(options.speed!==void 0)body.speed=options.speed;if(options.instructions)body.instructions=options.instructions;const headers={"Content-Type":"application/json"};if(apiKey)headers.Authorization=`Bearer ${apiKey}`;const response=await fetchWithRetry(`${baseUrl}/audio/speech`,{method:"POST",headers,body:JSON.stringify(body),signal:options.signal},options.retry);if(!response.ok)throw await failure("OpenAI","text-to-speech",response);const audio=new Uint8Array(await response.arrayBuffer()),contentType=response.headers.get("content-type")?.split(";")[0]?.trim(),mimeType=contentType?.startsWith("audio/")?contentType:MIME_TYPES[format];return{audio,mimeType,format,driver,model,voice}}export async function storeSpeech(speech,path,options={}){if(!path?.trim())throw Error("storeSpeech() needs a destination path.");let disk;if(options.disk&&typeof options.disk==="object")disk=options.disk;else{let storage;try{storage=await import("@stacksjs/storage")}catch(error){throw Error(`storeSpeech() needs @stacksjs/storage to resolve a disk by name (${error instanceof Error?error.message:String(error)}). Install it, or pass a storage adapter as { disk }.`)}disk=storage.Storage.disk(options.disk||void 0)}const result=await disk.write(path,speech.audio);return{path:result.path,size:result.size,mimeType:speech.mimeType}}const EXTENSIONS={"audio/mpeg":"mp3","audio/mp3":"mp3","audio/mp4":"m4a","audio/m4a":"m4a","audio/x-m4a":"m4a","audio/wav":"wav","audio/x-wav":"wav","audio/webm":"webm","audio/ogg":"ogg","audio/flac":"flac"};export async function speechToText(audio,options={}){if(options.temperature!==void 0&&!(options.temperature>=0&&options.temperature<=1))throw Error(`Transcription temperature must be between 0 and 1, got ${options.temperature}.`);const config=await loadConfig(options.config),driver=resolveSpeechDriver("Speech-to-text",config,options.driver),model=options.model??"whisper-1",{apiKey,baseUrl}=openAICredentials(config),blob=audio instanceof Blob?audio:new Blob([audio]);if(blob.size===0)throw Error("speechToText() needs non-empty audio.");const ownName=audio.name,fileName=options.filename||(typeof ownName==="string"&&ownName?ownName.split("/").pop():void 0)||`audio.${EXTENSIONS[blob.type.split(";")[0]??""]??"mp3"}`,form=new FormData;form.append("file",blob,fileName);form.append("model",model);form.append("response_format","json");if(options.language)form.append("language",options.language);if(options.prompt)form.append("prompt",options.prompt);if(options.temperature!==void 0)form.append("temperature",String(options.temperature));const headers={};if(apiKey)headers.Authorization=`Bearer ${apiKey}`;const response=await fetchWithRetry(`${baseUrl}/audio/transcriptions`,{method:"POST",headers,body:form,signal:options.signal},options.retry);if(!response.ok)throw await failure("OpenAI","speech-to-text",response);const data=await response.json();if(typeof data?.text!=="string")throw Error("OpenAI speech-to-text returned no text.");return{text:data.text,driver,model}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/ai",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.37",
+  "version": "0.75.40",
   "description": "Stacks Artificial Intelligence.",
   "author": "Chris Breuer",
   "contributors": [
@@ -65,8 +65,9 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/cli": "0.75.37",
-    "@stacksjs/config": "0.75.37",
+    "@stacksjs/cli": "0.75.40",
+    "@stacksjs/config": "0.75.40",
+    "@stacksjs/storage": "0.75.40",
     "@stacksjs/ts-cloud": "^0.16.15"
   },
   "peerDependencies": {