cortexdb-ag2 0.1.0__py3-none-any.whl

cortexdb_ag2/__init__.py

@@ -0,0 +1,21 @@
+"""CortexDB integration for AG2 (successor to AutoGen).
+
+Provides a memory-augmented agent mixin and callable tools that connect
+AG2's multi-agent framework to CortexDB's long-term memory system.
+"""
+
+from cortexdb_ag2.agent import CortexDBAgent
+from cortexdb_ag2.tools import (
+    cortexdb_forget_fn,
+    cortexdb_search_fn,
+    cortexdb_store_fn,
+    register_cortexdb_tools,
+)
+
+__all__ = [
+    "CortexDBAgent",
+    "cortexdb_search_fn",
+    "cortexdb_store_fn",
+    "cortexdb_forget_fn",
+    "register_cortexdb_tools",
+]

cortexdb_ag2/agent.py

@@ -0,0 +1,183 @@
+"""AG2 agent with built-in CortexDB memory.
+
+Provides a ConversableAgent subclass that automatically stores
+conversation turns and retrieves relevant context from CortexDB
+before generating responses. Compatible with AG2 (the successor
+to Microsoft AutoGen).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from autogen import ConversableAgent
+
+from cortexdb import Cortex
+
+
+class CortexDBAgent(ConversableAgent):
+    """AG2 ConversableAgent with automatic CortexDB memory integration.
+
+    Extends AG2's ConversableAgent to automatically store conversation
+    turns in CortexDB and retrieve relevant past context before generating
+    responses. This enables the agent to maintain long-term memory across
+    conversations and sessions.
+
+    The agent injects retrieved context as a system-level prefix to the
+    conversation, giving the LLM access to relevant memories without
+    modifying the visible chat history.
+
+    Args:
+        name: The agent's name.
+        cortex_client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+        auto_store: Whether to automatically store conversation turns.
+            Defaults to ``True``.
+        auto_recall: Whether to automatically retrieve context before
+            responding. Defaults to ``True``.
+        **kwargs: Additional keyword arguments passed to ConversableAgent.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_ag2 import CortexDBAgent
+
+        client = Cortex("http://localhost:3141")
+        agent = CortexDBAgent(
+            name="memory_assistant",
+            cortex_client=client,
+            scope="user:default",
+            llm_config=llm_config,
+            system_message="You are a helpful assistant with long-term memory.",
+        )
+    """
+
+    def __init__(
+        self,
+        name: str,
+        cortex_client: Cortex,
+        scope: str = "user:default",
+        auto_store: bool = True,
+        auto_recall: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(name=name, **kwargs)
+        self._cortex_client = cortex_client
+        self._scope = scope
+        self._auto_store = auto_store
+        self._auto_recall = auto_recall
+
+    def generate_reply(
+        self,
+        messages: Optional[list[dict[str, Any]]] = None,
+        sender: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> Union[str, dict[str, Any], None]:
+        """Generate a reply with CortexDB memory augmentation.
+
+        Before generating a reply, retrieves relevant context from CortexDB
+        based on the latest message. After generating, stores the conversation
+        turn for future recall.
+
+        Args:
+            messages: The conversation messages to respond to.
+            sender: The agent that sent the message.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The generated reply string, a structured reply dict, or None.
+        """
+        if messages and self._auto_recall:
+            latest_message = messages[-1]
+            content = latest_message.get("content", "")
+            if content:
+                context = self._recall_context(str(content))
+                if context:
+                    messages = self._inject_memory_context(messages, context)
+
+        reply = super().generate_reply(messages=messages, sender=sender, **kwargs)
+
+        if reply and self._auto_store and messages:
+            latest_content = messages[-1].get("content", "") if messages else ""
+            reply_text = reply if isinstance(reply, str) else reply.get("content", "")
+            if latest_content and reply_text:
+                self._store_turn(str(latest_content), str(reply_text))
+
+        return reply
+
+    def _recall_context(self, query: str) -> str:
+        """Retrieve relevant context from CortexDB.
+
+        Args:
+            query: The query to search for relevant memories.
+
+        Returns:
+            The context string from CortexDB, or empty string on failure.
+        """
+        try:
+            result = self._cortex_client.recall(
+                self._scope,
+                query=query,
+            )
+        except Exception:
+            return ""
+
+        return result.get("context_block", "") if result else ""
+
+    def _store_turn(self, user_message: str, assistant_reply: str) -> None:
+        """Store a conversation turn in CortexDB.
+
+        Args:
+            user_message: The user's message.
+            assistant_reply: The agent's reply.
+        """
+        content = f"User: {user_message}\nAssistant: {assistant_reply}"
+        try:
+            self._cortex_client.experience(self._scope, text=content)
+        except Exception:
+            pass
+
+    def _inject_memory_context(
+        self,
+        messages: list[dict[str, Any]],
+        context: str,
+    ) -> list[dict[str, Any]]:
+        """Inject retrieved memory context into the message list.
+
+        Prepends a system message containing the retrieved context
+        so the LLM can reference it when generating a response.
+
+        Args:
+            messages: The original conversation messages.
+            context: The retrieved context string from CortexDB.
+
+        Returns:
+            A new message list with the memory context injected.
+        """
+        context_message = {
+            "role": "system",
+            "content": (
+                f"Relevant context from long-term memory:\n\n{context}\n\n"
+                "Use this context to inform your response if relevant."
+            ),
+        }
+
+        augmented = list(messages)
+        augmented.insert(0, context_message)
+        return augmented
+
+    def clear_memory(self) -> dict[str, Any]:
+        """Clear all memories for this agent's scope.
+
+        Removes all stored memories from CortexDB for the configured
+        scope path.
+
+        Returns:
+            The forget response dict from CortexDB.
+        """
+        return self._cortex_client.forget(
+            self._scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason="AG2 agent memory clear requested",
+        )

cortexdb_ag2/tools.py

@@ -0,0 +1,165 @@
+"""AG2 callable tools for interacting with CortexDB.
+
+Provides factory functions that create CortexDB-backed callables
+suitable for registration with AG2's ConversableAgent tool system.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable, Optional
+
+from cortexdb import Cortex
+
+
+def cortexdb_search_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a search function for use as an AG2 tool.
+
+    Returns a callable that performs semantic recall over CortexDB's
+    memory store, suitable for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``query`` parameter and
+        returns the recalled context block.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_ag2 import cortexdb_search_fn
+
+        client = Cortex("http://localhost:3141")
+        search = cortexdb_search_fn(client, scope="user:default")
+
+        agent.register_for_llm(description="Search memories")(search)
+        user_proxy.register_for_execution()(search)
+    """
+
+    def search(
+        query: Annotated[str, "The search query to find relevant memories."],
+    ) -> str:
+        """Search CortexDB for relevant memories and past context."""
+        result = client.recall(scope, query=query)
+
+        context = result.get("context_block", "") if result else ""
+        if not context:
+            return "No relevant memories found."
+
+        return context
+
+    search.__name__ = "cortexdb_search"
+    search.__doc__ = "Search CortexDB for relevant memories and past context."
+    return search
+
+
+def cortexdb_store_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a store function for use as an AG2 tool.
+
+    Returns a callable that persists information into CortexDB's
+    long-term memory, suitable for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``content`` parameter and
+        returns a confirmation message.
+    """
+
+    def store(
+        content: Annotated[str, "The content to store as a memory."],
+    ) -> str:
+        """Store information in CortexDB's long-term memory."""
+        client.experience(scope, text=content)
+        return "Memory stored successfully in CortexDB."
+
+    store.__name__ = "cortexdb_store"
+    store.__doc__ = "Store information in CortexDB's long-term memory."
+    return store
+
+
+def cortexdb_forget_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a forget function for use as an AG2 tool.
+
+    Returns a callable that removes memories from CortexDB, suitable
+    for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``reason`` parameter
+        and returns a confirmation message.
+    """
+
+    def forget(
+        reason: Annotated[str, "The reason for forgetting these memories."],
+    ) -> str:
+        """Forget or remove memories from CortexDB."""
+        client.forget(
+            scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason=reason,
+        )
+        return f"Memories in scope '{scope}' have been forgotten."
+
+    forget.__name__ = "cortexdb_forget"
+    forget.__doc__ = "Forget or remove memories from CortexDB."
+    return forget
+
+
+def register_cortexdb_tools(
+    agent: Any,
+    executor: Any,
+    client: Cortex,
+    scope: str = "user:default",
+) -> None:
+    """Register all CortexDB tools with an AG2 agent and executor.
+
+    Convenience function that creates and registers search, store, and
+    forget tools on both the LLM-facing agent and the execution proxy.
+
+    Args:
+        agent: The AG2 ConversableAgent that will call the tools.
+        executor: The AG2 agent (typically UserProxyAgent) that
+            executes tool calls.
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Example::
+
+        from ag2 import ConversableAgent, UserProxyAgent
+        from cortexdb import Cortex
+        from cortexdb_ag2 import register_cortexdb_tools
+
+        client = Cortex("http://localhost:3141")
+        assistant = ConversableAgent("assistant", llm_config=llm_config)
+        user_proxy = UserProxyAgent("user_proxy")
+
+        register_cortexdb_tools(assistant, user_proxy, client, scope="user:default")
+    """
+    search = cortexdb_search_fn(client, scope)
+    store = cortexdb_store_fn(client, scope)
+    forget = cortexdb_forget_fn(client, scope)
+
+    for fn, desc in [
+        (search, "Search CortexDB for relevant memories and past context."),
+        (store, "Store information in CortexDB's long-term memory."),
+        (forget, "Forget or remove memories from CortexDB."),
+    ]:
+        agent.register_for_llm(description=desc)(fn)
+        executor.register_for_execution()(fn)

cortexdb_ag2-0.1.0.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: cortexdb-ag2
+Version: 0.1.0
+Summary: AG2 integration for CortexDB — long-term memory for AI agent conversations
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: ag2>=0.4
+Requires-Dist: cortexdbai>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cortexdb-ag2
+
+AG2 (formerly AutoGen) integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical example shows GPT-4o
+> in the AG2 LLM config. CortexDB itself is LLM-agnostic. Swap providers
+> through AG2's standard `llm_config` — Anthropic, Gemini, Mistral, and
+> Together AI all work. Nothing in `cortexdb-ag2` reads `OPENAI_API_KEY`.
+
+## Install
+
+```bash
+pip install cortexdb-ag2
+```
+
+## API base URL
+
+Defaults to `https://api-v1.cortexdb.ai` (audit FRI-8). Override with
+`CORTEXDB_API_URL`.

cortexdb_ag2-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cortexdb_ag2/__init__.py,sha256=MZgDfn2RcGWU-3XsHDy3_ZuwCUhQa-JLlu2AcxUkrL8,546
+cortexdb_ag2/agent.py,sha256=eWikM55fMJAOUcHq3KMDz7_wQvf7aVIZEA9F9BEAAGo,6344
+cortexdb_ag2/tools.py,sha256=6dfZZkWs1YG3ujJNKgRudMBOSTwBzB4btADzTN4Q-_E,5440
+cortexdb_ag2-0.1.0.dist-info/METADATA,sha256=Gln6iOUf5QyCgb8FLv9V9ySZ94U3GHANmKqA6DXX6EA,894
+cortexdb_ag2-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cortexdb_ag2-0.1.0.dist-info/RECORD,,

cortexdb_ag2-0.1.0.dist-info/WHEEL

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