@luanpoppe/ai 1.1.4 → 1.1.6

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

package/tests/e2e/ai-audio-multiprovider.test.ts

@@ -0,0 +1,118 @@
+import * as fs from "fs";
+import * as path from "path";
+import { AIAudio } from "../../src/index";
+import "dotenv/config";
+
+const AUDIO_FIXTURE_PATH = path.join(
+  process.cwd(),
+  "tests",
+  "e2e",
+  "@fixtures",
+  "audio-teste-saudacao.mp3",
+);
+
+describe("AIAudio multiprovider E2E", () => {
+  const openAIApiKey = process.env.OPENAI_API_KEY;
+  const openRouterApiKey = process.env.OPENROUTER_API_KEY;
+  const timeout = 120_000;
+
+  it(
+    "OpenAI STT + TTS round-trip curto",
+    { timeout },
+    async () => {
+      if (!openAIApiKey) {
+        console.log("OPENAI_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const audioBuffer = fs.readFileSync(AUDIO_FIXTURE_PATH);
+      const { text } = await AIAudio.transcribeDetailedOpenAI(
+        audioBuffer,
+        { languageIn2Digits: "pt", responseFormat: "json" },
+        openAIApiKey,
+      );
+
+      expect(text.length).toBeGreaterThan(0);
+
+      const speech = await AIAudio.speakOpenAI(
+        "OK",
+        { voice: "nova", model: "gpt-4o-mini-tts", responseFormat: "mp3" },
+        openAIApiKey,
+      );
+
+      expect(speech.audio.length).toBeGreaterThan(100);
+    },
+  );
+
+  it(
+    "OpenRouter STT",
+    { timeout },
+    async () => {
+      if (!openRouterApiKey) {
+        console.log("OPENROUTER_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const audioBuffer = fs.readFileSync(AUDIO_FIXTURE_PATH);
+      const result = await AIAudio.transcribeOpenRouter(
+        audioBuffer,
+        {
+          model: "openai/gpt-4o-mini-transcribe",
+          format: "mp3",
+          language: "pt",
+        },
+        openRouterApiKey,
+      );
+
+      expect(result.text.length).toBeGreaterThan(0);
+    },
+  );
+
+  it(
+    "OpenRouter TTS (Gemini — catálogo output_modalities=speech)",
+    { timeout },
+    async () => {
+      if (!openRouterApiKey) {
+        console.log("OPENROUTER_API_KEY não configurada — pulando");
+        return;
+      }
+
+      // Descoberto via GET /api/v1/models?output_modalities=speech
+      const speech = await AIAudio.speakOpenRouter(
+        "Teste de síntese.",
+        {
+          model: "google/gemini-3.1-flash-tts-preview",
+          voice: "Kore",
+        },
+        openRouterApiKey,
+      );
+
+      expect(speech.audio.length).toBeGreaterThan(100);
+      expect(speech.contentType).toBe("audio/pcm");
+    },
+  );
+
+  it(
+    "OpenRouter TTS (Mistral — mp3, requer providers liberados na conta)",
+    { timeout },
+    async () => {
+      if (!openRouterApiKey) {
+        console.log("OPENROUTER_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const speech = await AIAudio.speakOpenRouter(
+        "Hello, this is a synthesis test.",
+        {
+          model: "mistralai/voxtral-mini-tts-2603",
+          voice: "en_paul_neutral",
+          responseFormat: "mp3",
+        },
+        openRouterApiKey,
+      );
+
+      expect(speech.audio.length).toBeGreaterThan(100);
+      expect(speech.contentType).toBe("audio/mpeg");
+    },
+  );
+});

package/tests/e2e/ai-deepseek-structured-output.test.ts

@@ -0,0 +1,133 @@
+import { AI } from "../../src/index";
+import { AIMessages } from "../../src/langchain/messages";
+import z from "zod";
+import "dotenv/config";
+
+describe("AI E2E - DeepSeek Structured Output", () => {
+  const openRouterApiKey = process.env.OPENROUTER_API_KEY;
+  const timeout = 180 * 1000;
+
+  const requireOpenRouter = () => {
+    if (!openRouterApiKey) {
+      console.log("OPENROUTER_API_KEY não está configurada");
+      return false;
+    }
+    return true;
+  };
+
+  it(
+    "deve retornar schema numérico com deepseek-v4-flash",
+    { timeout },
+    async () => {
+      if (!requireOpenRouter()) return;
+
+      const ai = new AI({ openRouterApiKey: openRouterApiKey! });
+      const outputSchema = z.object({
+        sum: z.number(),
+        product: z.number(),
+      });
+
+      const result = await ai.callStructuredOutput({
+        aiModel: "openrouter/deepseek/deepseek-v4-flash",
+        messages: [
+          AIMessages.human(
+            "Calcule a soma e o produto de 7 e 4. Responda em json.",
+          ),
+        ],
+        outputSchema,
+      });
+
+      expect(result.response.sum).toBe(11);
+      expect(result.response.product).toBe(28);
+    },
+  );
+
+  it(
+    "deve extrair nome e idade com deepseek-v4-pro",
+    { timeout },
+    async () => {
+      if (!requireOpenRouter()) return;
+
+      const ai = new AI({ openRouterApiKey: openRouterApiKey! });
+      const outputSchema = z.object({
+        nome: z.string(),
+        idade: z.number(),
+      });
+
+      const result = await ai.callStructuredOutput({
+        aiModel: "openrouter/deepseek/deepseek-v4-pro",
+        messages: [
+          AIMessages.human(
+            "Extraia nome e idade do texto: João tem 30 anos. Responda em json.",
+          ),
+        ],
+        outputSchema,
+      });
+
+      expect(result.response.nome.toLowerCase()).toContain("joão");
+      expect(result.response.idade).toBe(30);
+    },
+  );
+
+  it(
+    "deve suportar campos opcional/nullable com deepseek-v4-flash",
+    { timeout },
+    async () => {
+      if (!requireOpenRouter()) return;
+
+      const ai = new AI({ openRouterApiKey: openRouterApiKey! });
+      const outputSchema = z.object({
+        prontuarioFormal: z
+          .string()
+          .describe("Texto do prontuário")
+          .nullable(),
+        dataConsulta: z
+          .string()
+          .optional()
+          .describe("Data DD/MM/AAAA"),
+      });
+
+      const result = await ai.callStructuredOutput({
+        aiModel: "openrouter/deepseek/deepseek-v4-flash",
+        messages: [
+          AIMessages.human(
+            "Crie um prontuário breve para João, 30 anos, consulta 25/01/2026. Responda em json.",
+          ),
+        ],
+        outputSchema,
+      });
+
+      expect(result.response.prontuarioFormal).toBeDefined();
+      expect(typeof result.response.prontuarioFormal).toBe("string");
+      if (result.response.dataConsulta) {
+        expect(typeof result.response.dataConsulta).toBe("string");
+      }
+    },
+  );
+
+  it(
+    "deve suportar aiModelsFallback deepseek -> openai",
+    { timeout },
+    async () => {
+      if (!requireOpenRouter()) return;
+
+      const ai = new AI({ openRouterApiKey: openRouterApiKey! });
+      const outputSchema = z.object({
+        answer: z.string(),
+      });
+
+      const result = await ai.callStructuredOutput({
+        aiModel: "openrouter/deepseek/deepseek-v4-flash",
+        messages: [
+          AIMessages.human(
+            'Responda em json: { "answer": "fallback deepseek ok" }',
+          ),
+        ],
+        outputSchema,
+        aiModelsFallback: ["openrouter/openai/gpt-5-nano"],
+      });
+
+      expect(result.response.answer.toLowerCase()).toContain("fallback");
+    },
+  );
+});

package/tests/e2e/ai-embeddings.test.ts

@@ -0,0 +1,87 @@
+import { AIEmbeddings } from "../../src/index";
+import "dotenv/config";
+
+describe("AIEmbeddings E2E", () => {
+  const openAIApiKey = process.env.OPENAI_API_KEY;
+  const googleGeminiToken = process.env.GOOGLE_GEMINI_TOKEN;
+  const openRouterApiKey = process.env.OPENROUTER_API_KEY;
+  const timeout = 60_000;
+
+  it(
+    "OpenAI text-embedding-3-small",
+    { timeout },
+    async () => {
+      if (!openAIApiKey) {
+        console.log("OPENAI_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const result = await AIEmbeddings.embedOpenAI(
+        "The quick brown fox jumps over the lazy dog.",
+        { model: "text-embedding-3-small" },
+        openAIApiKey,
+      );
+
+      expect(result.embeddings).toHaveLength(1);
+      expect(result.embeddings[0]!.length).toBeGreaterThan(100);
+    },
+  );
+
+  it(
+    "Gemini gemini-embedding-001",
+    { timeout },
+    async () => {
+      if (!googleGeminiToken) {
+        console.log("GOOGLE_GEMINI_TOKEN não configurada — pulando");
+        return;
+      }
+
+      const vector = await AIEmbeddings.embedQuery(
+        "Semantic search test.",
+        { model: "gemini-embedding-001" },
+        { googleGeminiToken },
+      );
+
+      expect(vector.length).toBeGreaterThan(100);
+    },
+  );
+
+  it(
+    "OpenRouter openai/text-embedding-3-small",
+    { timeout },
+    async () => {
+      if (!openRouterApiKey) {
+        console.log("OPENROUTER_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const result = await AIEmbeddings.embedOpenRouter(
+        ["First document.", "Second document."],
+        { model: "openrouter/openai/text-embedding-3-small" },
+        openRouterApiKey,
+      );
+
+      expect(result.embeddings).toHaveLength(2);
+      expect(result.embeddings[0]!.length).toBeGreaterThan(100);
+    },
+  );
+
+  it(
+    "embedDocuments em lote via roteamento OpenAI",
+    { timeout },
+    async () => {
+      if (!openAIApiKey) {
+        console.log("OPENAI_API_KEY não configurada — pulando");
+        return;
+      }
+
+      const vectors = await AIEmbeddings.embedDocuments(
+        ["doc a", "doc b"],
+        { model: "text-embedding-3-small" },
+        { openAIApiKey },
+      );
+
+      expect(vectors).toHaveLength(2);
+    },
+  );
+});