@luanpoppe/ai 1.1.4 → 1.1.6

package/src/embeddings/index.ts

@@ -0,0 +1,83 @@
+import type { AIEmbeddingModelNames } from "../@types/embedding-model-names";
+import { embedOpenAI } from "./embed-openai";
+import { embedOpenRouter } from "./embed-openrouter";
+import { embedGemini } from "./embed-gemini";
+import {
+  embedWithModel,
+  type EmbedOptions,
+} from "./route";
+import type {
+  EmbedApiKeys,
+  EmbeddingResult,
+  GeminiEmbeddingOptions,
+  GeminiEmbeddingTaskType,
+  OpenAIEmbeddingOptions,
+  OpenRouterEmbeddingOptions,
+} from "./types";
+
+export type {
+  AIEmbeddingModelNames,
+  OpenAIEmbeddingModel,
+  GeminiEmbeddingModel,
+  OpenRouterEmbeddingModel,
+  OpenRouterPrefixedEmbeddingModel,
+} from "../@types/embedding-model-names";
+
+export type {
+  EmbeddingResult,
+  EmbeddingUsage,
+  OpenAIEmbeddingOptions,
+  OpenRouterEmbeddingOptions,
+  GeminiEmbeddingOptions,
+  GeminiEmbeddingTaskType,
+  EmbedApiKeys,
+} from "./types";
+
+export type { EmbedOptions } from "./route";
+
+export { ANTHROPIC_NO_NATIVE_EMBEDDINGS } from "./types";
+export { embedWithModel };
+
+export class AIEmbeddings {
+  static embedOpenAI = embedOpenAI;
+  static embedOpenRouter = embedOpenRouter;
+  static embedGemini = embedGemini;
+
+  static async embed(
+    input: string | string[],
+    options: EmbedOptions,
+    keys: EmbedApiKeys,
+  ): Promise<EmbeddingResult> {
+    return embedWithModel(input, options, keys);
+  }
+
+  static async embedDocuments(
+    texts: string[],
+    options: EmbedOptions,
+    keys: EmbedApiKeys,
+  ): Promise<number[][]> {
+    const taskType =
+      options.taskType ??
+      (options.model.startsWith("gemini-embedding-")
+        ? ("RETRIEVAL_DOCUMENT" as const)
+        : undefined);
+
+    const result = await embedWithModel(texts, { ...options, taskType }, keys);
+    return result.embeddings;
+  }
+
+  static async embedQuery(
+    text: string,
+    options: EmbedOptions,
+    keys: EmbedApiKeys,
+  ): Promise<number[]> {
+    const taskType =
+      options.taskType ??
+      (options.model.startsWith("gemini-embedding-")
+        ? ("RETRIEVAL_QUERY" as const)
+        : undefined);
+
+    const result = await embedWithModel(text, { ...options, taskType }, keys);
+    return result.embeddings[0] ?? [];
+  }
+}

package/src/embeddings/route.ts

@@ -0,0 +1,62 @@
+import type {
+  EmbedApiKeys,
+  EmbeddingResult,
+  GeminiEmbeddingOptions,
+  OpenAIEmbeddingOptions,
+  OpenRouterEmbeddingOptions,
+} from "./types";
+import type { AIEmbeddingModelNames } from "../@types/embedding-model-names";
+import { embedOpenAI } from "./embed-openai";
+import { embedOpenRouter } from "./embed-openrouter";
+import { embedGemini } from "./embed-gemini";
+import {
+  isGeminiEmbeddingModel,
+  isOpenAIEmbeddingModel,
+  isOpenRouterEmbeddingModel,
+} from "./utils";
+
+export type EmbedOptions = {
+  model: AIEmbeddingModelNames;
+  dimensions?: number;
+  encodingFormat?: "float" | "base64";
+  taskType?: GeminiEmbeddingOptions["taskType"];
+  openRouterProvider?: OpenRouterEmbeddingOptions["openRouterProvider"];
+  openRouterAllowAllProviders?: boolean;
+};
+
+export async function embedWithModel(
+  input: string | string[],
+  options: EmbedOptions,
+  keys: EmbedApiKeys,
+): Promise<EmbeddingResult> {
+  const { model } = options;
+
+  if (isOpenRouterEmbeddingModel(model)) {
+    const orOptions: OpenRouterEmbeddingOptions = { model };
+    if (options.dimensions !== undefined) orOptions.dimensions = options.dimensions;
+    if (options.encodingFormat) orOptions.encodingFormat = options.encodingFormat;
+    if (options.openRouterProvider) {
+      orOptions.openRouterProvider = options.openRouterProvider;
+    }
+    if (options.openRouterAllowAllProviders !== undefined) {
+      orOptions.openRouterAllowAllProviders = options.openRouterAllowAllProviders;
+    }
+    return embedOpenRouter(input, orOptions, keys.openRouterApiKey);
+  }
+
+  if (isOpenAIEmbeddingModel(model)) {
+    const oaiOptions: OpenAIEmbeddingOptions = { model };
+    if (options.dimensions !== undefined) oaiOptions.dimensions = options.dimensions;
+    if (options.encodingFormat) oaiOptions.encodingFormat = options.encodingFormat;
+    return embedOpenAI(input, oaiOptions, keys.openAIApiKey);
+  }
+
+  if (isGeminiEmbeddingModel(model)) {
+    const geminiOptions: GeminiEmbeddingOptions = { model };
+    if (options.dimensions !== undefined) geminiOptions.dimensions = options.dimensions;
+    if (options.taskType) geminiOptions.taskType = options.taskType;
+    return embedGemini(input, geminiOptions, keys.googleGeminiToken);
+  }
+
+  throw new Error(`[@luanpoppe/ai] Modelo de embedding não suportado: ${model}`);
+}

