@getzep/zep-cloud 0.0.1-rc.1

package/esm/memory_manager.js

@@ -0,0 +1,302 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { Memory, MemorySearchResult, Session, } from "./memory_models";
+import { Message } from "./message_models";
+import { handleRequest } from "./utils";
+export default class MemoryManager {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Retrieves a session with the specified ID.
+     *
+     * @param {string} sessionId - The ID of the session to retrieve.
+     * @returns {Promise<Session>} A promise that resolves to the Session object.
+     * @throws {Error} Will throw an error if the sessionId is not provided.
+     * @throws {APIError} Will throw an error if the fetch request fails.
+     * @throws {NotFoundError} Will throw an error if the session is not found.
+     */
+    getSession(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!sessionId || sessionId.trim() === "") {
+                throw new Error("sessionId must be provided");
+            }
+            const response = yield handleRequest(fetch(this.client.getFullUrl(`/sessions/${sessionId}`), {
+                headers: this.client.headers,
+            }), `No session found for session ${sessionId}`);
+            const responseData = yield response.json();
+            return new Session(responseData);
+        });
+    }
+    synthesizeQuestion(sessionId, lastN = 3) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!sessionId || !sessionId.trim()) {
+                throw new Error("sessionId must be provided");
+            }
+            const response = yield handleRequest(fetch(`${this.client.getFullUrl(`/sessions/${sessionId}/synthesize_question`)}?lastNMessages=${lastN}`, {
+                headers: this.client.headers,
+            }), `No session found for session ${sessionId}`);
+            const responseData = (yield response.json());
+            return responseData.question;
+        });
+    }
+    /**
+     * Adds a session.
+     *
+     * @param {Session} session - The session to add.
+     * @returns {Promise<Session>} The added session.
+     * @throws {Error} Will throw an error if the session is not provided.
+     * @throws {Error} Will throw an error if the session.session_id is not provided.
+     * @throws {APIError} Will throw an error if the fetch request fails.
+     */
+    addSession(session) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!session) {
+                throw new Error("session must be provided");
+            }
+            if (!session.session_id || session.session_id.trim() === "") {
+                throw new Error("session.session_id must be provided");
+            }
+            const response = yield handleRequest(fetch(this.client.getFullUrl(`/sessions`), {
+                method: "POST",
+                headers: Object.assign(Object.assign({}, this.client.headers), { "Content-Type": "application/json" }),
+                body: JSON.stringify(session.toDict()),
+            }), `Failed to add session ${session.session_id}`);
+            const responseData = yield response.json();
+            return new Session(responseData);
+        });
+    }
+    /**
+     * Updates the specified session.
+     *
+     * @param {Session} session - The session data to update.
+     * @returns {Promise<Session>} The updated session.
+     * @throws {Error} Will throw an error if the session is not provided.
+     * @throws {Error} Will throw an error if the session.session_id is not provided.
+     * @throws {APIError} Will throw an error if the fetch request fails.
+     * @throws {NotFoundError} Will throw an error if the session is not found.
+     */
+    updateSession(session) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!session) {
+                throw new Error("session must be provided");
+            }
+            if (!session.session_id || session.session_id.trim() === "") {
+                throw new Error("session.session_id must be provided");
+            }
+            const response = yield handleRequest(fetch(this.client.getFullUrl(`/sessions/${session.session_id}`), {
+                method: "PATCH",
+                headers: Object.assign(Object.assign({}, this.client.headers), { "Content-Type": "application/json" }),
+                body: JSON.stringify(session.toDict()),
+            }), `Failed to update session ${session.session_id}`);
+            const responseData = yield response.json();
+            return new Session(responseData);
+        });
+    }
+    /**
+     * Asynchronously retrieve a list of paginated sessions.
+     *
+     * @param {number} [limit] - Limit the number of results returned.
+     * @param {number} [cursor] - Cursor for pagination.
+     * @returns {Promise<Array<Session>>} A list of all sessions paginated.
+     * @throws {APIError} If the API response format is unexpected.
+     */
+    listSessions(limit, cursor) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const params = new URLSearchParams();
+            if (limit !== undefined)
+                params.append("limit", limit.toString());
+            if (cursor !== undefined)
+                params.append("cursor", cursor.toString());
+            const response = yield handleRequest(fetch(`${this.client.getFullUrl("/sessions")}?${params.toString()}`, {
+                headers: this.client.headers,
+            }), `Failed to get sessions`);
+            const responseData = yield response.json();
+            return responseData.map((session) => new Session(session));
+        });
+    }
+    /**
+     * Retrieve all sessions, handling pagination automatically.
+     * Yields a generator of lists of sessions.
+     *
+     * @param {number} [chunkSize=100] - The number of sessions to retrieve at a time.
+     * @returns {AsyncGenerator<Array<Session>, void, unknown>}
+     *    The next chunk of sessions from the server.
+     * @throws {APIError} If the API response format is unexpected.
+     * @throws {ConnectionError} If the connection to the server fails.
+     */
+    listSessionsChunked(chunkSize = 100) {
+        return __asyncGenerator(this, arguments, function* listSessionsChunked_1() {
+            let cursor;
+            while (true) {
+                // eslint-disable-next-line no-await-in-loop
+                const sessions = yield __await(this.listSessions(chunkSize, cursor));
+                if (sessions.length === 0) {
+                    // We've reached the last page
+                    break;
+                }
+                yield yield __await(sessions);
+                if (cursor === undefined) {
+                    cursor = 0;
+                }
+                cursor += chunkSize;
+            }
+        });
+    }
+    /**
+     * Retrieves memory for a specific session.
+     * @param {string} sessionID - The ID of the session to retrieve memory for.
+     * @param {MemoryType} [type] - Optional. The type of memory to retrieve. Defaults to perpetual.
+     * @param {number} [lastn] - Optional. The number of most recent memories to retrieve.
+     * @returns {Promise<Array<Memory>>} - A promise that returns a Memory object.
+     * @throws {APIError} - If the request fails.
+     * @throws {NotFoundError} - If the session is not found.
+     */
+    getMemory(sessionID, type, lastn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = this.client.getFullUrl(`/sessions/${sessionID}/memory`);
+            let params = lastn !== undefined ? `?lastn=${lastn}` : "";
+            const memoryType = type !== null && type !== void 0 ? type : "perpetual";
+            params +=
+                lastn !== undefined
+                    ? `&memoryType=${memoryType}`
+                    : `?memoryType=${memoryType}`;
+            const response = yield handleRequest(fetch(`${url}${params}`, {
+                headers: this.client.headers,
+            }));
+            const data = yield response.json();
+            if (data.messages) {
+                return new Memory({
+                    messages: data.messages.map((message) => {
+                        return new Message(message);
+                    }),
+                    summary: data.summary,
+                    facts: data.facts,
+                });
+            }
+            return null;
+        });
+    }
+    /**
+     * Adds a new memory to a specific session.
+     * @param {string} sessionID - The ID of the session to add the memory to.
+     * @param {Memory} memory - The memory object to add to the session.
+     * @returns {Promise<Memory>} A promise that resolves to the added memory.
+     * @throws {APIError} If the request fails.
+     */
+    addMemory(sessionID, memory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = this.client.getFullUrl(`/sessions/${sessionID}/memory`);
+            const response = yield handleRequest(fetch(url, {
+                method: "POST",
+                headers: Object.assign(Object.assign({}, this.client.headers), { "Content-Type": "application/json" }),
+                body: JSON.stringify(memory.toDict()),
+            }), `Memory not found for session ${sessionID}.`);
+            return response.text();
+        });
+    }
+    /**
+     * Deletes the memory of a specific session.
+     * @param {string} sessionID - The ID of the session for which the memory
+     *                             should be deleted.
+     * @returns {Promise<string>} - Promise message indicating the memory has
+     *                              been deleted.
+     * @throws {APIError} - If the request fails.
+     * @throws {NotFoundError} - If the session is not found.
+     */
+    deleteMemory(sessionID) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = this.client.getFullUrl(`/sessions/${sessionID}/memory`);
+            const response = yield handleRequest(fetch(url, {
+                method: "DELETE",
+                headers: this.client.headers,
+            }), `No session found for sessionID: ${sessionID}`);
+            return response.text();
+        });
+    }
+    /**
+     * Searches memory of a specific session based on search payload provided.
+     * @param {string} sessionID - ID of the session for which the memory should be searched.
+     * @param {MemorySearchPayload} searchPayload - The search payload containing
+     * the search criteria.
+     * @param {number} [limit] - Optional limit on the number of search results returned.
+     * @returns {Promise<Array<MemorySearchResult>>} - Promise that resolves to array of search
+     * results.
+     * @throws {APIError} - If the request fails.
+     */
+    searchMemory(sessionID, searchPayload, limit) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const url = this.client.getFullUrl(`/sessions/${sessionID}/search`);
+            const params = limit !== undefined ? `?limit=${limit}&` : "";
+            const response = yield handleRequest(fetch(`${url}${params}`, {
+                method: "POST",
+                headers: Object.assign(Object.assign({}, this.client.headers), { "Content-Type": "application/json" }),
+                body: JSON.stringify(searchPayload),
+            }));
+            const data = yield response.json();
+            return data.map((searchResult) => new MemorySearchResult(searchResult));
+        });
+    }
+    /**
+     * Asynchronously classifies a session with the specified ID.
+     *
+     * @param sessionId - The ID of the session to classify.
+     * @param name - The name of the classifier. Used to store the classification in session metadata if persist is true.
+     * @param classes - The classes to use for classification.
+     * @param lastN - (Optional) The number of session messages to consider for classification. Defaults to 4.
+     * @param persist - (Optional) Whether to persist the classification to session metadata.
+     * Defaults to true.
+     * @param instruction - (Optional) Custom instruction for classification.
+     * @returns A promise that resolves to the classification response object.
+     *
+     * @throws Error if session ID, name, or classes are not provided or are invalid.
+     */
+    classifySession(sessionId, name, classes, lastN, persist = true, instruction = undefined) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!sessionId || sessionId.trim() === "") {
+                throw new Error("sessionId must be provided");
+            }
+            if (!name || name.trim() === "") {
+                throw new Error("name must be provided");
+            }
+            if (!classes || classes.length === 0) {
+                throw new Error("classes must be provided");
+            }
+            const request = {
+                sessionId,
+                name,
+                classes,
+                lastN,
+                persist,
+                instruction,
+            };
+            const url = this.client.getFullUrl(`/sessions/${sessionId}/classify`);
+            const response = yield handleRequest(fetch(url, {
+                method: "POST",
+                headers: Object.assign(Object.assign({}, this.client.headers), { "Content-Type": "application/json" }),
+                body: JSON.stringify(request),
+            }));
+            const data = yield response.json();
+            return data;
+        });
+    }
+}

