@luanpoppe/ai 1.1.5 → 1.1.6

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);
+  }
 }

package/src/langchain/models.ts

@@ -2,20 +2,90 @@ import {
   ChatGoogleGenerativeAI,
   GoogleGenerativeAIChatInput,
 } from "@langchain/google-genai";
+import { ChatOllama, type ChatOllamaInput } from "@langchain/ollama";
 import { ChatOpenAI, ChatOpenAIFields } from "@langchain/openai";
+import type { OpenRouterProviderPreferences } from "../@types/openrouter-provider";
+
+export const DEFAULT_OLLAMA_BASE_URL = "http://127.0.0.1:11434";
+
+export const DEFAULT_LOCAL_API_KEY = "not-needed";
+
+export type {
+  OpenRouterMaxPrice,
+  OpenRouterProviderPreferences,
+  OpenRouterProviderSort,
+} from "../@types/openrouter-provider";
 
 /** Nível de esforço de raciocínio para modelos OpenAI (o1, gpt-5, etc.). Valores: "low" | "medium" | "high" */
 export type ReasoningEffort = "low" | "medium" | "high";
 
+export type OllamaModelConfig = {
+  model: string;
+  baseUrl?: string | undefined;
+  maxTokens?: number | undefined;
+  temperature?: number | undefined;
+  numCtx?: number | undefined;
+};
+
+export type OpenAICompatibleModelConfig = {
+  model: string;
+  baseURL: string;
+  apiKey?: string | undefined;
+  maxTokens?: number | undefined;
+  temperature?: number | undefined;
+};
+
 export type LLMModelConfig = {
   model: string;
   apiKey?: string | undefined;
+  /** Override da URL do servidor (Ollama nativo ou OpenAI-compatible local) */
+  baseUrl?: string | undefined;
   maxTokens?: number | undefined;
   temperature?: number | undefined;
+  /** Tamanho do contexto (Ollama nativo, `num_ctx`) */
+  numCtx?: number | undefined;
   /** Nível de esforço de raciocínio (modelos OpenAI: o1, gpt-5, etc.) */
   reasoningEffort?: ReasoningEffort | undefined;
+  /** Preferências de roteamento de providers do OpenRouter */
+  openRouterProvider?: OpenRouterProviderPreferences | undefined;
+  /**
+   * Se true, não aplica `only: ["deepseek"]` em modelos `deepseek/*` via OpenRouter.
+   * Use para aceitar o roteamento padrão do OpenRouter (todos os providers).
+   */
+  openRouterAllowAllProviders?: boolean | undefined;
+  /**
+   * Força `response_format: { type: "json_object" }` no OpenRouter (ex.: DeepSeek).
+   * Uso interno via `callStructuredOutput`.
+   */
+  openRouterForceJsonObject?: boolean | undefined;
 };
 
