zep-ag2 0.1.0__tar.gz

zep_ag2-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Zep Cloud API key (required)
+# Sign up at https://www.getzep.com, then get your key at https://app.getzep.com
+ZEP_API_KEY=
+
+# OpenAI API key (required for examples that use GPT models)
+OPENAI_API_KEY=

zep_ag2-0.1.0/.gitignore

@@ -0,0 +1,104 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+out/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Secrets
+.env
+.env.local
+
+# Test data
+test_data
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+.idea
+.vscode
+
+# VSCode local history
+.history
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/**/*.py
+lib/**/*.pyc
+lib/**/__pycache__/
+lib/**/site-packages/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# PyCharm
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pytest
+.pytest_cache/
+.coverage
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# UV (Python package manager)
+uv.lock
+.uv_cache/
+__pypackages__/
+
+# Log files
+*.log
+
+# macOS
+.DS_Store
+
+# Node.js
+node_modules/
+dist/
+
+# Coverage (integration test runs)
+coverage.xml

zep_ag2-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the zep-ag2 package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-17
+
+### Added
+- Initial release of zep-ag2 integration package
+- `ZepMemoryManager` for system message injection and conversation memory
+- `ZepGraphMemoryManager` for knowledge graph operations
+- Tool factories: `create_search_memory_tool`, `create_add_memory_tool`,
+  `create_search_graph_tool`, `create_add_graph_data_tool`
+- `register_all_tools` convenience function for bulk tool registration
+- Sync tool execution via background event loop (AG2 calls tools synchronously)
+- Async manager classes with sync wrappers for non-async usage
+- Comprehensive test suite with >90% coverage
+- Examples for basic, graph, search-only, and full tool usage
+
+### Features
+- AG2 decorator-compatible tools (`@register_for_llm` / `@register_for_execution`)
+- System message enrichment with Zep memory context
+- Thread-based conversation memory storage
+- User and named knowledge graph support
+- Typed parameters with `Annotated` for AG2 tool descriptions
+- Single shared background event loop and reused Zep client for sync bridging
+  (Python 3.11–3.13 compatible)
+- Message (4000 char) and graph-data (9900 char) size guards with truncation
+
+[0.1.0]: https://github.com/getzep/zep/releases/tag/zep-ag2-v0.1.0

zep_ag2-0.1.0/Makefile

@@ -0,0 +1,81 @@
+# Makefile for zep-ag2 development
+
+.PHONY: help install format lint type-check test test-cov clean build all
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  install     - Install package and dependencies in development mode"
+	@echo "  format      - Format code with ruff"
+	@echo "  lint        - Run linting checks"
+	@echo "  type-check  - Run type checking with mypy"
+	@echo "  test        - Run tests"
+	@echo "  test-cov    - Run tests with coverage report"
+	@echo "  all         - Run format, lint, type-check, and test"
+	@echo "  build       - Build the package"
+	@echo "  clean       - Clean build artifacts"
+
+# Install package in development mode
+install:
+	uv sync --extra dev
+	# Workaround: macOS sets UF_HIDDEN on all files inside .venv (dot-directory),
+	# causing Python 3.11 to skip all .pth files. We mirror src/zep_ag2 directly
+	# into site-packages so the package is importable without .pth.
+	@SITE=$$(ls -d .venv/lib/python*/site-packages 2>/dev/null | head -1); \
+	if [ -n "$$SITE" ]; then \
+	  rm -rf "$$SITE/zep_ag2"; \
+	  cp -r src/zep_ag2 "$$SITE/zep_ag2"; \
+	  echo "Installed zep_ag2 into $$SITE"; \
+	fi
+
+# Format code
+format:
+	uv run ruff format .
+
+# Run linting checks
+lint:
+	uv run ruff check .
+
+# Fix linting issues automatically
+lint-fix:
+	uv run ruff check --fix .
+
+# Run type checking
+type-check:
+	uv run mypy src/
+
+# Run tests
+test:
+	uv run pytest tests/ -v
+
+# Run tests with coverage
+test-cov:
+	uv run pytest tests/ -v --cov=zep_ag2 --cov-report=term-missing --cov-report=xml
+
+# Run all checks (the order matters: format first, then lint, then type-check, then test)
+all: format lint type-check test
+
+# Build the package
+build:
+	uv build
+
+# Clean build artifacts
+clean:
+	rm -rf dist/
+	rm -rf build/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -f coverage.xml
+	rm -f .coverage
+
+# Development workflow - run this before committing
+pre-commit: lint-fix format lint type-check test
+	@echo "All checks passed! Ready to commit."
+
+# CI workflow - strict checks without auto-fixing
+ci: lint type-check test
+	@echo "CI checks passed!"

