@luanpoppe/ai 1.1.0 → 1.1.2

package/dist/index.js

@@ -1,143 +1,17 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangchainAudioTranscription = exports.LangchainTools = exports.LangchainMessages = exports.LangchainModels = exports.Langchain = exports.AudioUtils = exports.AIAudioTranscription = exports.AITools = exports.AIMessages = exports.AIModels = exports.AI = void 0;
-const models_1 = require("./langchain/models");
+exports.LangchainAudioTranscription = exports.LangchainTools = exports.LangchainMessages = exports.LangchainModels = exports.Langchain = exports.AudioUtils = exports.AIAudioTranscription = exports.AIMemory = exports.AITools = exports.AIMessages = exports.AIModels = exports.AI = void 0;
+const ai_1 = require("./ai");
+Object.defineProperty(exports, "AI", { enumerable: true, get: function () { return ai_1.AI; } });
+Object.defineProperty(exports, "Langchain", { enumerable: true, get: function () { return ai_1.AI; } });
+var models_1 = require("./langchain/models");
 Object.defineProperty(exports, "AIModels", { enumerable: true, get: function () { return models_1.AIModels; } });
-const zod_1 = __importDefault(require("zod"));
-const langchain_1 = require("langchain");
-const messages_1 = require("./langchain/messages");
+var messages_1 = require("./langchain/messages");
 Object.defineProperty(exports, "AIMessages", { enumerable: true, get: function () { return messages_1.AIMessages; } });
-const tools_1 = require("./langchain/tools");
+var tools_1 = require("./langchain/tools");
 Object.defineProperty(exports, "AITools", { enumerable: true, get: function () { return tools_1.AITools; } });
