@luanpoppe/ai 1.1.4 → 1.1.6

package/tests/e2e/ai-local-models.test.ts

@@ -0,0 +1,65 @@
+import { AI } from "../../src/index";
+import { AIMessages } from "../../src/langchain/messages";
+import "dotenv/config";
+
+const ollamaBaseUrl = process.env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434";
+const ollamaModel = process.env.OLLAMA_MODEL_NAME ?? "llama3.2";
+const localBaseUrl = process.env.LOCAL_BASE_URL;
+const localModel = process.env.LOCAL_MODEL_NAME ?? "local-model";
+
+const timeout = 180 * 1000;
+
+describe("AI E2E — modelos locais", () => {
+  describe.skipIf(!process.env.OLLAMA_E2E)(
+    "Ollama (API nativa, prefixo ollama/)",
+    () => {
+      it(
+        "deve responder via ChatOllama",
+        { timeout },
+        async () => {
+          const ai = new AI({ ollamaBaseUrl });
+
+          const result = await ai.call({
+            aiModel: `ollama/${ollamaModel}`,
+            messages: [
+              AIMessages.human(
+                "Responda apenas com: teste ollama ok",
+              ),
+            ],
+          });
+
+          expect(result.text).toBeDefined();
+          expect(result.text.length).toBeGreaterThan(0);
+        },
+      );
+    },
+  );
+
+  describe.skipIf(!localBaseUrl)(
+    "OpenAI-compatible (prefixo local/)",
+    () => {
+      it(
+        "deve responder via servidor local (LM Studio, Ollama /v1, etc.)",
+        { timeout },
+        async () => {
+          const ai = new AI({
+            localBaseUrl,
+            localApiKey: process.env.LOCAL_API_KEY,
+          });
+
+          const result = await ai.call({
+            aiModel: `local/${localModel}`,
+            messages: [
+              AIMessages.human(
+                "Responda apenas com: teste local ok",
+              ),
+            ],
+          });
+
+          expect(result.text).toBeDefined();
+          expect(result.text.length).toBeGreaterThan(0);
+        },
+      );
+    },
+  );
+});

package/tests/unit/audio/index.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { AIAudio, ANTHROPIC_NO_NATIVE_AUDIO } from "../../../src/index.js";
+
+describe("AIAudio facade", () => {
+  it("expõe métodos estáticos principais", () => {
+    expect(typeof AIAudio.transcribeWithWhisper).toBe("function");
+    expect(typeof AIAudio.transcribeDetailedOpenAI).toBe("function");
+    expect(typeof AIAudio.transcribeOpenRouter).toBe("function");
+    expect(typeof AIAudio.speakOpenAI).toBe("function");
+    expect(typeof AIAudio.speakOpenRouter).toBe("function");
+    expect(typeof AIAudio.transcribeWithGeminiPrompt).toBe("function");
+  });
+
+  it("exporta constante Anthropic", () => {
+    expect(ANTHROPIC_NO_NATIVE_AUDIO).toContain("Anthropic");
+  });
+});

package/tests/unit/audio/speech-openai.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { speakOpenAI } from "../../../src/audio/speech-openai.js";
+
+const mockSpeechCreate = vi.fn();
+
+vi.mock("openai", () => ({
+  default: class MockOpenAI {
+    audio = {
+      speech: {
+        create: mockSpeechCreate,
+      },
+    };
+  },
+}));
+
+describe("speech-openai", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSpeechCreate.mockResolvedValue({
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    });
+  });
+
+  it("cria speech com voice e model padrão", async () => {
+    const result = await speakOpenAI(
+      "Olá",
+      { voice: "nova" },
+      "sk-test",
+    );
+
+    expect(result.audio).toEqual(Buffer.from([1, 2, 3]));
+    expect(result.contentType).toBe("audio/mpeg");
+    expect(mockSpeechCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "gpt-4o-mini-tts",
+        voice: "nova",
+        input: "Olá",
+        response_format: "mp3",
+      }),
+    );
+  });
+
+  it("repassa instructions para gpt-4o-mini-tts", async () => {
+    await speakOpenAI(
+      "Oi",
+      {
+        voice: "alloy",
+        model: "gpt-4o-mini-tts",
+        instructions: "Fale devagar.",
+      },
+      "sk-test",
+    );
+
+    expect(mockSpeechCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ instructions: "Fale devagar." }),
+    );
+  });
+
+  it("rejeita instructions em tts-1", async () => {
+    await expect(
+      speakOpenAI(
+        "Oi",
+        { voice: "alloy", model: "tts-1", instructions: "x" },
+        "sk-test",
+      ),
+    ).rejects.toThrow("instructions");
+  });
+
+  it("exige API key", async () => {
+    await expect(speakOpenAI("Oi", { voice: "nova" })).rejects.toThrow(
+      "OpenAI API key",
+    );
+  });
+});