package/esm/memory_models.d.ts

@@ -0,0 +1,184 @@
+import { IMessage, Message } from "./message_models";
+/**
+ * Interface for Session data.
+ */
+export interface ISession {
+    uuid?: string;
+    created_at?: string;
+    updated_at?: string;
+    deleted_at?: string;
+    session_id: string;
+    metadata: Record<string, any>;
+    user_id?: string;
+}
+/**
+ * Represents a session object with a unique identifier, metadata, and other attributes.
+ */
+export declare class Session {
+    uuid?: string;
+    created_at?: string;
+    updated_at?: string;
+    deleted_at?: string;
+    session_id: string;
+    metadata: Record<string, any>;
+    user_id?: string;
+    /**
+     * Constructs a new Session instance.
+     * @param {ISession} data - The data to create a Session instance.
+     */
+    constructor(data: ISession);
+    /**
+     * Converts the Session instance to a dictionary.
+     * @returns {ISession} A dictionary representation of Session instance.
+     */
+    toDict(): ISession;
+}
+/**
+ * ISummary interface for providing input to create a Summary instance.
+ */
+export interface ISummary {
+    uuid: string;
+    created_at: string;
+    content: string;
+    metadata?: Record<string, any>;
+    recent_message_uuid: string;
+    token_count: number;
+}
+/**
+ * Represents a summary of a memory.
+ */
+export declare class Summary {
+    uuid: string;
+    created_at: string;
+    content: string;
+    metadata?: Record<string, any>;
+    recent_message_uuid: string;
+    token_count: number;
+    /**
+     * Constructs a new Summary instance.
+     * @param {ISummary} data - The data to create a summary instance.
+     */
+    constructor(data: ISummary);
+    /**
+     * Converts the Summary instance to a dictionary.
+     * @returns {ISummary} A dictionary representation of Summary instance.
+     */
+    toDict(): ISummary;
+}
+/**
+ * IMemory interface for providing input to create a Memory instance.
+ */
+export interface IMemory {
+    messages?: IMessage[];
+    metadata?: Record<string, any>;
+    summary?: ISummary;
+    facts?: string[];
+    uuid?: string;
+    created_at?: string;
+    token_count?: number;
+}
+/**
+ * Represents a memory containing messages, metadata, and a summary.
+ */
+export declare class Memory {
+    messages: Message[];
+    metadata: Record<string, any>;
+    summary?: Summary;
+    facts: string[];
+    uuid?: string;
+    created_at?: string;
+    token_count?: number;
+    /**
+     * Constructs a new Memory instance.
+     * @param {IMemory} data - The data to create a memory instance.
+     */
+    constructor(data?: IMemory);
+    /**
+     * Converts the Memory instance to a dictionary.
+     * @returns {IMemory} A dictionary representation of the Memory instance.
+     */
+    toDict(): IMemory;
+}
+/**
+ * SearchPayloadData interface for providing input to create SearchPayload.
+ */
+export interface IMemorySearchPayload {
+    text?: string;
+    metadata?: Record<string, any>;
+    search_scope?: "messages" | "summary";
+    search_type?: "similarity" | "mmr";
+    mmr_lambda?: number;
+}
+/**
+ * Represents the payload for a memory search.
+ *
+ * @property {string} text - The text to search for.
+ * @property {Record<string, any>} metadata - The metadata to filter the search by.
+ * @property {string} search_type - The type of search to perform. Either "similarity" or "mmr".
+ * @property {number} mmr_lambda - The lambda value to use for MMR reranking.
+ */
+export declare class MemorySearchPayload {
+    metadata?: Record<string, any>;
+    text?: string;
+    search_scope?: "messages" | "summary";
+    search_type?: "similarity" | "mmr";
+    mmr_lambda?: number;
+    /**
+     * Constructs a new SearchPayload instance.
+     * @param {IMemorySearchPayload} data - The data to create a Search Payload.
+     */
+    constructor(data: IMemorySearchPayload);
+}
+/**
+ * SearchResultData interface for providing input to create a SearchResult.
+ */
+export interface IMemorySearchResult {
+    message?: IMessage;
+    summary?: Summary;
+    metadata?: Record<string, any>;
+    score?: number;
+}
+/**
+ * Represents a search result from a memory search.
+ */
+export declare class MemorySearchResult {
+    message?: Message;
+    summary?: Summary;
+    metadata: Record<string, any>;
+    score?: number;
+    /**
+     * Constructs a new SearchResult instance.
+     * @param {IMemorySearchResult} data - The data to create a search result instance.
+     *
+     * @property {Message} message - The message that was found.
+     * @property {Summary} summary - The summary that was found.
+     * @property {Record<string, any>} metadata - The metadata of the result, if any.
+     * @property {string} summary - The summary of the message.
+     * @property {number} score - The score of the result.
+     */
+    constructor(data?: IMemorySearchResult);
+}
+export interface Question {
+    question: string;
+}
+export interface ClassifySessionRequest {
+    /** Unique identifier of the session */
+    sessionId: string;
+    /** Name of the classifier (e.g. "emotion" or "intent") */
+    name: string;
+    /** List of classes to classify the session into */
+    classes: string[];
+    /** Number of session messages to consider for classification (default is 4) */
+    lastN?: number;
+    /** Whether to persist the classification to session metadata (default is true) */
+    persist?: boolean;
+    /** Custom instruction for classification */
+    instruction?: string;
+}
+/** Response after classifying a session */
+export interface ClassifySessionResponse {
+    /** Name of the classification algorithm or rule set used */
+    name: string;
+    /** Class the session is classified into */
+    class: string;
+}