-class AI {
-    tokens;
-    constructor(tokens) {
-        this.tokens = tokens;
-    }
-    async call(params) {
-        const { messages } = params;
-        const agent = (0, langchain_1.createAgent)({
-            ...this.standardAgent(params),
-        });
-        const response = await agent.invoke({ messages });
-        const rawContent = response.messages.at(-1)?.content;
-        const text = typeof rawContent === "string" && rawContent.trim()
-            ? rawContent
-            : "Empty response from the model";
-        return {
-            text,
-            messages: response.messages,
-        };
-    }
-    async callStructuredOutput(params) {
-        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 = (0, langchain_1.createAgent)({
-            ...this.standardAgent(params),
-            responseFormat: normalizedSchema,
-        });
-        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'
-     */
-    normalizeSchemaForOpenAI(schema, aiModel) {
-        // 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 zod_1.default.ZodObject) {
-            const shape = schema.shape;
-            const newShape = {};
-            // 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 zod_1.default.ZodOptional) {
-                    // Converte .optional() para .nullable() para compatibilidade com OpenAI
-                    const innerType = value._def.innerType;
-                    // Usa z.union para criar um tipo nullable
-                    newShape[key] = zod_1.default.union([innerType, zod_1.default.null()]);
-                }
-                else {
-                    newShape[key] = value;
-                }
-            }
-            return zod_1.default.object(newShape);
-        }
-        return schema;
-    }
-    getRawAgent(params, outputSchema) {
-        const agent = (0, langchain_1.createAgent)({
-            ...this.standardAgent(params),
-            responseFormat: outputSchema,
-        });
-        return { agent };
-    }
-    getModel(params) {
-        const { aiModel, modelConfig } = params;
-        const config = {
-            model: aiModel,
-            maxTokens: modelConfig?.maxTokens,
-            temperature: modelConfig?.temperature,
-        };
-        if (aiModel.startsWith("gpt")) {
-            config.apiKey = this.tokens.openAIApiKey;
-            return models_1.AIModels.gpt(config);
-        }
-        if (aiModel.startsWith("gemini")) {
-            config.apiKey = this.tokens.googleGeminiToken;
-            return models_1.AIModels.gemini(config);
-        }
-        if (aiModel.startsWith("openrouter/")) {
-            const modelName = aiModel.replace(/^openrouter\//, "");
-            return models_1.AIModels.openrouter({
-                ...config,
-                model: modelName,
-                apiKey: this.tokens.openRouterApiKey,
-            });
-        }
-        throw new Error("Model not supported");
-    }
-    standardAgent(params) {
-        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,
-        };
-    }
-    standardMiddlewares(maxRetries) {
-        return [
-            (0, langchain_1.modelRetryMiddleware)({
-                maxRetries,
-                backoffFactor: 2.0,
-                initialDelayMs: 1000,
-            }),
-            (0, langchain_1.modelFallbackMiddleware)("gemini-2.5-flash", "gpt-4o-mini"),
-        ];
-    }
-}
-exports.AI = AI;
-exports.Langchain = AI;
+var checkpointers_1 = require("./langchain/checkpointers");
+Object.defineProperty(exports, "AIMemory", { enumerable: true, get: function () { return checkpointers_1.AIMemory; } });
 var audio_transcription_1 = require("./langchain/audio-transcription");
 Object.defineProperty(exports, "AIAudioTranscription", { enumerable: true, get: function () { return audio_transcription_1.AIAudioTranscription; } });
 var audio_utils_1 = require("./utils/audio-utils");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,+CAA8D;AAsNrD,yFAtNA,iBAAQ,OAsNA;AApNjB,8CAAoB;AAEpB,yCAMmB;AAEnB,mDAAkD;AA0M/B,2FA1MV,qBAAU,OA0MU;AAzM7B,6CAA4C;AAyMb,wFAzMtB,eAAO,OAyMsB;AArKtC,MAAa,EAAE;IACO;IAApB,YAAoB,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE7C,KAAK,CAAC,IAAI,CAAC,MAAoB;QAC7B,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAE5B,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC;YACxB,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;SAC9B,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAElD,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAA6B,CAAC;QAC3E,MAAM,IAAI,GACR,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,EAAE;YACjD,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,+BAA+B,CAAC;QACtC,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,MAAuC;QAEvC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAEnD,gEAAgE;QAChE,2EAA2E;QAC3E,MAAM,gBAAgB,GAAG,IAAI,CAAC,wBAAwB,CACpD,YAAY,EACZ,OAAO,CACR,CAAC;QAEF,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC;YACxB,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;YAC7B,cAAc,EAAE,gBAAuB;SACxC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC;YAClC,QAAQ;SACT,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;QAExE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACK,wBAAwB,CAC9B,MAAS,EACT,OAAe;QAEf,kDAAkD;QAClD,MAAM,aAAa,GACjB,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;QAExE,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,sEAAsE;QACtE,IAAI,MAAM,YAAY,aAAC,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,MAAM,QAAQ,GAAiC,EAAE,CAAC;YAElD,0EAA0E;YAC1E,8DAA8D;YAC9D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,KAAK,YAAY,aAAC,CAAC,WAAW,EAAE,CAAC;oBACnC,wEAAwE;oBACxE,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,SAAyB,CAAC;oBACvD,0CAA0C;oBAC1C,QAAQ,CAAC,GAAG,CAAC,GAAG,aAAC,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,aAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBACjD,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACxB,CAAC;YACH,CAAC;YAED,OAAO,aAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,WAAW,CACT,MAAoB,EACpB,YAAsC;QAEtC,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC;YACxB,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;YAC7B,cAAc,EAAE,YAAmB;SACpC,CAAC,CAAC;QAEH,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAEO,QAAQ,CAAC,MAAoB;QACnC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;QAExC,MAAM,MAAM,GAAmB;YAC7B,KAAK,EAAE,OAAO;YACd,SAAS,EAAE,WAAW,EAAE,SAAS;YACjC,WAAW,EAAE,WAAW,EAAE,WAAW;SACtC,CAAC;QAEF,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;YAEzC,OAAO,iBAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC;YAE9C,OAAO,iBAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACtC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;YACvD,OAAO,iBAAQ,CAAC,UAAU,CAAC;gBACzB,GAAG,MAAM;gBACT,KAAK,EAAE,SAAS;gBAChB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;aACrC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IAEO,aAAa,CACnB,MAAoB;QAEpB,MAAM,EAAE,YAAY,EAAE,UAAU,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC;QAEhD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO;YACL,KAAK;YACL,YAAY,EAAE,YAAY,IAAI,EAAE;YAChC,UAAU,EAAE;gBACV,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC;gBACvC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC;aACpC;YACD,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;YAChC,cAAc,EAAE,SAAgB;SACjC,CAAC;IACJ,CAAC;IAEO,mBAAmB,CAAC,UAAkB;QAC5C,OAAO;YACL,IAAA,gCAAoB,EAAC;gBACnB,UAAU;gBACV,aAAa,EAAE,GAAG;gBAClB,cAAc,EAAE,IAAI;aACrB,CAAC;YACF,IAAA,mCAAuB,EAAC,kBAAkB,EAAE,aAAa,CAAC;SAC3D,CAAC;IACJ,CAAC;CACF;AAnKD,gBAmKC;AAiBc,uBAAS;AAdxB,uEAAuE;AAA9D,2HAAA,oBAAoB,OAAA;AAC7B,mDAAiD;AAAxC,yGAAA,UAAU,OAAA;AAwBnB,iEAAiE;AACjE,6CAAiE;AAAxD,yGAAA,QAAQ,OAAmB;AACpC,mEAAmE;AACnE,iDAAuE;AAA9D,6GAAA,UAAU,OAAqB;AACxC,gEAAgE;AAChE,2CAA8D;AAArD,uGAAA,OAAO,OAAkB;AAClC,6EAA6E;AAC7E,uEAAsG;AAA7F,kIAAA,oBAAoB,OAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,6BAA0B;AAQjB,mFARA,OAAE,OAQA;AAwCI,0FAhDN,OAAE,OAgDa;AA/BxB,6CAA8C;AAArC,kGAAA,QAAQ,OAAA;AACjB,iDAAkD;AAAzC,sGAAA,UAAU,OAAA;AACnB,2CAA4C;AAAnC,gGAAA,OAAO,OAAA;AAChB,2DAAqD;AAA5C,yGAAA,QAAQ,OAAA;AAcjB,uEAAuE;AAA9D,2HAAA,oBAAoB,OAAA;AAC7B,mDAAiD;AAAxC,yGAAA,UAAU,OAAA;AAwBnB,iEAAiE;AACjE,6CAAiE;AAAxD,yGAAA,QAAQ,OAAmB;AACpC,mEAAmE;AACnE,iDAAuE;AAA9D,6GAAA,UAAU,OAAqB;AACxC,gEAAgE;AAChE,2CAA8D;AAArD,uGAAA,OAAO,OAAkB;AAClC,6EAA6E;AAC7E,uEAAsG;AAA7F,kIAAA,oBAAoB,OAA+B"}