package/tests/unit/audio/speech-openrouter.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { speakOpenRouter } from "../../../src/audio/speech-openrouter.js";
+
+const mockSpeechCreate = vi.fn();
+let capturedBaseURL: string | undefined;
+
+vi.mock("../../../src/audio/openrouter-client.js", () => ({
+  createOpenRouterOpenAIClient: (apiKey: string) => {
+    capturedBaseURL = "https://openrouter.ai/api/v1";
+    return {
+      apiKey,
+      audio: {
+        speech: { create: mockSpeechCreate },
+      },
+    };
+  },
+}));
+
+describe("speech-openrouter", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    capturedBaseURL = undefined;
+    mockSpeechCreate.mockResolvedValue({
+      arrayBuffer: async () => new Uint8Array([9, 8]).buffer,
+    });
+  });
+
+  it("cria speech com model slug e voice", async () => {
+    const result = await speakOpenRouter(
+      "Resumo",
+      {
+        model: "google/gemini-2.5-flash-preview-tts",
+        voice: "Kore",
+        responseFormat: "mp3",
+      },
+      "or-key",
+    );
+
+    expect(result.audio).toEqual(Buffer.from([9, 8]));
+    expect(mockSpeechCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "google/gemini-2.5-flash-preview-tts",
+        voice: "Kore",
+        input: "Resumo",
+      }),
+    );
+  });
+
+  it("mescla instructions em provider.options sem apagar only", async () => {
+    await speakOpenRouter(
+      "Oi",
+      {
+        model: "deepseek/some-tts",
+        voice: "alloy",
+        instructions: "Tom formal.",
+      },
+      "or-key",
+    );
+
+    const body = mockSpeechCreate.mock.calls[0][0] as Record<string, unknown>;
+    const provider = body.provider as Record<string, unknown>;
+    expect(provider.only).toEqual(["deepseek"]);
+    expect(provider.options).toEqual({
+      openai: { instructions: "Tom formal." },
+    });
+  });
+
+  it("usa pcm por padrão para modelos Gemini TTS", async () => {
+    await speakOpenRouter(
+      "Oi",
+      {
+        model: "google/gemini-3.1-flash-tts-preview",
+        voice: "Kore",
+      },
+      "or-key",
+    );
+
+    expect(mockSpeechCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ response_format: "pcm" }),
+    );
+  });
+
+  it("exige model e voice", async () => {
+    await expect(
+      speakOpenRouter("x", { model: "", voice: "a" }, "k"),
+    ).rejects.toThrow("model é obrigatório");
+  });
+});

