langchain-memorae 0.1.0__tar.gz

langchain_memorae-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: langchain-memorae
+Version: 0.1.0
+Summary: MeMorae memory and retrieval adapters for LangChain and LangGraph
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: langchain-classic<2,>=1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: examples
+Requires-Dist: langchain-openai>=0.2; extra == "examples"
+Requires-Dist: langgraph>=0.2; extra == "examples"
+Requires-Dist: flask>=3; extra == "examples"
+
+# langchain-memorae
+
+Connect an existing LangChain, LangGraph, or local chatbot to MeMorae's project-key API. MeMorae handles ingestion, approval, and retrieval; this package only calls the existing endpoints. The MeMorae backend must already be running.
+
+MCP exposes MeMorae tools to MCP clients. This package provides Python memory and retriever objects for application code using LangChain or LangGraph.
+
+## Install
+
+From the repository root:
+
+```bash
+pip install -e integrations/langchain-memorae
+```
+
+When published, install with `pip install langchain-memorae`.
+
+## Basic usage
+
+```python
+from langchain_memorae import MeMoraeMemory, MeMoraeRetriever
+
+memory = MeMoraeMemory(api_key="MEMORAE_PROJECT_API_KEY",
+                       base_url="http://localhost:8000",
+                       subject_id="user_123", namespace="default")
+context = memory.load_memory_variables({"input": "What food do I like?"})
+memory.save_context({"input": "I love pizza"}, {"output": "Got it."})
+
+retriever = MeMoraeRetriever(api_key="MEMORAE_PROJECT_API_KEY",
+                             base_url="http://localhost:8000",
+                             subject_id="user_123", namespace="default")
+docs = retriever.invoke("What sports do I enjoy?")
+```
+
+`context["history"]` is a compact string of retrieved memories. `docs` contains LangChain `Document` objects with `memory_id` and `source_ids` metadata. Ingestion is asynchronous on the server; a new message may take time to appear in search. Assistant output is saved only with `save_assistant=True`.
+
+`subject_id` identifies the end user whose memories are recalled. `namespace` separates memory spaces for that user; use the same values for saving and searching. A project API key determines the project scope. Keep it on your server, load it from an environment variable, and never put it in browser code or logs.
+
+## LangGraph
+
+In a graph, call `memory.load_memory_variables({"input": question})` in a recall node before the answer node. Call `memory.save_context({"input": question}, {"output": answer})` in a save node afterward. See [langgraph_chatbot.py](examples/langgraph_chatbot.py) for a complete small graph.
+
+## Local chatbot
+
+Wrap your existing answer function: load `history`, pass it to the function as context, then save the question and answer. See [local_chatbot_flask.py](examples/local_chatbot_flask.py) for a Flask route and [basic_chatbot.py](examples/basic_chatbot.py) for ChatOpenAI. Examples read `MEMORAE_API_KEY`, `MEMORAE_BASE_URL`, and `MEMORAE_SUBJECT_ID` from the environment. The ChatOpenAI examples also need `OPENAI_API_KEY` and their optional dependencies.
+
+`clear()` is a no-op because clearing remote memories is a separate MeMorae review action.

langchain_memorae-0.1.0/README.md

