@getzep/zep-cloud 0.0.1-rc.1

package/examples/documents/index.ts

@@ -0,0 +1,188 @@
+/**
+ * This file demonstrates the following features of Zep:
+ * 1. Checking the embedding status of a collection.
+ * 2. Reading a chunk of text from a file.
+ * 3. Printing the results of a search.
+ * 4. Searching for documents using both text and metadata.
+ * 5. MMR Search Re-ranking.
+ * 6. Searching for documents similar to a given document using embeddings.
+ * 7. Searching for non-existent documents.
+ */
+
+import * as fs from "fs";
+import { faker } from "@faker-js/faker";
+import { ZepClient } from "../../src";
+import { Document } from "../../src/api/resources/document/client/Client";
+import { CreateDocumentRequest, DocumentSearchResult } from "../../src/api";
+
+/**
+ * checkEmbeddingStatus checks the embedding status of a collection.
+ * It waits until all documents in the collection are embedded.
+ * @param client - The ZepClient instance.
+ * @param collectionName - The name of the collection.
+ */
+async function checkEmbeddingStatus(client: ZepClient, collectionName: string): Promise<void> {
+    let c = await client.document.getCollection(collectionName);
+
+    while (c.documentEmbeddedCount != c.documentCount) {
+        console.log(`Embedding status: ${c.documentEmbeddedCount}/${c.documentCount} documents embedded`);
+        // Wait for 1 second
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+
+        // Fetch the collection again to get the updated status
+        c = await client.document.getCollection(collectionName);
+    }
+}
+
+/**
+ * readChunkFromFile reads a chunk of text from a file.
+ * @param file - The file to read from.
+ * @param chunkSize - The size of the chunk to read.
+ * @returns An array of strings, each string being a chunk of text.
+ */
+function readChunkFromFile(file: string, chunkSize: number): string[] {
+    const text = fs.readFileSync(file, "utf8");
+    const chunks = naiveSplitText(text, chunkSize);
+    console.log(`Splitting text into ${chunks.length} chunks of max size ${chunkSize} characters.`);
+    return chunks;
+}
+
+/**
+ * printResults prints the results of a search.
+ * @param results - The results of the search.
+ */
+function printResults(results: DocumentSearchResult[]): void {
+    for (const result of results) {
+        console.log(`${result.content} - ${JSON.stringify(result.metadata)} -> ${result.score}\n`);
+    }
+}
+
+/**
+ * naiveSplitText splits a text into chunks of a maximum size.
+ * It's a simple chunke that uses paragraphs and sentences as guides.
+ * @param text - The text to split.
+ * @param maxChunkSize - The maximum size of a chunk.
+ * @returns An array of strings, each string being a chunk of text.
+ */
+function naiveSplitText(text: string, maxChunkSize: number): string[] {
+    // Naive text splitter chunks document into chunks of maxChunkSize,
+    // using paragraphs and sentences as guides.
+
+    const chunks: string[] = [];
+
+    // Remove extraneous whitespace
+    text = text.split(/\s+/).join(" ");
+
+    // Split into paragraphs
+    let paragraphs = text.split("\n\n");
+
+    // Clean up paragraphs
+    paragraphs = paragraphs.map((p) => p.trim()).filter((p) => p.length > 0);
+
+    for (const paragraph of paragraphs) {
+        if (paragraph.length > 0 && paragraph.length <= maxChunkSize) {
+            chunks.push(paragraph);
+        } else {
+            const sentences = paragraph.split(". ");
+            let currentChunk = "";
+
+            for (const sentence of sentences) {
+                if (currentChunk.length + sentence.length > maxChunkSize) {
+                    chunks.push(currentChunk);
+                    currentChunk = sentence;
+                } else {
+                    currentChunk += (currentChunk ? ". " : "") + sentence;
+                }
+            }
+
+            if (currentChunk) {
+                chunks.push(currentChunk);
+            }
+        }
+    }
+
+    return chunks;
+}
+
+/**
+ * This demonstrates how to use the ZepClient to interact with a Zep API.
+ */
+async function main() {
+    const projectApiKey = process.env.ZEP_API_KEY;
+
+    const file = "babbages_calculating_engine.txt";
+    const maxChunkSize = 500;
+    const collectionName = `babbage${faker.string.alphanumeric({ length: 8 })}`;
+
+    console.log(`Creating collection ${collectionName}`);
+
+    const client = new ZepClient({
+        apiKey: projectApiKey,
+    });
+    await client.document.addCollection(collectionName, {
+        description: "Babbage's Calculating Engine", // optional
+        metadata: { qux: faker.string.sample() }, // optional
+    });
+
+    console.log(`Created collection ${collectionName}`);
+
+    const chunks = readChunkFromFile(file, maxChunkSize);
+
+    const documents: CreateDocumentRequest[] = chunks.map((chunk) => ({
+        content: chunk,
+        documentId: faker.system.fileName(), // optional document ID used in your system
+        metadata: { foo: faker.string.sample(), bar: "qux" }, // optional metadata
+    }));
+
+    console.log(`Adding ${documents.length} documents to collection ${collectionName}`);
+
+    const uuids = await client.document.addDocuments(collectionName, documents);
+
+    console.log(`Added ${uuids.length} documents to collection ${collectionName}`);
+
+    await checkEmbeddingStatus(client, collectionName);
+
+    // Search for documents using text
+    const query = "The celestial motions are nothing but a continual";
+    const { results: searchResults } = await client.document.search(collectionName, {
+        text: query,
+        limit: 3,
+    });
+    console.log(`Found ${searchResults!.length} documents matching query '${query}'`);
+    printResults(searchResults!);
+
+    const mmrSearchResults = await client.document.search(collectionName, {
+        text: query,
+        searchType: "mmr",
+        mmrLambda: 0.6,
+    });
+    console.log(`Found ${mmrSearchResults.results?.length} documents matching MMR query '${query}'`);
+    printResults(mmrSearchResults.results!);
+
+    // Search for documents using both text and metadata
+    const metadataQuery = {
+        where: { jsonpath: '$[*] ? (@.bar == "qux")' },
+    };
+
+    const { results: newSearchResults } = await client.document.search(collectionName, {
+        text: query,
+        metadata: metadataQuery,
+        limit: 3,
+    });
+    console.log(`Found ${newSearchResults!.length} documents matching query '${query}' ${metadataQuery}`);
+    printResults(newSearchResults!);
+
+    // Search for non-existent documents will result in an empty array
+    await client.document.search(collectionName, {
+        metadata: {
+            where: { jsonpath: '$[*] ? (@.this_key_does == "not exist")' },
+        },
+        limit: 3,
+    });
+
+    // Delete the collection
+    console.log(`Deleting collection ${collectionName}`);
+    await client.document.deleteCollection(collectionName);
+}
+
+main();

