@getzep/zep-cloud 0.0.1-rc.1

package/esm/langchain/vector_store.js

@@ -0,0 +1,319 @@
+/* eslint import/no-extraneous-dependencies: 0 */
+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 __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import { VectorStore, } from "@langchain/core/vectorstores";
+import { Document } from "@langchain/core/documents";
+import { maximalMarginalRelevance } from "@langchain/core/utils/math";
+import { FakeEmbeddings } from "@langchain/core/utils/testing";
+import ZepClient from "../zep-client";
+import { NotFoundError } from "../errors";
+function zepDocsToDocumentsAndScore(results) {
+    return results.map((d) => [
+        new Document({
+            pageContent: d.content,
+            metadata: d.metadata,
+        }),
+        d.score ? d.score : 0,
+    ]);
+}
+function assignMetadata(value) {
+    if (typeof value === "object" && value !== null) {
+        return value;
+    }
+    if (value !== undefined) {
+        console.warn("Metadata filters must be an object, Record, or undefined.");
+    }
+    return undefined;
+}
+/**
+ * ZepVectorStore is a VectorStore implementation
+ * that uses the Zep long-term memory store as a backend.
+ *
+ * If the collection does not exist, it will be created automatically.
+ *
+ * Requires `zep-js` to be installed:
+ * ```bash
+ * npm install @getzep/zep-js
+ * ```
+ *
+ * @property {ZepClient} client - The ZepClient instance used to interact with Zep's API.
+ * @property {Promise<void>} initPromise - A promise that resolves
+ * when the collection is initialized.
+ * @property {DocumentCollection} collection - The Zep document collection.
+ */
+export class ZepVectorStore extends VectorStore {
+    constructor(embeddings, args) {
+        super(embeddings, args);
+        this.initPromise = this.initCollection(args).catch((err) => {
+            console.error("Error initializing collection:", err);
+            throw err;
+        });
+    }
+    /**
+     * Initializes the document collection. If the collection does not exist, it creates a new one.
+     *
+     * @param {IZepConfig} args - The configuration object for the Zep API.
+     */
+    initCollection(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (args.client) {
+                this.client = args.client;
+            }
+            else {
+                this.client = yield ZepClient.init(args.apiKey, args.apiUrl);
+            }
+            try {
+                this.collection = yield this.client.document.getCollection(args.collectionName);
+                // If the Embedding passed in is fake, but the collection is not auto embedded, throw an error
+                if (!this.collection.is_auto_embedded) {
+                    throw new Error(`You can't pass in FakeEmbeddings when collection ${args.collectionName} 
+ is not set to auto-embed.`);
+                }
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    if (err instanceof NotFoundError || err.name === "NotFoundError") {
+                        yield this.createCollection(args);
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * Creates a new document collection.
+     *
+     * @param {IZepConfig} args - The configuration object for the Zep API.
+     */
+    createCollection(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.collection = yield this.client.document.addCollection({
+                name: args.collectionName,
+                description: args.description,
+                metadata: args.metadata,
+            });
+            // eslint-disable-next-line no-console
+            console.info("Created new collection:", args.collectionName);
+        });
+    }
+    /**
+     * Adds vectors and corresponding documents to the collection.
+     *
+     * @param {number[][]} vectors - The vectors to add.
+     * @param {Document[]} documents - The corresponding documents to add.
+     * @returns {Promise<string[]>} - A promise that resolves with the UUIDs of the added documents.
+     */
+    addVectors(vectors, documents) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const docs = [];
+            for (let i = 0; i < documents.length; i += 1) {
+                const doc = {
+                    content: documents[i].pageContent,
+                    metadata: documents[i].metadata,
+                    embedding: vectors.length > 0 ? vectors[i] : undefined,
+                };
+                docs.push(doc);
+            }
+            // Wait for collection to be initialized
+            yield this.initPromise;
+            return this.collection.addDocuments(docs);
+        });
+    }
+    /**
+     * Adds documents to the collection. The documents are first embedded into vectors
+     * using the provided embedding model.
+     *
+     * @param {Document[]} documents - The documents to add.
+     * @returns {Promise<string[]>} - A promise that resolves with the UUIDs of the added documents.
+     */
+    addDocuments(documents) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const vectors = [];
+            return this.addVectors(vectors, documents);
+        });
+    }
+    // eslint-disable-next-line class-methods-use-this,no-underscore-dangle
+    _vectorstoreType() {
+        return "zep";
+    }
+    /**
+     * Deletes documents from the collection.
+     *
+     * @param {IZepDeleteParams} params - The list of Zep document UUIDs to delete.
+     * @returns {Promise<void>}
+     */
+    delete(params) {
+        var _a, e_1, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            // Wait for collection to be initialized
+            yield this.initPromise;
+            try {
+                // eslint-disable-next-line no-restricted-syntax
+                for (var _d = true, _e = __asyncValues(params.uuids), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const uuid = _c;
+                    yield this.collection.deleteDocument(uuid);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        });
+    }
+    /**
+     * Performs a similarity search in the collection and returns the results with their scores.
+     *
+     * @param {number[]} query - The query vector.
+     * @param {number} k - The number of results to return.
+     * @param {Record<string, unknown>} filter - The filter to apply to the search. Zep only supports Record<string, unknown> as filter.
+     * @returns {Promise<[Document, number][]>} - A promise that resolves with the search results and their scores.
+     */
+    similaritySearchVectorWithScore(query, k, filter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            const results = yield this.collection.search({
+                embedding: new Float32Array(query),
+                metadata: assignMetadata(filter),
+            }, k);
+            return zepDocsToDocumentsAndScore(results);
+        });
+    }
+    // eslint-disable-next-line no-underscore-dangle
+    _similaritySearchWithScore(query, k, filter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            const results = yield this.collection.search({
+                text: query,
+                metadata: assignMetadata(filter),
+            }, k);
+            return zepDocsToDocumentsAndScore(results);
+        });
+    }
+    similaritySearchWithScore(query, k = 4, filter = undefined, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _callbacks = undefined) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._similaritySearchWithScore(query, k, filter);
+        });
+    }
+    /**
+     * Performs a similarity search on the Zep collection.
+     *
+     * @param {string} query - The query string to search for.
+     * @param {number} [k=4] - The number of results to return. Defaults to 4.
+     * @param {this["FilterType"] | undefined} [filter=undefined] - An optional set of JSONPath filters to apply to the search.
+     * @param {Callbacks | undefined} [_callbacks=undefined] - Optional callbacks. Currently not implemented.
+     * @returns {Promise<Document[]>} - A promise that resolves to an array of Documents that are similar to the query.
+     *
+     * @async
+     */
+    similaritySearch(query, k = 4, filter = undefined, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _callbacks = undefined) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.initPromise;
+            const zepResults = yield this.collection.search({ text: query, metadata: assignMetadata(filter) }, k);
+            const results = zepDocsToDocumentsAndScore(zepResults);
+            return results.map((result) => result[0]);
+        });
+    }
+    /**
+     * Return documents selected using the maximal marginal relevance.
+     * Maximal marginal relevance optimizes for similarity to the query AND diversity
+     * among selected documents.
+     *
+     * @param {string} query - Text to look up documents similar to.
+     * @param options
+     * @param {number} options.k - Number of documents to return.
+     * @param {number} options.fetchK=20- Number of documents to fetch before passing to the MMR algorithm.
+     * @param {number} options.lambda=0.5 - Number between 0 and 1 that determines the degree of diversity among the results,
+     *                 where 0 corresponds to maximum diversity and 1 to minimum diversity.
+     * @param {Record<string, any>} options.filter - Optional Zep JSONPath query to pre-filter on document metadata field
+     *
+     * @returns {Promise<Document[]>} - List of documents selected by maximal marginal relevance.
+     */
+    maxMarginalRelevanceSearch(query, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { k, fetchK = 20, lambda = 0.5, filter } = options;
+            const [zepResults, queryEmbeddingArray] = yield this.collection.searchReturnQueryVector({ text: query, metadata: assignMetadata(filter) }, fetchK);
+            const queryEmbedding = Array.from(queryEmbeddingArray);
+            const results = zepDocsToDocumentsAndScore(zepResults);
+            const embeddingList = zepResults.map((doc) => Array.from(doc.embedding ? doc.embedding : []));
+            const mmrIndexes = maximalMarginalRelevance(queryEmbedding, embeddingList, lambda, k);
+            return mmrIndexes
+                .filter((idx) => idx !== -1)
+                .map((idx) => results[idx][0]);
+        });
+    }
+    static init(zepConfig) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = new this(new FakeEmbeddings(), zepConfig);
+            // Wait for collection to be initialized
+            yield instance.initPromise;
+            return instance;
+        });
+    }
+    /**
+     * Creates a new ZepVectorStore instance from an array of texts. Each text is converted into a Document and added to the collection.
+     *
+     * @param {string[]} texts - The texts to convert into Documents.
+     * @param {object[] | object} metadatas - The metadata to associate with each Document.
+     * If an array is provided, each element is associated with the corresponding Document.
+     * If an object is provided, it is associated with all Documents.
+     * @param {Embeddings} embeddings - The embeddings to use for vectorizing the texts.
+     * @param {IZepConfig} zepConfig - The configuration object for the Zep API.
+     * @returns {Promise<ZepVectorStore>} - A promise that resolves with the new ZepVectorStore instance.
+     */
+    static fromTexts(texts, metadatas, embeddings, zepConfig) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const docs = [];
+            for (let i = 0; i < texts.length; i += 1) {
+                const metadata = Array.isArray(metadatas) ? metadatas[i] : metadatas;
+                const newDoc = new Document({
+                    pageContent: texts[i],
+                    metadata,
+                });
+                docs.push(newDoc);
+            }
+            return ZepVectorStore.fromDocuments(docs, embeddings, zepConfig);
+        });
+    }
+    /**
+     * Creates a new ZepVectorStore instance from an array of Documents. Each Document is added to a Zep collection.
+     *
+     * @param {Document[]} docs - The Documents to add.
+     * @param {Embeddings} embeddings - The embeddings to use for vectorizing the Document contents.
+     * @param {IZepConfig} zepConfig - The configuration object for the Zep API.
+     * @returns {Promise<ZepVectorStore>} - A promise that resolves with the new ZepVectorStore instance.
+     */
+    static fromDocuments(docs, embeddings, zepConfig) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instance = new this(embeddings, zepConfig);
+            // Wait for collection to be initialized
+            yield instance.initPromise;
+            yield instance.addDocuments(docs);
+            return instance;
+        });
+    }
+}