package/dist/langchain/checkpointers.d.ts

@@ -0,0 +1,86 @@
+import { BaseCheckpointSaver, type StateSnapshot } from "@langchain/langgraph";
+import type { GetHistoryResult, GraphWithStateHistory, MemoryConfig } from "../@types/checkpointers";
+export type { BaseCheckpointSaver };
+export type { MemoryConfig, MemoryCheckpointerConfig, SqliteCheckpointerConfig, PostgresCheckpointerConfig, RedisCheckpointerConfig, MongoDBCheckpointerConfig, GraphWithStateHistory, MessageRole, HistoryMessageItem, GetHistoryResult, } from "../@types/checkpointers";
+/**
+ * Classe para gerenciar memória e checkpointers de conversas LangGraph.
+ *
+ * @example
+ * // Memória (desenvolvimento)
+ * const memory = new AIMemory({ type: "memory" });
+ * const checkpointer = await memory.getCheckpointer();
+ *
+ * @example
+ * // SQLite
+ * const memory = new AIMemory({ type: "sqlite", connectionString: "./data.db" });
+ *
+ * @example
+ * // Acessar histórico de conversa
+ * const { agent } = await ai.getRawAgent({ ... });
+ * const history = await memory.getHistory("thread-1", agent);
+ * const messages = history[0]?.values?.messages ?? [];
+ */
+export declare class AIMemory {
+    private config;
+    private checkpointer;
+    private checkpointerPromise;
+    private agent;
+    constructor(config: MemoryConfig, agent?: GraphWithStateHistory);
+    /**
+     * Define o agent/grafo para uso em getHistory quando graph não é passado.
+     * Chamado automaticamente por AI.getRawAgent() quando a instância está vinculada ao AI.
+     */
+    setAgent(agent: GraphWithStateHistory): void;
+    /**
+     * Cria ou retorna a instância de checkpointer baseada na configuração.
+     *
+     * @example
+     * const cp = await memory.getCheckpointer();
+     * const graph = workflow.compile({ checkpointer: cp });
+     */
+    getCheckpointer(): Promise<BaseCheckpointSaver>;
+    /**
+     * Retorna o histórico de checkpoints e lista de mensagens de uma thread.
+     *
+     * @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).
+     * @returns Objeto com fullHistory (checkpoints) e messages (lista com role, createdAt, content)
+     *
+     * @example
+     * // Com ai.memory (agent definido automaticamente em call/getRawAgent)
+     * await ai.call({ messages: [...], threadId: "1" });
+     * const { fullHistory, messages } = await ai.memory.getHistory("1");
+     *
+     * @example
+     * // Passando graph explicitamente
+     * const { fullHistory, messages } = await memory.getHistory("1", agent);
+     *
+     * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state-history
+     * @see https://docs.langchain.com/oss/javascript/langgraph/add-memory#manage-checkpoints
+     */
+    getHistory(threadId: string, graph?: GraphWithStateHistory): Promise<GetHistoryResult>;
+    /**
+     * 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.
+     */
+    private extractMessagesFromHistory;
+    private getMessageRole;
+    private extractContent;
+    /**
+     * Retorna o estado atual (último checkpoint) de uma thread.
+     *
+     * @param threadId - ID da thread/conversa
+     * @param graph - Grafo compilado com checkpointer
+     * @param checkpointId - Opcional: ID de um checkpoint específico
+     *
+     * @example
+     * const state = await memory.getState("1", agent);
+     * const messages = state?.values?.messages ?? [];
+     *
+     * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state
+     */
+    getState(threadId: string, graph?: GraphWithStateHistory, checkpointId?: string): Promise<StateSnapshot | null>;
+    private createCheckpointer;
+}
+//# sourceMappingURL=checkpointers.d.ts.map

