cortexdb-langchain 0.1.0__py3-none-any.whl

cortexdb_langchain/__init__.py

@@ -0,0 +1,29 @@
+"""CortexDB integration for LangChain.
+
+Provides chat-message history, retrievers, and tools that connect LangChain
+applications to CortexDB's long-term memory system.
+"""
+
+from cortexdb_langchain.memory import CortexDBChatMessageHistory
+from cortexdb_langchain.retriever import CortexDBRetriever
+from cortexdb_langchain.tools import (
+    CortexDBForgetTool,
+    CortexDBSearchTool,
+    CortexDBStoreTool,
+)
+
+__all__ = [
+    "CortexDBChatMessageHistory",
+    "CortexDBRetriever",
+    "CortexDBForgetTool",
+    "CortexDBSearchTool",
+    "CortexDBStoreTool",
+]
+
+# Legacy BaseMemory backend — only present on langchain-core < 1.0.
+try:
+    from cortexdb_langchain.memory import CortexDBMemory  # noqa: F401
+
+    __all__.append("CortexDBMemory")
+except ImportError:
+    pass

cortexdb_langchain/memory.py

@@ -0,0 +1,141 @@
+"""LangChain memory backed by CortexDB.
+
+Primary, version-agnostic primitive: :class:`CortexDBChatMessageHistory`, a
+``BaseChatMessageHistory`` (available in langchain-core 0.3 **and** 1.x). Use it
+with ``RunnableWithMessageHistory`` to give a chain/agent long-term memory:
+messages are persisted to CortexDB and relevant context is recalled back.
+
+The legacy :class:`CortexDBMemory` (built on the pre-1.0 ``BaseMemory``) is kept
+only when that base class is importable (langchain-core < 1.0), since 1.x removed
+the ``BaseMemory`` framework entirely.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.messages import AIMessage, BaseMessage
+
+from cortexdb import Cortex
+
+
+class CortexDBChatMessageHistory(BaseChatMessageHistory):
+    """Chat-message history backed by CortexDB (langchain-core 0.3 + 1.x).
+
+    - ``add_message`` / ``add_messages`` persist each message via ``experience``.
+    - ``messages`` recalls relevant long-term context for ``recall_query`` and
+      surfaces it as a single ``AIMessage`` (CortexDB is semantic memory, not a
+      literal per-session log). Set ``recall_query`` to the current user input.
+    - ``clear`` forgets the scope.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_langchain import CortexDBChatMessageHistory
+
+        client = Cortex("https://api-v1.cortexdb.ai", actor="user:app", bearer="v4.public...")
+        history = CortexDBChatMessageHistory(client=client, scope="user:my-app")
+    """
+
+    def __init__(
+        self,
+        client: Cortex,
+        scope: str = "user:default",
+        recall_query: str = "",
+    ) -> None:
+        self._client = client
+        self.scope = scope
+        self.recall_query = recall_query
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        query = self.recall_query
+        if not query:
+            return []
+        result = self._client.recall(self.scope, query=str(query))
+        block = result.get("context_block", "")
+        return [AIMessage(content=block)] if block else []
+
+    def add_message(self, message: BaseMessage) -> None:
+        self._client.experience(
+            self.scope, text=f"{message.type}: {message.content}"
+        )
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        for message in messages:
+            self.add_message(message)
+
+    def clear(self) -> None:
+        self._client.forget(
+            self.scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason="LangChain memory clear requested",
+        )
+
+
+# ── Legacy BaseMemory backend (langchain-core < 1.0 only) ────────────────────
+# langchain-core 1.x removed BaseMemory and the classic `memory=` chain hook, so
+# we only define this when the base class is importable.
+try:
+    from langchain_core.memory import BaseMemory as _BaseMemory
+except ImportError:  # langchain-core >= 1.0
+    _BaseMemory = None
+
+if _BaseMemory is not None:
+    from pydantic import PrivateAttr
+
+    class CortexDBMemory(_BaseMemory):  # type: ignore[misc,valid-type]
+        """Deprecated: classic BaseMemory backend (langchain-core < 1.0).
+
+        Prefer :class:`CortexDBChatMessageHistory` with
+        ``RunnableWithMessageHistory`` on langchain-core 1.x.
+        """
+
+        memory_key: str = "cortex_context"
+        input_key: Optional[str] = None
+        output_key: Optional[str] = None
+        scope: str = "user:default"
+
+        _client: Cortex = PrivateAttr()
+
+        def __init__(self, client: Cortex, **kwargs: Any) -> None:
+            super().__init__(**kwargs)
+            self._client = client
+
+        @property
+        def memory_variables(self) -> list[str]:
+            return [self.memory_key]
+
+        def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, Any]:
+            if self.input_key is not None:
+                query = inputs.get(self.input_key, "")
+            else:
+                query = next(iter(inputs.values()), "") if inputs else ""
+            if not query:
+                return {self.memory_key: ""}
+            result = self._client.recall(self.scope, query=str(query))
+            return {self.memory_key: result.get("context_block", "")}
+
+        def save_context(
+            self, inputs: dict[str, Any], outputs: dict[str, str]
+        ) -> None:
+            if self.output_key is not None:
+                output_text = outputs.get(self.output_key, "")
+            else:
+                output_text = next(iter(outputs.values()), "") if outputs else ""
+            if self.input_key is not None:
+                input_text = inputs.get(self.input_key, "")
+            else:
+                input_text = next(iter(inputs.values()), "") if inputs else ""
+            content = f"User: {input_text}\nAssistant: {output_text}"
+            self._client.experience(self.scope, text=content)
+
+        def clear(self) -> None:
+            self._client.forget(
+                self.scope,
+                confirm_all=True,
+                cascade="redact_events",
+                reason="LangChain memory clear requested",
+            )

cortexdb_langchain/retriever.py

@@ -0,0 +1,74 @@
+"""LangChain retriever backed by CortexDB.
+
+Provides a standard LangChain retriever interface for semantic search
+over CortexDB's memory store, compatible with retrieval chains and
+retrieval-augmented generation (RAG) pipelines.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import Field, PrivateAttr
+
+from cortexdb import Cortex
+
+
+class CortexDBRetriever(BaseRetriever):
+    """LangChain retriever that queries CortexDB's memory store.
+
+    Wraps CortexDB's ``recall`` API as a standard LangChain retriever,
+    returning results as LangChain ``Document`` objects.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The scope path for memory isolation (hierarchical string).
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_langchain import CortexDBRetriever
+
+        client = Cortex(
+            "https://api-v1.cortexdb.ai",
+            actor="user:app",
+            bearer="v4.public...",
+        )
+        retriever = CortexDBRetriever(client=client, scope="user:my-app")
+
+        docs = retriever.invoke("What happened in the last sprint?")
+        for doc in docs:
+            print(doc.page_content)
+    """
+
+    scope: str = "user:default"
+
+    _client: Cortex = PrivateAttr()
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun,
+    ) -> list[Document]:
+        result = self._client.recall(self.scope, query=query)
+
+        metadata = {
+            "source": "cortexdb",
+            "scope": self.scope,
+            "pack_id": result.get("pack_id"),
+        }
+
+        return [
+            Document(
+                page_content=result.get("context_block", ""),
+                metadata=metadata,
+            )
+        ]