package/examples/langchain/message_history_anthropic_example.ts

@@ -0,0 +1,61 @@
+import { ZepClient } from "../../src";
+import { ZepChatMessageHistory } from "../../src/langchain";
+import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
+import { RunnableWithMessageHistory } from "@langchain/core/runnables";
+import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";
+import { ChatAnthropic } from "@langchain/anthropic";
+
+async function main() {
+    const sessionId = process.env.ZEP_SESSION_ID;
+    if (!sessionId) {
+        throw new Error("ZEP_SESSION_ID not set");
+    }
+
+    const zepClient = new ZepClient({
+        apiKey: process.env.ZEP_API_KEY,
+    });
+
+    const prompt = ChatPromptTemplate.fromMessages([
+        ["system", "Answer the user's question below. Be polite and helpful:"],
+        new MessagesPlaceholder("history"),
+        ["human", "{question}"],
+    ]);
+
+    const chain = prompt
+        .pipe(
+            new ChatAnthropic({
+                temperature: 0.8,
+                modelName: "claude-3-sonnet-20240229",
+            })
+        )
+        .withConfig({
+            callbacks: [new ConsoleCallbackHandler()],
+        });
+
+    const chainWithHistory = new RunnableWithMessageHistory({
+        runnable: chain,
+        getMessageHistory: (sessionId) =>
+            new ZepChatMessageHistory({
+                client: zepClient,
+                sessionId: sessionId,
+                memoryType: "perpetual",
+            }),
+        inputMessagesKey: "question",
+        historyMessagesKey: "history",
+    });
+
+    const result = await chainWithHistory.invoke(
+        {
+            question: "What did we talk about earlier?",
+        },
+        {
+            configurable: {
+                sessionId: sessionId,
+            },
+        }
+    );
+
+    console.log("result", result);
+}
+
+main();