package/tests/unit/audio/transcription-openai.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  transcribeDetailedOpenAI,
+  transcribeToSrtOpenAI,
+  transcribeToVttOpenAI,
+  transcribeDiarizedOpenAI,
+  translateOpenAI,
+  transcribeWithWhisperOpenAI,
+} from "../../../src/audio/transcription-openai.js";
+
+const mockTranscriptionsCreate = vi.fn();
+const mockTranslationsCreate = vi.fn();
+
+vi.mock("openai", () => ({
+  default: class MockOpenAI {
+    audio = {
+      transcriptions: { create: mockTranscriptionsCreate },
+      translations: { create: mockTranslationsCreate },
+    };
+  },
+  toFile: async (buffer: Buffer, filename: string) =>
+    new File([new Uint8Array(buffer)], filename, { type: "audio/mpeg" }),
+}));
+
+describe("transcription-openai", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("transcribeDetailedOpenAI mapeia verbose_json com words", async () => {
+    mockTranscriptionsCreate.mockResolvedValue({
+      text: "olá",
+      language: "pt",
+      duration: 1.2,
+      words: [{ word: "olá", start: 0, end: 0.5 }],
+      segments: [{ id: 0, start: 0, end: 0.5, text: "olá" }],
+    });
+
+    const result = await transcribeDetailedOpenAI(
+      Buffer.from("audio"),
+      {
+        model: "whisper-1",
+        responseFormat: "verbose_json",
+        timestampGranularities: ["word"],
+      },
+      "sk-test",
+    );
+
+    expect(result.text).toBe("olá");
+    expect(result.words).toHaveLength(1);
+    expect(result.segments).toHaveLength(1);
+  });
+
+  it("transcribeToSrtOpenAI usa response_format srt", async () => {
+    mockTranscriptionsCreate.mockResolvedValue("1\n00:00:00,000 --> 00:00:01,000\nolá");
+
+    const srt = await transcribeToSrtOpenAI(
+      Buffer.from("audio"),
+      { languageIn2Digits: "pt" },
+      "sk-test",
+    );
+
+    expect(srt).toContain("olá");
+    expect(mockTranscriptionsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ response_format: "srt", model: "whisper-1" }),
+    );
+  });
+
+  it("transcribeToVttOpenAI usa response_format vtt", async () => {
+    mockTranscriptionsCreate.mockResolvedValue("WEBVTT\n\n00:00:00.000 --> 00:00:01.000\nolá");
+
+    const vtt = await transcribeToVttOpenAI(Buffer.from("audio"), {}, "sk-test");
+
+    expect(vtt).toContain("WEBVTT");
+    expect(mockTranscriptionsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ response_format: "vtt" }),
+    );
+  });
+
+  it("transcribeDiarizedOpenAI mapeia speakers", async () => {
+    mockTranscriptionsCreate.mockResolvedValue({
+      text: "fala a fala b",
+      segments: [
+        { speaker: "A", start: 0, end: 1, text: "fala a" },
+        { speaker: "B", start: 1, end: 2, text: "fala b" },
+      ],
+    });
+
+    const result = await transcribeDiarizedOpenAI(Buffer.from("audio"), {}, "sk-test");
+
+    expect(result.speakers).toHaveLength(2);
+    expect(result.speakers?.[0].speaker).toBe("A");
+    expect(mockTranscriptionsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "gpt-4o-transcribe-diarize",
+        response_format: "diarized_json",
+      }),
+    );
+  });
+
+  it("translateOpenAI chama translations.create", async () => {
+    mockTranslationsCreate.mockResolvedValue({ text: "hello" });
+
+    const text = await translateOpenAI(Buffer.from("audio"), {}, "sk-test");
+
+    expect(text).toBe("hello");
+    expect(mockTranslationsCreate).toHaveBeenCalled();
+  });
+
+  it("rejeita timestampGranularities fora de whisper-1 verbose_json", async () => {
+    await expect(
+      transcribeDetailedOpenAI(Buffer.from("x"), {
+        model: "gpt-4o-transcribe",
+        responseFormat: "json",
+        timestampGranularities: ["word"],
+      }),
+    ).rejects.toThrow("timestampGranularities");
+  });
+
+  it("transcribeWithWhisperOpenAI retorna string", async () => {
+    mockTranscriptionsCreate.mockResolvedValue("texto simples");
+
+    const text = await transcribeWithWhisperOpenAI(Buffer.from("audio"), {}, "sk-test");
+
+    expect(text).toBe("texto simples");
+    expect(mockTranscriptionsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ response_format: "text" }),
+    );
+  });
+});

