zep-crewai 0.1.0__py3-none-any.whl

zep_crewai/__init__.py

@@ -0,0 +1,45 @@
+"""
+Zep CrewAI Integration.
+
+This package provides memory integration between Zep and CrewAI agents,
+enabling persistent conversation memory and context retrieval.
+
+Installation:
+    pip install zep-crewai
+
+Usage:
+    from zep_crewai import ZepStorage
+    from zep_cloud.client import AsyncZep
+    from crewai.memory.external.external_memory import ExternalMemory
+    from crewai import Crew
+
+    # Initialize Zep client and storage
+    zep_client = AsyncZep(api_key="your-api-key")
+    zep_storage = ZepStorage(client=zep_client, user_id="user123", thread_id="thread123")
+    external_memory = ExternalMemory(storage=zep_storage)
+
+    # Create crew with Zep memory
+    crew = Crew(
+        agents=[...],
+        tasks=[...],
+        external_memory=external_memory
+    )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Zep AI"
+__description__ = "Zep integration for CrewAI"
+
+from .exceptions import ZepDependencyError
+
+try:
+    # Check for required CrewAI dependencies - just test import
+    import crewai.memory.storage.interface  # noqa: F401
+
+    # Import our integration
+    from .memory import ZepStorage
+
+    __all__ = ["ZepStorage", "ZepDependencyError"]
+
+except ImportError as e:
+    raise ZepDependencyError(framework="CrewAI", install_command="pip install zep-crewai") from e

zep_crewai/exceptions.py

@@ -0,0 +1,12 @@
+"""
+Exception classes for CrewAI integration.
+"""
+
+
+class ZepDependencyError(ImportError):
+    """Raised when required CrewAI dependencies are not installed."""
+
+    def __init__(self, framework: str, install_command: str):
+        self.framework = framework
+        self.install_command = install_command
+        super().__init__(f"{framework} dependencies not found. Install with: {install_command}")

zep_crewai/memory.py

@@ -0,0 +1,177 @@
+"""
+Zep Memory integration for CrewAI.
+
+This module provides memory storage that integrates Zep with CrewAI's memory system.
+"""
+
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from crewai.memory.storage.interface import Storage
+from zep_cloud.client import Zep
+from zep_cloud.types import GraphSearchResults, Message
+
+
+class ZepStorage(Storage):
+    """
+    A storage implementation that integrates with Zep for persistent storage
+    and retrieval of CrewAI agent memories.
+    """
+
+    def __init__(self, client: Zep, user_id: str, thread_id: str, **kwargs: Any) -> None:
+        """
+        Initialize ZepStorage with a Zep client instance.
+
+        Args:
+            client: An initialized Zep instance (sync client)
+            user_id: User ID identifying a created Zep user (required)
+            thread_id: Thread ID identifying current conversation thread (required)
+            **kwargs: Additional configuration options
+        """
+        if not isinstance(client, Zep):
+            raise TypeError("client must be an instance of Zep")
+
+        if not user_id:
+            raise ValueError("user_id is required")
+
+        if not thread_id:
+            raise ValueError("thread_id is required")
+
+        self._client = client
+        self._user_id = user_id
+        self._thread_id = thread_id
+        self._config = kwargs
+
+        self._logger = logging.getLogger(__name__)
+
+    def save(self, value: Any, metadata: dict[str, Any] | None = None) -> None:
+        """
+        Save a memory entry to Zep using metadata-based routing.
+
+        Routes storage based on metadata.type:
+        - "message": Store as thread message with role from metadata
+        - "json" or "text": Store as graph data
+
+        Args:
+            value: The memory content to store
+            metadata: Metadata including type, role, name, etc.
+        """
+        metadata = metadata or {}
+
+        content_str = str(value)
+        content_type = metadata.get("type", "text")
+        if content_type not in ["message", "json", "text"]:
+            content_type = "text"
+
+        try:
+            if content_type == "message":
+                message_metadata = metadata.copy()
+                role = message_metadata.get("role", "norole")
+                name = message_metadata.get("name")
+
+                message = Message(
+                    role=role,
+                    name=name,
+                    content=content_str,
+                )
+
+                self._client.thread.add_messages(thread_id=self._thread_id, messages=[message])
+
+                self._logger.debug(
+                    f"Saved message from {metadata.get('name', 'unknown')}: {content_str[:100]}..."
+                )
+
+            else:
+                self._client.graph.add(
+                    user_id=self._user_id,
+                    data=content_str,
+                    type=content_type,
+                )
+
+                self._logger.debug(f"Saved {content_type} data: {content_str[:100]}...")
+
+        except Exception as e:
+            self._logger.error(f"Error saving to Zep: {e}")
+            raise
+
+    def search(
+        self, query: str, limit: int = 5, score_threshold: float = 0.5
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Search Zep user graph.
+
+        This always retrieves thread-specific context and performs targeted graph search on the user graph
+        using the provided query, combining both sources.
+
+        Args:
+            query: Search query string (truncated to 400 chars max for graph search)
+            limit: Maximum number of results to return from graph search
+
+        Returns:
+            List of matching memory entries from both thread context and graph search
+        """
+        results: list[dict[str, Any]] = []
+
+        # Truncate query to max 400 characters to avoid API errors
+        truncated_query = query[:400] if len(query) > 400 else query
+
+        # Define search functions for concurrent execution
+        def get_thread_context() -> Any:
+            try:
+                return self._client.thread.get_user_context(thread_id=self._thread_id)
+            except Exception as e:
+                self._logger.debug(f"Thread context not available: {e}")
+                return None
+
+        def search_graph_edges() -> list[str]:
+            try:
+                if not query:
+                    return []
+                results: GraphSearchResults = self._client.graph.search(
+                    user_id=self._user_id, query=truncated_query, limit=limit, scope="edges"
+                )
+                edges: list[str] = []
+                if results.edges:
+                    for edge in results.edges:
+                        edge_str = f"{edge.fact} (valid_at: {edge.valid_at}, invalid_at: {edge.invalid_at or 'current'})"
+                        edges.append(edge_str)
+                return edges
+            except Exception as e:
+                self._logger.debug(f"Graph search not available: {e}")
+                return []
+
+        thread_context = None
+        edges_search_results: list[str] = []
+
+        try:
+            with ThreadPoolExecutor(max_workers=2) as executor:
+                future_thread = executor.submit(get_thread_context)
+                future_edges = executor.submit(search_graph_edges)
+
+                thread_context = future_thread.result()
+                edges_search_results = future_edges.result() or []
+
+        except Exception as e:
+            self._logger.debug(f"Failed to search user memories: {e}")
+
+        if thread_context and hasattr(thread_context, "context") and thread_context.context:
+            results.append({"memory": thread_context.context})
+
+        for result in edges_search_results:
+            results.append({"memory": result})
+
+        return results
+
+    def reset(self) -> None:
+        pass
+
+    @property
+    def user_id(self) -> str:
+        """Get the user ID."""
+        return self._user_id
+
+    @property
+    def thread_id(self) -> str:
+        """Get the thread ID."""
+        return self._thread_id