package/esm/memory_models.js

@@ -0,0 +1,141 @@
+import { Message } from "./message_models";
+/**
+ * Represents a session object with a unique identifier, metadata, and other attributes.
+ */
+export class Session {
+    /**
+     * Constructs a new Session instance.
+     * @param {ISession} data - The data to create a Session instance.
+     */
+    constructor(data) {
+        this.uuid = data.uuid;
+        this.created_at = data.created_at;
+        this.updated_at = data.updated_at;
+        this.deleted_at = data.deleted_at;
+        this.session_id = data.session_id;
+        this.metadata = data.metadata;
+        this.user_id = data.user_id;
+    }
+    /**
+     * Converts the Session instance to a dictionary.
+     * @returns {ISession} A dictionary representation of Session instance.
+     */
+    toDict() {
+        return {
+            uuid: this.uuid,
+            created_at: this.created_at,
+            updated_at: this.updated_at,
+            deleted_at: this.deleted_at,
+            session_id: this.session_id,
+            metadata: this.metadata,
+            user_id: this.user_id,
+        };
+    }
+}
+/**
+ * Represents a summary of a memory.
+ */
+export class Summary {
+    /**
+     * Constructs a new Summary instance.
+     * @param {ISummary} data - The data to create a summary instance.
+     */
+    constructor(data) {
+        this.uuid = data.uuid;
+        this.created_at = data.created_at;
+        this.content = data.content;
+        this.metadata = data.metadata;
+        this.recent_message_uuid = data.recent_message_uuid;
+        this.token_count = data.token_count;
+    }
+    /**
+     * Converts the Summary instance to a dictionary.
+     * @returns {ISummary} A dictionary representation of Summary instance.
+     */
+    toDict() {
+        return {
+            uuid: this.uuid,
+            created_at: this.created_at,
+            content: this.content,
+            metadata: this.metadata,
+            recent_message_uuid: this.recent_message_uuid,
+            token_count: this.token_count,
+        };
+    }
+}
+/**
+ * Represents a memory containing messages, metadata, and a summary.
+ */
+export class Memory {
+    /**
+     * Constructs a new Memory instance.
+     * @param {IMemory} data - The data to create a memory instance.
+     */
+    constructor(data = {}) {
+        this.messages = (data.messages || []).map((messageData) => new Message(messageData));
+        this.metadata = data.metadata || {};
+        this.summary = data.summary ? new Summary(data.summary) : undefined;
+        this.uuid = data.uuid;
+        this.created_at = data.created_at;
+        this.token_count = data.token_count;
+        this.facts = data.facts || [];
+    }
+    /**
+     * Converts the Memory instance to a dictionary.
+     * @returns {IMemory} A dictionary representation of the Memory instance.
+     */
+    toDict() {
+        var _a;
+        return {
+            messages: this.messages.map((message) => message.toDict()),
+            metadata: this.metadata,
+            summary: (_a = this.summary) === null || _a === void 0 ? void 0 : _a.toDict(),
+            uuid: this.uuid,
+            created_at: this.created_at,
+            token_count: this.token_count,
+            facts: this.facts,
+        };
+    }
+}
+/**
+ * Represents the payload for a memory search.
+ *
+ * @property {string} text - The text to search for.
+ * @property {Record<string, any>} metadata - The metadata to filter the search by.
+ * @property {string} search_type - The type of search to perform. Either "similarity" or "mmr".
+ * @property {number} mmr_lambda - The lambda value to use for MMR reranking.
+ */
+export class MemorySearchPayload {
+    /**
+     * Constructs a new SearchPayload instance.
+     * @param {IMemorySearchPayload} data - The data to create a Search Payload.
+     */
+    constructor(data) {
+        this.metadata = data.metadata;
+        this.text = data.text;
+        this.search_scope = data.search_scope || "messages";
+        this.search_type = data.search_type || "similarity";
+        this.mmr_lambda = data.mmr_lambda || 0.5;
+    }
+}
+/**
+ * Represents a search result from a memory search.
+ */
+export class MemorySearchResult {
+    /**
+     * Constructs a new SearchResult instance.
+     * @param {IMemorySearchResult} data - The data to create a search result instance.
+     *
+     * @property {Message} message - The message that was found.
+     * @property {Summary} summary - The summary that was found.
+     * @property {Record<string, any>} metadata - The metadata of the result, if any.
+     * @property {string} summary - The summary of the message.
+     * @property {number} score - The score of the result.
+     */
+    constructor(data = {}) {
+        this.message = data.message ? new Message(data.message) : undefined;
+        this.summary = data.summary ? new Summary(data.summary) : undefined;
+        this.metadata = data.metadata || {};
+        this.score = data.score;
+    }
+}

package/esm/message_manager.d.ts

@@ -0,0 +1,9 @@
+import { Message } from "./message_models";
+import { IZepClient } from "./interfaces";
+export default class MessageManager {
+    client: IZepClient;
+    constructor(client: IZepClient);
+    getSessionMessages(sessionId: string, limit?: number, cursor?: number): Promise<Message[]>;
+    getSessionMessage(sessionId: string, messageId: string): Promise<Message>;
+    updateSessionMessageMetadata(sessionId: string, messageId: string, metadata: Record<string, any>): Promise<Message>;
+}