@luanpoppe/ai 1.1.3 → 1.1.4

package/src/utils/image-utils.ts

@@ -0,0 +1,113 @@
+import type { ImageBuffer, ImageMimeType } from "../@types/image";
+
+export class ImageUtils {
+  static bufferToBase64(buffer: ImageBuffer): string {
+    if (buffer instanceof Buffer) {
+      return buffer.toString("base64");
+    }
+
+    if (buffer instanceof ArrayBuffer) {
+      const uint8Array = new Uint8Array(buffer);
+      return Buffer.from(uint8Array).toString("base64");
+    }
+
+    if (buffer instanceof Uint8Array) {
+      return Buffer.from(buffer).toString("base64");
+    }
+
+    throw new Error("Tipo de buffer não suportado");
+  }
+
+  static detectMimeTypeFromExtension(filename?: string): ImageMimeType | null {
+    if (!filename) {
+      return null;
+    }
+
+    const extension = filename.toLowerCase().split(".").pop();
+
+    const mimeTypeMap: Record<string, ImageMimeType> = {
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      png: "image/png",
+      gif: "image/gif",
+      webp: "image/webp",
+    };
+
+    return extension ? mimeTypeMap[extension] ?? null : null;
+  }
+
+  static detectMimeTypeFromBuffer(buffer: ImageBuffer): ImageMimeType | null {
+    let bytes: Uint8Array;
+
+    if (buffer instanceof Buffer) {
+      bytes = new Uint8Array(buffer.slice(0, 16));
+    } else if (buffer instanceof ArrayBuffer) {
+      bytes = new Uint8Array(buffer.slice(0, 16));
+    } else {
+      bytes = buffer.slice(0, 16);
+    }
+
+    // JPEG: FF D8 FF
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+      return "image/jpeg";
+    }
+
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (
+      bytes[0] === 0x89 &&
+      bytes[1] === 0x50 &&
+      bytes[2] === 0x4e &&
+      bytes[3] === 0x47 &&
+      bytes[4] === 0x0d &&
+      bytes[5] === 0x0a &&
+      bytes[6] === 0x1a &&
+      bytes[7] === 0x0a
+    ) {
+      return "image/png";
+    }
+
+    // GIF: 47 49 46 38 (GIF8)
+    if (
+      bytes[0] === 0x47 &&
+      bytes[1] === 0x49 &&
+      bytes[2] === 0x46 &&
+      bytes[3] === 0x38
+    ) {
+      return "image/gif";
+    }
+
+    // WebP: 52 49 46 46 (RIFF) ... 57 45 42 50 (WEBP)
+    if (
+      bytes[0] === 0x52 &&
+      bytes[1] === 0x49 &&
+      bytes[2] === 0x46 &&
+      bytes[3] === 0x46 &&
+      bytes[8] === 0x57 &&
+      bytes[9] === 0x45 &&
+      bytes[10] === 0x42 &&
+      bytes[11] === 0x50
+    ) {
+      return "image/webp";
+    }
+
+    return null;
+  }
+
+  static detectImageMimeType(
+    buffer: ImageBuffer,
+    filename?: string
+  ): ImageMimeType {
+    const mimeFromExtension =
+      ImageUtils.detectMimeTypeFromExtension(filename);
+    if (mimeFromExtension) {
+      return mimeFromExtension;
+    }
+
+    const mimeFromBuffer = ImageUtils.detectMimeTypeFromBuffer(buffer);
+    if (mimeFromBuffer) {
+      return mimeFromBuffer;
+    }
+
+    return "image/jpeg";
+  }
+}

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

@@ -58,7 +58,7 @@ describe("AI Audio E2E Tests", () => {
       }
     );
 