zep_ag2-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: zep-ag2
+Version: 0.1.0
+Summary: Zep memory integration for AG2 (AutoGen community fork)
+Project-URL: Homepage, https://github.com/getzep/zep
+Project-URL: Documentation, https://help.getzep.com/integrations/ag2
+Project-URL: Repository, https://github.com/getzep/zep
+Project-URL: Bug Tracker, https://github.com/getzep/zep/issues
+Project-URL: Changelog, https://github.com/getzep/zep/blob/main/integrations/ag2/python/CHANGELOG.md
+Author: faridun-ag2
+Author-email: Zep AI <support@getzep.com>
+License-Expression: Apache-2.0
+Keywords: ag2,agent,autogen,knowledge-graph,llm,memory,zep
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: ag2>=0.9.0
+Requires-Dist: zep-cloud>=3.23.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: openai>=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-ag2
+
+Zep memory integration for [AG2](https://ag2.ai)
+
+## Installation
+
+```bash
+pip install zep-ag2
+```
+
+## Quick Start
+
+### System Message Injection
+
+```python
+import asyncio
+import os
+from autogen import AssistantAgent, UserProxyAgent, LLMConfig
+from zep_cloud.client import AsyncZep
+from zep_ag2 import ZepMemoryManager, register_all_tools
+
+async def main():
+    zep = AsyncZep(api_key=os.environ["ZEP_API_KEY"])
+
+    llm_config = LLMConfig(
+        {"model": "gpt-4o-mini", "api_key": os.environ["OPENAI_API_KEY"]}
+    )
+
+    assistant = AssistantAgent(
+        name="assistant",
+        llm_config=llm_config,
+        system_message="You are a helpful assistant with long-term memory.",
+    )
+    user_proxy = UserProxyAgent(
+        name="user",
+        human_input_mode="NEVER",
+        code_execution_config=False,
+        is_termination_msg=lambda msg: "TERMINATE" in (msg.get("content") or ""),
+    )
+
+    # Enrich agent with memory context
+    memory_mgr = ZepMemoryManager(zep, user_id="user123", session_id="session456")
+    await memory_mgr.enrich_system_message(assistant, query="conversation topic")
+
+    # Register memory tools (sync — AG2 calls them automatically)
+    register_all_tools(assistant, user_proxy, zep, user_id="user123", session_id="session456")
+
+    result = user_proxy.initiate_chat(
+        assistant, message="What do you remember about me?"
+    )
+
+asyncio.run(main())
+```
+
+### Tool-Based Memory Access
+
+```python
+from zep_ag2 import create_search_graph_tool, create_add_graph_data_tool
+
+# Create tools bound to a user's knowledge graph
+search_tool = create_search_graph_tool(zep, user_id="user123")
+add_tool = create_add_graph_data_tool(zep, user_id="user123")
+
+# Register with AG2's decorator pattern
+assistant.register_for_llm(description="Search knowledge graph")(search_tool)
+user_proxy.register_for_execution()(search_tool)
+
+assistant.register_for_llm(description="Add to knowledge graph")(add_tool)
+user_proxy.register_for_execution()(add_tool)
+```
+
+## Features
+
+- **Tool-based memory access** — Register Zep search/add as AG2 tools via `@register_for_llm`
+- **System message injection** — Automatically enrich agent context with relevant memories
+- **Knowledge graph** — Access Zep's knowledge graph from AG2 agents
+- **Conversation memory** — Store and retrieve thread-based conversation history
+- **Sync tool execution** — Tools run synchronously via a single shared background event loop, compatible with AG2's execution model on Python 3.11–3.13
+
+## API Reference
+
+### ZepMemoryManager
+
+Manages Zep memory for AG2 agents via system message injection.
+
+- `ZepMemoryManager(client, user_id, session_id=None)` — Initialize with Zep client
+- `await enrich_system_message(agent, query=None, limit=5)` — Inject memory context
+- `await get_memory_context(query=None, limit=5)` — Get formatted context string
+- `await add_messages(messages)` — Store messages in Zep thread
+- `await get_session_facts()` — Get extracted session facts
+
+### ZepGraphMemoryManager
+
+Manages Zep knowledge graph for AG2 agents.
+
+- `ZepGraphMemoryManager(client, graph_id)` — Initialize with graph ID
+- `await search(query, limit=5, scope="edges")` — Search the graph
+- `await add_data(data, data_type="text")` — Add data to the graph
+- `await enrich_system_message(agent, query=None, limit=5)` — Inject graph context
+
+### Tool Factories
+
+All tool factories return **synchronous** callables (AG2 executes tools synchronously).
+Internally they bridge to the async Zep SDK on a single shared background event loop,
+reusing the `AsyncZep` client you pass in (no per-call client construction).
+
+- `create_search_memory_tool(client, user_id, session_id=None)` — Search conversation memory
+- `create_add_memory_tool(client, user_id, session_id=None)` — Add conversation memory
+- `create_search_graph_tool(client, user_id=None, graph_id=None)` — Search knowledge graph
+- `create_add_graph_data_tool(client, user_id=None, graph_id=None)` — Add graph data
+- `register_all_tools(agent, executor, client, user_id, ...)` — Register all tools at once
+
+## Examples
+
+- **[Basic Memory](examples/ag2_basic.py)** — System message injection + memory tools
+- **[Graph Memory](examples/ag2_graph.py)** — Knowledge graph with ZepGraphMemoryManager
+- **[Search Tools](examples/ag2_tools_search.py)** — Read-only search tool registration
+- **[Full Tools](examples/ag2_tools_full.py)** — All tools in a GroupChat with multiple agents
+- **[Manual Test](examples/manual_test.py)** — End-to-end integration test with real APIs
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+export ZEP_API_KEY="your-zep-cloud-api-key"
+
+# Required for examples that use LLM
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+## Development
+
+```bash
+make install        # Install dev dependencies
+make pre-commit     # Format, lint, type-check, test
+make ci             # CI validation
+```
+
+## Requirements
+
+- Python 3.11+
+- `ag2>=0.9.0`
+- `zep-cloud>=3.23.0`
+
+## License
+
+Apache-2.0 — see [LICENSE](../../../LICENSE) for details.
+
+## Support
+
+- [Zep Documentation](https://help.getzep.com)
+- [AG2 Documentation](https://docs.ag2.ai)
+- [GitHub Issues](https://github.com/getzep/zep/issues)
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details.

zep_ag2-0.1.0/README.md

@@ -0,0 +1,159 @@
+# zep-ag2
+
+Zep memory integration for [AG2](https://ag2.ai)
+
+## Installation
+
+```bash
+pip install zep-ag2
+```
+
+## Quick Start
+
+### System Message Injection
+
+```python
+import asyncio
+import os
+from autogen import AssistantAgent, UserProxyAgent, LLMConfig
+from zep_cloud.client import AsyncZep
+from zep_ag2 import ZepMemoryManager, register_all_tools
+
+async def main():
+    zep = AsyncZep(api_key=os.environ["ZEP_API_KEY"])
+
+    llm_config = LLMConfig(
+        {"model": "gpt-4o-mini", "api_key": os.environ["OPENAI_API_KEY"]}
+    )
+
+    assistant = AssistantAgent(
+        name="assistant",
+        llm_config=llm_config,
+        system_message="You are a helpful assistant with long-term memory.",
+    )
+    user_proxy = UserProxyAgent(
+        name="user",
+        human_input_mode="NEVER",
+        code_execution_config=False,
+        is_termination_msg=lambda msg: "TERMINATE" in (msg.get("content") or ""),
+    )
+
+    # Enrich agent with memory context
+    memory_mgr = ZepMemoryManager(zep, user_id="user123", session_id="session456")
+    await memory_mgr.enrich_system_message(assistant, query="conversation topic")
+
+    # Register memory tools (sync — AG2 calls them automatically)
+    register_all_tools(assistant, user_proxy, zep, user_id="user123", session_id="session456")
+
+    result = user_proxy.initiate_chat(
+        assistant, message="What do you remember about me?"
+    )
+
+asyncio.run(main())
+```
+
+### Tool-Based Memory Access
+
+```python
+from zep_ag2 import create_search_graph_tool, create_add_graph_data_tool
+
+# Create tools bound to a user's knowledge graph
+search_tool = create_search_graph_tool(zep, user_id="user123")
+add_tool = create_add_graph_data_tool(zep, user_id="user123")
+
+# Register with AG2's decorator pattern
+assistant.register_for_llm(description="Search knowledge graph")(search_tool)
+user_proxy.register_for_execution()(search_tool)
+
+assistant.register_for_llm(description="Add to knowledge graph")(add_tool)
+user_proxy.register_for_execution()(add_tool)
+```
+
+## Features
+
+- **Tool-based memory access** — Register Zep search/add as AG2 tools via `@register_for_llm`
+- **System message injection** — Automatically enrich agent context with relevant memories
+- **Knowledge graph** — Access Zep's knowledge graph from AG2 agents
+- **Conversation memory** — Store and retrieve thread-based conversation history
+- **Sync tool execution** — Tools run synchronously via a single shared background event loop, compatible with AG2's execution model on Python 3.11–3.13
+
+## API Reference
+
+### ZepMemoryManager
+
+Manages Zep memory for AG2 agents via system message injection.
+
+- `ZepMemoryManager(client, user_id, session_id=None)` — Initialize with Zep client
+- `await enrich_system_message(agent, query=None, limit=5)` — Inject memory context
+- `await get_memory_context(query=None, limit=5)` — Get formatted context string
+- `await add_messages(messages)` — Store messages in Zep thread
+- `await get_session_facts()` — Get extracted session facts
+
+### ZepGraphMemoryManager
+
+Manages Zep knowledge graph for AG2 agents.
+
+- `ZepGraphMemoryManager(client, graph_id)` — Initialize with graph ID
+- `await search(query, limit=5, scope="edges")` — Search the graph
+- `await add_data(data, data_type="text")` — Add data to the graph
+- `await enrich_system_message(agent, query=None, limit=5)` — Inject graph context
+
+### Tool Factories
+
+All tool factories return **synchronous** callables (AG2 executes tools synchronously).
+Internally they bridge to the async Zep SDK on a single shared background event loop,
+reusing the `AsyncZep` client you pass in (no per-call client construction).
+
+- `create_search_memory_tool(client, user_id, session_id=None)` — Search conversation memory
+- `create_add_memory_tool(client, user_id, session_id=None)` — Add conversation memory
+- `create_search_graph_tool(client, user_id=None, graph_id=None)` — Search knowledge graph
+- `create_add_graph_data_tool(client, user_id=None, graph_id=None)` — Add graph data
+- `register_all_tools(agent, executor, client, user_id, ...)` — Register all tools at once
+
+## Examples
+
+- **[Basic Memory](examples/ag2_basic.py)** — System message injection + memory tools
+- **[Graph Memory](examples/ag2_graph.py)** — Knowledge graph with ZepGraphMemoryManager
+- **[Search Tools](examples/ag2_tools_search.py)** — Read-only search tool registration
+- **[Full Tools](examples/ag2_tools_full.py)** — All tools in a GroupChat with multiple agents
+- **[Manual Test](examples/manual_test.py)** — End-to-end integration test with real APIs
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+export ZEP_API_KEY="your-zep-cloud-api-key"
+
+# Required for examples that use LLM
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+## Development
+
+```bash
+make install        # Install dev dependencies
+make pre-commit     # Format, lint, type-check, test
+make ci             # CI validation
+```
+
+## Requirements
+
+- Python 3.11+
+- `ag2>=0.9.0`
+- `zep-cloud>=3.23.0`
+
+## License
+
+Apache-2.0 — see [LICENSE](../../../LICENSE) for details.
+
+## Support
+
+- [Zep Documentation](https://help.getzep.com)
+- [AG2 Documentation](https://docs.ag2.ai)
+- [GitHub Issues](https://github.com/getzep/zep/issues)
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details.

zep_ag2-0.1.0/SETUP.md

@@ -0,0 +1,61 @@
+# Setup
+
+This guide gets you from zero to a running AG2 agent with Zep memory.
+
+## 1. Sign up for Zep and get an API key
+
+1. Create a free account at [https://www.getzep.com](https://www.getzep.com).
+2. Open the Zep dashboard at [https://app.getzep.com](https://app.getzep.com).
+3. Create (or select) a project and copy its **API key**.
+
+## 2. Install
+
+```bash
+pip install zep-ag2
+```
+
+This installs the integration along with its runtime dependencies (`ag2` and
+`zep-cloud`).
+
+For local development of this package:
+
+```bash
+make install   # uv sync --extra dev
+```
+
+## 3. Configure environment variables
+
+The examples read configuration from environment variables. Copy the template
+and fill in your keys:
+
+```bash
+cp .env.example .env
+```
+
+```bash
+# Required
+export ZEP_API_KEY="your-zep-cloud-api-key"
+
+# Required for examples that call an LLM
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+## 4. Run an example
+
+```bash
+python examples/ag2_basic.py
+```
+
+Other runnable examples live in [`examples/`](examples):
+
+- `ag2_basic.py` — system message injection + memory tools
+- `ag2_graph.py` — knowledge graph with `ZepGraphMemoryManager`
+- `ag2_tools_search.py` — read-only search tool registration
+- `ag2_tools_full.py` — all tools across a multi-agent GroupChat
+- `manual_test.py` — end-to-end integration test against real APIs
+
+## Next steps
+
+- Read the [README](README.md) for the API reference.
+- See the [Zep documentation](https://help.getzep.com) for memory concepts,
+  knowledge graphs, and best practices.