package/src/embeddings/types.ts

@@ -0,0 +1,53 @@
+import type { OpenRouterProviderPreferences } from "../@types/openrouter-provider";
+import type { AIEmbeddingModelNames } from "../@types/embedding-model-names";
+
+export type GeminiEmbeddingTaskType =
+  | "RETRIEVAL_DOCUMENT"
+  | "RETRIEVAL_QUERY"
+  | "SEMANTIC_SIMILARITY"
+  | "CLASSIFICATION"
+  | "CLUSTERING"
+  | "QUESTION_ANSWERING"
+  | "FACT_VERIFICATION"
+  | "CODE_RETRIEVAL_QUERY";
+
+export type EmbeddingUsage = {
+  prompt_tokens?: number;
+  total_tokens?: number;
+};
+
+export type EmbeddingResult = {
+  embeddings: number[][];
+  model: string;
+  usage?: EmbeddingUsage;
+};
+
+export type OpenAIEmbeddingOptions = {
+  model: AIEmbeddingModelNames;
+  dimensions?: number;
+  encodingFormat?: "float" | "base64";
+};
+
+export type OpenRouterEmbeddingOptions = {
+  model: AIEmbeddingModelNames;
+  dimensions?: number;
+  encodingFormat?: "float" | "base64";
+  openRouterProvider?: OpenRouterProviderPreferences;
+  openRouterAllowAllProviders?: boolean;
+};
+
+export type GeminiEmbeddingOptions = {
+  model: AIEmbeddingModelNames;
+  dimensions?: number;
+  taskType?: GeminiEmbeddingTaskType;
+};
+
+export type EmbedApiKeys = {
+  openAIApiKey?: string;
+  googleGeminiToken?: string;
+  openRouterApiKey?: string;
+};
+
+/** A API pública da Anthropic não oferece embeddings nativos (recomenda Voyage AI para RAG com Claude). */
+export const ANTHROPIC_NO_NATIVE_EMBEDDINGS =
+  "A API da Anthropic não suporta embeddings nativos. Use OpenAI, Gemini ou OpenRouter para vetorizar texto antes de AI.call com modelos anthropic." as const;

package/src/embeddings/utils.ts

@@ -0,0 +1,21 @@
+export function normalizeInput(input: string | string[]): string[] {
+  return Array.isArray(input) ? input : [input];
+}
+
+export function stripOpenRouterPrefix(model: string): string {
+  return model.startsWith("openrouter/")
+    ? model.slice("openrouter/".length)
+    : model;
+}
+
+export function isOpenAIEmbeddingModel(model: string): boolean {
+  return model.startsWith("text-embedding-");
+}
+
+export function isGeminiEmbeddingModel(model: string): boolean {
+  return model.startsWith("gemini-embedding-");
+}
+
+export function isOpenRouterEmbeddingModel(model: string): boolean {
+  return model.startsWith("openrouter/");
+}

package/src/index.ts

@@ -15,9 +15,23 @@ export type {
   AICallStructuredOutputParams,
   AICallStructuredOutputReturn,
 } from "./@types/ai-call";
+export type { AIModelNames } from "./@types/model-names";
 
 export { AIModels } from "./langchain/models";