package/tests/unit/audio/transcription-openrouter.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { transcribeOpenRouter } from "../../../src/audio/transcription-openrouter.js";
+
+const mockFetch = vi.fn();
+
+vi.stubGlobal("fetch", mockFetch);
+
+describe("transcription-openrouter", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        text: "transcrito via OR",
+        usage: { seconds: 2, cost: 0.001 },
+      }),
+    });
+  });
+
+  it("envia input_audio base64 e model", async () => {
+    const buf = Buffer.from("fake-audio");
+    const result = await transcribeOpenRouter(
+      buf,
+      { model: "openai/whisper-1", format: "mp3", language: "pt" },
+      "or-key",
+    );
+
+    expect(result.text).toBe("transcrito via OR");
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://openrouter.ai/api/v1/audio/transcriptions",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          Authorization: "Bearer or-key",
+        }),
+      }),
+    );
+
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0][1] as RequestInit).body as string,
+    );
+    expect(body.model).toBe("openai/whisper-1");
+    expect(body.input_audio.format).toBe("mp3");
+    expect(body.input_audio.data).toBe(buf.toString("base64"));
+    expect(body.language).toBe("pt");
+  });
+
+  it("aplica provider default deepseek para modelos deepseek", async () => {
+    await transcribeOpenRouter(
+      Buffer.from("x"),
+      { model: "deepseek/some-stt" },
+      "or-key",
+    );
+
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0][1] as RequestInit).body as string,
+    );
+    expect(body.provider).toEqual({ only: ["deepseek"] });
+  });
+
+  it("exige openRouterApiKey", async () => {
+    await expect(
+      transcribeOpenRouter(Buffer.from("x"), { model: "openai/whisper-1" }),
+    ).rejects.toThrow("OpenRouter API key");
+  });
+
+  it("propaga erro HTTP", async () => {
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 400,
+      text: async () => "bad request",
+    });
+
+    await expect(
+      transcribeOpenRouter(
+        Buffer.from("x"),
+        { model: "openai/whisper-1" },
+        "or-key",
+      ),
+    ).rejects.toThrow("OpenRouter STT falhou");
+  });
+});

package/tests/unit/embeddings/embed-gemini.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { embedGemini } from "../../../src/embeddings/embed-gemini.js";
+
+const mockEmbedQuery = vi.fn();
+const mockEmbedDocuments = vi.fn();
+
+vi.mock("@langchain/google-genai", () => ({
+  GoogleGenerativeAIEmbeddings: class MockGoogleGenerativeAIEmbeddings {
+    constructor(public params: Record<string, unknown>) {}
+    embedQuery = mockEmbedQuery;
+    embedDocuments = mockEmbedDocuments;
+  },
+}));
+
+describe("embed-gemini", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEmbedQuery.mockResolvedValue([0.5, 0.6]);
+    mockEmbedDocuments.mockResolvedValue([
+      [0.1, 0.2],
+      [0.3, 0.4],
+    ]);
+  });
+
+  it("embedQuery para input único", async () => {
+    const result = await embedGemini(
+      "hello",
+      { model: "gemini-embedding-001" },
+      "gemini-key",
+    );
+
+    expect(result.embeddings).toEqual([[0.5, 0.6]]);
+    expect(mockEmbedQuery).toHaveBeenCalledWith("hello");
+  });
+
+  it("embedDocuments para lote", async () => {
+    const result = await embedGemini(
+      ["a", "b"],
+      { model: "gemini-embedding-001", taskType: "RETRIEVAL_DOCUMENT" },
+      "gemini-key",
+    );
+
+    expect(result.embeddings).toHaveLength(2);
+    expect(mockEmbedDocuments).toHaveBeenCalledWith(["a", "b"]);
+  });
+
+  it("exige googleGeminiToken", async () => {
+    await expect(
+      embedGemini("x", { model: "gemini-embedding-001" }),
+    ).rejects.toThrow("googleGeminiToken");
+  });
+});

package/tests/unit/embeddings/embed-openai.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { embedOpenAI } from "../../../src/embeddings/embed-openai.js";
+
+const mockEmbeddingsCreate = vi.fn();
+
+vi.mock("openai", () => ({
+  default: class MockOpenAI {
+    embeddings = { create: mockEmbeddingsCreate };
+  },
+}));
+
+describe("embed-openai", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEmbeddingsCreate.mockResolvedValue({
+      model: "text-embedding-3-small",
+      data: [
+        { index: 0, embedding: [0.1, 0.2] },
+        { index: 1, embedding: [0.3, 0.4] },
+      ],
+      usage: { prompt_tokens: 10, total_tokens: 10 },
+    });
+  });
+
+  it("cria embeddings para string única", async () => {
+    mockEmbeddingsCreate.mockResolvedValueOnce({
+      model: "text-embedding-3-small",
+      data: [{ index: 0, embedding: [0.1, 0.2] }],
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+
+    const result = await embedOpenAI(
+      "hello",
+      { model: "text-embedding-3-small" },
+      "sk-test",
+    );
+
+    expect(result.embeddings).toEqual([[0.1, 0.2]]);
+    expect(mockEmbeddingsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "text-embedding-3-small",
+        input: "hello",
+      }),
+    );
+  });
+
+  it("cria embeddings em lote", async () => {
+    const result = await embedOpenAI(
+      ["a", "b"],
+      { model: "text-embedding-3-large", dimensions: 256 },
+      "sk-test",
+    );
+
+    expect(result.embeddings).toHaveLength(2);
+    expect(mockEmbeddingsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        input: ["a", "b"],
+        dimensions: 256,
+      }),
+    );
+  });
+
+  it("exige API key", async () => {
+    await expect(
+      embedOpenAI("x", { model: "text-embedding-3-small" }),
+    ).rejects.toThrow("OpenAI API key");
+  });
+});

