attestari-langchain 0.0.1__tar.gz

attestari_langchain-0.0.1/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.python-version
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Data / local
+*.sqlite
+*.db
+eval/data/
+.attestari/
+
+# Internal planning / strategy docs — never publish
+internal/
+
+# Node / TS SDK
+node_modules/
+clients/ts/dist/
+*.tsbuildinfo
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Local agent tooling (launch.json can hold a dev KEK / local env)
+.claude/
+
+# Screen-recording source for docs/deletion-demo.gif — the GIF is committed, the source is not
+deletion-demo.mp4

attestari_langchain-0.0.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: attestari-langchain
+Version: 0.0.1
+Summary: LangChain integration for Attestari — the auditable memory layer for AI agents.
+License: Apache-2.0
+Keywords: agents,ai,attestari,langchain,memory
+Requires-Python: >=3.11
+Requires-Dist: attestari>=0.0.1
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# attestari-langchain
+
+LangChain integration for [Attestari](https://github.com/attestari/attestari) — the
+auditable memory layer for AI agents.
+
+Two pieces, both built on stable `langchain-core` primitives, so instead of
+replaying a raw chat transcript your chain stores **facts with provenance** —
+bi-temporal recall, a tamper-evident audit trail, and a signed deletion
+certificate, on plain Postgres or zero-dependency in memory:
+
+- **`AttestariRetriever`** (`BaseRetriever`) — recall a subject's relevant facts as
+  `Document`s, each carrying provenance in its metadata (fact id, source episode,
+  valid-from, confidence). Supports bi-temporal `as_of` recall. The idiomatic way
+  to inject long-term memory into an LCEL / RAG chain or an agent tool.
+- **`AttestariChatMessageHistory`** (`BaseChatMessageHistory`) — a drop-in history for
+  `RunnableWithMessageHistory`: it *learns facts* from each **human** turn (not a raw
+  transcript, and never from the assistant's own words), surfaces the subject's known facts as a system message, and maps
+  `clear()` to Attestari's provable deletion (`forget`).
+
+## Install
+
+```bash
+pip install attestari-langchain        # pulls in attestari + langchain-core
+```
+
+## Use — inject memory into a chain (AttestariRetriever)
+
+```python
+from attestari import Memory
+from attestari_langchain import AttestariRetriever
+
+mem = Memory()                       # or Memory.local() / Memory.postgres()
+mem.add("Hi, I'm Alice. I live in Toronto.", subject_id="user_42")
+
+retriever = AttestariRetriever(
+    mem=mem,                         # the Attestari engine
+    subject_id="user_42",            # an opaque pseudonym, not raw PII
+    k=5,                             # facts to recall
+    # as_of="2022-01-01",            # optional: recall what was true then
+)
+
+docs = retriever.invoke("where does the user live?")
+# -> [Document("user_42 lives in Toronto", metadata={fact_id, source_episode_id, score, ...})]
+```
+
+> The zero-dependency default extractor understands **first-person** statements
+> ("I live in…", "my name is…"). For arbitrary third-person text, install
+> `attestari[anthropic]` and set `ANTHROPIC_API_KEY` for Claude-powered extraction.
+
+Drop `retriever` into any LCEL chain the way you would any other retriever; each
+returned `Document` carries provenance in `.metadata` you can show or audit.
+
+## Use — conversational memory (AttestariChatMessageHistory)
+
+```python
+from attestari import Memory
+from attestari_langchain import AttestariChatMessageHistory
+from langchain_core.messages import HumanMessage
+
+history = AttestariChatMessageHistory(mem=Memory(), subject_id="user_42")
+history.add_messages([HumanMessage("Hi, I'm Alice and I live in Toronto.")])
+history.messages          # -> [SystemMessage("Known facts about the user:\n- user lives_in Toronto")]
+history.clear()           # provable deletion (forget) for this subject
+```
+
+Wire it into `RunnableWithMessageHistory` as the `get_session_history` factory:
+
+```python
+from langchain_core.runnables.history import RunnableWithMessageHistory
+
+chain_with_memory = RunnableWithMessageHistory(
+    chain,
+    lambda session_id: AttestariChatMessageHistory(mem=Memory.local(), subject_id=session_id),
+    input_messages_key="input",
+    history_messages_key="history",
+)
+```
+
+## Constructor reference
+
+**`AttestariRetriever`**
+
+| Field | Default | Purpose |
+|---|---|---|
+| `mem` | — | The Attestari engine: `Memory()`, `Memory.local()`, or `Memory.postgres()`. |
+| `subject_id` | `None` | Scope recall to one subject (opaque pseudonym). |
+| `k` | `5` | How many facts to recall. |
+| `as_of` | `None` | Bi-temporal instant — recall what was true `as_of` this ISO date. |
+
+**`AttestariChatMessageHistory(mem, subject_id)`** — `add_messages(msgs)` ingests each
+human turn (assistant messages are conversation, not testimony — they are not
+attributed to the user as facts), `messages` returns the subject's live facts as one system message, and
+`clear()` maps to provable deletion.
+
+A runnable, no-LLM example is in [`example.py`](example.py):
+`python clients/langchain/example.py`.
+
+Apache-2.0.

attestari_langchain-0.0.1/README.md

@@ -0,0 +1,98 @@
+# attestari-langchain
+
+LangChain integration for [Attestari](https://github.com/attestari/attestari) — the
+auditable memory layer for AI agents.
+
+Two pieces, both built on stable `langchain-core` primitives, so instead of
+replaying a raw chat transcript your chain stores **facts with provenance** —
+bi-temporal recall, a tamper-evident audit trail, and a signed deletion
+certificate, on plain Postgres or zero-dependency in memory:
+
+- **`AttestariRetriever`** (`BaseRetriever`) — recall a subject's relevant facts as
+  `Document`s, each carrying provenance in its metadata (fact id, source episode,
+  valid-from, confidence). Supports bi-temporal `as_of` recall. The idiomatic way
+  to inject long-term memory into an LCEL / RAG chain or an agent tool.
+- **`AttestariChatMessageHistory`** (`BaseChatMessageHistory`) — a drop-in history for
+  `RunnableWithMessageHistory`: it *learns facts* from each **human** turn (not a raw
+  transcript, and never from the assistant's own words), surfaces the subject's known facts as a system message, and maps
+  `clear()` to Attestari's provable deletion (`forget`).
+
+## Install
+
+```bash
+pip install attestari-langchain        # pulls in attestari + langchain-core
+```
+
+## Use — inject memory into a chain (AttestariRetriever)
+
+```python
+from attestari import Memory
+from attestari_langchain import AttestariRetriever
+
+mem = Memory()                       # or Memory.local() / Memory.postgres()
+mem.add("Hi, I'm Alice. I live in Toronto.", subject_id="user_42")
+
+retriever = AttestariRetriever(
+    mem=mem,                         # the Attestari engine
+    subject_id="user_42",            # an opaque pseudonym, not raw PII
+    k=5,                             # facts to recall
+    # as_of="2022-01-01",            # optional: recall what was true then
+)
+
+docs = retriever.invoke("where does the user live?")
+# -> [Document("user_42 lives in Toronto", metadata={fact_id, source_episode_id, score, ...})]
+```
+
+> The zero-dependency default extractor understands **first-person** statements
+> ("I live in…", "my name is…"). For arbitrary third-person text, install
+> `attestari[anthropic]` and set `ANTHROPIC_API_KEY` for Claude-powered extraction.
+
+Drop `retriever` into any LCEL chain the way you would any other retriever; each
+returned `Document` carries provenance in `.metadata` you can show or audit.
+
+## Use — conversational memory (AttestariChatMessageHistory)
+
+```python
+from attestari import Memory
+from attestari_langchain import AttestariChatMessageHistory
+from langchain_core.messages import HumanMessage
+
+history = AttestariChatMessageHistory(mem=Memory(), subject_id="user_42")
+history.add_messages([HumanMessage("Hi, I'm Alice and I live in Toronto.")])
+history.messages          # -> [SystemMessage("Known facts about the user:\n- user lives_in Toronto")]
+history.clear()           # provable deletion (forget) for this subject
+```
+
+Wire it into `RunnableWithMessageHistory` as the `get_session_history` factory:
+
+```python
+from langchain_core.runnables.history import RunnableWithMessageHistory
+
+chain_with_memory = RunnableWithMessageHistory(
+    chain,
+    lambda session_id: AttestariChatMessageHistory(mem=Memory.local(), subject_id=session_id),
+    input_messages_key="input",
+    history_messages_key="history",
+)
+```
+
+## Constructor reference
+
+**`AttestariRetriever`**
+
+| Field | Default | Purpose |
+|---|---|---|
+| `mem` | — | The Attestari engine: `Memory()`, `Memory.local()`, or `Memory.postgres()`. |
+| `subject_id` | `None` | Scope recall to one subject (opaque pseudonym). |
+| `k` | `5` | How many facts to recall. |
+| `as_of` | `None` | Bi-temporal instant — recall what was true `as_of` this ISO date. |
+
+**`AttestariChatMessageHistory(mem, subject_id)`** — `add_messages(msgs)` ingests each
+human turn (assistant messages are conversation, not testimony — they are not
+attributed to the user as facts), `messages` returns the subject's live facts as one system message, and
+`clear()` maps to provable deletion.
+
+A runnable, no-LLM example is in [`example.py`](example.py):
+`python clients/langchain/example.py`.
+
+Apache-2.0.

attestari_langchain-0.0.1/example.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""AttestariRetriever + AttestariChatMessageHistory — no LLM or API key needed.
+
+    pip install langchain-core
+    python clients/langchain/example.py
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+# Make `attestari` and `attestari_langchain` importable without installing.
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "src"))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / "src"))
+
+from attestari import Memory  # noqa: E402
+from attestari_langchain import AttestariChatMessageHistory, AttestariRetriever  # noqa: E402
+
+
+def main() -> int:
+    mem = Memory()
+    history = AttestariChatMessageHistory(mem, subject_id="user_42")
+
+    # What RunnableWithMessageHistory would feed in as the conversation happens:
+    from langchain_core.messages import AIMessage, HumanMessage
+
+    history.add_messages([HumanMessage("Hi, I'm Alice and I live in Toronto.")])
+    history.add_messages([AIMessage("Nice to meet you, Alice!")])
+    history.add_messages([HumanMessage("I moved to Berlin.")])
+
+    print("Memory injected into the prompt (history.messages):")
+    print("  " + history.messages[0].content.replace("\n", "\n  "))
+
+    # The retriever is how you inject relevant facts into a RAG/agent chain —
+    # each Document carries provenance you can show or audit.
+    retriever = AttestariRetriever(mem=mem, subject_id="user_42", k=3)
+    docs = retriever.invoke("where does the user live?")
+    print("\nAttestariRetriever results (with provenance):")
+    for d in docs:
+        print(f"  - {d.page_content!r}  [fact_id={d.metadata['fact_id'][:8]}…, "
+              f"score={d.metadata['score']:.2f}]")
+
+    # The differentiator: provable deletion via clear().
+    history.clear()
+    after = retriever.invoke("where does the user live?")
+
+    assert any("Berlin" in d.page_content for d in docs), "expected Berlin to supersede Toronto"
+    assert after == [], "expected nothing recalled after clear()"
+    print("\n✅ Recall, supersession (Berlin > Toronto), and provable deletion all hold.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

attestari_langchain-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "attestari-langchain"
+version = "0.0.1"
+description = "LangChain integration for Attestari — the auditable memory layer for AI agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+keywords = ["ai", "agents", "memory", "attestari", "langchain"]
+dependencies = [
+  "attestari>=0.0.1",
+  "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/attestari_langchain"]

attestari_langchain-0.0.1/src/attestari_langchain/__init__.py

@@ -0,0 +1,125 @@
+"""LangChain integration for Attestari — the auditable memory layer for AI agents.
+
+Two pieces, both built on the stable `langchain-core` primitives:
+
+- **`AttestariRetriever`** (`BaseRetriever`) — recall a subject's relevant facts and
+  hand them to a chain/agent as `Document`s, each carrying **provenance** in its
+  metadata (fact id, source episode, valid-from, confidence). Supports bi-temporal
+  `as_of` retrieval. This is the idiomatic way to inject long-term memory into a
+  modern LCEL / RAG chain or an agent tool.
+- **`AttestariChatMessageHistory`** (`BaseChatMessageHistory`) — a drop-in history for
+  `RunnableWithMessageHistory`: it *learns facts* from each turn (not a raw
+  transcript), surfaces the subject's known facts as context, and maps `clear()`
+  to Attestari's provable deletion (`forget`).
+
+    from attestari import Memory
+    from attestari_langchain import AttestariRetriever
+
+    mem = Memory()                       # or Memory.postgres() for durable storage
+    mem.add("Alice lives in Toronto.", subject_id="user_42")
+    retriever = AttestariRetriever(mem=mem, subject_id="user_42")
+    retriever.invoke("where does the user live?")   # -> [Document("user lives_in Toronto", ...)]
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from attestari import Memory
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.documents import Document
+from langchain_core.messages import BaseMessage, SystemMessage
+from langchain_core.retrievers import BaseRetriever
+from pydantic import ConfigDict
+
+__all__ = ["AttestariRetriever", "AttestariChatMessageHistory"]
+__version__ = "0.0.1"
+
+
+def _triple(edge: Any) -> str:
+    return f"{edge.subject} {edge.predicate.replace('_', ' ')} {edge.object}"
+
+
+class AttestariRetriever(BaseRetriever):
+    """Retrieve a subject's relevant facts as provenance-carrying `Document`s."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    mem: Memory
+    """The Attestari engine — `Memory()` (in-memory) or `Memory.postgres()` (durable)."""
+    subject_id: str | None = None
+    """Scope retrieval to one subject. Use an opaque pseudonym, not raw PII."""
+    k: int = 5
+    """How many facts to recall."""
+    as_of: str | None = None
+    """Optional bi-temporal instant — recall what was true `as_of` this date."""
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        results = self.mem.search(
+            query, subject_id=self.subject_id, as_of=self.as_of, limit=self.k
+        )
+        docs: list[Document] = []
+        for r in results:
+            e = r.edge
+            docs.append(
+                Document(
+                    page_content=_triple(e),
+                    metadata={
+                        "fact_id": e.fact_id,
+                        "subject": e.subject,
+                        "predicate": e.predicate,
+                        "object": e.object,
+                        "valid_from": e.valid_from.isoformat() if e.valid_from else None,
+                        "source_episode_id": e.source_episode_id,
+                        "confidence": e.confidence,
+                        "score": r.score,
+                    },
+                )
+            )
+        return docs
+
+
+class AttestariChatMessageHistory(BaseChatMessageHistory):
+    """A `BaseChatMessageHistory` that learns facts instead of storing a transcript.
+
+    Drop into `RunnableWithMessageHistory`. `add_messages` ingests each turn into
+    Attestari; `messages` returns the subject's current facts as a single system
+    message; `clear` performs provable deletion.
+    """
+
+    def __init__(self, mem: Memory, subject_id: str):
+        self.mem = mem
+        self.subject_id = subject_id
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        live = [
+            e
+            for e in self.mem.timeline(subject_id=self.subject_id)
+            if e.valid_to is None
+        ]
+        if not live:
+            return []
+        facts = "\n".join(f"- {_triple(e)}" for e in live)
+        return [SystemMessage(content=f"Known facts about the user:\n{facts}")]
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        # Only HUMAN turns become memories. Extractors attribute first-person
+        # statements ("I", "my") to the subject — ingesting an AIMessage would
+        # mint facts about the *user* out of the assistant's own words (e.g.
+        # "I'd say Berlin is lovely" -> lives_in Berlin). The assistant's turns
+        # are conversation, not testimony.
+        for m in messages:
+            if m.type != "human":
+                continue
+            content = m.content if isinstance(m.content, str) else str(m.content)
+            if content.strip():
+                self.mem.add(content, subject_id=self.subject_id)
+
+    def clear(self) -> None:
+        """Provable deletion: forget everything for this subject."""
+        self.mem.forget(self.subject_id)

attestari_langchain-0.0.1/tests/test_attestari_memory.py

@@ -0,0 +1,104 @@
+"""Tests for the Attestari LangChain integration (retriever + chat history)."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+import pytest
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(ROOT / "src"))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "src"))
+
+pytest.importorskip("langchain_core", reason="needs langchain-core")
+
+from langchain_core.messages import AIMessage, HumanMessage  # noqa: E402
+
+from attestari import Memory  # noqa: E402
+from attestari_langchain import AttestariChatMessageHistory, AttestariRetriever  # noqa: E402
+
+
+# -- AttestariRetriever ----------------------------------------------------- #
+
+def test_retriever_recalls_with_provenance():
+    mem = Memory()
+    mem.add("I live in Toronto and I work at Acme.", subject_id="alice")
+    docs = AttestariRetriever(mem=mem, subject_id="alice").invoke("where does the user live?")
+    assert any("Toronto" in d.page_content for d in docs)
+    d = docs[0]
+    assert d.metadata["fact_id"] and d.metadata["source_episode_id"]
+    assert "score" in d.metadata
+
+
+def test_retriever_supersession():
+    mem = Memory()
+    mem.add("I live in Toronto.", subject_id="alice")
+    mem.add("I moved to Berlin.", subject_id="alice")
+    docs = AttestariRetriever(mem=mem, subject_id="alice").invoke("where does the user live?")
+    blob = " ".join(d.page_content for d in docs)
+    assert "Berlin" in blob and "Toronto" not in blob
+
+
+def test_retriever_time_travel_as_of():
+    mem = Memory()
+    mem.add("I live in Toronto.", subject_id="alice", valid_from="2021-01-01")
+    mem.add("I moved to Berlin.", subject_id="alice", valid_from="2026-01-01")
+    docs = AttestariRetriever(mem=mem, subject_id="alice", as_of="2022-01-01").invoke(
+        "where does the user live?"
+    )
+    assert any("Toronto" in d.page_content for d in docs)
+
+
+def test_retriever_respects_k():
+    mem = Memory()
+    mem.add("I live in Toronto. I work at Acme. My name is Alice.", subject_id="alice")
+    docs = AttestariRetriever(mem=mem, subject_id="alice", k=1).invoke("tell me about the user")
+    assert len(docs) <= 1
+
+
+# -- AttestariChatMessageHistory -------------------------------------------- #
+
+def test_history_learns_and_surfaces_facts():
+    mem = Memory()
+    h = AttestariChatMessageHistory(mem, subject_id="alice")
+    h.add_messages([HumanMessage("I live in Toronto.")])
+    h.add_messages([AIMessage("Noted.")])
+    msgs = h.messages
+    assert len(msgs) == 1 and "Toronto" in msgs[0].content
+
+
+def test_history_empty_when_no_facts():
+    h = AttestariChatMessageHistory(Memory(), subject_id="nobody")
+    assert h.messages == []
+
+
+def test_history_clear_is_provable_deletion():
+    mem = Memory()
+    h = AttestariChatMessageHistory(mem, subject_id="alice")
+    h.add_messages([HumanMessage("I live in Toronto.")])
+    h.clear()
+    assert h.messages == []
+    assert AttestariRetriever(mem=mem, subject_id="alice").invoke("where?") == []
+
+
+def test_subject_isolation():
+    mem = Memory()
+    AttestariChatMessageHistory(mem, "alice").add_messages([HumanMessage("I live in Toronto.")])
+    AttestariChatMessageHistory(mem, "bob").add_messages([HumanMessage("I live in Berlin.")])
+    bob_docs = AttestariRetriever(mem=mem, subject_id="bob").invoke("where does the user live?")
+    blob = " ".join(d.page_content for d in bob_docs)
+    assert "Berlin" in blob and "Toronto" not in blob
+
+
+def test_history_does_not_learn_from_ai_messages():
+    """Assistant turns are conversation, not testimony: a first-person pattern
+    in an AIMessage must not mint a fact attributed to the user."""
+    mem = Memory()
+    h = AttestariChatMessageHistory(mem, subject_id="alice")
+    h.add_messages([AIMessage("I moved to Berlin and I work at Globex.")])
+    assert h.messages == []                      # nothing was learned
+    assert mem.timeline(subject_id="alice") == []
+    h.add_messages([HumanMessage("I live in Toronto.")])
+    blob = " ".join(m.content for m in h.messages)
+    assert "Toronto" in blob and "Berlin" not in blob