-export type { LLMModelConfig, ReasoningEffort } from "./langchain/models";
+export {
+  DEFAULT_OLLAMA_BASE_URL,
+  DEFAULT_LOCAL_API_KEY,
+} from "./langchain/models";
+export type {
+  LLMModelConfig,
+  OllamaModelConfig,
+  OpenAICompatibleModelConfig,
+  ReasoningEffort,
+  OpenRouterMaxPrice,
+  OpenRouterProviderPreferences,
+  OpenRouterProviderSort,
+} from "./langchain/models";
+export { resolveOpenRouterProvider } from "./langchain/models";
 export { AIMessages } from "./langchain/messages";
 export { AITools } from "./langchain/tools";
 export { AIMemory } from "./langchain/memory";
@@ -34,6 +48,41 @@ export type {
   HistoryMessageItem,
   GetHistoryResult,
 } from "./langchain/memory";
+export { AIAudio } from "./audio";
+export type {
+  WhisperModel,
+  OpenAITranscriptionOptions,
+  OpenAITranscriptionResponseFormat,
+  OpenAITranscriptionDetailed,
+  OpenRouterTranscriptionOptions,
+  OpenRouterTranscriptionResult,
+  OpenAISpeechOptions,
+  OpenAISpeechModel,
+  OpenRouterSpeechOptions,
+  SpeechResult,
+  TranscriptionWord,
+  TranscriptionSegment,
+  DiarizedSegment,
+  GeminiTranscriptionOptions,
+} from "./audio";
+export { ANTHROPIC_NO_NATIVE_AUDIO } from "./audio";
+export { AIEmbeddings, ANTHROPIC_NO_NATIVE_EMBEDDINGS } from "./embeddings";
+export type {
+  AIEmbeddingModelNames,
+  OpenAIEmbeddingModel,
+  GeminiEmbeddingModel,
+  OpenRouterEmbeddingModel,
+  OpenRouterPrefixedEmbeddingModel,
+  EmbeddingResult,
+  EmbeddingUsage,
+  OpenAIEmbeddingOptions,
+  OpenRouterEmbeddingOptions,
+  GeminiEmbeddingOptions,
+  GeminiEmbeddingTaskType,
+  EmbedApiKeys,
+  EmbedOptions,
+} from "./embeddings";
+/** @deprecated Use AIAudio instead */
 export { AIAudioTranscription } from "./langchain/audio-transcription";
 export { AudioUtils } from "./utils/audio-utils";
 export { ImageUtils } from "./utils/image-utils";
@@ -45,10 +94,8 @@ export type {
   ImageContentBlock,
   HumanMessageWithImageOptions,
 } from "./langchain/messages";
-export type {
-  WhisperModel,
-  WhisperTranscriptionOptions,
-} from "./langchain/audio-transcription";
+/** @deprecated Use OpenAITranscriptionOptions from AIAudio */
+export type { WhisperTranscriptionOptions } from "./langchain/audio-transcription";
 
 // Aliases para compatibilidade (deprecated - serão removidos em 2.0.0)
 /** @deprecated Use AI instead. Will be removed in 2.0.0 */

package/src/langchain/audio-transcription.ts

@@ -1,105 +1,34 @@
-import * as fs from "fs";
-import * as path from "path";
-import OpenAI from "openai";
-import { toFile } from "openai";
 import type { AudioBuffer, AudioMimeType } from "../@types/audio";
-import { MIME_TO_EXTENSION } from "../@types/audio";
+import { AIAudio } from "../audio";
+import type {
+  OpenAITranscriptionOptions,
+  WhisperModel,
+} from "../audio/types";
 
-/** Modelos disponíveis na API de transcrição OpenAI (Speech-to-Text) */
-export type WhisperModel =
-  | "whisper-1"
-  | "gpt-4o-transcribe"
-  | "gpt-4o-mini-transcribe"
-  | "gpt-4o-mini-transcribe-2025-12-15"
-  | "gpt-4o-transcribe-diarize";
+export type { WhisperModel };
 