package/tests/unit/embeddings/embed-openrouter.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { embedOpenRouter } from "../../../src/embeddings/embed-openrouter.js";
+
+const mockEmbeddingsCreate = vi.fn();
+
+vi.mock("../../../src/utils/openrouter-client.js", () => ({
+  createOpenRouterOpenAIClient: () => ({
+    embeddings: { create: mockEmbeddingsCreate },
+  }),
+}));
+
+describe("embed-openrouter", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEmbeddingsCreate.mockResolvedValue({
+      model: "openai/text-embedding-3-small",
+      data: [{ index: 0, embedding: [1, 2, 3] }],
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+  });
+
+  it("remove prefixo openrouter/ do model", async () => {
+    const result = await embedOpenRouter(
+      "test",
+      { model: "openrouter/openai/text-embedding-3-small" },
+      "or-key",
+    );
+
+    expect(result.embeddings[0]).toEqual([1, 2, 3]);
+    expect(mockEmbeddingsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "openai/text-embedding-3-small",
+        input: "test",
+      }),
+    );
+  });
+
+  it("repassa provider quando informado", async () => {
+    await embedOpenRouter(
+      "test",
+      {
+        model: "openrouter/openai/text-embedding-3-small",
+        openRouterProvider: { sort: "price" },
+      },
+      "or-key",
+    );
+
+    expect(mockEmbeddingsCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: { sort: "price" },
+      }),
+    );
+  });
+
+  it("exige openRouterApiKey", async () => {
+    await expect(
+      embedOpenRouter("x", {
+        model: "openrouter/openai/text-embedding-3-small",
+      }),
+    ).rejects.toThrow("OpenRouter API key");
+  });
+});

package/tests/unit/embeddings/index.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  AIEmbeddings,
+  ANTHROPIC_NO_NATIVE_EMBEDDINGS,
+} from "../../../src/index.js";
+
+vi.mock("../../../src/embeddings/embed-openai.js", () => ({
+  embedOpenAI: vi.fn().mockResolvedValue({
+    embeddings: [[1]],
+    model: "text-embedding-3-small",
+  }),
+}));
+
+vi.mock("../../../src/embeddings/embed-openrouter.js", () => ({
+  embedOpenRouter: vi.fn().mockResolvedValue({
+    embeddings: [[2]],
+    model: "openai/text-embedding-3-small",
+  }),
+}));
+
+vi.mock("../../../src/embeddings/embed-gemini.js", () => ({
+  embedGemini: vi.fn().mockResolvedValue({
+    embeddings: [[3]],
+    model: "gemini-embedding-001",
+  }),
+}));
+
+describe("AIEmbeddings facade", () => {
+  it("expõe métodos estáticos", () => {
+    expect(typeof AIEmbeddings.embedOpenAI).toBe("function");
+    expect(typeof AIEmbeddings.embedOpenRouter).toBe("function");
+    expect(typeof AIEmbeddings.embedGemini).toBe("function");
+    expect(typeof AIEmbeddings.embedDocuments).toBe("function");
+    expect(typeof AIEmbeddings.embedQuery).toBe("function");
+  });
+
+  it("exporta constante Anthropic", () => {
+    expect(ANTHROPIC_NO_NATIVE_EMBEDDINGS).toContain("Anthropic");
+  });
+
+  it("embedQuery roteia por prefixo openrouter/", async () => {
+    const { embedOpenRouter } = await import(
+      "../../../src/embeddings/embed-openrouter.js"
+    );
+
+    const vec = await AIEmbeddings.embedQuery(
+      "q",
+      { model: "openrouter/openai/text-embedding-3-small" },
+      { openRouterApiKey: "k" },
+    );
+
+    expect(vec).toEqual([2]);
+    expect(embedOpenRouter).toHaveBeenCalled();
+  });
+});