package/examples/langchain/message_history_example.ts

@@ -0,0 +1,60 @@
+import { ZepClient } from "../../src";
+import { ZepChatMessageHistory } from "../../src/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
+import { RunnableWithMessageHistory } from "@langchain/core/runnables";
+import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";
+
+async function main() {
+    const sessionId = process.env.ZEP_SESSION_ID;
+    if (!sessionId) {
+        throw new Error("ZEP_SESSION_ID not set");
+    }
+    const zepClient = new ZepClient({
+        apiKey: process.env.ZEP_API_KEY,
+    });
+
+    const prompt = ChatPromptTemplate.fromMessages([
+        ["system", "Answer the user's question below. Be polite and helpful:"],
+        new MessagesPlaceholder("history"),
+        ["human", "{question}"],
+    ]);
+
+    const chain = prompt
+        .pipe(
+            new ChatOpenAI({
+                temperature: 0.8,
+                modelName: "gpt-3.5-turbo-1106",
+            })
+        )
+        .withConfig({
+            callbacks: [new ConsoleCallbackHandler()],
+        });
+
+    const chainWithHistory = new RunnableWithMessageHistory({
+        runnable: chain,
+        getMessageHistory: (sessionId) =>
+            new ZepChatMessageHistory({
+                client: zepClient,
+                sessionId: sessionId,
+                memoryType: "perpetual",
+            }),
+        inputMessagesKey: "question",
+        historyMessagesKey: "history",
+    });
+
+    const result = await chainWithHistory.invoke(
+        {
+            question: "What did we talk about earlier?",
+        },
+        {
+            configurable: {
+                sessionId: sessionId,
+            },
+        }
+    );
+
+    console.log("result", result);
+}
+
+main();

package/examples/langchain/message_history_vector_store_example.ts

