@luanpoppe/ai 1.1.2 → 1.1.3

package/src/ai.ts

@@ -1,306 +1,306 @@
-import { AIModels, LLMModelConfig } from "./langchain/models";
-import z from "zod";
-import { createAgent, modelRetryMiddleware } from "langchain";
-import type { AIAgent } from "./@types/agent";
-
-import {
-  AIMemory,
-  type BaseCheckpointSaver,
-  type MemoryConfig,
-} from "./langchain/checkpointers";
-import type { AIModelNames } from "./@types/model-names";
-import type {
-  AICallParams,
-  AICallReturn,
-  AICallStructuredOutputParams,
-  AICallStructuredOutputReturn,
-} from "./@types/ai-call";
-
-export type {
-  AICallParams,
-  AICallReturn,
-  AICallStructuredOutputParams,
-  AICallStructuredOutputReturn,
-} from "./@types/ai-call";
-
-type AIConstructor = {
-  googleGeminiToken?: string;
-  openAIApiKey?: string;
-  openRouterApiKey?: string;
-  /** Lista padrão de modelos de fallback (usada em call/callStructuredOutput quando não passada no método) */
-  aiModelsFallback?: AIModelNames[];
-  /** Configuração de persistência de histórico (memory, sqlite, postgres, redis, mongodb) ou instância AIMemory */
-  memory?: MemoryConfig | AIMemory;
-  /** Instância de checkpointer para usuários avançados (alternativa a memory) */
-  checkpointer?: BaseCheckpointSaver;
-};
-
-export class AI {
-  private _memory: AIMemory | undefined;
-
-  /**
-   * Instância de AIMemory. Lança exceção se memory não estiver configurado.
-   *
-   * @example
-   * const { fullHistory, messages } = await ai.memory.getHistory(threadId);
-   */
-  get memory(): AIMemory {
-    if (!this._memory) {
-      throw new Error(
-        "memory não está configurado. Passe memory no construtor do AI (ex: memory: { type: 'memory' }).",
-      );
-    }
-    return this._memory;
-  }
-
-  private checkpointer: BaseCheckpointSaver | undefined;
-  private checkpointerPromise: Promise<BaseCheckpointSaver> | undefined;
-
-  constructor(private config: AIConstructor) {
-    if (config.checkpointer) {
-      this.checkpointer = config.checkpointer;
-    }
-    if (config.memory) {
-      this._memory =
-        config.memory instanceof AIMemory
-          ? config.memory
-          : new AIMemory(config.memory);
-    }
-  }
-
-  private async getCheckpointer(): Promise<BaseCheckpointSaver | undefined> {
-    if (this.checkpointer) return this.checkpointer;
-    if (this._memory) {
-      if (!this.checkpointerPromise) {
-        this.checkpointerPromise = this._memory.getCheckpointer();
-      }
-      this.checkpointer = await this.checkpointerPromise;
-      return this.checkpointer;
-    }
-    return undefined;
-  }
-
-  private ensureThreadIdWhenCheckpointer(params: AICallParams): void {
-    if (this.config.checkpointer || this.config.memory !== undefined) {
-      if (!params.threadId) {
-        throw new Error(
-          "threadId é obrigatório quando memory ou checkpointer está configurado. " +
-            "Passe threadId em AICallParams para identificar a conversa.",
-        );
-      }
-    }
-  }
-
-  private async invokeWithRetryAndFallback<T>(
-    params: AICallParams,
-    createAgentForModel: (paramsForModel: AICallParams) => AIAgent,
-    execute: (agent: AIAgent) => Promise<T>,
-  ): Promise<{ result: T; agent: AIAgent }> {
-    const fallback =
-      params.aiModelsFallback ?? this.config.aiModelsFallback ?? [];
-    const models: (typeof params.aiModel)[] = [params.aiModel, ...fallback];
-    let lastError: unknown;
-
-    for (const aiModel of models) {
-      const paramsForModel = { ...params, aiModel };
-      const agent = createAgentForModel(paramsForModel);
-
-      try {
-        const result = await execute(agent);
-        return { result, agent };
-      } catch (error) {
-        lastError = error;
-      }
-    }
-
-    throw lastError;
-  }
-
-  async call(params: AICallParams): AICallReturn {
-    const { messages } = params;
-
-    this.ensureThreadIdWhenCheckpointer(params);
-    const checkpointer = await this.getCheckpointer();
-
-    const invokeConfig =
-      params.threadId && checkpointer
-        ? { configurable: { thread_id: params.threadId } }
-        : undefined;
-
-    const { result: response, agent } = await this.invokeWithRetryAndFallback(
-      params,
-      (paramsForModel) =>
-        createAgent({
-          ...this.standardAgent(paramsForModel, checkpointer),
-        }),
-      (agent) => agent.invoke({ messages }, invokeConfig as any),
-    );
-
-    this._memory?.setAgent(agent);
-
-    const rawContent = response.messages.at(-1)?.content as string | undefined;
-    const text =
-      typeof rawContent === "string" && rawContent.trim()
-        ? rawContent
-        : "Empty response from the model";
-    return {
-      text,
-      messages: response.messages,
-    };
-  }
-
-  async callStructuredOutput<T extends z.ZodSchema>(
-    params: AICallStructuredOutputParams<T>,
-  ): AICallStructuredOutputReturn<typeof params.outputSchema> {
-    const { outputSchema, messages } = params;
-
-    this.ensureThreadIdWhenCheckpointer(params);
-    const checkpointer = await this.getCheckpointer();
-
-    const invokeConfig =
-      params.threadId && checkpointer
-        ? { configurable: { thread_id: params.threadId } }
-        : undefined;
-
-    const { result: response, agent } = await this.invokeWithRetryAndFallback(
-      params,
-      (paramsForModel) =>
-        createAgent({
-          ...this.standardAgent(paramsForModel, checkpointer),
-          responseFormat: this.normalizeSchemaForOpenAI(
-            outputSchema,
-            paramsForModel.aiModel,
-          ) as any,
-        }),
-      (agent) => agent.invoke({ messages }, invokeConfig as any),
-    );
-
-    this._memory?.setAgent(agent);
-
-    const parsedResponse = outputSchema.parse(response?.structuredResponse);
-
-    return { response: parsedResponse };
-  }
-
-  /**
-   * Normaliza schemas Zod para compatibilidade com OpenAI/OpenRouter
-   * OpenAI exige que todos os campos em properties estejam no array required
-   * quando usa response_format: 'extract'
-   */
-  private normalizeSchemaForOpenAI<T extends z.ZodSchema>(
-    schema: T,
-    aiModel: string,
-  ): z.ZodSchema {
-    // Apenas normaliza para modelos OpenAI/OpenRouter
-    const isOpenAIModel =
-      aiModel.startsWith("gpt") || aiModel.startsWith("openrouter/openai/");
-
-    if (!isOpenAIModel) {
-      return schema;
-    }
-
-    // Se o schema é um objeto Zod, precisamos normalizar campos opcionais
-    if (schema instanceof z.ZodObject) {
-      const shape = schema.shape;
-      const newShape: Record<string, z.ZodTypeAny> = {};
-
-      // Converte campos opcionais para nullable para compatibilidade com OpenAI
-      // OpenAI requer que todos os campos estejam no array required
-      for (const [key, value] of Object.entries(shape)) {
-        if (value instanceof z.ZodOptional) {
-          // Converte .optional() para .nullable() para compatibilidade com OpenAI
-          const innerType = value._def.innerType as z.ZodTypeAny;
-          // Usa z.union para criar um tipo nullable
-          newShape[key] = z.union([innerType, z.null()]);
-        } else {
-          newShape[key] = value;
-        }
-      }
-
-      return z.object(newShape);
-    }
-
-    return schema;
-  }
-
-  async getRawAgent(
-    params: AICallParams,
-    outputSchema?: z.ZodSchema | undefined,
-  ): Promise<{ agent: AIAgent }> {
-    this.ensureThreadIdWhenCheckpointer(params);
-    const checkpointer = await this.getCheckpointer();
-
-    const agent = createAgent({
-      ...this.standardAgent(params, checkpointer),
-      responseFormat: outputSchema as any,
-    });
-
-    this._memory?.setAgent(agent);
-
-    return { agent };
-  }
-
-  private getModel(params: AICallParams) {
-    const { aiModel, modelConfig } = params;
-
-    const config: LLMModelConfig = {
-      model: aiModel,
-      maxTokens: modelConfig?.maxTokens,
-      temperature: modelConfig?.temperature,
-    };
-
-    if (aiModel.startsWith("gpt")) {
-      config.apiKey = this.config.openAIApiKey;
-
-      return AIModels.gpt(config);
-    }
-
-    if (aiModel.startsWith("gemini")) {
-      config.apiKey = this.config.googleGeminiToken;
-
-      return AIModels.gemini(config);
-    }
-
-    if (aiModel.startsWith("openrouter/")) {
-      const modelName = aiModel.replace(/^openrouter\//, "");
-      return AIModels.openrouter({
-        ...config,
-        model: modelName,
-        apiKey: this.config.openRouterApiKey,
-      });
-    }
-
-    throw new Error("Model not supported");
-  }
-
-  private standardAgent(
-    params: AICallParams,
-    checkpointer?: BaseCheckpointSaver,
-  ): Parameters<typeof createAgent>[0] {
-    const { systemPrompt, maxRetries = 3 } = params;
-
-    const model = this.getModel(params);
-    return {
-      model,
-      systemPrompt: systemPrompt ?? "",
-      middleware: [
-        ...this.standardMiddlewares(maxRetries),
-        ...(params.agent?.middleware ?? []),
-      ],
-      tools: params.agent?.tools ?? [],
-      responseFormat: undefined as any,
-      ...(checkpointer && { checkpointer }),
-    };
-  }
-
-  private standardMiddlewares(maxRetries: number) {
-    return [
-      modelRetryMiddleware({
-        maxRetries,
-        backoffFactor: 2.0,
-        initialDelayMs: 1000,
-        onFailure: "error",
-      }),
-    ];
-  }
-}
+import { AIModels, LLMModelConfig } from "./langchain/models";
+import z from "zod";
+import { createAgent, modelRetryMiddleware } from "langchain";
+import type { AIAgent } from "./@types/agent";
+
+import {
+  AIMemory,
+  type BaseCheckpointSaver,
+  type MemoryConfig,
+} from "./langchain/memory";
+import type { AIModelNames } from "./@types/model-names";
+import type {
+  AICallParams,
+  AICallReturn,
+  AICallStructuredOutputParams,
+  AICallStructuredOutputReturn,
+} from "./@types/ai-call";
+
+export type {
+  AICallParams,
+  AICallReturn,
+  AICallStructuredOutputParams,
+  AICallStructuredOutputReturn,
+} from "./@types/ai-call";
+
+type AIConstructor = {
+  googleGeminiToken?: string;
+  openAIApiKey?: string;
+  openRouterApiKey?: string;
+  /** Lista padrão de modelos de fallback (usada em call/callStructuredOutput quando não passada no método) */
+  aiModelsFallback?: AIModelNames[];
+  /** Configuração de persistência de histórico (memory, sqlite, postgres, redis, mongodb) ou instância AIMemory */
+  memory?: MemoryConfig | AIMemory;
+  /** Instância de checkpointer para usuários avançados (alternativa a memory) */
+  checkpointer?: BaseCheckpointSaver;
+};
+
+export class AI {
+  private _memory: AIMemory | undefined;
+
+  /**
+   * Instância de AIMemory. Lança exceção se memory não estiver configurado.
+   *
+   * @example
+   * const { fullHistory, messages } = await ai.memory.getHistory(threadId);
+   */
+  get memory(): AIMemory {
+    if (!this._memory) {
+      throw new Error(
+        "memory não está configurado. Passe memory no construtor do AI (ex: memory: { type: 'memory' }).",
+      );
+    }
+    return this._memory;
+  }
+
+  private checkpointer: BaseCheckpointSaver | undefined;
+  private checkpointerPromise: Promise<BaseCheckpointSaver> | undefined;
+
+  constructor(private config: AIConstructor) {
+    if (config.checkpointer) {
+      this.checkpointer = config.checkpointer;
+    }
+    if (config.memory) {
+      this._memory =
+        config.memory instanceof AIMemory
+          ? config.memory
+          : new AIMemory(config.memory);
+    }
+  }
+
+  private async getCheckpointer(): Promise<BaseCheckpointSaver | undefined> {
+    if (this.checkpointer) return this.checkpointer;
+    if (this._memory) {
+      if (!this.checkpointerPromise) {
+        this.checkpointerPromise = this._memory.getCheckpointer();
+      }
+      this.checkpointer = await this.checkpointerPromise;
+      return this.checkpointer;
+    }
+    return undefined;
+  }
+
+  private ensureThreadIdWhenCheckpointer(params: AICallParams): void {
+    if (this.config.checkpointer || this.config.memory !== undefined) {
+      if (!params.threadId) {
+        throw new Error(
+          "threadId é obrigatório quando memory ou checkpointer está configurado. " +
+            "Passe threadId em AICallParams para identificar a conversa.",
+        );
+      }
+    }
+  }
+
+  private async invokeWithRetryAndFallback<T>(
+    params: AICallParams,
+    createAgentForModel: (paramsForModel: AICallParams) => AIAgent,
+    execute: (agent: AIAgent) => Promise<T>,
+  ): Promise<{ result: T; agent: AIAgent }> {
+    const fallback =
+      params.aiModelsFallback ?? this.config.aiModelsFallback ?? [];
+    const models: (typeof params.aiModel)[] = [params.aiModel, ...fallback];
+    let lastError: unknown;
+
+    for (const aiModel of models) {
+      const paramsForModel = { ...params, aiModel };
+      const agent = createAgentForModel(paramsForModel);
+
+      try {
+        const result = await execute(agent);
+        return { result, agent };
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError;
+  }
+
+  async call(params: AICallParams): AICallReturn {
+    const { messages } = params;
+
+    this.ensureThreadIdWhenCheckpointer(params);
+    const checkpointer = await this.getCheckpointer();
+
+    const invokeConfig =
+      params.threadId && checkpointer
+        ? { configurable: { thread_id: params.threadId } }
+        : undefined;
+
+    const { result: response, agent } = await this.invokeWithRetryAndFallback(
+      params,
+      (paramsForModel) =>
+        createAgent({
+          ...this.standardAgent(paramsForModel, checkpointer),
+        }),
+      (agent) => agent.invoke({ messages }, invokeConfig as any),
+    );
+
+    this._memory?.setAgent(agent);
+
+    const rawContent = response.messages.at(-1)?.content as string | undefined;
+    const text =
+      typeof rawContent === "string" && rawContent.trim()
+        ? rawContent
+        : "Empty response from the model";
+    return {
+      text,
+      messages: response.messages,
+    };
+  }
+
+  async callStructuredOutput<T extends z.ZodSchema>(
+    params: AICallStructuredOutputParams<T>,
+  ): AICallStructuredOutputReturn<typeof params.outputSchema> {
+    const { outputSchema, messages } = params;
+
+    this.ensureThreadIdWhenCheckpointer(params);
+    const checkpointer = await this.getCheckpointer();
+
+    const invokeConfig =
+      params.threadId && checkpointer
+        ? { configurable: { thread_id: params.threadId } }
+        : undefined;
+
+    const { result: response, agent } = await this.invokeWithRetryAndFallback(
+      params,
+      (paramsForModel) =>
+        createAgent({
+          ...this.standardAgent(paramsForModel, checkpointer),
+          responseFormat: this.normalizeSchemaForOpenAI(
+            outputSchema,
+            paramsForModel.aiModel,
+          ) as any,
+        }),
+      (agent) => agent.invoke({ messages }, invokeConfig as any),
+    );
+
+    this._memory?.setAgent(agent);
+
+    const parsedResponse = outputSchema.parse(response?.structuredResponse);
+
+    return { response: parsedResponse };
+  }
+
+  /**
+   * Normaliza schemas Zod para compatibilidade com OpenAI/OpenRouter
+   * OpenAI exige que todos os campos em properties estejam no array required
+   * quando usa response_format: 'extract'
+   */
+  private normalizeSchemaForOpenAI<T extends z.ZodSchema>(
+    schema: T,
+    aiModel: string,
+  ): z.ZodSchema {
+    // Apenas normaliza para modelos OpenAI/OpenRouter
+    const isOpenAIModel =
+      aiModel.startsWith("gpt") || aiModel.startsWith("openrouter/openai/");
+
+    if (!isOpenAIModel) {
+      return schema;
+    }
+
+    // Se o schema é um objeto Zod, precisamos normalizar campos opcionais
+    if (schema instanceof z.ZodObject) {
+      const shape = schema.shape;
+      const newShape: Record<string, z.ZodTypeAny> = {};
+
+      // Converte campos opcionais para nullable para compatibilidade com OpenAI
+      // OpenAI requer que todos os campos estejam no array required
+      for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z.ZodOptional) {
+          // Converte .optional() para .nullable() para compatibilidade com OpenAI
+          const innerType = value._def.innerType as z.ZodTypeAny;
+          // Usa z.union para criar um tipo nullable
+          newShape[key] = z.union([innerType, z.null()]);
+        } else {
+          newShape[key] = value;
+        }
+      }
+
+      return z.object(newShape);
+    }
+
+    return schema;
+  }
+
+  async getRawAgent(
+    params: AICallParams,
+    outputSchema?: z.ZodSchema | undefined,
+  ): Promise<{ agent: AIAgent }> {
+    this.ensureThreadIdWhenCheckpointer(params);
+    const checkpointer = await this.getCheckpointer();
+
+    const agent = createAgent({
+      ...this.standardAgent(params, checkpointer),
+      responseFormat: outputSchema as any,
+    });
+
+    this._memory?.setAgent(agent);
+
+    return { agent };
+  }
+
+  private getModel(params: AICallParams) {
+    const { aiModel, modelConfig } = params;
+
+    const config: LLMModelConfig = {
+      model: aiModel,
+      maxTokens: modelConfig?.maxTokens,
+      temperature: modelConfig?.temperature,
+    };
+
+    if (aiModel.startsWith("gpt")) {
+      config.apiKey = this.config.openAIApiKey;
+
+      return AIModels.gpt(config);
+    }
+
+    if (aiModel.startsWith("gemini")) {
+      config.apiKey = this.config.googleGeminiToken;
+
+      return AIModels.gemini(config);
+    }
+
+    if (aiModel.startsWith("openrouter/")) {
+      const modelName = aiModel.replace(/^openrouter\//, "");
+      return AIModels.openrouter({
+        ...config,
+        model: modelName,
+        apiKey: this.config.openRouterApiKey,
+      });
+    }
+
+    throw new Error("Model not supported");
+  }
+
+  private standardAgent(
+    params: AICallParams,
+    checkpointer?: BaseCheckpointSaver,
+  ): Parameters<typeof createAgent>[0] {
+    const { systemPrompt, maxRetries = 3 } = params;
+
+    const model = this.getModel(params);
+    return {
+      model,
+      systemPrompt: systemPrompt ?? "",
+      middleware: [
+        ...this.standardMiddlewares(maxRetries),
+        ...(params.agent?.middleware ?? []),
+      ],
+      tools: params.agent?.tools ?? [],
+      responseFormat: undefined as any,
+      ...(checkpointer && { checkpointer }),
+    };
+  }
+
+  private standardMiddlewares(maxRetries: number) {
+    return [
+      modelRetryMiddleware({
+        maxRetries,
+        backoffFactor: 2.0,
+        initialDelayMs: 1000,
+        onFailure: "error",
+      }),
+    ];
+  }
+}

package/src/index.ts

@@ -19,7 +19,7 @@ export type {
 export { AIModels } from "./langchain/models";
 export { AIMessages } from "./langchain/messages";
 export { AITools } from "./langchain/tools";
-export { AIMemory } from "./langchain/checkpointers";
+export { AIMemory } from "./langchain/memory";
 export type {
   MemoryConfig,
   BaseCheckpointSaver,
@@ -32,7 +32,7 @@ export type {
   MessageRole,
   HistoryMessageItem,
   GetHistoryResult,
-} from "./langchain/checkpointers";
+} from "./langchain/memory";
 export { AIAudioTranscription } from "./langchain/audio-transcription";
 export { AudioUtils } from "./utils/audio-utils";
 export type { AudioBuffer, AudioMimeType } from "./@types/audio";