package/dist/langchain/checkpointers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointers.d.ts","sourceRoot":"","sources":["../../src/langchain/checkpointers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EAEnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EAErB,YAAY,EAEb,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,mBAAmB,EAAE,CAAC;AACpC,YAAY,EACV,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,EACrB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,QAAQ;IAMjB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,mBAAmB,CAA2C;IACtE,OAAO,CAAC,KAAK,CAAoC;gBAGvC,MAAM,EAAE,YAAY,EAC5B,KAAK,CAAC,EAAE,qBAAqB;IAK/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;IAI5C;;;;;;OAMG;IACG,eAAe,IAAI,OAAO,CAAC,mBAAmB,CAAC;IASrD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC;IAiB5B;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAwClC,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,cAAc;IAgBtB;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,qBAAqB,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAiBlB,kBAAkB;CA4FjC"}

package/dist/langchain/checkpointers.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIMemory = void 0;
+const langgraph_1 = require("@langchain/langgraph");
+/**
+ * Classe para gerenciar memória e checkpointers de conversas LangGraph.
+ *
+ * @example
+ * // Memória (desenvolvimento)
+ * const memory = new AIMemory({ type: "memory" });
+ * const checkpointer = await memory.getCheckpointer();
+ *
+ * @example
+ * // SQLite
+ * const memory = new AIMemory({ type: "sqlite", connectionString: "./data.db" });
+ *
+ * @example
+ * // Acessar histórico de conversa
+ * const { agent } = await ai.getRawAgent({ ... });
+ * const history = await memory.getHistory("thread-1", agent);
+ * const messages = history[0]?.values?.messages ?? [];
+ */
+class AIMemory {
+    config;
+    checkpointer;
+    checkpointerPromise;
+    agent;
+    constructor(config, agent) {
+        this.config = config;
+        this.agent = agent;
+    }
+    /**
+     * Define o agent/grafo para uso em getHistory quando graph não é passado.
+     * Chamado automaticamente por AI.getRawAgent() quando a instância está vinculada ao AI.
+     */
+    setAgent(agent) {
+        this.agent = agent;
+    }
+    /**
+     * Cria ou retorna a instância de checkpointer baseada na configuração.
+     *
+     * @example
+     * const cp = await memory.getCheckpointer();
+     * const graph = workflow.compile({ checkpointer: cp });
+     */
+    async getCheckpointer() {
+        if (this.checkpointer)
+            return this.checkpointer;
+        if (!this.checkpointerPromise) {
+            this.checkpointerPromise = this.createCheckpointer();
+        }
+        this.checkpointer = await this.checkpointerPromise;
+        return this.checkpointer;
+    }
+    /**
+     * Retorna o histórico de checkpoints e lista de mensagens de uma thread.
+     *
+     * @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).
+     * @returns Objeto com fullHistory (checkpoints) e messages (lista com role, createdAt, content)
+     *
+     * @example
+     * // Com ai.memory (agent definido automaticamente em call/getRawAgent)
+     * await ai.call({ messages: [...], threadId: "1" });
+     * const { fullHistory, messages } = await ai.memory.getHistory("1");
+     *
+     * @example
+     * // Passando graph explicitamente
+     * const { fullHistory, messages } = await memory.getHistory("1", agent);
+     *
+     * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state-history
+     * @see https://docs.langchain.com/oss/javascript/langgraph/add-memory#manage-checkpoints
+     */
+    async getHistory(threadId, graph) {
+        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 = [];
+        for await (const snapshot of graphToUse.getStateHistory(config)) {
+            fullHistory.push(snapshot);
+        }
+        const messages = this.extractMessagesFromHistory(fullHistory);
+        return { fullHistory, messages };
+    }
+    /**
+     * 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.
+     */
+    extractMessagesFromHistory(history) {
+        const result = [];
+        let previousMessageCount = 0;
+        // history[0] = mais recente, history[length-1] = mais antigo
+        // Cada snapshot acumula mensagens; só adicionamos as novas
+        for (let i = history.length - 1; i >= 0; i--) {
+            const snapshot = history[i];
+            const snapshotMessages = (snapshot.values?.messages ?? []);
+            const createdAt = snapshot.createdAt ??
+                new Date().toISOString();
+            for (let j = previousMessageCount; j < snapshotMessages.length; j++) {
+                const msg = snapshotMessages[j];
+                if (!msg)
+                    continue;
+                const role = this.getMessageRole(msg);
+                if (role === "system")
+                    continue;
+                result.push({
+                    role: role,
+                    createdAt,
+                    content: this.extractContent(msg),
+                });
+            }
+            previousMessageCount = snapshotMessages.length;
+        }
+        return result;
+    }
+    getMessageRole(msg) {
+        const role = msg.role?.toLowerCase();
+        if (role === "human" || role === "user")
+            return "human";
+        if (role === "ai" || role === "assistant")
+            return "ai";
+        if (role === "tool")
+            return "tool";
+        const type = msg.getType?.() ??
+            msg._getType?.() ??
+            msg.constructor?.name?.toLowerCase() ?? "";
+        const normalized = type.toLowerCase().replace("message", "").trim();
+        if (normalized === "human" || normalized === "user")
+            return "human";
+        if (normalized === "ai" || normalized === "assistant")
+            return "ai";
+        if (normalized === "tool")
+            return "tool";
+        return "system";
+    }
+    extractContent(msg) {
+        const c = msg.content;
+        if (typeof c === "string")
+            return c;
+        if (Array.isArray(c)) {
+            return c
+                .map((block) => typeof block === "string" ? block : block?.text ?? "")
+                .filter(Boolean)
+                .join("\n");
+        }
+        return "";
+    }
+    /**
+     * Retorna o estado atual (último checkpoint) de uma thread.
+     *
+     * @param threadId - ID da thread/conversa
+     * @param graph - Grafo compilado com checkpointer
+     * @param checkpointId - Opcional: ID de um checkpoint específico
+     *
+     * @example
+     * const state = await memory.getState("1", agent);
+     * const messages = state?.values?.messages ?? [];
+     *
+     * @see https://docs.langchain.com/oss/javascript/langgraph/persistence#get-state
+     */
+    async getState(threadId, graph, checkpointId) {
+        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;
+        }
+        const config = {
+            configurable: { thread_id: threadId, ...(checkpointId && { checkpoint_id: checkpointId }) },
+        };
+        return (await graphToUse.getState(config)) ?? null;
+    }
+    async createCheckpointer() {
+        if (this.checkpointer)
+            return this.checkpointer;
+        switch (this.config.type) {
+            case "memory": {
+                return new langgraph_1.MemorySaver();
+            }
+            case "sqlite": {
+                try {
+                    const { SqliteSaver } = await import("@langchain/langgraph-checkpoint-sqlite");
+                    return SqliteSaver.fromConnString(this.config.connectionString);
+                }
+                catch (err) {
+                    throw new Error('Checkpointer SQLite requer o pacote "@langchain/langgraph-checkpoint-sqlite". ' +
+                        "Instale com: pnpm add @langchain/langgraph-checkpoint-sqlite", { cause: err });
+                }
+            }
+            case "postgres": {
+                try {
+                    const { PostgresSaver } = await import("@langchain/langgraph-checkpoint-postgres");
+                    const checkpointer = PostgresSaver.fromConnString(this.config.connectionString);
+                    await checkpointer.setup();
+                    return checkpointer;
+                }
+                catch (err) {
+                    throw new Error('Checkpointer Postgres requer o pacote "@langchain/langgraph-checkpoint-postgres". ' +
+                        "Instale com: pnpm add @langchain/langgraph-checkpoint-postgres", { cause: err });
+                }
+            }
+            case "redis": {
+                try {
+                    const { RedisSaver } = await import("@langchain/langgraph-checkpoint-redis");
+                    return (await RedisSaver.fromUrl(this.config.url, this.config.options ?? {}));
+                }
+                catch (err) {
+                    throw new Error('Checkpointer Redis requer o pacote "@langchain/langgraph-checkpoint-redis". ' +
+                        "Instale com: pnpm add @langchain/langgraph-checkpoint-redis", { cause: err });
+                }
+            }
+            case "mongodb": {
+                try {
+                    const { MongoDBSaver } = await import("@langchain/langgraph-checkpoint-mongodb");
+                    if ("client" in this.config) {
+                        return new MongoDBSaver({
+                            client: this.config.client,
+                        });
+                    }
+                    const { MongoClient } = await import("mongodb");
+                    const client = new MongoClient(this.config.url);
+                    return new MongoDBSaver({ client });
+                }
+                catch (err) {
+                    throw new Error('Checkpointer MongoDB requer os pacotes "@langchain/langgraph-checkpoint-mongodb" e "mongodb". ' +
+                        "Instale com: pnpm add @langchain/langgraph-checkpoint-mongodb mongodb", { cause: err });
+                }
+            }
+            default: {
+                const _exhaustive = this.config;
+                throw new Error(`Tipo de checkpointer não suportado: ${_exhaustive?.type}`);
+            }
+        }
+    }
+}
+exports.AIMemory = AIMemory;
+//# sourceMappingURL=checkpointers.js.map