@@ -0,0 +1,122 @@
+import { ZepClient } from "../../src";
+import { ChatOpenAI } from "@langchain/openai";
+import { BasePromptTemplate, ChatPromptTemplate, MessagesPlaceholder, PromptTemplate } from "@langchain/core/prompts";
+import { ZepChatMessageHistory, ZepVectorStore } from "../../src/langchain";
+import { Document } from "@langchain/core/documents";
+import {
+    RunnableLambda,
+    RunnableMap,
+    RunnablePassthrough,
+    RunnableWithMessageHistory,
+} from "@langchain/core/runnables";
+import { StringOutputParser } from "@langchain/core/output_parsers";
+import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";
+import { formatDocument } from "langchain/schema/prompt_template";
+
+const DEFAULT_DOCUMENT_PROMPT = PromptTemplate.fromTemplate("{pageContent}");
+interface ChainInput {
+    question: string;
+    sessionId: string;
+}
+async function combineDocuments(
+    docs: Document[],
+    documentPrompt: BasePromptTemplate = DEFAULT_DOCUMENT_PROMPT,
+    documentSeparator: string = "\n\n"
+) {
+    const docStrings: string[] = await Promise.all(
+        docs.map((doc) => {
+            return formatDocument(doc, documentPrompt);
+        })
+    );
+    return docStrings.join(documentSeparator);
+}
+async function main() {
+    const collectionName = process.env.ZEP_COLLECTION_NAME;
+    if (!collectionName) {
+        throw new Error("ZEP_COLLECTION_NAME is required");
+    }
+    const sessionId = process.env.ZEP_SESSION_ID;
+    if (!sessionId) {
+        throw new Error("ZEP_SESSION_ID is required");
+    }
+    const zepClient = new ZepClient({
+        apiKey: process.env.ZEP_API_KEY,
+    });
+
+    const vectorStore = await ZepVectorStore.init({
+        client: zepClient,
+        collectionName: collectionName,
+    });
+
+    const prompt = ChatPromptTemplate.fromMessages([
+        ["system", `Answer the question based only on the following context: {context}`],
+        new MessagesPlaceholder("history"),
+        ["human", "{question}"],
+    ]);
+
+    const model = new ChatOpenAI({
+        temperature: 0.8,
+        modelName: "gpt-3.5-turbo-1106",
+    });
+    const retriever = vectorStore.asRetriever();
+    const searchQuery = new RunnableLambda({
+        func: async (input: any) => {
+            const { question } = await zepClient.memory.synthesizeQuestion(input.session_id);
+            return question;
+        },
+    });
+    const retrieverLambda = new RunnableLambda({
+        func: async (question: string) => {
+            const response = await retriever.invoke(question);
+            return combineDocuments(response);
+        },
+    });
+    const setupAndRetrieval = RunnableMap.from({
+        context: searchQuery.pipe(retrieverLambda),
+        question: (x: any) => x.question,
+        history: (x: any) => x.history,
+    });
+    const outputParser = new StringOutputParser();
+
+    const ragChain = setupAndRetrieval.pipe(prompt).pipe(model).pipe(outputParser);
+
+    const invokeChain = (chainInput: ChainInput) => {
+        const chainWithHistory = new RunnableWithMessageHistory({
+            runnable: RunnablePassthrough.assign({
+                session_id: () => chainInput.sessionId,
+            }).pipe(ragChain),
+            getMessageHistory: (sessionId) =>
+                new ZepChatMessageHistory({
+                    client: zepClient,
+                    sessionId: sessionId,
+                    memoryType: "perpetual",
+                }),
+            inputMessagesKey: "question",
+            historyMessagesKey: "history",
+        });
+
+        return chainWithHistory.invoke(
+            { question: chainInput.question },
+            {
+                configurable: {
+                    sessionId: chainInput.sessionId,
+                },
+            }
+        );
+    };
+
+    const chain = new RunnableLambda({
+        func: invokeChain,
+    }).withConfig({
+        callbacks: [new ConsoleCallbackHandler()],
+    });
+
+    const result = await chain.invoke({
+        question: "Project Gutenberg?",
+        sessionId: sessionId,
+    });
+
+    console.log("result", result);
+}
+
+main();

package/examples/langchain/vector_store_example.ts

