@luanpoppe/ai 1.1.5 → 1.1.6

package/src/audio/types.ts

@@ -0,0 +1,127 @@
+import type { AudioMimeType } from "../@types/audio";
+import type { OpenRouterProviderPreferences } from "../@types/openrouter-provider";
+
+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 OpenAITranscriptionResponseFormat =
+  | "json"
+  | "text"
+  | "srt"
+  | "verbose_json"
+  | "vtt"
+  | "diarized_json";
+
+export type OpenAITranscriptionOptions = {
+  model?: WhisperModel;
+  languageIn2Digits?: string;
+  prompt?: string;
+  responseFormat?: OpenAITranscriptionResponseFormat;
+  temperature?: number;
+  timestampGranularities?: ("word" | "segment")[];
+  format?: string | AudioMimeType;
+  /** Obrigatório para `gpt-4o-transcribe-diarize` em áudio > 30s */
+  chunkingStrategy?: "auto" | { type: "server_vad" };
+};
+
+export type TranscriptionWord = {
+  word: string;
+  start: number;
+  end: number;
+};
+
+export type TranscriptionSegment = {
+  id?: number;
+  start: number;
+  end: number;
+  text: string;
+};
+
+export type DiarizedSegment = {
+  speaker: string;
+  start: number;
+  end: number;
+  text: string;
+};
+
+export type OpenAITranscriptionDetailed = {
+  text: string;
+  language?: string;
+  duration?: number;
+  words?: TranscriptionWord[];
+  segments?: TranscriptionSegment[];
+  speakers?: DiarizedSegment[];
+};
+
+export type OpenRouterTranscriptionOptions = {
+  model: string;
+  format?: string | AudioMimeType;
+  language?: string;
+  temperature?: number;
+  openRouterProvider?: OpenRouterProviderPreferences;
+  /** Quando true, não aplica default de provider (ex.: deepseek only) */
+  openRouterAllowAllProviders?: boolean;
+};
+
+export type OpenRouterTranscriptionResult = {
+  text: string;
+  usage?: {
+    seconds?: number;
+    cost?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+  };
+};
+
+export type OpenAISpeechModel =
+  | "tts-1"
+  | "tts-1-hd"
+  | "gpt-4o-mini-tts"
+  | "gpt-4o-mini-tts-2025-12-15";
+
+export type OpenAISpeechResponseFormat =
+  | "mp3"
+  | "opus"
+  | "aac"
+  | "flac"
+  | "wav"
+  | "pcm";
+
+export type OpenAISpeechOptions = {
+  model?: OpenAISpeechModel;
+  voice: string;
+  responseFormat?: OpenAISpeechResponseFormat;
+  speed?: number;
+  /** Apenas modelos gpt-4o-mini-tts* */
+  instructions?: string;
+};
+
+export type OpenRouterSpeechOptions = {
+  model: string;
+  voice: string;
+  responseFormat?: "mp3" | "pcm";
+  speed?: number;
+  instructions?: string;
+  openRouterProvider?: OpenRouterProviderPreferences;
+  openRouterAllowAllProviders?: boolean;
+};
+
+export type SpeechResult = {
+  audio: Buffer;
+  contentType: string;
+};
+
+export type GeminiTranscriptionOptions = {
+  model?: string;
+  prompt?: string;
+  googleGeminiToken?: string;
+};
+
+/** A API pública da Anthropic não oferece STT/TTS nativo (apenas texto/imagem/documento). */
+export const ANTHROPIC_NO_NATIVE_AUDIO =
+  "A API da Anthropic não suporta áudio nativo. Use STT (OpenAI/OpenRouter) e depois AI.call com modelos anthropic." as const;

package/src/audio/utils.ts

@@ -0,0 +1,20 @@
+import type { AudioBuffer, AudioMimeType } from "../@types/audio";
+import { MIME_TO_EXTENSION } from "../@types/audio";
+
+export function getAudioExtension(format?: string | AudioMimeType): string {
+  if (!format) return "mp3";
+  if (format.startsWith("audio/")) {
+    return MIME_TO_EXTENSION[format as AudioMimeType] ?? "mp3";
+  }
+  return format.replace(/^\./, "");
+}
+
+export function toAudioBuffer(audioBuffer: AudioBuffer): Buffer {
+  if (audioBuffer instanceof Buffer) return audioBuffer;
+  if (audioBuffer instanceof ArrayBuffer) return Buffer.from(audioBuffer);
+  return Buffer.from(audioBuffer as Uint8Array);
+}
+
+export function bufferToBase64(audioBuffer: AudioBuffer): string {
+  return toAudioBuffer(audioBuffer).toString("base64");
+}

package/src/embeddings/embed-gemini.ts