-export type WhisperTranscriptionOptions = {
-  /** Modelo de transcrição. Padrão: "whisper-1". gpt-4o-transcribe e gpt-4o-mini-transcribe têm maior qualidade. */
-  model?: WhisperModel;
-  languageIn2Digits?: string;
-  prompt?: string;
-  responseFormat?: "json" | "text" | "srt" | "verbose_json" | "vtt";
-  temperature?: number;
-  timestampGranularities?: ("word" | "segment")[];
-  /** Formato do áudio: extensão ("mp3", "wav", "webm") ou MIME type ("audio/wav", "audio/webm") */
-  format?: string | AudioMimeType;
-};
-
-function getExtension(format?: string | AudioMimeType): string {
-  if (!format) return "mp3";
-  if (format.startsWith("audio/")) {
-    return MIME_TO_EXTENSION[format as AudioMimeType] ?? "mp3";
-  }
-  return format.replace(/^\./, "");
-}
-
-function toBuffer(audioBuffer: AudioBuffer): Buffer {
-  if (audioBuffer instanceof Buffer) return audioBuffer;
-  if (audioBuffer instanceof ArrayBuffer) return Buffer.from(audioBuffer);
-  return Buffer.from(audioBuffer as Uint8Array);
-}
+/** @deprecated Use OpenAITranscriptionOptions from AIAudio */
+export type WhisperTranscriptionOptions = OpenAITranscriptionOptions;
 