zep_crewai-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: zep-crewai
+Version: 0.1.0
+Summary: CrewAI integration for Zep
+Project-URL: Homepage, https://github.com/getzep/zep
+Project-URL: Documentation, https://help.getzep.com
+Project-URL: Repository, https://github.com/getzep/zep
+Project-URL: Bug Tracker, https://github.com/getzep/zep/issues
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: crewai>=0.80.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: rich>=14.0.0
+Requires-Dist: zep-cloud>=3.0.0rc1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Zep CrewAI Integration Tutorial
+
+Learn how to add persistent memory to your CrewAI agents using Zep's powerful memory platform.
+
+## Installation
+
+Install the Zep CrewAI integration package:
+
+```bash
+pip install zep-crewai
+```
+
+## Setup
+
+### 1. Get Your API Key
+
+Sign up at [Zep Cloud](https://app.getzep.com) and get your API key.
+
+### 2. Set Environment Variable
+
+```bash
+export ZEP_API_KEY="your-zep-api-key"
+```
+
+## Basic Usage
+
+### 1. Initialize Zep Client
+
+```python
+import os
+from zep_cloud.client import Zep
+
+# Initialize Zep client
+zep_client = Zep(api_key=os.getenv("ZEP_API_KEY"))
+```
+
+### 2. Create User and Thread
+
+**Important**: You must create a user and thread in Zep before using ZepStorage.
+
+```python
+# Create a user 
+user_id = "john_doe_123"
+zep_client.user.add(
+    user_id=user_id,
+    first_name="John",
+    last_name="Doe",
+    email="john.doe@example.com"
+)
+
+# Create a thread 
+thread_id = "project_alpha_456"
+zep_client.thread.create(
+    user_id=user_id,
+    thread_id=thread_id
+)
+```
+
+### 3. Initialize ZepStorage
+
+```python
+from zep_crewai import ZepStorage
+from crewai.memory.external.external_memory import ExternalMemory
+
+# Create storage for your project
+zep_storage = ZepStorage(
+    client=zep_client,
+    user_id=user_id,   
+    thread_id=thread_id
+)
+
+# Wrap in CrewAI's external memory
+external_memory = ExternalMemory(storage=zep_storage)
+```
+
+### 4. Create Crew with Persistent Memory
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Create your agents
+research_agent = Agent(
+    role='Research Analyst',
+    goal='Analyze market trends and provide insights',
+    backstory='You are an expert at finding and analyzing market data...',
+)
+
+# Create crew with Zep memory
+crew = Crew(
+    agents=[research_agent],
+    tasks=[...],
+    external_memory=external_memory,  # This enables the crew to search Zep
+    process=Process.sequential,
+)
+
+# Run your crew - memories will be automatically saved and retrieved
+result = crew.kickoff()
+```
+
+## How Memory Works
+
+Zep stores different types of content using metadata-based routing.
+
+### Messages (Conversation Context)
+Stored in Zep threads for conversation history:
+
+```python
+external_memory.save(
+    "I need help planning a business trip to New York",
+    metadata={"type": "message", "role": "user", "name": "John Doe"}
+)
+
+external_memory.save(
+    "I'd be happy to help you plan your trip!",
+    metadata={"type": "message", "role": "assistant", "name": "Travel Agent"}
+)
+```
+
+### Structured Data
+Added as episodes to the user knowledge graph in Zep:
+
+```python
+# JSON data
+external_memory.save(
+    '{"destination": "New York", "duration": "3 days", "budget": 2000}',
+    metadata={"type": "json"}
+)
+
+# Text facts and insights
+external_memory.save(
+    "User prefers mid-range hotels with business amenities",
+    metadata={"type": "text"}
+)
+```
+
+### Automatic Memory Retrieval
+
+CrewAI automatically searches your memories when agents need context:
+
+```python
+# When agents run, they automatically get relevant context from Zep
+results = crew.kickoff()
+
+# You can also search manually
+memory_results = zep_storage.search("hotel preferences", limit=5)
+for result in memory_results:
+    print(result['memory'])
+```
+
+## Complete Example
+
+For a full working example, check out [`examples/simple_example.py`](examples/simple_example.py) in this repository. This example demonstrates:
+
+- Setting up Zep user and thread
+- Saving different types of memory (messages, JSON data, text)
+- Creating CrewAI agents with access to Zep memory
+- Automatic context retrieval during agent execution
+
+## Requirements
+
+- Python 3.10+
+- `zep-cloud>=3.0.0rc1`
+- `crewai>=0.80.0`

zep_crewai-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+zep_crewai/__init__.py,sha256=H8xpqfQd79JPRbd7h9wHjgSbsKrQGiTDV_CePgeo_cQ,1280
+zep_crewai/exceptions.py,sha256=buRZJt5TDankN7PvLq_u0wDlQ0Sp6LKXroS1qTj6koY,403
+zep_crewai/memory.py,sha256=lhoOsmJK6Yfe9OULt7OQ98Rk963pCY9_HGbHTnA22u8,6082
+zep_crewai-0.1.0.dist-info/METADATA,sha256=panKSkdvw1uRiGebFgNZ8lfL_xQaPd_L5mSH6bDku-8,4470
+zep_crewai-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+zep_crewai-0.1.0.dist-info/RECORD,,

zep_crewai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any