@@ -0,0 +1,46 @@
+# langchain-memorae
+
+Connect an existing LangChain, LangGraph, or local chatbot to MeMorae's project-key API. MeMorae handles ingestion, approval, and retrieval; this package only calls the existing endpoints. The MeMorae backend must already be running.
+
+MCP exposes MeMorae tools to MCP clients. This package provides Python memory and retriever objects for application code using LangChain or LangGraph.
+
+## Install
+
+From the repository root:
+
+```bash
+pip install -e integrations/langchain-memorae
+```
+
+When published, install with `pip install langchain-memorae`.
+
+## Basic usage
+
+```python
+from langchain_memorae import MeMoraeMemory, MeMoraeRetriever
+
+memory = MeMoraeMemory(api_key="MEMORAE_PROJECT_API_KEY",
+                       base_url="http://localhost:8000",
+                       subject_id="user_123", namespace="default")
+context = memory.load_memory_variables({"input": "What food do I like?"})
+memory.save_context({"input": "I love pizza"}, {"output": "Got it."})
+
+retriever = MeMoraeRetriever(api_key="MEMORAE_PROJECT_API_KEY",
+                             base_url="http://localhost:8000",
+                             subject_id="user_123", namespace="default")
+docs = retriever.invoke("What sports do I enjoy?")
+```
+
+`context["history"]` is a compact string of retrieved memories. `docs` contains LangChain `Document` objects with `memory_id` and `source_ids` metadata. Ingestion is asynchronous on the server; a new message may take time to appear in search. Assistant output is saved only with `save_assistant=True`.
+
+`subject_id` identifies the end user whose memories are recalled. `namespace` separates memory spaces for that user; use the same values for saving and searching. A project API key determines the project scope. Keep it on your server, load it from an environment variable, and never put it in browser code or logs.
+
+## LangGraph
+
+In a graph, call `memory.load_memory_variables({"input": question})` in a recall node before the answer node. Call `memory.save_context({"input": question}, {"output": answer})` in a save node afterward. See [langgraph_chatbot.py](examples/langgraph_chatbot.py) for a complete small graph.
+
+## Local chatbot
+
+Wrap your existing answer function: load `history`, pass it to the function as context, then save the question and answer. See [local_chatbot_flask.py](examples/local_chatbot_flask.py) for a Flask route and [basic_chatbot.py](examples/basic_chatbot.py) for ChatOpenAI. Examples read `MEMORAE_API_KEY`, `MEMORAE_BASE_URL`, and `MEMORAE_SUBJECT_ID` from the environment. The ChatOpenAI examples also need `OPENAI_API_KEY` and their optional dependencies.
+
+`clear()` is a no-op because clearing remote memories is a separate MeMorae review action.

langchain_memorae-0.1.0/langchain_memorae/__init__.py

@@ -0,0 +1,8 @@
+"""MeMorae adapters for LangChain and LangGraph."""
+from .client import MeMoraeClient
+from .memory import MeMoraeMemory
+from .retriever import MeMoraeRetriever
+from .types import IngestResult, MemoryRecord, SearchResult
+
+__all__ = ["MeMoraeClient", "MeMoraeMemory", "MeMoraeRetriever",
+           "IngestResult", "MemoryRecord", "SearchResult"]

langchain_memorae-0.1.0/langchain_memorae/client.py

@@ -0,0 +1,89 @@
+"""HTTP client for the existing MeMorae project-key integration API."""
+from typing import Any
+from uuid import uuid4
+
+import httpx
+
+from .types import IngestResult, MemoryRecord, SearchResult
+
+
+class MeMoraeClient:
+    def __init__(self, api_key: str, base_url: str = "http://localhost:8000",
+                 subject_id: str = "", namespace: str = "default", timeout: float = 30.0):
+        if not api_key or not api_key.strip():
+            raise ValueError("MeMorae project API key is required")
+        if not subject_id:
+            raise ValueError("subject_id is required")
+        if not namespace:
+            raise ValueError("namespace is required")
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.subject_id = subject_id
+        self.namespace = namespace
+        self.timeout = timeout
+
+    def __repr__(self) -> str:
+        return (f"MeMoraeClient(base_url={self.base_url!r}, "
+                f"subject_id={self.subject_id!r}, namespace={self.namespace!r})")
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.post(
+                    f"{self.base_url}{path}", json=payload,
+                    headers={"Authorization": f"Bearer {self._api_key}"},
+                )
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(f"MeMorae API returned HTTP {exc.response.status_code}") from None
+        except httpx.RequestError:
+            raise RuntimeError("MeMorae API request failed") from None
+
+    def ingest_message(self, text: str, role: str = "user", turn_id: str | None = None,
+                       metadata: dict[str, Any] | None = None) -> IngestResult:
+        if role not in {"user", "assistant"}:
+            raise ValueError("role must be 'user' or 'assistant'")
+        if not text:
+            raise ValueError("text is required")
+        # The integration endpoint ingests user messages. The existing source
+        # endpoint accepts other roles and resolves its project from this key.
+        conversation_id = turn_id or str(uuid4())
+        payload = {"subject_id": self.subject_id, "namespace": self.namespace,
+                   "conversation_id": conversation_id, "idempotency_key": str(uuid4()),
+                   "content": text}
+        if role == "user":
+            data = self._post("/v1/integrations/messages", payload)
+        else:
+            scope = self._get_scope()
+            data = self._post("/v1/sources/messages", {
+                **payload, "project_id": scope["project_id"], "role": role,
+            })
+        # The API has no metadata field; it is intentionally not sent.
+        return IngestResult(id=str(data["id"]), status=data["status"], created=data["created"])
+
+    def _get_scope(self) -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                response = client.get(f"{self.base_url}/v1/integrations/scope",
+                                      headers={"Authorization": f"Bearer {self._api_key}"})
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(f"MeMorae API returned HTTP {exc.response.status_code}") from None
+        except httpx.RequestError:
+            raise RuntimeError("MeMorae API request failed") from None
+
+    def search(self, query: str, limit: int = 8) -> SearchResult:
+        if not query:
+            raise ValueError("query is required")
+        data = self._post("/v1/integrations/memories/search", {
+            "subject_id": self.subject_id, "namespace": self.namespace,
+            "query": query, "limit": limit,
+        })
+        memories = [MemoryRecord(id=str(item["id"]), content=item["content"],
+                                 type=item.get("type"), sources=item.get("sources") or [],
+                                 retrieval_explanation=item.get("retrieval_explanation") or {})
+                    for item in data.get("memories", [])]
+        return SearchResult(memories=memories, context=data.get("context"),
+                            memory_state=data.get("memory_state"))

