@luanpoppe/ai 1.1.0 → 1.1.2

package/src/@types/checkpointers.ts

@@ -0,0 +1,117 @@
+import type { StateSnapshot } from "@langchain/langgraph";
+
+/**
+ * Interface mínima para um grafo compilado com checkpointer.
+ * Usado para acessar o histórico de conversas via getStateHistory.
+ *
+ * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state-history
+ * @see https://docs.langchain.com/oss/javascript/langgraph/add-memory#manage-checkpoints
+ */
+export interface GraphWithStateHistory {
+  /**
+   * Retorna o histórico completo de checkpoints de uma thread.
+   * Ordenado cronologicamente (mais recente primeiro).
+   */
+  getStateHistory(config: {
+    configurable: { thread_id: string; checkpoint_id?: string };
+  }): AsyncIterable<StateSnapshot>;
+
+  /**
+   * Retorna o estado atual (último checkpoint) da thread.
+   */
+  getState?(config: {
+    configurable: { thread_id: string; checkpoint_id?: string };
+  }): Promise<StateSnapshot>;
+}
+
+/**
+ * Configuração para checkpointer em memória (desenvolvimento/testes).
+ */
+export type MemoryCheckpointerConfig = {
+  type: "memory";
+};
+
+/**
+ * Configuração para checkpointer SQLite.
+ * Use ":memory:" para testes ou path para arquivo persistente.
+ */
+export type SqliteCheckpointerConfig = {
+  type: "sqlite";
+  connectionString: string;
+};
+
+/**
+ * Configuração para checkpointer Postgres.
+ */
+export type PostgresCheckpointerConfig = {
+  type: "postgres";
+  connectionString: string;
+};
+
+/**
+ * Configuração para checkpointer Redis.
+ * Requer Redis 8+ ou Redis Stack (RedisJSON, RediSearch).
+ */
+export type RedisCheckpointerConfig = {
+  type: "redis";
+  url: string;
+  options?: {
+    defaultTTL?: number;
+    refreshOnRead?: boolean;
+  };
+};
+
+/**
+ * Configuração para checkpointer MongoDB com cliente existente.
+ */
+export type MongoDBCheckpointerConfigWithClient = {
+  type: "mongodb";
+  client: { close?: () => Promise<void> };
+};
+
+/**
+ * Configuração para checkpointer MongoDB com URL.
+ */
+export type MongoDBCheckpointerConfigWithUrl = {
+  type: "mongodb";
+  url: string;
+};
+
+export type MongoDBCheckpointerConfig =
+  | MongoDBCheckpointerConfigWithClient
+  | MongoDBCheckpointerConfigWithUrl;
+
+/**
+ * Configuração para persistência de histórico de conversas.
+ * Permite escolher o backend de armazenamento.
+ */
+export type MemoryConfig =
+  | MemoryCheckpointerConfig
+  | SqliteCheckpointerConfig
+  | PostgresCheckpointerConfig
+  | RedisCheckpointerConfig
+  | MongoDBCheckpointerConfig;
+
+/**
+ * Tipo de mensagem no histórico (Human, AI ou Tool).
+ */
+export type MessageRole = "human" | "ai" | "tool";
+
+/**
+ * Item de mensagem extraído do histórico, com role, horário e conteúdo.
+ */
+export type HistoryMessageItem = {
+  role: MessageRole;
+  createdAt: string;
+  content: string;
+};
+
+/**
+ * Retorno do método getHistory com histórico completo e lista de mensagens.
+ */
+export type GetHistoryResult = {
+  /** Histórico completo de checkpoints (mais recente primeiro). */
+  fullHistory: StateSnapshot[];
+  /** Lista de mensagens em ordem cronológica, com role, horário e conteúdo. */
+  messages: HistoryMessageItem[];
+};

package/src/ai.ts

@@ -0,0 +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",
+      }),
+    ];
+  }
+}

package/src/index.ts

@@ -1,218 +1,38 @@
-import { AIModels, LLMModelConfig } from "./langchain/models";
-import { AIModelNames } from "./@types/model-names";
 import z from "zod";