cortexdb_langchain/tools.py

@@ -0,0 +1,121 @@
+"""LangChain tools for interacting with CortexDB.
+
+Provides search, store, and forget tools that allow LangChain agents
+to interact with CortexDB's memory system as part of their tool-use
+capabilities.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from cortexdb import Cortex
+
+
+class _SearchInput(BaseModel):
+    query: str = Field(description="The search query to find relevant memories.")
+
+
+class CortexDBSearchTool(BaseTool):
+    """LangChain tool for searching memories in CortexDB."""
+
+    name: str = "cortexdb_search"
+    description: str = (
+        "Search CortexDB for relevant memories and past context. "
+        "Use this when you need to recall information from previous "
+        "conversations or stored knowledge."
+    )
+    args_schema: Type[BaseModel] = _SearchInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        query: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        result = self._client.recall(self.scope, query=query)
+
+        context = result.get("context_block", "")
+        if not context:
+            return "No relevant memories found."
+
+        return context
+
+
+class _StoreInput(BaseModel):
+    content: str = Field(description="The content to store as a memory.")
+
+
+class CortexDBStoreTool(BaseTool):
+    """LangChain tool for storing memories in CortexDB."""
+
+    name: str = "cortexdb_store"
+    description: str = (
+        "Store information in CortexDB's long-term memory. "
+        "Use this to save important facts, decisions, or context "
+        "that should be remembered for future interactions."
+    )
+    args_schema: Type[BaseModel] = _StoreInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        content: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        resp = self._client.experience(self.scope, text=content)
+        return f"Memory stored successfully (event_id: {resp.get('event_id')})."
+
+
+class _ForgetInput(BaseModel):
+    query: str = Field(description="Query identifying the memories to forget.")
+    reason: str = Field(description="The reason for forgetting these memories.")
+
+
+class CortexDBForgetTool(BaseTool):
+    """LangChain tool for forgetting memories in CortexDB."""
+
+    name: str = "cortexdb_forget"
+    description: str = (
+        "Forget or remove memories from CortexDB. "
+        "Use this when information should no longer be retained, "
+        "such as for privacy compliance or data correction."
+    )
+    args_schema: Type[BaseModel] = _ForgetInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        query: str,
+        reason: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        resp = self._client.forget(
+            self.scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason=reason,
+        )
+        return f"Forget request accepted (audit_id: {resp.get('audit_id')})."

cortexdb_langchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: cortexdb-langchain
+Version: 0.1.0
+Summary: LangChain integration for CortexDB — long-term memory for AI systems
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: cortexdbai>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cortexdb-langchain
+
+LangChain integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical quickstart uses
+> `from langchain_openai import ChatOpenAI` for the example agent. CortexDB
+> itself is LLM-agnostic — the LangChain example just needs *some* model to
+> drive the agent. Swap with one line:
+>
+> ```python
+> # OpenAI (default in the docs)
+> from langchain_openai import ChatOpenAI
+> llm = ChatOpenAI(model="gpt-4o")
+>
+> # Anthropic
+> from langchain_anthropic import ChatAnthropic
+> llm = ChatAnthropic(model="claude-sonnet-4-6")
+>
+> # Google
+> from langchain_google_genai import ChatGoogleGenerativeAI
+> llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro")
+>
+> # Local / Ollama (no API key)
+> from langchain_community.chat_models import ChatOllama
+> llm = ChatOllama(model="llama3.1")
+> ```
+>
+> Nothing in `cortexdb-langchain` reads `OPENAI_API_KEY`. The retriever and
+> memory classes only talk to the CortexDB v1 surface.
+
+## Install
+
+```bash
+pip install cortexdb-langchain
+```
+
+## API base URL
+
+The SDK and integration default to `https://api-v1.cortexdb.ai` (audit FRI-8).
+Override with `CORTEXDB_API_URL` if you self-host.

cortexdb_langchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+cortexdb_langchain/__init__.py,sha256=k7DwyE8EJUq-fy-pLozMENjFOtWW_pOxL1KfttzawA4,803
+cortexdb_langchain/memory.py,sha256=wVzgfTKR8sP3NHhDByVh_htqtfeUVP-FSooSzJEC7qk,5356
+cortexdb_langchain/retriever.py,sha256=GImZOZvUEezJqnetPctRvTbZXqxazxp-DbXhLtiYP5s,2180
+cortexdb_langchain/tools.py,sha256=_mjDRQUNm4_ISZD7hI1cSjm6ibMI1IvJhdl8ZjcPG5I,3607
+cortexdb_langchain-0.1.0.dist-info/METADATA,sha256=Vr4iddBlO-_AHFuSJ9_ae8oroJAFxkb0OVRLDXLfiog,1595
+cortexdb_langchain-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cortexdb_langchain-0.1.0.dist-info/RECORD,,

cortexdb_langchain-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