package/esm/langchain/zep_message_placeholder.d.ts

@@ -0,0 +1,23 @@
+import { InputValues } from "@langchain/core/memory";
+import { BaseMessagePromptTemplate, MessagesPlaceholderFields, TypedPromptInputValues } from "@langchain/core/prompts";
+import { BaseMessage } from "@langchain/core/messages";
+interface ZepMessagesPlaceholderFields<T extends string> {
+    variableName: T;
+    systemPrompt: string;
+    optional?: boolean;
+}
+/**
+ * Class that represents a placeholder for messages in a chat prompt. It
+ * extends the BaseMessagePromptTemplate.
+ */
+export declare class ZepMessagesPlaceholder<RunInput extends InputValues = any> extends BaseMessagePromptTemplate<RunInput> implements MessagesPlaceholderFields<Extract<keyof RunInput, string>> {
+    static lc_name(): string;
+    variableName: Extract<keyof RunInput, string>;
+    systemPrompt: string;
+    optional: boolean;
+    constructor(fields: ZepMessagesPlaceholderFields<Extract<keyof RunInput, string>>);
+    get inputVariables(): Extract<keyof RunInput, string>[];
+    validateInputOrThrow(input: Array<unknown> | undefined, variableName: Extract<keyof RunInput, string>): input is BaseMessage[];
+    formatMessages(values: TypedPromptInputValues<RunInput>): Promise<BaseMessage[]>;
+}
+export {};

