@luanpoppe/ai 1.1.2 → 1.1.3

package/src/langchain/{checkpointers.ts → memory.ts}

@@ -84,7 +84,7 @@ export class AIMemory {
    *
    * @param threadId - ID da thread/conversa
    * @param graph - Opcional. Grafo compilado com checkpointer. Se não passado, usa o agent
-   *                definido no construtor ou via setAgent (ex: agent de ai.getRawAgent).
+   *                definido no construtor ou via setAgent. Se nenhum disponível, usa o checkpointer.
    * @returns Objeto com fullHistory (checkpoints) e messages (lista com role, createdAt, content)
    *
    * @example
@@ -96,6 +96,11 @@ export class AIMemory {
    * // Passando graph explicitamente
    * const { fullHistory, messages } = await memory.getHistory("1", agent);
    *
+   * @example
+   * // Apenas com checkpointer (sem graph)
+   * const memory = new AIMemory({ type: "memory" });
+   * const { fullHistory, messages } = await memory.getHistory("1");
+   *
    * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state-history
    * @see https://docs.langchain.com/oss/javascript/langgraph/add-memory#manage-checkpoints
    */
@@ -104,21 +109,45 @@ export class AIMemory {
     graph?: GraphWithStateHistory
   ): Promise<GetHistoryResult> {
     const graphToUse = graph ?? this.agent;
-    if (!graphToUse) {
-      throw new Error(
-        "É necessário passar graph em getHistory ou definir o agent no construtor/setAgent do AIMemory."
-      );
-    }
-    const config = { configurable: { thread_id: threadId } };
     const fullHistory: StateSnapshot[] = [];
-    for await (const snapshot of graphToUse.getStateHistory(config)) {
-      fullHistory.push(snapshot);
+
+    if (graphToUse) {
+      const config = { configurable: { thread_id: threadId } };
+      for await (const snapshot of graphToUse.getStateHistory(config)) {
+        fullHistory.push(snapshot);
+      }
+    } else {
+      const checkpointer = await this.getCheckpointer();
+      const config = { configurable: { thread_id: threadId } };
+      for await (const tuple of checkpointer.list(config)) {
+        fullHistory.push(this.checkpointTupleToSnapshot(tuple));
+      }
     }
 
     const messages = this.extractMessagesFromHistory(fullHistory);
     return { fullHistory, messages };
   }
 
+  /**
+   * Converte CheckpointTuple (do checkpointer.list) em StateSnapshot.
+   * Permite obter histórico usando apenas o checkpointer, sem o graph.
+   */
+  private checkpointTupleToSnapshot(tuple: {
+    checkpoint: { channel_values: Record<string, unknown>; ts?: string };
+    config?: unknown;
+    metadata?: unknown;
+  }): StateSnapshot {
+    const { checkpoint } = tuple;
+    return {
+      values: checkpoint.channel_values ?? {},
+      createdAt: checkpoint.ts ?? new Date().toISOString(),
+      config: tuple.config ?? { configurable: {} },
+      metadata: tuple.metadata,
+      next: [],
+      tasks: [],
+    } as StateSnapshot;
+  }
+
   /**
    * Extrai lista de mensagens com role, createdAt e content a partir do histórico.
    * Percorre os checkpoints do mais antigo ao mais recente para atribuir createdAt correto.
@@ -220,19 +249,17 @@ export class AIMemory {
     checkpointId?: string
   ): Promise<StateSnapshot | null> {
     const graphToUse = graph ?? this.agent;
-    if (!graphToUse) {
-      throw new Error(
-        "É necessário passar graph em getState ou definir o agent no construtor/setAgent do AIMemory."
-      );
-    }
-    if (!graphToUse.getState) {
-      const { fullHistory } = await this.getHistory(threadId, graphToUse);
-      return fullHistory[0] ?? null;
+    if (graphToUse?.getState) {
+      const config = {
+        configurable: {
+          thread_id: threadId,
+          ...(checkpointId && { checkpoint_id: checkpointId }),
+        },
+      };
+      return (await graphToUse.getState(config)) ?? null;
     }
-    const config = {
-      configurable: { thread_id: threadId, ...(checkpointId && { checkpoint_id: checkpointId }) },
-    };
-    return (await graphToUse.getState(config)) ?? null;
+    const { fullHistory } = await this.getHistory(threadId, graphToUse ?? undefined);
+    return fullHistory[0] ?? null;
   }
 
   private async createCheckpointer(): Promise<BaseCheckpointSaver> {
@@ -328,4 +355,3 @@ export class AIMemory {
     }
   }
 }
-

package/tests/e2e/ai.test.ts

@@ -1,4 +1,7 @@
+import { createAgent } from "langchain";
 import { AI } from "../../src/index";
+import { AIMemory } from "../../src/langchain/memory";
+import { AIModels } from "../../src/langchain/models";
 import { AIMessages } from "../../src/langchain/messages";
 import z from "zod";
 import "dotenv/config";
@@ -623,6 +626,55 @@ describe("AI E2E Tests", () => {
         );
       },
     );
+
+    it(
+      "deve retornar histórico via getHistory usando apenas checkpointer - sem graph",
+      { timeout },
+      async () => {
+        if (!openAIApiKey) {
+          console.log("OPENAI_API_KEY não está configurada");
+          return;
+        }
+        const memory = new AIMemory({ type: "memory" });
+        const checkpointer = await memory.getCheckpointer();
+        const model = AIModels.gpt({
+          apiKey: openAIApiKey!,
+          model: "gpt-5-nano",
+        });
+        const agent = createAgent({
+          model,
+          checkpointer,
+          systemPrompt: "",
+        });
+
+        const threadId = "e2e-checkpointer-only-thread";
+
+        await agent.invoke(
+          { messages: [AIMessages.human("Responda apenas: recebido.")] },
+          { configurable: { thread_id: threadId } },
+        );
+
+        await agent.invoke(
+          { messages: [AIMessages.human("O que eu disse antes?")] },
+          { configurable: { thread_id: threadId } },
+        );
+
+        const { fullHistory, messages } = await memory.getHistory(threadId);
+
+        console.log({ messages });
+
+        expect(fullHistory.length).toBeGreaterThan(0);
+        expect(messages.length).toBeGreaterThanOrEqual(2);
+
+        const allContent = messages.map((m) => m.content).join(" ");
+        expect(allContent).toContain("Responda apenas");
+        expect(allContent).toContain("O que eu disse");
+
+        expect(
+          messages.every((m) => ["human", "ai", "tool"].includes(m.role)),
+        ).toBe(true);
+      },
+    );
   });
 
   describe("Múltiplas mensagens em conversa", () => {

package/tests/unit/index.test.ts

@@ -2,7 +2,7 @@ import { AI } from "../../src/index";
 import { AIModels } from "../../src/langchain/models";
 import { createAgent } from "langchain";
 import { AIMessages } from "../../src/langchain/messages";
-import { AIMemory } from "../../src/langchain/checkpointers";
+import { AIMemory } from "../../src/langchain/memory";
 import z from "zod";
 
 // Mock das dependências
@@ -23,8 +23,8 @@ vi.mock("../../src/langchain/models", () => ({
   },
 }));
 
-vi.mock("../../src/langchain/checkpointers", async () => {
-  const actual = await vi.importActual("../../src/langchain/checkpointers");
+vi.mock("../../src/langchain/memory", async () => {
+  const actual = await vi.importActual("../../src/langchain/memory");
   return {
     ...actual,
     AIMemory: vi.fn().mockImplementation(function () {

package/tests/unit/langchain/checkpointers.test.ts

@@ -1,4 +1,4 @@
-import { AIMemory } from "../../../src/langchain/checkpointers";
+import { AIMemory } from "../../../src/langchain/memory";
 import { MemorySaver } from "@langchain/langgraph";
 import { describe, it, expect, vi } from "vitest";
 
@@ -97,11 +97,54 @@ describe("AIMemory", () => {
       });
     });
 
-    it("deve lançar erro quando graph não é passado e agent não foi definido", async () => {
+    it("deve usar checkpointer.list quando graph e agent não estão disponíveis", async () => {
       const memory = new AIMemory({ type: "memory" });
-      await expect(memory.getHistory("1")).rejects.toThrow(
-        "É necessário passar graph em getHistory ou definir o agent"
-      );
+      const mockTuple1 = {
+        checkpoint: {
+          channel_values: { messages: [{ role: "user", content: "oi" }] },
+          ts: "2024-01-01T10:00:00Z",
+        },
+        config: { configurable: { thread_id: "1" } },
+        metadata: {},
+      };
+      const mockTuple2 = {
+        checkpoint: {
+          channel_values: {
+            messages: [
+              { role: "user", content: "oi" },
+              { role: "assistant", content: "olá" },
+            ],
+          },
+          ts: "2024-01-01T10:01:00Z",
+        },
+        config: { configurable: { thread_id: "1" } },
+        metadata: {},
+      };
+      const mockList = vi.fn(async function* () {
+        yield mockTuple2;
+        yield mockTuple1;
+      });
+      vi.spyOn(memory, "getCheckpointer").mockResolvedValue({
+        list: mockList,
+      } as any);
+
+      const result = await memory.getHistory("1");
+
+      expect(result.fullHistory).toHaveLength(2);
+      expect(result.fullHistory[0].values).toEqual(mockTuple2.checkpoint.channel_values);
+      expect(result.fullHistory[1].values).toEqual(mockTuple1.checkpoint.channel_values);
+      expect(result.messages).toHaveLength(2);
+      expect(result.messages[0]).toEqual({
+        role: "human",
+        createdAt: "2024-01-01T10:00:00Z",
+        content: "oi",
+      });
+      expect(result.messages[1]).toEqual({
+        role: "ai",
+        createdAt: "2024-01-01T10:01:00Z",
+        content: "olá",
+      });
+      expect(mockList).toHaveBeenCalledWith({ configurable: { thread_id: "1" } });
     });
   });
 
@@ -143,5 +186,29 @@ describe("AIMemory", () => {
       const state = await memory.getState("1", mockGraph as any);
       expect(state).toEqual(mockState);
     });
+
+    it("deve usar checkpointer quando graph não está disponível", async () => {
+      const memory = new AIMemory({ type: "memory" });
+      const mockTuple = {
+        checkpoint: {
+          channel_values: { messages: [{ role: "user", content: "oi" }] },
+          ts: "2024-01-01T10:00:00Z",
+        },
+        config: { configurable: { thread_id: "1" } },
+        metadata: {},
+      };
+      const mockList = vi.fn(async function* () {
+        yield mockTuple;
+      });
+      vi.spyOn(memory, "getCheckpointer").mockResolvedValue({
+        list: mockList,
+      } as any);
+
+      const state = await memory.getState("1");
+
+      expect(state).not.toBeNull();
+      expect(state?.values).toEqual({ messages: [{ role: "user", content: "oi" }] });
+      expect(mockList).toHaveBeenCalledWith({ configurable: { thread_id: "1" } });
+    });
   });
 });