@@ -0,0 +1,71 @@
+import { ZepClient } from "../../src";
+import { ChatOpenAI } from "@langchain/openai";
+import { BasePromptTemplate, ChatPromptTemplate, PromptTemplate } from "@langchain/core/prompts";
+import { ZepVectorStore } from "../../src/langchain";
+import { Document } from "@langchain/core/documents";
+import { RunnableMap, RunnableLambda, RunnablePassthrough } from "@langchain/core/runnables";
+import { StringOutputParser } from "@langchain/core/output_parsers";
+import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";
+import { formatDocument } from "langchain/schema/prompt_template";
+
+const DEFAULT_DOCUMENT_PROMPT = PromptTemplate.fromTemplate("{pageContent}");
+
+async function combineDocuments(
+    docs: Document[],
+    documentPrompt: BasePromptTemplate = DEFAULT_DOCUMENT_PROMPT,
+    documentSeparator: string = "\n\n"
+) {
+    const docStrings: string[] = await Promise.all(
+        docs.map((doc) => {
+            return formatDocument(doc, documentPrompt);
+        })
+    );
+    return docStrings.join(documentSeparator);
+}
+async function main() {
+    const collectionName = process.env.ZEP_COLLECTION_NAME;
+    if (!collectionName) {
+        throw new Error("ZEP_COLLECTION_NAME is required");
+    }
+    const zepClient = new ZepClient({
+        apiKey: process.env.ZEP_API_KEY,
+    });
+
+    const vectorStore = await ZepVectorStore.init({
+        client: zepClient,
+        collectionName: collectionName,
+    });
+
+    const prompt = ChatPromptTemplate.fromMessages([
+        ["system", `Answer the question based only on the following context: {context}`],
+        ["human", "{question}"],
+    ]);
+
+    const model = new ChatOpenAI({
+        temperature: 0.8,
+        modelName: "gpt-3.5-turbo-1106",
+    });
+    const retriever = vectorStore.asRetriever();
+
+    const setupAndRetrieval = RunnableMap.from({
+        context: new RunnableLambda({
+            func: (input: string) => retriever.invoke(input).then(combineDocuments),
+        }),
+        question: new RunnablePassthrough(),
+    });
+    const outputParser = new StringOutputParser();
+
+    const chain = setupAndRetrieval
+        .pipe(prompt)
+        .pipe(model)
+        .pipe(outputParser)
+        .withConfig({
+            callbacks: [new ConsoleCallbackHandler()],
+        });
+
+    const result = await chain.invoke("Project Gutenberg?");
+
+    console.log("result", result);
+}
+
+main();

package/examples/memory/chat_shoe_store_history.ts

@@ -0,0 +1,104 @@
+import { RoleType } from "../../src/api/";
+
+export const history: {
+    role: string;
+    role_type: RoleType;
+    content: string;
+    metadata?: { [key: string]: any };
+}[] = [
+    {
+        role: "user",
+        role_type: "user",
+        content: "Hi there, I'm looking for a new pair of shoes. I'm not sure where to start.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Hello! I'd be happy to help you find the perfect pair of shoes. To get started, could you tell me what brand you're interested in, or if you're open to any brand?",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "I like Nike and Adidas, but I'm open to other brands too.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "That's great! It's important to find the right shoe for your needs. Could you tell me what you'll be using these shoes for mainly? For example, are they for running, basketball, or casual wear?",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "I'll be using them for running.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Fantastic! Now, could you please provide me with your shoe size and foot width? This information will help me narrow down the options for you.",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "I wear a men's size 10, and I'm not sure about the foot width.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Thank you. Based on your size, I'll make sure to suggest shoes with a wide range of sizes and widths available.",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "I have a bit of a pronation issue. Do I need to consider that while choosing shoes?",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Yes, pronation is essential when choosing running shoes. It refers to the way your foot rolls inward or outward when you walk or run. For pronation issues, stability or motion control shoes are usually recommended. I'll make sure to consider this in my suggestions.",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "Great, I have a budget of around $120.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Perfect! I'll make sure to find the best running shoes that fit your preferences, taking into account your brand preferences, running needs, size, and budget.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "I've found a few great options for you. The first one is the Brooks Ghost 14, which is known for its cushioning and support, ideal for runners with pronation issues. It's available in your size, and it's within your budget.",
+        metadata: { bar: "foo" },
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "I've heard good things about Brooks, but I was kind of hoping to get a Nike or an Adidas shoe.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "I understand. In that case, I'd recommend the Adidas Ultraboost 21. It's a popular choice among runners for its comfort, energy return, and stability. Plus, it's on sale at $129.99 today, almost within your budget.",
+    },
+    {
+        role: "user",
+        role_type: "user",
+        content: "They're nice looking. Yes, I think I'll go with those.",
+    },
+    {
+        role: "assistant",
+        role_type: "assistant",
+        content:
+            "Excellent choice! To complete the purchase, I'll need you to provide your credit card information in our secure payment form. This will allow us to process your order and ensure a smooth delivery.",
+    },
+];