+const DEEPSEEK_OPENROUTER_PROVIDER: OpenRouterProviderPreferences = {
+  only: ["deepseek"],
+};
+
+export function resolveOpenRouterProvider(
+  model: string,
+  config: Pick<
+    LLMModelConfig,
+    "openRouterProvider" | "openRouterAllowAllProviders"
+  >,
+): OpenRouterProviderPreferences | undefined {
+  if (config.openRouterProvider !== undefined) {
+    return config.openRouterProvider;
+  }
+
+  if (config.openRouterAllowAllProviders === true) {
+    return undefined;
+  }
+
+  if (model.startsWith("deepseek/")) {
+    return DEEPSEEK_OPENROUTER_PROVIDER;
+  }
+
+  return undefined;
+}
+
 export class AIModels {
   static gpt(params: LLMModelConfig) {
     const { model, apiKey, maxTokens, temperature, reasoningEffort } = params;
@@ -59,7 +129,16 @@ export class AIModels {
   }
 
   static openrouter(params: LLMModelConfig) {
-    const { apiKey, maxTokens, model, temperature, reasoningEffort } = params;
+    const {
+      apiKey,
+      maxTokens,
+      model,
+      temperature,
+      reasoningEffort,
+      openRouterProvider,
+      openRouterAllowAllProviders,
+      openRouterForceJsonObject,
+    } = params;
 
     if (!apiKey)
       throw new Error(
@@ -76,13 +155,61 @@ export class AIModels {
 
     if (maxTokens) options.maxTokens = maxTokens;
     if (temperature) options.temperature = temperature;
-    if (reasoningEffort) {
+
+    const provider = resolveOpenRouterProvider(model, {
+      openRouterProvider,
+      openRouterAllowAllProviders,
+    });
+
+    if (reasoningEffort || provider || openRouterForceJsonObject) {
       options.modelKwargs = {
         ...(options.modelKwargs ?? {}),
-        reasoning_effort: reasoningEffort,
+        ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+        ...(provider ? { provider } : {}),
+        ...(openRouterForceJsonObject
+          ? { response_format: { type: "json_object" } }
+          : {}),
       };
     }
 
     return new ChatOpenAI(options);
   }
+
+  static ollama(params: OllamaModelConfig) {
+    const { model, baseUrl, maxTokens, temperature, numCtx } = params;
+
+    const options: ChatOllamaInput = {
+      model,
+      baseUrl: baseUrl ?? DEFAULT_OLLAMA_BASE_URL,
+    };
+
+    if (temperature !== undefined) options.temperature = temperature;
+    if (numCtx !== undefined) options.numCtx = numCtx;
+    if (maxTokens !== undefined) options.numPredict = maxTokens;
+
+    return new ChatOllama(options);
+  }
+
+  static openaiCompatible(params: OpenAICompatibleModelConfig) {
+    const { model, baseURL, apiKey, maxTokens, temperature } = params;
+
+    if (!baseURL) {
+      throw new Error(
+        "baseURL é obrigatório para servidores OpenAI-compatible (LM Studio, Ollama /v1, vLLM, etc.).",
+      );
+    }
+
+    const options: ChatOpenAIFields = {
+      model,
+      apiKey: apiKey ?? DEFAULT_LOCAL_API_KEY,
+      configuration: {
+        baseURL,
+      },
+    };
+
+    if (maxTokens) options.maxTokens = maxTokens;
+    if (temperature !== undefined) options.temperature = temperature;
+
+    return new ChatOpenAI(options);
+  }
 }

package/src/langchain/structured-output.ts

@@ -0,0 +1,77 @@
+import type { BaseMessage } from "langchain";
+import z from "zod";
+
+/** Modelos DeepSeek (direto ou via OpenRouter) não aceitam `json_schema`; apenas `json_object`. */
+export function isDeepSeekJsonObjectOnlyModel(aiModel: string): boolean {
+  return (
+    aiModel.startsWith("openrouter/deepseek/") || aiModel.startsWith("deepseek/")
+  );
+}
+
+export function buildJsonObjectSystemAppend(schema: z.ZodSchema): string {
+  const jsonSchema = z.toJSONSchema(schema);
+  return [
+    "",
+    "IMPORTANTE: Responda somente com um objeto JSON válido (sem markdown, sem texto extra).",
+    "O JSON deve seguir este schema:",
+    JSON.stringify(jsonSchema, null, 2),
+  ].join("\n");
+}
+
+export function mergeSystemPromptWithJsonSchema(
+  systemPrompt: string | undefined,
+  schema: z.ZodSchema,
+): string {
+  const base = systemPrompt?.trim() ?? "";
+  const append = buildJsonObjectSystemAppend(schema);
+  return base ? `${base}\n${append}` : append.trim();
+}
+
+function contentToString(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (part && typeof part === "object" && "text" in part) {
+          return String((part as { text?: unknown }).text ?? "");
+        }
+        return "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** Extrai e faz parse de JSON na última mensagem do assistente (suporta fences ```json). */
+export function parseJsonFromAssistantMessages(
+  messages: BaseMessage[],
+): unknown {
+  const last = messages.at(-1);
+  if (!last) {
+    throw new Error(
+      "[@luanpoppe/ai] Nenhuma mensagem do assistente para extrair JSON.",
+    );
+  }
+
+  const raw = contentToString((last as { content?: unknown }).content).trim();
+  if (!raw) {
+    throw new Error("[@luanpoppe/ai] Resposta vazia ao extrair JSON estruturado.");
+  }
+
+  const fenced = raw.match(/^```(?:json)?\s*([\s\S]*?)```$/i);
+  const jsonText = (fenced?.[1] ?? raw).trim();
+
+  try {
+    return JSON.parse(jsonText);
+  } catch {
+    const start = jsonText.indexOf("{");
+    const end = jsonText.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      return JSON.parse(jsonText.slice(start, end + 1));
+    }
+    throw new Error(
+      "[@luanpoppe/ai] Não foi possível fazer parse do JSON retornado pelo modelo.",
+    );
+  }
+}

package/src/utils/openrouter-client.ts

@@ -0,0 +1,10 @@
+import OpenAI from "openai";
+
+export const OPENROUTER_API_BASE = "https://openrouter.ai/api/v1";
+
+export function createOpenRouterOpenAIClient(apiKey: string): OpenAI {
+  return new OpenAI({
+    apiKey,
+    baseURL: OPENROUTER_API_BASE,
+  });
+}

package/tests/e2e/README.md

@@ -25,6 +25,59 @@ O arquivo `.env` é carregado automaticamente pelo `dotenv` configurado no `vite
 
 ## Executando os testes
 
+### DeepSeek structured output
+```bash
+pnpm test:e2e -- ai-deepseek-structured-output
+```
+Requer `OPENROUTER_API_KEY`. Valida `callStructuredOutput` com `openrouter/deepseek/deepseek-v4-flash` e `deepseek-v4-pro`.
+
+### Modelos locais (Ollama + LM Studio / OpenAI-compatible)
+```bash
+pnpm test:e2e -- ai-local-models
+```
+
+**Ollama (prefixo `ollama/`, API nativa):**
+1. Instale e inicie o Ollama (`ollama serve`)
+2. Baixe um modelo: `ollama pull llama3.2`
+3. No `.env`: `OLLAMA_E2E=1`, opcionalmente `OLLAMA_BASE_URL` e `OLLAMA_MODEL_NAME`
+
+**LM Studio / Ollama `/v1` (prefixo `local/`):**
+1. Ative o servidor local compatível com OpenAI (ex.: LM Studio em `http://localhost:1234/v1`)
+2. No `.env`: `LOCAL_BASE_URL=http://localhost:1234/v1` e `LOCAL_MODEL_NAME` com o nome exato do modelo no servidor
+
+```typescript
+const ai = new AI({
+  ollamaBaseUrl: "http://127.0.0.1:11434",
+  localBaseUrl: "http://localhost:1234/v1",
+  localApiKey: "not-needed",
+});
+
+await ai.call({ aiModel: "ollama/llama3.2", messages: [...] });
+await ai.call({ aiModel: "local/seu-modelo", messages: [...] });
+```
+
+Limitações: tools e structured output dependem do modelo local; áudio (STT/TTS) continua via `AIAudio` na nuvem.
+
+### Embeddings (`AIEmbeddings`)
+```bash
+pnpm test:e2e -- ai-embeddings
+```
+- OpenAI: `OPENAI_API_KEY` — `text-embedding-3-small`
+- Gemini: `GOOGLE_GEMINI_TOKEN` — `gemini-embedding-001`
+- OpenRouter: `OPENROUTER_API_KEY` — `openrouter/openai/text-embedding-3-small`
+
+Listar modelos: `GET https://openrouter.ai/api/v1/embeddings/models`
+
+### STT/TTS multiprovider (`AIAudio`)
+```bash
+pnpm test:e2e -- ai-audio-multiprovider
+```
+- OpenAI: `OPENAI_API_KEY` (STT detailed + TTS)
+- OpenRouter: `OPENROUTER_API_KEY` (STT + TTS)
+  - TTS Gemini: `google/gemini-3.1-flash-tts-preview` + `Kore` + `pcm`
+  - TTS Mistral: `mistralai/voxtral-mini-tts-2603` + `en_paul_neutral` + `mp3` (exige providers liberados na conta OR)
+- Listar modelos TTS: `GET https://openrouter.ai/api/v1/models?output_modalities=speech`
+
 ### Todos os testes E2E
 ```bash
 pnpm test:e2e