package/esm/langchain/zep_message_placeholder.js

@@ -0,0 +1,73 @@
+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());
+    });
+};
+import { BaseMessagePromptTemplate, } from "@langchain/core/prompts";
+import { isBaseMessage, SystemMessage, } from "@langchain/core/messages";
+/**
+ * Class that represents a placeholder for messages in a chat prompt. It
+ * extends the BaseMessagePromptTemplate.
+ */
+export class ZepMessagesPlaceholder extends BaseMessagePromptTemplate {
+    static lc_name() {
+        return "ZepMessagesPlaceholder";
+    }
+    constructor(fields) {
+        var _a;
+        super(fields);
+        this.variableName = fields.variableName;
+        this.systemPrompt = fields.systemPrompt;
+        this.optional = (_a = fields.optional) !== null && _a !== void 0 ? _a : false;
+    }
+    get inputVariables() {
+        return [this.variableName];
+    }
+    validateInputOrThrow(input, variableName) {
+        if (this.optional && !input) {
+            return false;
+        }
+        if (!input) {
+            const error = new Error(`Error: Field "${variableName}" in prompt uses a ZepMessagesPlaceholder, which expects an array of BaseMessages as an input value. Received: undefined`);
+            error.name = "InputFormatError";
+            throw error;
+        }
+        let isInputBaseMessage = false;
+        if (Array.isArray(input)) {
+            isInputBaseMessage = input.every((message) => isBaseMessage(message));
+        }
+        else {
+            isInputBaseMessage = isBaseMessage(input);
+        }
+        if (!isInputBaseMessage) {
+            const readableInput = typeof input === "string" ? input : JSON.stringify(input, null, 2);
+            const error = new Error(`Error: Field "${variableName}" in prompt uses a ZepMessagesPlaceholder, which expects an array of BaseMessages as an input value. Received: ${readableInput}`);
+            error.name = "InputFormatError";
+            throw error;
+        }
+        return true;
+    }
+    formatMessages(values) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateInputOrThrow(values[this.variableName], this.variableName);
+            const messages = values[this.variableName];
+            const systemMessages = messages.filter((m) => m instanceof SystemMessage);
+            if (systemMessages.length) {
+                const concatenatedSystemPrompt = systemMessages
+                    .map((m) => m.content)
+                    .join("\n");
+                return [
+                    new SystemMessage({
+                        content: `${this.systemPrompt}\n${concatenatedSystemPrompt}`,
+                    }),
+                    ...messages.filter((m) => !(m instanceof SystemMessage)),
+                ];
+            }
+            return messages !== null && messages !== void 0 ? messages : [];
+        });
+    }
+}

package/esm/memory_manager.d.ts

@@ -0,0 +1,112 @@
+import { ClassifySessionResponse, Memory, MemorySearchPayload, MemorySearchResult, Session } from "./memory_models";
+import { IZepClient, MemoryType } from "./interfaces";
+export default class MemoryManager {
+    client: IZepClient;
+    constructor(client: IZepClient);
+    /**
+     * 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: string): Promise<Session>;
+    synthesizeQuestion(sessionId: string, lastN?: number): Promise<string>;
+    /**
+     * 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: Session): Promise<Session>;
+    /**
+     * 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: Session): Promise<Session>;
+    /**
+     * 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?: number, cursor?: number): Promise<Array<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?: number): AsyncGenerator<Array<Session>, void, unknown>;
+    /**
+     * 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: string, type?: MemoryType, lastn?: number): Promise<Memory | 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: string, memory: Memory): Promise<string>;
+    /**
+     * 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: string): Promise<string>;
+    /**
+     * 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: string, searchPayload: MemorySearchPayload, limit?: number): Promise<Array<MemorySearchResult>>;
+    /**
+     * 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: string, name: string, classes: string[], lastN?: number, persist?: boolean, instruction?: string | undefined): Promise<ClassifySessionResponse>;
+}