@getzep/zep-cloud 2.4.0 → 2.6.0

package/dist/serialization/types/AddTripleResponse.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddTripleResponse = void 0;
+const core = __importStar(require("../../core"));
+const EntityEdge_1 = require("./EntityEdge");
+const EntityNode_1 = require("./EntityNode");
+exports.AddTripleResponse = core.serialization.object({
+    edge: EntityEdge_1.EntityEdge.optional(),
+    sourceNode: core.serialization.property("source_node", EntityNode_1.EntityNode.optional()),
+    targetNode: core.serialization.property("target_node", EntityNode_1.EntityNode.optional()),
+});

package/dist/serialization/types/EntityNode.d.ts

@@ -7,6 +7,7 @@ import * as core from "../../core";
 export declare const EntityNode: core.serialization.ObjectSchema<serializers.EntityNode.Raw, Zep.EntityNode>;
 export declare namespace EntityNode {
     interface Raw {
+        attributes?: Record<string, unknown> | null;
         created_at: string;
         labels?: string[] | null;
         name: string;

package/dist/serialization/types/EntityNode.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityNode = void 0;
 const core = __importStar(require("../../core"));
 exports.EntityNode = core.serialization.object({
+    attributes: core.serialization.record(core.serialization.string(), core.serialization.unknown()).optional(),
     createdAt: core.serialization.property("created_at", core.serialization.string()),
     labels: core.serialization.list(core.serialization.string()).optional(),
     name: core.serialization.string(),

package/dist/serialization/types/SearchFilters.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as serializers from "../index";
+import * as Zep from "../../api/index";
+import * as core from "../../core";
+export declare const SearchFilters: core.serialization.ObjectSchema<serializers.SearchFilters.Raw, Zep.SearchFilters>;
+export declare namespace SearchFilters {
+    interface Raw {
+        node_labels?: string[] | null;
+    }
+}

package/dist/serialization/types/SearchFilters.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchFilters = void 0;
+const core = __importStar(require("../../core"));
+exports.SearchFilters = core.serialization.object({
+    nodeLabels: core.serialization.property("node_labels", core.serialization.list(core.serialization.string()).optional()),
+});

package/dist/serialization/types/index.d.ts

@@ -32,11 +32,13 @@ export * from "./SummaryListResponse";
 export * from "./User";
 export * from "./UserListResponse";
 export * from "./UserNodeResponse";
+export * from "./AddTripleResponse";
 export * from "./EntityEdge";
 export * from "./EntityNode";
 export * from "./GraphSearchResults";
 export * from "./GraphSearchScope";
 export * from "./Reranker";
+export * from "./SearchFilters";
 export * from "./ClassifySessionRequest";
 export * from "./CreateDocumentRequest";
 export * from "./FactRatingExamples";

package/dist/serialization/types/index.js

@@ -48,11 +48,13 @@ __exportStar(require("./SummaryListResponse"), exports);
 __exportStar(require("./User"), exports);
 __exportStar(require("./UserListResponse"), exports);
 __exportStar(require("./UserNodeResponse"), exports);
+__exportStar(require("./AddTripleResponse"), exports);
 __exportStar(require("./EntityEdge"), exports);
 __exportStar(require("./EntityNode"), exports);
 __exportStar(require("./GraphSearchResults"), exports);
 __exportStar(require("./GraphSearchScope"), exports);
 __exportStar(require("./Reranker"), exports);
+__exportStar(require("./SearchFilters"), exports);
 __exportStar(require("./ClassifySessionRequest"), exports);
 __exportStar(require("./CreateDocumentRequest"), exports);
 __exportStar(require("./FactRatingExamples"), exports);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.4.0";
+export declare const SDK_VERSION = "2.6.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = "2.4.0";
+exports.SDK_VERSION = "2.6.0";

package/examples/langgraph/.env.example

@@ -0,0 +1,7 @@
+# OpenAI API key for the language model
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Tavily API key for web search functionality
+TAVILY_API_KEY=your_tavily_api_key_here
+# Zep API key for memory persistence
+ZEP_API_KEY=your_zep_api_key_here

package/examples/langgraph/README.md

@@ -0,0 +1,165 @@
+# LangGraph CLI Agent
+
+This is a simple CLI agent built with LangGraph.js that can answer questions and use tools to search for information. It also integrates with Zep for memory persistence.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- OpenAI API key
+- Tavily API key (for search functionality)
+- Zep API key (for memory persistence)
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Create a `.env` file in this directory with your API keys:
+
+```
+OPENAI_API_KEY=your_openai_api_key_here
+TAVILY_API_KEY=your_tavily_api_key_here
+ZEP_API_KEY=your_zep_api_key_here
+```
+
+## Running the Agent
+
+To start the CLI agent, run:
+
+```bash
+npm start
+```
+
+### Command-Line Options
+
+The agent supports various command-line options through Commander.js:
+
+```bash
+# Get help
+npm start -- --help
+
+# Basic usage with user ID
+npm start -- --userId john_doe
+
+# Using kebab-case format
+npm start -- --user-id john_doe --session-id vacation_planning
+
+# Customize the system message
+npm start -- --system-message "You are a travel assistant helping with vacation planning."
+
+# Enable debug mode
+npm start -- --debug
+```
+
+Available options:
+
+| Option                       | Description                                |
+| ---------------------------- | ------------------------------------------ |
+| `--userId <id>`              | User ID to associate with the conversation |
+| `--user-id <id>`             | Alternative format for user ID             |
+| `--sessionId <id>`           | Session ID for the conversation            |
+| `--session-id <id>`          | Alternative format for session ID          |
+| `--system-message <message>` | Custom system message to use               |
+| `--debug`                    | Enable debug mode with additional logging  |
+| `--help`                     | Display help information                   |
+| `--version`                  | Display version information                |
+
+### Memory Features
+
+Using the user ID and session ID options allows you to:
+
+- **Maintain separate conversation histories** for different users
+- **Continue specific conversations** by using the same session ID
+- **Group related conversations** under the same user ID
+- **Switch between different contexts** by changing the session ID
+
+The agent will automatically create users and sessions in Zep if they don't exist, and will load previous conversation history when available.
+
+## Features
+
+This will launch an interactive CLI where you can chat with the agent. Type your questions and the agent will respond. The agent can:
+
+- Answer general knowledge questions
+- Search the web for information using Tavily
+- Maintain context throughout the conversation
+- Persist conversation history using Zep memory
+- Retrieve past conversations when restarted
+- Associate conversations with specific users
+- Continue conversations across different sessions
+- Use custom system messages
+
+Type `exit` to quit the application.
+
+## How It Works
+
+This agent is built using LangGraph.js, which allows for creating stateful, multi-step AI workflows as graphs. The agent:
+
+1. Takes user input
+2. Processes it through an LLM (OpenAI)
+3. Decides whether to use tools or respond directly
+4. If tools are needed, executes them and returns to the LLM
+5. Returns the final response to the user
+6. Persists all messages to Zep memory (if configured)
+
+The graph maintains state between interactions, allowing for conversational context to be preserved. Additionally, the Zep memory integration provides long-term persistence of conversation history.
+
+## Memory Integration
+
+The agent uses Zep for memory persistence. When a Zep API key is provided, the agent will:
+
+1. Create a new session in Zep (or use an existing one)
+2. Store all user and AI messages in Zep memory
+3. Maintain conversation history across restarts
+4. Load previous messages when restarted
+5. Provide context to the agent about the previous conversation
+
+### User and Session Management
+
+The agent supports specifying a user ID and session ID via command-line arguments:
+
+- **User ID**: Associates conversations with a specific user in Zep
+- **Session ID**: Uses a specific session ID for the conversation
+
+This allows for powerful use cases such as:
+
+- **Multi-user support**: Different users can have their own conversation histories
+- **Topic-based sessions**: Create different sessions for different topics (e.g., "travel_planning", "tech_support")
+- **Conversation continuity**: Resume specific conversations by using the same session ID
+- **Organizational structure**: Group related conversations under the same user ID
+- **A/B testing**: Compare different conversation flows by using different session IDs
+
+### Advanced Memory Features
+
+The Zep memory integration includes several advanced features:
+
+- **User Management**: Creates and manages users associated with conversations
+- **Session Management**: Creates and retrieves sessions for persistent conversations
+- **Message Retrieval**: Loads previous messages when the agent is restarted
+- **Memory Search**: Can search for relevant messages based on semantic similarity
+- **Context Retrieval**: Can retrieve context information about the conversation
+
+This allows the agent to maintain context over long periods and provide more personalized responses based on past interactions.
+
+## Customization
+
+You can modify `agent.ts` to:
+
+- Change the LLM model
+- Add additional tools
+- Adjust the graph structure
+- Customize the CLI interface
+- Configure memory settings
+
+The `zep-memory.ts` file contains the Zep memory integration and can be customized to:
+
+- Change how messages are stored and retrieved
+- Modify user and session management
+- Add additional memory features
+- Customize message conversion between LangChain and Zep formats
+
+## License
+
+MIT

package/examples/langgraph/agent.ts

@@ -0,0 +1,261 @@
+// agent.ts
+import dotenv from "dotenv";
+
+// Load environment variables from .env file
+dotenv.config();
+
+import { TavilySearchResults } from "@langchain/community/tools/tavily_search";
+import { ChatOpenAI } from "@langchain/openai";
+import { HumanMessage, AIMessage, BaseMessage, SystemMessage } from "@langchain/core/messages";
+import { ToolNode } from "@langchain/langgraph/prebuilt";
+import { StateGraph, MessagesAnnotation } from "@langchain/langgraph";
+import { fileURLToPath } from "url";
+import path from "path";
+import { Command } from "commander";
+import { ZepMemory } from "./zep-memory";
+
+// Define the tools for the agent to use
+const tools = [new TavilySearchResults({ maxResults: 3 })];
+const toolNode = new ToolNode(tools);
+
+// Create a model and give it access to the tools
+const model = new ChatOpenAI({
+  model: "gpt-4o-mini",
+  temperature: 0,
+}).bindTools(tools);
+
+// Define the function that determines whether to continue or not
+function shouldContinue({ messages }: typeof MessagesAnnotation.State) {
+  const lastMessage = messages[messages.length - 1] as AIMessage;
+
+  // If the LLM makes a tool call, then we route to the "tools" node
+  if (lastMessage.tool_calls?.length) {
+    return "tools";
+  }
+  // Otherwise, we stop (reply to the user) using the special "__end__" node
+  return "__end__";
+}
+
+// Define the function that calls the model
+async function callModel(state: typeof MessagesAnnotation.State) {
+  const response = await model.invoke(state.messages);
+  return { messages: [...state.messages, response] };
+}
+
+// Define the workflow as a graph
+const workflow = new StateGraph(MessagesAnnotation)
+  .addNode("agent", callModel)
+  .addNode("tools", toolNode)
+  .addEdge("__start__", "agent")
+  .addConditionalEdges("agent", shouldContinue, ["tools", "__end__"])
+  .addEdge("tools", "agent");
+
+// Compile the graph
+export const graph = workflow.compile();
+
+// Parse command line arguments using Commander
+function parseCommandLineArgs() {
+  const program = new Command();
+  
+  program
+    .name("langgraph-agent")
+    .description("LangGraph CLI Agent with Zep memory integration")
+    .version("1.0.0")
+    .option("--userId <id>", "User ID to associate with the conversation")
+    .option("--user-id <id>", "User ID to associate with the conversation (alternative format)")
+    .option("--sessionId <id>", "Session ID for the conversation")
+    .option("--session-id <id>", "Session ID for the conversation (alternative format)")
+    .option("--system-message <message>", "Custom system message to use")
+    .option("--debug", "Enable debug mode with additional logging");
+  
+  program.parse();
+  
+  const options = program.opts();
+  
+  // Handle alternative formats and naming
+  return {
+    userId: options.userId,
+    sessionId: options.sessionId,
+    systemMessage: options.systemMessage || "You are a helpful assistant. Answer the user's questions to the best of your ability.",
+    debug: !!options.debug
+  };
+}
+
+// Check if this file is being run directly
+const isMainModule = () => {
+  if (typeof require !== 'undefined' && require.main === module) {
+    return true;
+  }
+  
+  if (import.meta.url) {
+    try {
+      const currentFilePath = fileURLToPath(import.meta.url);
+      const currentFileName = path.basename(currentFilePath);
+      // Check if this script was run directly with node/tsx
+      return process.argv[1] && process.argv[1].endsWith(currentFileName);
+    } catch (e) {
+      return false;
+    }
+  }
+  
+  return false;
+};
+
+// Parse command line arguments once and store the result
+const args = isMainModule() ? parseCommandLineArgs() : {
+  userId: undefined,
+  sessionId: undefined,
+  systemMessage: "You are a helpful assistant. Answer the user's questions to the best of your ability.",
+  debug: false
+};
+
+// Initialize Zep memory if API key is available
+let zepMemory: ZepMemory | undefined;
+if (process.env.ZEP_API_KEY) {
+  zepMemory = new ZepMemory(process.env.ZEP_API_KEY, args.sessionId, args.userId);
+  
+  if (args.debug) {
+    console.log("Zep memory initialized with session ID:", zepMemory.getSessionId());
+    if (args.userId) {
+      console.log("Using user ID:", args.userId);
+    }
+  }
+}
+
+// CLI interface
+if (isMainModule()) {
+  // This will run when the script is executed directly
+  const runCLI = async () => {
+    const systemMessage = args.systemMessage;
+    
+    console.log("🦜🔗 LangGraph Agent CLI");
+    if (args.userId) {
+      console.log(`User ID: ${args.userId}`);
+    }
+    if (args.sessionId) {
+      console.log(`Session ID: ${args.sessionId}`);
+    }
+    console.log("Type 'exit' to quit the application");
+    console.log("------------------------------");
+    
+    // Create a readline interface
+    const readline = await import("readline");
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    
+    // Create a new chat session
+    const config = { configurable: { sessionId: args.sessionId || "cli-session" } };
+    let state = { messages: [] as BaseMessage[] };
+    
+    // Initialize Zep memory if available
+    if (zepMemory) {
+      try {
+        await zepMemory.initialize(args.userId);
+        console.log("Connected to Zep memory service");
+        
+        // Try to load previous messages from Zep memory
+        try {
+          const previousMessages = await zepMemory.getMessages(10);
+          if (previousMessages.length > 0) {
+            state.messages = previousMessages;
+            console.log(`Loaded ${previousMessages.length} messages from previous conversation`);
+          }
+        } catch (error) {
+          console.error("Failed to load previous messages:", error);
+          console.log("Starting a new conversation");
+        }
+      } catch (error) {
+        console.error("Failed to initialize Zep memory:", error);
+        console.log("Continuing without memory persistence");
+        zepMemory = undefined;
+      }
+    }
+    
+    const askQuestion = () => {
+      rl.question("\nYou: ", async (input) => {
+        if (input.toLowerCase() === "exit") {
+          console.log("Goodbye!");
+          rl.close();
+          return;
+        }
+        
+        // Add the user's message to the state
+        const userMessage = new HumanMessage(input);
+        let systemMessageWithContext = systemMessage;
+        
+        // Persist user message to Zep memory if available
+        let context: string | undefined;
+        if (zepMemory) {
+          try {
+            // Add the user message to Zep memory and get the context, if available
+            context = await zepMemory.addMessage(userMessage, true);
+          } catch (error) {
+            console.error("Failed to persist user message to Zep memory:", error);
+          }
+          
+          try {
+            if (args.debug) {
+              console.log(context);
+            }
+            if (context) {
+              systemMessageWithContext = systemMessage + "\n" + context;
+            }
+          } catch (error) {
+            console.error("Failed to get memory with context:", error);
+          }
+        }
+        
+        // Get the last 5 messages from the current state (excluding any previous system messages)
+        const previousMessages = state.messages
+          .filter(msg => !(msg instanceof SystemMessage))
+          .slice(-5);
+        
+        // Create new state with system message at the beginning followed by the history messages
+        state.messages = [
+          new SystemMessage(systemMessageWithContext), 
+          ...previousMessages, 
+          userMessage
+        ];
+        
+        try {
+          // Process the input through the graph
+          const result = await graph.invoke(state, config);
+          
+          // Extract the AI's response using instanceof instead of _getType()
+          const aiMessages = result.messages.filter((msg) => msg instanceof AIMessage);
+          const lastAIMessage = aiMessages[aiMessages.length - 1] as AIMessage;
+          
+          console.log(`\nAI: ${lastAIMessage.content}`);
+          
+          // Persist AI message to Zep memory if available
+          if (zepMemory) {
+            try {
+              await zepMemory.addMessage(lastAIMessage);
+            } catch (error) {
+              console.error("Failed to persist AI message to Zep memory:", error);
+            }
+          }
+          
+          // Update the state for the next interaction
+          // We don't want to completely replace the state, just update the messages
+          // to maintain our structure with the system message at the beginning
+          const resultMessages = result.messages.filter(msg => !(msg instanceof SystemMessage));
+          state = { 
+            messages: resultMessages 
+          };
+        } catch (error) {
+          console.error("Error:", error);
+        }
+        
+        // Ask for the next input
+        askQuestion();
+      });
+    };
+    
+    askQuestion();
+  };
+  
+  runCLI().catch(console.error);
+}