@@ -0,0 +1,54 @@
+import { GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
+import type { EmbeddingResult, GeminiEmbeddingOptions } from "./types";
+import { normalizeInput } from "./utils";
+
+export async function embedGemini(
+  input: string | string[],
+  options: GeminiEmbeddingOptions,
+  googleGeminiToken?: string,
+): Promise<EmbeddingResult> {
+  if (!googleGeminiToken) {
+    throw new Error(
+      "googleGeminiToken é obrigatório para embedGemini.",
+    );
+  }
+
+  const texts = normalizeInput(input);
+  const modelParams: ConstructorParameters<typeof GoogleGenerativeAIEmbeddings>[0] =
+    {
+      apiKey: googleGeminiToken,
+      model: options.model,
+    };
+  if (options.taskType) {
+    modelParams.taskType = options.taskType as NonNullable<
+      typeof modelParams.taskType
+    >;
+  }
+
+  const embeddingsModel = new GoogleGenerativeAIEmbeddings(modelParams);
+
+  const embeddings =
+    texts.length === 1
+      ? [await embeddingsModel.embedQuery(texts[0]!)]
+      : await embeddingsModel.embedDocuments(texts);
+
+  const result: EmbeddingResult = {
+    embeddings,
+    model: options.model,
+  };
+
+  if (options.dimensions !== undefined && options.model === "gemini-embedding-001") {
+    result.embeddings = result.embeddings.map((vec) =>
+      truncateAndNormalizeL2(vec, options.dimensions!),
+    );
+  }
+
+  return result;
+}
+
+function truncateAndNormalizeL2(vector: number[], dimensions: number): number[] {
+  const truncated = vector.slice(0, dimensions);
+  const norm = Math.sqrt(truncated.reduce((sum, v) => sum + v * v, 0));
+  if (norm === 0) return truncated;
+  return truncated.map((v) => v / norm);
+}

package/src/embeddings/embed-openai.ts

@@ -0,0 +1,53 @@
+import OpenAI from "openai";
+import type { OpenAIEmbeddingOptions, EmbeddingResult } from "./types";
+import { normalizeInput } from "./utils";
+
+function createOpenAIClient(apiKey?: string): OpenAI {
+  if (!apiKey) {
+    throw new Error("OpenAI API key is not passed in the embedding parameters");
+  }
+  return new OpenAI({ apiKey });
+}
+
+function mapEmbeddingResponse(
+  response: OpenAI.CreateEmbeddingResponse,
+  model: string,
+): EmbeddingResult {
+  const embeddings = response.data
+    .sort((a, b) => a.index - b.index)
+    .map((item) => item.embedding as number[]);
+
+  const result: EmbeddingResult = {
+    embeddings,
+    model: response.model ?? model,
+  };
+
+  if (response.usage) {
+    result.usage = {
+      prompt_tokens: response.usage.prompt_tokens,
+      total_tokens: response.usage.total_tokens,
+    };
+  }
+
+  return result;
+}
+
+export async function embedOpenAI(
+  input: string | string[],
+  options: OpenAIEmbeddingOptions,
+  openAIApiKey?: string,
+): Promise<EmbeddingResult> {
+  const openai = createOpenAIClient(openAIApiKey);
+  const texts = normalizeInput(input);
+
+  const response = await openai.embeddings.create({
+    model: options.model,
+    input: texts.length === 1 ? texts[0]! : texts,
+    ...(options.dimensions !== undefined ? { dimensions: options.dimensions } : {}),
+    ...(options.encodingFormat
+      ? { encoding_format: options.encodingFormat }
+      : {}),
+  });
+
+  return mapEmbeddingResponse(response, options.model);
+}

package/src/embeddings/embed-openrouter.ts

@@ -0,0 +1,64 @@
+import type OpenAI from "openai";
+import { resolveOpenRouterProvider } from "../langchain/models";
+import { createOpenRouterOpenAIClient } from "../utils/openrouter-client";
+import type { EmbeddingResult, OpenRouterEmbeddingOptions } from "./types";
+import { normalizeInput, stripOpenRouterPrefix } from "./utils";
+
+function mapEmbeddingResponse(
+  response: OpenAI.CreateEmbeddingResponse,
+  model: string,
+): EmbeddingResult {
+  const embeddings = response.data
+    .sort((a, b) => a.index - b.index)
+    .map((item) => item.embedding as number[]);
+
+  const result: EmbeddingResult = {
+    embeddings,
+    model: response.model ?? model,
+  };
+
+  if (response.usage) {
+    result.usage = {
+      prompt_tokens: response.usage.prompt_tokens,
+      total_tokens: response.usage.total_tokens,
+    };
+  }
+
+  return result;
+}
+
+export async function embedOpenRouter(
+  input: string | string[],
+  options: OpenRouterEmbeddingOptions,
+  openRouterApiKey?: string,
+): Promise<EmbeddingResult> {
+  if (!openRouterApiKey) {
+    throw new Error(
+      "OpenRouter API key is not passed in the embedding parameters",
+    );
+  }
+
+  const openRouterModel = stripOpenRouterPrefix(options.model);
+  const client = createOpenRouterOpenAIClient(openRouterApiKey);
+  const texts = normalizeInput(input);
+
+  const provider = resolveOpenRouterProvider(openRouterModel, {
+    openRouterProvider: options.openRouterProvider,
+    openRouterAllowAllProviders: options.openRouterAllowAllProviders,
+  });
+
+  const body: Record<string, unknown> = {
+    model: openRouterModel,
+    input: texts.length === 1 ? texts[0]! : texts,
+  };
+
+  if (options.dimensions !== undefined) body.dimensions = options.dimensions;
+  if (options.encodingFormat) body.encoding_format = options.encodingFormat;
+  if (provider) body.provider = provider;
+
+  const response = await client.embeddings.create(
+    body as unknown as OpenAI.EmbeddingCreateParams,
+  );
+
+  return mapEmbeddingResponse(response, openRouterModel);
+}

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

@@ -18,7 +18,20 @@ export type {
 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";
@@ -35,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";
@@ -46,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 */