package/dist/langchain/checkpointers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointers.js","sourceRoot":"","sources":["../../src/langchain/checkpointers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpoppe/ai",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "",
   "main": "dist/index.js",
   "keywords": [],
@@ -8,6 +8,7 @@
   "license": "ISC",
   "dependencies": {
     "@langchain/community": "^1.1.10",
+    "@langchain/langgraph": "^1.1.1",
     "openai": "^6.17.0",
     "@langchain/core": "^1.1.16",
     "@langchain/google-genai": "^2.1.12",
@@ -15,6 +16,13 @@
     "langchain": "^1.2.12",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "@langchain/langgraph-checkpoint-mongodb": "^1.1.7",
+    "@langchain/langgraph-checkpoint-postgres": "^1.0.0",
+    "@langchain/langgraph-checkpoint-redis": "^1.0.2",
+    "@langchain/langgraph-checkpoint-sqlite": "^1.0.1",
+    "mongodb": "^7.1.0"
+  },
   "devDependencies": {
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.18",

package/src/@types/agent.ts

@@ -0,0 +1,3 @@
+import type { createAgent } from "langchain";
+
+export type AIAgent = ReturnType<typeof createAgent>;

package/src/@types/ai-call.ts

@@ -0,0 +1,38 @@
+import type { AgentMiddleware, BaseMessage } from "langchain";
+import type { ClientTool, ServerTool } from "@langchain/core/tools";
+import type { LLMModelConfig } from "../langchain/models";
+import type { AIModelNames } from "./model-names";
+import type { MessageInput } from "../langchain/messages";
+import type z from "zod";
+
+export type AICallParams = {
+  agent?: {
+    middleware?: AgentMiddleware[];
+    tools?: (ServerTool | ClientTool)[];
+  };
+
+  modelConfig?: Omit<LLMModelConfig, "apiKey" | "model">;
+
+  aiModel: AIModelNames;
+  /** Lista de modelos de fallback quando o principal falhar após todos os retries (suporta OpenRouter, Gemini, GPT) */
+  aiModelsFallback?: AIModelNames[];
+  messages: MessageInput[];
+  systemPrompt?: string;
+  maxRetries?: number;
+  /** ID da thread/conversa para persistência de histórico (obrigatório quando memory/checkpointer está ativo) */
+  threadId?: string;
+};
+
+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>;
+}>;