langchain_memorae-0.1.0/langchain_memorae/memory.py

@@ -0,0 +1,51 @@
+"""LangChain memory adapter."""
+from typing import Any
+
+try:
+    from langchain_core.memory import BaseMemory
+except ImportError:
+    from langchain_classic.base_memory import BaseMemory
+from pydantic import PrivateAttr, SecretStr
+
+from .client import MeMoraeClient
+
+
+class MeMoraeMemory(BaseMemory):
+    api_key: SecretStr
+    base_url: str = "http://localhost:8000"
+    subject_id: str
+    namespace: str = "default"
+    timeout: float = 30.0
+    memory_key: str = "history"
+    input_key: str = "input"
+    output_key: str = "output"
+    limit: int = 8
+    save_assistant: bool = False
+    _client: MeMoraeClient = PrivateAttr()
+
+    def model_post_init(self, __context: Any) -> None:
+        self._client = MeMoraeClient(self.api_key.get_secret_value(), self.base_url, self.subject_id,
+                                    self.namespace, self.timeout)
+
+    @property
+    def memory_variables(self) -> list[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+        query = str(inputs.get(self.input_key, "")).strip()
+        if not query:
+            return {self.memory_key: ""}
+        result = self._client.search(query, self.limit)
+        return {self.memory_key: "\n".join(item.content for item in result.memories)}
+
+    def save_context(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> None:
+        user_text = str(inputs.get(self.input_key, "")).strip()
+        if user_text:
+            self._client.ingest_message(user_text)
+        if self.save_assistant:
+            assistant_text = str(outputs.get(self.output_key, "")).strip()
+            if assistant_text:
+                self._client.ingest_message(assistant_text, role="assistant")
+
+    def clear(self) -> None:
+        """No remote deletion: MeMorae memories are managed by its own review API."""

langchain_memorae-0.1.0/langchain_memorae/retriever.py

@@ -0,0 +1,30 @@
+"""LangChain retriever adapter."""
+from typing import Any
+
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import PrivateAttr, SecretStr
+
+from .client import MeMoraeClient
+
+
+class MeMoraeRetriever(BaseRetriever):
+    api_key: SecretStr
+    base_url: str = "http://localhost:8000"
+    subject_id: str
+    namespace: str = "default"
+    timeout: float = 30.0
+    limit: int = 8
+    _client: MeMoraeClient = PrivateAttr()
+
+    def model_post_init(self, __context: Any) -> None:
+        self._client = MeMoraeClient(self.api_key.get_secret_value(), self.base_url, self.subject_id,
+                                    self.namespace, self.timeout)
+
+    def _get_relevant_documents(self, query: str, *, run_manager: Any = None) -> list[Document]:
+        result = self._client.search(query, self.limit)
+        return [Document(page_content=item.content, metadata={
+            "memory_id": item.id, "type": item.type,
+            "source_ids": [str(source["source_id"]) for source in item.sources
+                           if source.get("source_id") is not None],
+        }) for item in result.memories]

langchain_memorae-0.1.0/langchain_memorae/types.py

@@ -0,0 +1,26 @@
+"""Small, framework-independent API result types."""
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class MemoryRecord:
+    id: str
+    content: str
+    type: str | None = None
+    sources: list[dict[str, Any]] = field(default_factory=list)
+    retrieval_explanation: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    memories: list[MemoryRecord]
+    context: str | None = None
+    memory_state: str | None = None
+
+
+@dataclass(frozen=True)
+class IngestResult:
+    id: str
+    status: str
+    created: bool

langchain_memorae-0.1.0/langchain_memorae.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: langchain-memorae
+Version: 0.1.0
+Summary: MeMorae memory and retrieval adapters for LangChain and LangGraph
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: langchain-classic<2,>=1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: examples
+Requires-Dist: langchain-openai>=0.2; extra == "examples"
+Requires-Dist: langgraph>=0.2; extra == "examples"
+Requires-Dist: flask>=3; extra == "examples"
+
+# langchain-memorae
+
+Connect an existing LangChain, LangGraph, or local chatbot to MeMorae's project-key API. MeMorae handles ingestion, approval, and retrieval; this package only calls the existing endpoints. The MeMorae backend must already be running.
+
+MCP exposes MeMorae tools to MCP clients. This package provides Python memory and retriever objects for application code using LangChain or LangGraph.
+
+## Install
+
+From the repository root:
+
+```bash
+pip install -e integrations/langchain-memorae
+```
+
+When published, install with `pip install langchain-memorae`.
+
+## Basic usage
+
+```python
+from langchain_memorae import MeMoraeMemory, MeMoraeRetriever
+
+memory = MeMoraeMemory(api_key="MEMORAE_PROJECT_API_KEY",
+                       base_url="http://localhost:8000",
+                       subject_id="user_123", namespace="default")
+context = memory.load_memory_variables({"input": "What food do I like?"})
+memory.save_context({"input": "I love pizza"}, {"output": "Got it."})
+
+retriever = MeMoraeRetriever(api_key="MEMORAE_PROJECT_API_KEY",
+                             base_url="http://localhost:8000",
+                             subject_id="user_123", namespace="default")
+docs = retriever.invoke("What sports do I enjoy?")
+```
+
+`context["history"]` is a compact string of retrieved memories. `docs` contains LangChain `Document` objects with `memory_id` and `source_ids` metadata. Ingestion is asynchronous on the server; a new message may take time to appear in search. Assistant output is saved only with `save_assistant=True`.
+
+`subject_id` identifies the end user whose memories are recalled. `namespace` separates memory spaces for that user; use the same values for saving and searching. A project API key determines the project scope. Keep it on your server, load it from an environment variable, and never put it in browser code or logs.
+
+## LangGraph
+
+In a graph, call `memory.load_memory_variables({"input": question})` in a recall node before the answer node. Call `memory.save_context({"input": question}, {"output": answer})` in a save node afterward. See [langgraph_chatbot.py](examples/langgraph_chatbot.py) for a complete small graph.
+
+## Local chatbot
+
+Wrap your existing answer function: load `history`, pass it to the function as context, then save the question and answer. See [local_chatbot_flask.py](examples/local_chatbot_flask.py) for a Flask route and [basic_chatbot.py](examples/basic_chatbot.py) for ChatOpenAI. Examples read `MEMORAE_API_KEY`, `MEMORAE_BASE_URL`, and `MEMORAE_SUBJECT_ID` from the environment. The ChatOpenAI examples also need `OPENAI_API_KEY` and their optional dependencies.
+
+`clear()` is a no-op because clearing remote memories is a separate MeMorae review action.

langchain_memorae-0.1.0/langchain_memorae.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+langchain_memorae/__init__.py
+langchain_memorae/client.py
+langchain_memorae/memory.py
+langchain_memorae/retriever.py
+langchain_memorae/types.py
+langchain_memorae.egg-info/PKG-INFO
+langchain_memorae.egg-info/SOURCES.txt
+langchain_memorae.egg-info/dependency_links.txt
+langchain_memorae.egg-info/requires.txt
+langchain_memorae.egg-info/top_level.txt
+tests/test_integration.py

langchain_memorae-0.1.0/langchain_memorae.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_memorae-0.1.0/langchain_memorae.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx<1,>=0.25
+langchain-core<2,>=0.3
+langchain-classic<2,>=1
+
+[examples]
+langchain-openai>=0.2
+langgraph>=0.2
+flask>=3
+
+[test]
+pytest>=8

langchain_memorae-0.1.0/langchain_memorae.egg-info/top_level.txt

@@ -0,0 +1 @@
+langchain_memorae

langchain_memorae-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-memorae"
+version = "0.1.0"
+description = "MeMorae memory and retrieval adapters for LangChain and LangGraph"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.25,<1", "langchain-core>=0.3,<2", "langchain-classic>=1,<2"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+examples = ["langchain-openai>=0.2", "langgraph>=0.2", "flask>=3"]
+
+[tool.setuptools.packages.find]
+include = ["langchain_memorae*"]

langchain_memorae-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langchain_memorae-0.1.0/tests/test_integration.py

@@ -0,0 +1,69 @@
+import httpx
+import pytest
+
+from langchain_memorae import MeMoraeClient, MeMoraeMemory, MeMoraeRetriever
+
+
+def fake_http(monkeypatch, response_data):
+    calls = []
+
+    def handler(request):
+        calls.append(request)
+        return httpx.Response(200 if request.method == "GET" else 202, json=response_data)
+
+    original = httpx.Client
+
+    def client_factory(*args, **kwargs):
+        return original(*args, transport=httpx.MockTransport(handler), **kwargs)
+
+    monkeypatch.setattr(httpx, "Client", client_factory)
+    return calls
+
+
+def test_search_formatting(monkeypatch):
+    calls = fake_http(monkeypatch, {"memory_state": "ready", "context": "likes pizza",
+        "memories": [{"id": "m1", "content": "Likes pizza", "type": "preference",
+                      "sources": [{"source_id": "s1"}]}]})
+    result = MeMoraeClient("memora_secret", subject_id="u1").search("food")
+    assert result.memories[0].content == "Likes pizza"
+    assert result.memories[0].sources[0]["source_id"] == "s1"
+    assert calls[0].url.path == "/v1/integrations/memories/search"
+    assert b'"limit":8' in calls[0].content
+
+
+def test_save_context_ingests_user_only(monkeypatch):
+    calls = fake_http(monkeypatch, {"id": "s1", "status": "pending", "created": True})
+    memory = MeMoraeMemory(api_key="memora_secret", subject_id="u1")
+    memory.save_context({"input": "I love pizza"}, {"output": "Got it"})
+    assert len(calls) == 1
+    assert calls[0].url.path == "/v1/integrations/messages"
+    assert b"I love pizza" in calls[0].content
+    assert b"Got it" not in calls[0].content
+
+
+def test_retriever_documents(monkeypatch):
+    fake_http(monkeypatch, {"memories": [{"id": "m1", "content": "Tennis",
+                                      "sources": [{"source_id": "s1"}]}]})
+    document = MeMoraeRetriever(api_key="memora_secret", subject_id="u1").invoke("sports")[0]
+    assert document.page_content == "Tennis"
+    assert document.metadata["memory_id"] == "m1"
+    assert document.metadata["source_ids"] == ["s1"]
+
+
+def test_missing_key_and_no_leakage(monkeypatch):
+    with pytest.raises(ValueError, match="required"):
+        MeMoraeClient("", subject_id="u1")
+    with pytest.raises(ValueError, match="required"):
+        MeMoraeMemory(api_key="", subject_id="u1")
+    secret = "memora_very_secret"
+    assert secret not in repr(MeMoraeClient(secret, subject_id="u1"))
+    assert secret not in repr(MeMoraeMemory(api_key=secret, subject_id="u1"))
+    assert secret not in repr(MeMoraeRetriever(api_key=secret, subject_id="u1"))
+    # Error construction itself must not expose the Authorization header.
+    def failed(request):
+        return httpx.Response(401, json={"detail": "denied"})
+    original = httpx.Client
+    monkeypatch.setattr(httpx, "Client", lambda *a, **k: original(*a, transport=httpx.MockTransport(failed), **k))
+    with pytest.raises(RuntimeError) as error:
+        MeMoraeClient(secret, subject_id="u1").search("food")
+    assert secret not in str(error.value)