-import { MessageInput } from "./langchain/messages";
-import {
-  AgentMiddleware,
-  BaseMessage,
-  createAgent,
-  modelFallbackMiddleware,
-  modelRetryMiddleware,
-} from "langchain";
-import { ClientTool, ServerTool } from "@langchain/core/tools";
-import { AIMessages } from "./langchain/messages";
-import { AITools } from "./langchain/tools";
-
-type AIConstructor = {
-  googleGeminiToken?: string;
-  openAIApiKey?: string;
-  openRouterApiKey?: string;
-};
-
-export type AICallParams = {
-  agent?: {
-    middleware?: AgentMiddleware[];
-    tools?: (ServerTool | ClientTool)[];
-  };
-
-  modelConfig?: Omit<LLMModelConfig, "apiKey" | "model">;
-
-  aiModel: AIModelNames;
-  messages: MessageInput[];
-  systemPrompt?: string;
-  maxRetries?: number;
-};
-
-export type AICallReturn = Promise<{
-  text: string;
-  messages: BaseMessage[];
-}>;
-
-export type AICallStructuredOutputParams<T extends z.ZodSchema> =
-  AICallParams & {
-    outputSchema: T;
-  };
-
-export type AICallStructuredOutputReturn<T> = Promise<{
-  response: z.infer<T>;
-}>;
-
-export class AI {
-  constructor(private tokens: AIConstructor) {}
-
-  async call(params: AICallParams): AICallReturn {
-    const { messages } = params;
-
-    const agent = createAgent({
-      ...this.standardAgent(params),
-    });
-
-    const response = await agent.invoke({ messages });
-
-    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, aiModel } = params;
-
-    // Normaliza o schema para compatibilidade com OpenAI/OpenRouter
-    // OpenAI exige que todos os campos em properties estejam no array required
-    const normalizedSchema = this.normalizeSchemaForOpenAI(
-      outputSchema,
-      aiModel
-    );
-
-    const agent = createAgent({
-      ...this.standardAgent(params),
-      responseFormat: normalizedSchema as any,
-    });
-
-    const response = await agent.invoke({
-      messages,
-    });
-
-    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;
-  }
-
-  getRawAgent(
-    params: AICallParams,
-    outputSchema?: z.ZodSchema | undefined
-  ): { agent: ReturnType<typeof createAgent> } {
-    const agent = createAgent({
-      ...this.standardAgent(params),
-      responseFormat: outputSchema as any,
-    });
-
-    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.tokens.openAIApiKey;
-
-      return AIModels.gpt(config);
-    }
-
-    if (aiModel.startsWith("gemini")) {
-      config.apiKey = this.tokens.googleGeminiToken;
-
-      return AIModels.gemini(config);
-    }
-
-    if (aiModel.startsWith("openrouter/")) {
-      const modelName = aiModel.replace(/^openrouter\//, "");
-      return AIModels.openrouter({
-        ...config,
-        model: modelName,
-        apiKey: this.tokens.openRouterApiKey,
-      });
-    }
-
-    throw new Error("Model not supported");
-  }
-
-  private standardAgent(
-    params: AICallParams
-  ): 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,
-    };
-  }
-
-  private standardMiddlewares(maxRetries: number) {
-    return [
-      modelRetryMiddleware({
-        maxRetries,
-        backoffFactor: 2.0,
-        initialDelayMs: 1000,
-      }),
-      modelFallbackMiddleware("gemini-2.5-flash", "gpt-4o-mini"),
-    ];
-  }
-}
-
-export { AIModels, AIMessages, AITools };
+import { AI } from "./ai";
+import type {
+  AICallParams,
+  AICallReturn,
+  AICallStructuredOutputParams,
+  AICallStructuredOutputReturn,
+} from "./@types/ai-call";
+
+export { AI };
+export type { AIAgent } from "./@types/agent";
+export type {
+  AICallParams,
+  AICallReturn,
+  AICallStructuredOutputParams,
+  AICallStructuredOutputReturn,
+} from "./@types/ai-call";
+
+export { AIModels } from "./langchain/models";
+export { AIMessages } from "./langchain/messages";
+export { AITools } from "./langchain/tools";
+export { AIMemory } from "./langchain/checkpointers";
+export type {
+  MemoryConfig,
+  BaseCheckpointSaver,
+  MemoryCheckpointerConfig,
+  SqliteCheckpointerConfig,
+  PostgresCheckpointerConfig,
+  RedisCheckpointerConfig,
+  MongoDBCheckpointerConfig,
+  GraphWithStateHistory,
+  MessageRole,
+  HistoryMessageItem,
+  GetHistoryResult,
+} from "./langchain/checkpointers";
 export { AIAudioTranscription } from "./langchain/audio-transcription";
 export { AudioUtils } from "./utils/audio-utils";
 export type { AudioBuffer, AudioMimeType } from "./@types/audio";