cortexdbai 0.4.0__tar.gz → 0.4.2__tar.gz

{cortexdbai-0.4.0 → cortexdbai-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.4.0
+Version: 0.4.2
 Summary: The Long-Term Memory Layer for AI Systems
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://docs.cortexdb.ai
@@ -25,8 +25,13 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: pydantic>=2.0
 Requires-Dist: requests>=2.31
 Requires-Dist: tenacity>=8.0
+Provides-Extra: ag2
+Requires-Dist: ag2>=0.4; extra == 'ag2'
+Provides-Extra: agno
+Requires-Dist: agno>=1.0; extra == 'agno'
 Provides-Extra: all-integrations
 Requires-Dist: ag2>=0.4; extra == 'all-integrations'
+Requires-Dist: agno>=1.0; extra == 'all-integrations'
 Requires-Dist: beeai-framework>=0.1; extra == 'all-integrations'
 Requires-Dist: camel-ai>=0.2; extra == 'all-integrations'
 Requires-Dist: controlflow>=0.11; extra == 'all-integrations'
@@ -77,6 +82,8 @@ Provides-Extra: hermes
 Provides-Extra: instructor
 Requires-Dist: instructor>=1.0; extra == 'instructor'
 Requires-Dist: pydantic>=2.0; extra == 'instructor'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
 Provides-Extra: langgraph
 Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
 Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph'

{cortexdbai-0.4.0 → cortexdbai-0.4.2}/README.md

@@ -1,140 +1,140 @@
-# CortexDB Python SDK
-
-**The Long-Term Memory Layer for AI Systems.**
-
-CortexDB gives your AI agents persistent, structured memory. Capture experiences, then recall a stratified pack (events, facts, beliefs, episodes, concepts) or get a grounded answer — all scoped to a hierarchical `scope` path.
-
-[![PyPI version](https://img.shields.io/pypi/v/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
-[![Python](https://img.shields.io/pypi/pyversions/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
-
-This SDK targets the **v1 API** (`/v1/experience`, `/v1/recall`, `/v1/answer`, …), PASETO auth, and hierarchical scopes. The pre-0.3 `remember()`/`tenant_id` client was retired — `Cortex` is now an alias of `V1Client`.
-
-## Installation
-
-```bash
-pip install cortexdbai
-```
-
-## Quick start
-
-```python
-from cortexdb import Cortex
-
-# Local `docker run` with auth disabled (CORTEX_API_KEY unset on the server):
-with Cortex("http://localhost:3141") as c:
-    c.experience("ws:demo", text="Priya at Acme signed for 200 seats. Q3 close.")
-    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
-    print(pack["context_block"])
-```
-
-### Hosted / multi-tenant (PASETO bearer + actor)
-
-```python
-with Cortex(
-    "https://api-v1.cortexdb.ai",
-    actor="user:alice",
-    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256)
-) as c:
-    out = c.answer(
-        "org:initech/user:alice",
-        "What did Alice say about coffee?",
-    )
-    print(out["answer"])
-```
-
-### One-call signup (no prior credentials)
-
-```python
-from cortexdb import Cortex
-
-c = Cortex.signup()                      # POST /v1/auth/signup → free-tier PASETO
-c.experience(c.actor, text="hello, memory!")
-print(c.recall(c.actor, query="what did I say?")["context_block"])
-```
-
-## Core operations
-
-```python
-# Write — async by default (202); pass wait= for synchronous indexing.
-c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
-c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
-
-# Recall — returns a StratifiedPack { context_block, layers, provenance }.
-pack = c.recall("ws:demo", query="recent deploys", view="holistic")
-
-# Answer — recall + LLM render with citations.
-ans = c.answer("ws:demo", "What changed in payments recently?")
-
-# Forget — GDPR erasure. confirm_all wipes the whole scope.
-c.forget("ws:demo", confirm_all=True, cascade="redact_events",
-         audit_note="GDPR Article 17 request")
-
-# Layer reads (paginated { items, has_more }).
-c.events("ws:demo")
-c.facts("ws:demo")
-c.beliefs("ws:demo")
-c.episodes("ws:demo")
-c.understanding("ws:demo")
-```
-
-## Async usage
-
-`AsyncCortex` mirrors every method:
-
-```python
-import asyncio
-from cortexdb import AsyncCortex
-
-async def main():
-    async with AsyncCortex("http://localhost:3141") as c:
-        await c.experience("ws:demo", text="async memory works great")
-        pack = await c.recall("ws:demo", query="what works?")
-        print(pack["context_block"])
-
-asyncio.run(main())
-```
-
-## Error handling
-
-```python
-from cortexdb import (
-    Cortex,
-    V1Error,             # base
-    V1APIError,          # non-2xx envelope
-    V1AuthError,         # 401 / actor mismatch
-    V1PolicyDeniedError, # 403 — missing capability
-    V1RateLimitError,    # 429 (carries retry_after)
-    V1NotConfiguredError,# 503 — feature not configured
-    V1ConnectionError,
-    V1TimeoutError,
-)
-
-with Cortex("http://localhost:3141") as c:
-    try:
-        c.experience("ws:demo", text="important data")
-    except V1RateLimitError as e:
-        print(f"rate limited; retry after {e.retry_after}s")
-    except V1PolicyDeniedError as e:
-        print(f"missing capability: {e}")
-    except V1APIError as e:
-        print(f"API error [{e.status_code}]: {e}")
-```
-
-## Constructor
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `api_url` | `str` | `http://localhost:3141` | CortexDB v1 surface URL |
-| `actor` | `str` | `user:default` | Sent as `X-Cortex-Actor`; must match the token subject when authed |
-| `bearer` | `str \| None` | `None` | PASETO v4 public / JWT bearer (omit for auth-disabled dev) |
-| `timeout` | `float` | `30.0` | Request timeout (seconds) |
-
-## Links
-
-- [Documentation](https://docs.cortexdb.ai)
-- [Issue Tracker](https://github.com/cortexdb/cortexdb/issues)
-
-## License
-
-Apache-2.0
+# CortexDB Python SDK
+
+**The Long-Term Memory Layer for AI Systems.**
+
+CortexDB gives your AI agents persistent, structured memory. Capture experiences, then recall a stratified pack (events, facts, beliefs, episodes, concepts) or get a grounded answer — all scoped to a hierarchical `scope` path.
+
+[![PyPI version](https://img.shields.io/pypi/v/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![Python](https://img.shields.io/pypi/pyversions/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
+
+This SDK targets the **v1 API** (`/v1/experience`, `/v1/recall`, `/v1/answer`, …), PASETO auth, and hierarchical scopes. The pre-0.3 `remember()`/`tenant_id` client was retired — `Cortex` is now an alias of `V1Client`.
+
+## Installation
+
+```bash
+pip install cortexdbai
+```
+
+## Quick start
+
+```python
+from cortexdb import Cortex
+
+# Local `docker run` with auth disabled (CORTEX_API_KEY unset on the server):
+with Cortex("http://localhost:3141") as c:
+    c.experience("ws:demo", text="Priya at Acme signed for 200 seats. Q3 close.")
+    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
+    print(pack["context_block"])
+```
+
+### Hosted / multi-tenant (PASETO bearer + actor)
+
+```python
+with Cortex(
+    "https://api-v1.cortexdb.ai",
+    actor="user:alice",
+    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256)
+) as c:
+    out = c.answer(
+        "org:initech/user:alice",
+        "What did Alice say about coffee?",
+    )
+    print(out["answer"])
+```
+
+### One-call signup (no prior credentials)
+
+```python
+from cortexdb import Cortex
+
+c = Cortex.signup()                      # POST /v1/auth/signup → free-tier PASETO
+c.experience(c.actor, text="hello, memory!")
+print(c.recall(c.actor, query="what did I say?")["context_block"])
+```
+
+## Core operations
+
+```python
+# Write — async by default (202); pass wait= for synchronous indexing.
+c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
+c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
+
+# Recall — returns a StratifiedPack { context_block, layers, provenance }.
+pack = c.recall("ws:demo", query="recent deploys", view="holistic")
+
+# Answer — recall + LLM render with citations.
+ans = c.answer("ws:demo", "What changed in payments recently?")
+
+# Forget — GDPR erasure. confirm_all wipes the whole scope.
+c.forget("ws:demo", confirm_all=True, cascade="redact_events",
+         audit_note="GDPR Article 17 request")
+
+# Layer reads (paginated { items, has_more }).
+c.events("ws:demo")
+c.facts("ws:demo")
+c.beliefs("ws:demo")
+c.episodes("ws:demo")
+c.understanding("ws:demo")
+```
+
+## Async usage
+
+`AsyncCortex` mirrors every method:
+
+```python
+import asyncio
+from cortexdb import AsyncCortex
+
+async def main():
+    async with AsyncCortex("http://localhost:3141") as c:
+        await c.experience("ws:demo", text="async memory works great")
+        pack = await c.recall("ws:demo", query="what works?")
+        print(pack["context_block"])
+
+asyncio.run(main())
+```
+
+## Error handling
+
+```python
+from cortexdb import (
+    Cortex,
+    V1Error,             # base
+    V1APIError,          # non-2xx envelope
+    V1AuthError,         # 401 / actor mismatch
+    V1PolicyDeniedError, # 403 — missing capability
+    V1RateLimitError,    # 429 (carries retry_after)
+    V1NotConfiguredError,# 503 — feature not configured
+    V1ConnectionError,
+    V1TimeoutError,
+)
+
+with Cortex("http://localhost:3141") as c:
+    try:
+        c.experience("ws:demo", text="important data")
+    except V1RateLimitError as e:
+        print(f"rate limited; retry after {e.retry_after}s")
+    except V1PolicyDeniedError as e:
+        print(f"missing capability: {e}")
+    except V1APIError as e:
+        print(f"API error [{e.status_code}]: {e}")
+```
+
+## Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_url` | `str` | `http://localhost:3141` | CortexDB v1 surface URL |
+| `actor` | `str` | `user:default` | Sent as `X-Cortex-Actor`; must match the token subject when authed |
+| `bearer` | `str \| None` | `None` | PASETO v4 public / JWT bearer (omit for auth-disabled dev) |
+| `timeout` | `float` | `30.0` | Request timeout (seconds) |
+
+## Links
+
+- [Documentation](https://docs.cortexdb.ai)
+- [Issue Tracker](https://github.com/cortexdb/cortexdb/issues)
+
+## License
+
+Apache-2.0

{cortexdbai-0.4.0 → cortexdbai-0.4.2}/cortexdb/__init__.py

@@ -1,71 +1,71 @@
-"""CortexDB Python SDK — the long-term memory layer for AI systems.
-
-The SDK is a thin HTTP client over the v1 API surface that cortexdb
-exposes by default on port 3141. The top-level :class:`Cortex` class
-(alias :class:`V1Client`) is what you should reach for.
-
-Quick start::
-
-    from cortexdb import Cortex
-
-    # Local docker run with no auth (CORTEX_API_KEY unset on the server):
-    with Cortex("http://localhost:3141") as c:
-        c.experience("ws:demo", text="Priya at Acme signed for 200 seats.")
-        pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
-        print(pack)
-
-    # Hosted / multi-tenant deployment with PASETO bearer + actor header:
-    with Cortex(
-        "https://api-v1.cortexdb.ai",
-        actor="user:alice",
-        bearer="eyJ...",
-    ) as c:
-        out = c.answer(
-            "org:initech/user:alice",
-            question="What did Alice say about coffee?",
-        )
-
-Versions ≤ 0.2.x exposed a separate ``cortexdb.Cortex`` class targeting
-the legacy ``/v1/remember`` endpoints. That surface was retired in 0.3.0
-because the cortexdb binary's public port now only serves the v1 API;
-the legacy endpoints survive only as an internal bench-compat helper.
-If you need them, pin ``cortexdbai<0.3``.
-"""
-
-from cortexdb.v1 import V1Client, AsyncV1Client
-from cortexdb.v1.exceptions import (
-    V1APIError,
-    V1AuthError,
-    V1ConnectionError,
-    V1Error,
-    V1NotConfiguredError,
-    V1PolicyDeniedError,
-    V1RateLimitError,
-    V1TimeoutError,
-)
-from cortexdb import v1  # the explicit submodule namespace
-
-# Ergonomic top-level aliases. New code can write either form.
-Cortex = V1Client
-AsyncCortex = AsyncV1Client
-
-__version__ = "0.3.2"
-__all__ = [
-    # Clients (preferred top-level names)
-    "Cortex",
-    "AsyncCortex",
-    # Explicit v1 names (identical classes, kept for code that pinned them)
-    "V1Client",
-    "AsyncV1Client",
-    # Submodule
-    "v1",
-    # Exceptions
-    "V1Error",
-    "V1APIError",
-    "V1AuthError",
-    "V1ConnectionError",
-    "V1TimeoutError",
-    "V1RateLimitError",
-    "V1NotConfiguredError",
-    "V1PolicyDeniedError",
-]
+"""CortexDB Python SDK — the long-term memory layer for AI systems.
+
+The SDK is a thin HTTP client over the v1 API surface that cortexdb
+exposes by default on port 3141. The top-level :class:`Cortex` class
+(alias :class:`V1Client`) is what you should reach for.
+
+Quick start::
+
+    from cortexdb import Cortex
+
+    # Local docker run with no auth (CORTEX_API_KEY unset on the server):
+    with Cortex("http://localhost:3141") as c:
+        c.experience("ws:demo", text="Priya at Acme signed for 200 seats.")
+        pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
+        print(pack)
+
+    # Hosted / multi-tenant deployment with PASETO bearer + actor header:
+    with Cortex(
+        "https://api-v1.cortexdb.ai",
+        actor="user:alice",
+        bearer="eyJ...",
+    ) as c:
+        out = c.answer(
+            "org:initech/user:alice",
+            question="What did Alice say about coffee?",
+        )
+
+Versions ≤ 0.2.x exposed a separate ``cortexdb.Cortex`` class targeting
+the legacy ``/v1/remember`` endpoints. That surface was retired in 0.3.0
+because the cortexdb binary's public port now only serves the v1 API;
+the legacy endpoints survive only as an internal bench-compat helper.
+If you need them, pin ``cortexdbai<0.3``.
+"""
+
+from cortexdb.v1 import V1Client, AsyncV1Client
+from cortexdb.v1.exceptions import (
+    V1APIError,
+    V1AuthError,
+    V1ConnectionError,
+    V1Error,
+    V1NotConfiguredError,
+    V1PolicyDeniedError,
+    V1RateLimitError,
+    V1TimeoutError,
+)
+from cortexdb import v1  # the explicit submodule namespace
+
+# Ergonomic top-level aliases. New code can write either form.
+Cortex = V1Client
+AsyncCortex = AsyncV1Client
+
+__version__ = "0.4.2"
+__all__ = [
+    # Clients (preferred top-level names)
+    "Cortex",
+    "AsyncCortex",
+    # Explicit v1 names (identical classes, kept for code that pinned them)
+    "V1Client",
+    "AsyncV1Client",
+    # Submodule
+    "v1",
+    # Exceptions
+    "V1Error",
+    "V1APIError",
+    "V1AuthError",
+    "V1ConnectionError",
+    "V1TimeoutError",
+    "V1RateLimitError",
+    "V1NotConfiguredError",
+    "V1PolicyDeniedError",
+]

cortexdbai-0.4.2/cortexdb/integrations/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 .agent import CortexDBAgent
+from .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",
+]

cortexdbai-0.4.2/cortexdb/integrations/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",
+        )