-    it(
+    it.skip(
       "deve processar áudio diretamente com Gemini (multimodal)",
       { timeout },
       async () => {
@@ -132,7 +132,7 @@ describe("AI Audio E2E Tests", () => {
       }
     );
 
-    it(
+    it.skip(
       "deve processar áudio com OpenRouter usando Gemini (multimodal)",
       { timeout },
       async () => {
@@ -168,7 +168,7 @@ describe("AI Audio E2E Tests", () => {
       }
     );
 
-    it(
+    it.skip(
       "deve processar áudio com OpenRouter usando GPT (transcrição prévia com Whisper)",
       { timeout },
       async () => {

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

@@ -0,0 +1,173 @@
+import * as fs from "fs";
+import * as path from "path";
+import { AI } from "../../src/index";
+import { AIMessages } from "../../src/langchain/messages";
+import "dotenv/config";
+
+const IMAGE_FIXTURE_PATH = path.join(
+  process.cwd(),
+  "tests",
+  "e2e",
+  "@fixtures",
+  "imagem-teste-bateria.jpg"
+);
+
+const PROMPT =
+  "Descreva brevemente o que há nesta imagem. Responda em uma frase.";
+
+const EXPECTED_TERMS = [
+  "bateria",
+  "baterista",
+  "pratos",
+  "tambor",
+  "drum",
+  "cymbal",
+  "palco",
+  "stage",
+];
+
+function responseRelatesToImage(text: string): boolean {
+  const lower = text.toLowerCase();
+  return EXPECTED_TERMS.some((term) => lower.includes(term));
+}
+
+describe("AI Image E2E Tests", () => {
+  const openAIApiKey = process.env.OPENAI_API_KEY;
+  const googleGeminiToken = process.env.GOOGLE_GEMINI_TOKEN;
+  const openRouterApiKey = process.env.OPENROUTER_API_KEY;
+
+  const timeout = 180 * 1000;
+
+  describe("Suporte a imagens", () => {
+    it(
+      "deve processar imagem com OpenAI (gpt-4o)",
+      { timeout },
+      async () => {
+        if (!openAIApiKey) {
+          console.log("OPENAI_API_KEY não está configurada");
+          return;
+        }
+        const ai = new AI({
+          openAIApiKey: openAIApiKey!,
+        });
+
+        const imageBuffer = fs.readFileSync(IMAGE_FIXTURE_PATH);
+        const message = AIMessages.humanImage({
+          image: {
+            buffer: imageBuffer,
+            filename: "imagem-teste-bateria.jpg",
+          },
+          text: PROMPT,
+        });
+
+        const result = await ai.call({
+          aiModel: "gpt-4o",
+          messages: [message],
+        });
+
+        expect(result.text).toBeDefined();
+        expect(result.text.length).toBeGreaterThan(0);
+        expect(result.text).not.toContain("Model call failed");
+        expect(result.text).not.toContain("Invalid");
+        expect(responseRelatesToImage(result.text)).toBe(true);
+      }
+    );
+
+    it.skip(
+      "deve processar imagem com Gemini (gemini-2.5-flash)",
+      { timeout },
+      async () => {
+        if (!googleGeminiToken) {
+          console.log("GOOGLE_GEMINI_TOKEN não está configurada");
+          return;
+        }
+        const ai = new AI({
+          googleGeminiToken: googleGeminiToken!,
+        });
+
+        const imageBuffer = fs.readFileSync(IMAGE_FIXTURE_PATH);
+        const message = AIMessages.humanImage({
+          image: {
+            buffer: imageBuffer,
+            filename: "imagem-teste-bateria.jpg",
+          },
+          text: PROMPT,
+        });
+
+        const result = await ai.call({
+          aiModel: "gemini-2.5-flash",
+          messages: [message],
+        });
+
+        expect(result.text).toBeDefined();
+        expect(result.text.length).toBeGreaterThan(0);
+        expect(responseRelatesToImage(result.text)).toBe(true);
+      }
+    );
+
+    it.skip(
+      "deve processar imagem com OpenRouter (openrouter/openai/gpt-4o)",
+      { timeout },
+      async () => {
+        if (!openRouterApiKey) {
+          console.log("OPENROUTER_API_KEY não está configurada");
+          return;
+        }
+        const ai = new AI({
+          openRouterApiKey: openRouterApiKey!,
+        });
+
+        const imageBuffer = fs.readFileSync(IMAGE_FIXTURE_PATH);
+        const message = AIMessages.humanImage({
+          image: {
+            buffer: imageBuffer,
+            filename: "imagem-teste-bateria.jpg",
+          },
+          text: PROMPT,
+        });
+
+        const result = await ai.call({
+          aiModel: "openrouter/openai/gpt-4o",
+          messages: [message],
+        });
+
+        expect(result.text).toBeDefined();
+        expect(result.text.length).toBeGreaterThan(0);
+        expect(result.text).not.toContain("Model call failed");
+        expect(responseRelatesToImage(result.text)).toBe(true);
+      }
+    );
+
+    it.skip(
+      "deve processar imagem com OpenRouter (openrouter/google/gemini-2.5-flash)",
+      { timeout },
+      async () => {
+        if (!openRouterApiKey) {
+          console.log("OPENROUTER_API_KEY não está configurada");
+          return;
+        }
+        const ai = new AI({
+          openRouterApiKey: openRouterApiKey!,
+        });
+
+        const imageBuffer = fs.readFileSync(IMAGE_FIXTURE_PATH);
+        const message = AIMessages.humanImage({
+          image: {
+            buffer: imageBuffer,
+            filename: "imagem-teste-bateria.jpg",
+          },
+          text: PROMPT,
+        });
+
+        const result = await ai.call({
+          aiModel: "openrouter/google/gemini-2.5-flash",
+          messages: [message],
+        });
+
+        expect(result.text).toBeDefined();
+        expect(result.text.length).toBeGreaterThan(0);
+        expect(responseRelatesToImage(result.text)).toBe(true);
+      }
+    );
+  });
+});

package/tests/e2e/ai.test.ts

@@ -45,7 +45,7 @@ describe("AI E2E Tests", () => {
       },
     );
 
-    it(
+    it.skip(
       "deve fazer uma chamada real para Gemini e retornar resposta",
       { timeout },
       async () => {
@@ -139,7 +139,7 @@ describe("AI E2E Tests", () => {
       },
     );
 
-    it(
+    it.skip(
       "deve criar múltiplas mensagens e fazer chamada",
       { timeout },
       async () => {
@@ -348,7 +348,7 @@ describe("AI E2E Tests", () => {
       },
     );
 
-    it(
+    it.skip(
       "deve retornar resposta estruturada com Gemini",
       { timeout },
       async () => {
@@ -484,8 +484,9 @@ describe("AI E2E Tests", () => {
           AIMessages.human("Explique o que é TypeScript em uma frase curta."),
         ];
 
+        // gpt-4o suporta temperature; gpt-5-nano (reasoning) só aceita default
         const result = await ai.call({
-          aiModel: "gpt-5-nano",
+          aiModel: "gpt-4o",
           messages,
           modelConfig: {
             maxTokens: 50,
@@ -499,6 +500,45 @@ describe("AI E2E Tests", () => {
       },
     );
 
+    // Níveis suportados pela API OpenAI (o1, gpt-5-nano, etc.): low, medium, high.
+    // Modelos mais recentes (gpt-5.2) podem suportar também: none, minimal, xhigh.
+    it.each([
+      { reasoningEffort: "low" as const },
+      { reasoningEffort: "medium" as const },
+      { reasoningEffort: "high" as const },
+    ])(
+      "deve usar reasoningEffort=$reasoningEffort em chamada real ao GPT",
+      { timeout },
+      async ({ reasoningEffort }) => {
+        if (!openAIApiKey) {
+          console.log("OPENAI_API_KEY não está configurada");
+          return;
+        }
+        const ai = new AI({
+          openAIApiKey: openAIApiKey!,
+        });
+
+        const messages = [
+          AIMessages.human(
+            "Responda apenas com a palavra 'OK' (modelo de reasoning).",
+          ),
+        ];
+
+        const result = await ai.call({
+          aiModel: "gpt-5-nano",
+          messages,
+          modelConfig: {
+            reasoningEffort,
+          },
+        });
+
+        expect(result.text).toBeDefined();
+        expect(result.text.length).toBeGreaterThan(0);
+        expect(result.messages).toBeDefined();
+        expect(result.messages.length).toBeGreaterThan(0);
+      },
+    );
+
     it(
       "deve usar maxTokens e temperature corretamente com OpenRouter",
       { timeout },

package/tests/unit/index.test.ts

@@ -293,6 +293,101 @@ describe("AI", () => {
       });
     });
 
+    it("deve passar reasoningEffort no modelConfig", async () => {
+      const mockModel = {} as any;
+      const mockMessages = [AIMessages.human("Teste")];
+      const mockResponse = {
+        messages: [{ content: "Resposta" } as any],
+      };
+
+      vi.mocked(AIModels.gpt).mockReturnValue(mockModel);
+      vi.mocked(createAgent).mockReturnValue({
+        invoke: vi.fn().mockResolvedValue(mockResponse),
+      } as any);
+
+      await ai.call({
+        aiModel: "gpt-5-nano",
+        messages: mockMessages,
+        modelConfig: {
+          reasoningEffort: "medium",
+        },
+      });
+
+      expect(AIModels.gpt).toHaveBeenCalledWith({
+        model: "gpt-5-nano",
+        apiKey: mockTokens.openAIApiKey,
+        reasoningEffort: "medium",
+      });
+    });
+
+    it("deve exibir warning quando reasoningEffort é passado com modelo Gemini", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const mockModel = {} as any;
+      const mockMessages = [AIMessages.human("Teste")];
+      const mockResponse = {
+        messages: [{ content: "Resposta" } as any],
+      };
+
+      vi.mocked(AIModels.gemini).mockReturnValue(mockModel);
+      vi.mocked(createAgent).mockReturnValue({
+        invoke: vi.fn().mockResolvedValue(mockResponse),
+      } as any);
+
+      const aiWithGemini = new AI({
+        openAIApiKey: "test-key",
+        googleGeminiToken: "test-gemini-token",
+      });
+
+      await aiWithGemini.call({
+        aiModel: "gemini-2.5-flash",
+        messages: mockMessages,
+        modelConfig: {
+          reasoningEffort: "high",
+        },
+      });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('O modelo "gemini-2.5-flash" não suporta reasoningEffort'),
+      );
+      expect(AIModels.gemini).toHaveBeenCalledWith(
+        expect.not.objectContaining({ reasoningEffort: expect.anything() }),
+      );
+      warnSpy.mockRestore();
+    });
+
+    it("deve exibir warning quando reasoningEffort é passado com OpenRouter não-OpenAI", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const mockModel = {} as any;
+      const mockMessages = [AIMessages.human("Teste")];
+      const mockResponse = {
+        messages: [{ content: "Resposta" } as any],
+      };
+
+      vi.mocked(AIModels.openrouter).mockReturnValue(mockModel);
+      vi.mocked(createAgent).mockReturnValue({
+        invoke: vi.fn().mockResolvedValue(mockResponse),
+      } as any);
+
+      const aiWithOpenRouter = new AI({
+        openRouterApiKey: "test-openrouter-key",
+      });
+
+      await aiWithOpenRouter.call({
+        aiModel: "openrouter/google/gemini-2.5-flash",
+        messages: mockMessages,
+        modelConfig: {
+          reasoningEffort: "high",
+        },
+      });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'O modelo "openrouter/google/gemini-2.5-flash" não suporta reasoningEffort',
+        ),
+      );
+      warnSpy.mockRestore();
+    });
+
     it("deve lançar erro quando memory está ativo e threadId não é fornecido", async () => {
       const aiWithMemory = new AI({
         openAIApiKey: "test-key",

package/tests/unit/langchain/image-utils.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { ImageUtils } from "../../../src/utils/image-utils";
+
+describe("ImageUtils", () => {
+  describe("bufferToBase64", () => {
+    it("deve converter Buffer para base64", () => {
+      const buffer = Buffer.from("test data");
+      const result = ImageUtils.bufferToBase64(buffer);
+      expect(result).toBe("dGVzdCBkYXRh");
+    });
+
+    it("deve converter ArrayBuffer para base64", () => {
+      const arrayBuffer = new TextEncoder().encode("test data").buffer;
+      const result = ImageUtils.bufferToBase64(arrayBuffer);
+      expect(result).toBe("dGVzdCBkYXRh");
+    });
+
+    it("deve converter Uint8Array para base64", () => {
+      const uint8Array = new TextEncoder().encode("test data");
+      const result = ImageUtils.bufferToBase64(uint8Array);
+      expect(result).toBe("dGVzdCBkYXRh");
+    });
+
+    it("deve lançar erro para tipo não suportado", () => {
+      expect(() => {
+        ImageUtils.bufferToBase64("invalid" as any);
+      }).toThrow("Tipo de buffer não suportado");
+    });
+  });
+
+  describe("detectMimeTypeFromExtension", () => {
+    it("deve detectar JPEG pela extensão", () => {
+      expect(ImageUtils.detectMimeTypeFromExtension("imagem.jpg")).toBe(
+        "image/jpeg"
+      );
+      expect(ImageUtils.detectMimeTypeFromExtension("foto.jpeg")).toBe(
+        "image/jpeg"
+      );
+      expect(ImageUtils.detectMimeTypeFromExtension("foto.JPG")).toBe(
+        "image/jpeg"
+      );
+    });
+
+    it("deve detectar PNG pela extensão", () => {
+      expect(ImageUtils.detectMimeTypeFromExtension("imagem.png")).toBe(
+        "image/png"
+      );
+    });
+
+    it("deve detectar GIF pela extensão", () => {
+      expect(ImageUtils.detectMimeTypeFromExtension("animacao.gif")).toBe(
+        "image/gif"
+      );
+    });
+
+    it("deve detectar WebP pela extensão", () => {
+      expect(ImageUtils.detectMimeTypeFromExtension("foto.webp")).toBe(
+        "image/webp"
+      );
+    });
+
+    it("deve retornar null para extensão desconhecida", () => {
+      expect(
+        ImageUtils.detectMimeTypeFromExtension("arquivo.unknown")
+      ).toBeNull();
+    });
+
+    it("deve retornar null quando filename não é fornecido", () => {
+      expect(ImageUtils.detectMimeTypeFromExtension(undefined)).toBeNull();
+    });
+  });
+
+  describe("detectMimeTypeFromBuffer", () => {
+    it("deve detectar JPEG pelos magic bytes", () => {
+      const buffer = Buffer.from([0xff, 0xd8, 0xff, 0x00, 0x00]);
+      expect(ImageUtils.detectMimeTypeFromBuffer(buffer)).toBe("image/jpeg");
+    });
+
+    it("deve detectar PNG pelos magic bytes", () => {
+      const buffer = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00,
+      ]);
+      expect(ImageUtils.detectMimeTypeFromBuffer(buffer)).toBe("image/png");
+    });
+
+    it("deve detectar GIF pelos magic bytes", () => {
+      const buffer = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x00, 0x00]);
+      expect(ImageUtils.detectMimeTypeFromBuffer(buffer)).toBe("image/gif");
+    });
+
+    it("deve detectar WebP pelos magic bytes", () => {
+      const buffer = Buffer.from([
+        0x52, 0x49, 0x46, 0x46, 0x00, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50,
+      ]);
+      expect(ImageUtils.detectMimeTypeFromBuffer(buffer)).toBe("image/webp");
+    });
+
+    it("deve retornar null para buffer desconhecido", () => {
+      const buffer = Buffer.from([0x00, 0x00, 0x00, 0x00]);
+      expect(ImageUtils.detectMimeTypeFromBuffer(buffer)).toBeNull();
+    });
+  });
+
+  describe("detectImageMimeType", () => {
+    it("deve priorizar extensão sobre magic bytes", () => {
+      const buffer = Buffer.from([0xff, 0xd8, 0xff]); // Magic bytes de JPEG
+      const result = ImageUtils.detectImageMimeType(buffer, "imagem.png");
+      expect(result).toBe("image/png");
+    });
+
+    it("deve usar magic bytes quando extensão não está disponível", () => {
+      const buffer = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00,
+      ]);
+      const result = ImageUtils.detectImageMimeType(buffer);
+      expect(result).toBe("image/png");
+    });
+
+    it("deve usar fallback para JPEG quando não consegue detectar", () => {
+      const buffer = Buffer.from([0x00, 0x00, 0x00, 0x00]);
+      const result = ImageUtils.detectImageMimeType(buffer);
+      expect(result).toBe("image/jpeg");
+    });
+  });
+});