+/**
+ * @deprecated Use {@link AIAudio.transcribeWithWhisper} instead.
+ */
 export class AIAudioTranscription {
-  static async transcribeWithWhisper(
+  static transcribeWithWhisper(
     audioBuffer: AudioBuffer,
     options: WhisperTranscriptionOptions = {},
-    openAIApiKey?: string
+    openAIApiKey?: string,
   ): Promise<string> {
-    if (openAIApiKey) {
-      process.env.OPENAI_API_KEY = openAIApiKey;
-    }
-
-    const buffer = toBuffer(audioBuffer);
-    const extension = getExtension(options.format);
-    const fileName = `whisper-${Date.now()}.${extension}`;
-
-    const file = await toFile(buffer, fileName);
-
-    const openai = new OpenAI();
-
-    const transcriptionParams: OpenAI.Audio.TranscriptionCreateParams = {
-      file,
-      model: options.model ?? "whisper-1",
-      response_format: options.responseFormat ?? "text",
-    };
-
-    if (options.languageIn2Digits) {
-      transcriptionParams.language = options.languageIn2Digits;
-    }
-    if (options.prompt) {
-      transcriptionParams.prompt = options.prompt;
-    }
-    if (options.temperature !== undefined) {
-      transcriptionParams.temperature = options.temperature;
-    }
-    if (options.timestampGranularities) {
-      transcriptionParams.timestamp_granularities =
-        options.timestampGranularities;
-    }
-
-    const response = await openai.audio.transcriptions.create(
-      transcriptionParams
-    );
-
-    return typeof response === "string" ? response : response.text;
+    return AIAudio.transcribeWithWhisper(audioBuffer, options, openAIApiKey);
   }
 
-  static async transcribeFileWithWhisper(
+  static transcribeFileWithWhisper(
     filePath: string,
     options: WhisperTranscriptionOptions = {},
-    openAIApiKey?: string
+    openAIApiKey?: string,
   ): Promise<string> {
-    if (!fs.existsSync(filePath)) {
-      throw new Error(`Arquivo não encontrado: ${filePath}`);
-    }
-
-    const audioBuffer = fs.readFileSync(filePath);
-    const format =
-      options.format ?? (path.extname(filePath).replace(/^\./, "") || "mp3");
-    return this.transcribeWithWhisper(
-      audioBuffer,
-      { ...options, format },
-      openAIApiKey
-    );
+    return AIAudio.transcribeFileWithWhisper(filePath, options, openAIApiKey);
   }
 }
+
+export type { AudioBuffer, AudioMimeType };

package/src/langchain/messages.ts

@@ -3,7 +3,7 @@ import { AudioUtils } from "../utils/audio-utils";
 import { ImageUtils } from "../utils/image-utils";
 import type { AudioBuffer, AudioMimeType } from "../@types/audio";
 import type { ImageBuffer, ImageMimeType } from "../@types/image";
-import { AIAudioTranscription } from "./audio-transcription";
+import { AIAudio } from "../audio";
 
 export type MessageInput = SystemMessage | HumanMessage | AIMessage;
 
@@ -39,8 +39,11 @@ export type HumanMessageWithAudioOptions = {
     filename?: string;
   };
   text?: string;
-  provider?: "openai" | "gemini" | "auto";
+  provider?: "openai" | "gemini" | "openrouter" | "auto";
   openAIApiKey?: string;
+  openRouterApiKey?: string;
+  /** Modelo OpenRouter STT (ex.: openai/whisper-1) quando provider é openrouter ou auto com OR */
+  openRouterTranscriptionModel?: string;
 };
 
 export class AIMessages {
@@ -83,16 +86,31 @@ export class AIMessages {
   static async humanAudio(
     options: HumanMessageWithAudioOptions
   ): Promise<HumanMessage> {
-    const { audio, text, provider = "auto", openAIApiKey } = options;
+    const {
+      audio,
+      text,
+      provider = "auto",
+      openAIApiKey,
+      openRouterApiKey,
+      openRouterTranscriptionModel,
+    } = options;
     const { buffer, mimeType, filename } = audio;
 
+    const resolvedProvider = this.resolveAudioProvider(
+      provider,
+      openAIApiKey,
+      openRouterApiKey,
+    );
+
     return this.createHumanMessageWithAudio(
       buffer,
       text,
       mimeType,
       filename,
-      provider,
-      openAIApiKey
+      resolvedProvider,
+      openAIApiKey,
+      openRouterApiKey,
+      openRouterTranscriptionModel,
     );
   }
 
@@ -100,22 +118,45 @@ export class AIMessages {
     return new AIMessage(message);
   }
 
+  private static resolveAudioProvider(
+    provider: "openai" | "gemini" | "openrouter" | "auto",
+    openAIApiKey?: string,
+    openRouterApiKey?: string,
+  ): "openai" | "gemini" | "openrouter" {
+    if (provider !== "auto") return provider;
+    if (openAIApiKey) return "openai";
+    if (openRouterApiKey) return "openrouter";
+    return "gemini";
+  }
+
   private static async createHumanMessageWithAudio(
     audioBuffer: AudioBuffer,
     text?: string,
     mimeType?: AudioMimeType,
     filename?: string,
-    provider: "openai" | "gemini" | "auto" = "auto",
-    openAIApiKey?: string
+    provider: "openai" | "gemini" | "openrouter" = "gemini",
+    openAIApiKey?: string,
+    openRouterApiKey?: string,
+    openRouterTranscriptionModel = "openai/whisper-1",
   ): Promise<HumanMessage> {
-    // Para OpenAI, faz transcrição prévia automaticamente devido à limitação da API
-    if (provider === "openai")
+    if (provider === "openai") {
       return await this.processAudioOpenAi(
         audioBuffer,
         mimeType,
         text,
-        openAIApiKey
+        openAIApiKey,
+      );
+    }
+
+    if (provider === "openrouter") {
+      return await this.processAudioOpenRouter(
+        audioBuffer,
+        mimeType,
+        text,
+        openRouterApiKey,
+        openRouterTranscriptionModel,
       );
+    }
 
     // Para Gemini e outros, usa multimodal direto (trabalho síncrono, mas retorna Promise para compatibilidade)
     const base64Data = AudioUtils.bufferToBase64(audioBuffer);
@@ -168,10 +209,10 @@ export class AIMessages {
         ? { format: mimeType }
         : { language: "pt" };
 
-      const transcribedText = await AIAudioTranscription.transcribeWithWhisper(
+      const transcribedText = await AIAudio.transcribeWithWhisper(
         audioBuffer,
         transcriptionOptions,
-        openAIApiKey
+        openAIApiKey,
       );
 
       // Combina o texto original (se fornecido) com a transcrição
@@ -192,4 +233,35 @@ export class AIMessages {
       );
     }
   }
+
+  private static async processAudioOpenRouter(
+    audioBuffer: AudioBuffer,
+    mimeType?: AudioMimeType,
+    text?: string,
+    openRouterApiKey?: string,
+    openRouterTranscriptionModel = "openai/whisper-1",
+  ) {
+    if (!openRouterApiKey) {
+      throw new Error(
+        "openRouterApiKey é necessária quando provider é 'openrouter'.",
+      );
+    }
+
+    const format = mimeType ?? AudioUtils.detectAudioMimeType(audioBuffer);
+    const { text: transcribedText } = await AIAudio.transcribeOpenRouter(
+      audioBuffer,
+      {
+        model: openRouterTranscriptionModel,
+        format,
+        ...(text ? {} : { language: "pt" }),
+      },
+      openRouterApiKey,
+    );
+
+    const finalText = text
+      ? `${text}\n\nÁudio transcrito: ${transcribedText}`
+      : `Áudio transcrito: ${transcribedText}`;
+
+    return new HumanMessage(finalText);
+  }
 }