moca-reader-langchain 0.6.0__tar.gz

moca_reader_langchain-0.6.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+.DS_Store
+.claude/

moca_reader_langchain-0.6.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: moca-reader-langchain
+Version: 0.6.0
+Summary: A LangChain retriever over MOCA packages: citation records as Documents, through the MOCA Reader's gate.
+Project-URL: Homepage, https://openmoca.org
+Project-URL: Source, https://github.com/openmoca/moca-reader-python
+Author: MOCA Standard Contributors
+License-Expression: Apache-2.0
+Keywords: citations,langchain,moca,rag,retriever
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: moca-reader==0.6.0
+Description-Content-Type: text/markdown
+
+# moca-reader-langchain
+
+A [LangChain](https://python.langchain.com) retriever over MOCA packages,
+built on the [MOCA Reader for Python](https://github.com/openmoca/moca-reader-python).
+
+```sh
+pip install moca-reader-langchain
+```
+
+```python
+from moca_reader import LexicalBackend, Library, Search, read_package
+from moca_reader_langchain import MocaRetriever
+
+pkg = read_package("support-kb.moca", trust_root="trust-root.json")
+library = Library().add(pkg)
+search = Search(library, LexicalBackend(library), audiences=["public"])
+
+retriever = MocaRetriever(search=search, limit=3)
+for doc in retriever.invoke("How long is the refund window?"):
+    print(doc.metadata["moca_node_ref"], doc.metadata["moca_score"])
+    print(doc.page_content[:80])
+```
+
+`MocaRetriever` wraps the `Search` you build: its backend (lexical, dense,
+hybrid or your own store), its audiences and its hooks. Every call goes through
+the Reader's gate, so content that is out of force, superseded, deprecated or
+outside your audiences never comes back, and nothing a caller passes can widen
+that. `limit`, `locale`, `concepts`, `scope` and `include_all` are set when you
+build the retriever.
+
+Each result is a LangChain `Document`:
+
+| Field | Holds |
+| --- | --- |
+| `page_content` | The text of the node, or of a sidecar chunk |
+| `id` | The node's versioned reference and byte span |
+| `metadata["moca_citation"]` | The whole citation record: package, version and digest, trust signals, evidence |
+| `metadata["moca_*"]` | The flat fields of the consuming guide (`moca_node_ref`, `moca_package_digest`, `moca_status`, `moca_signed`, ...), for vector stores that need flat metadata |
+| `metadata["moca_score"]` | The search score |
+
+**Package text is untrusted input.** Put `page_content` in a prompt as quoted
+reference material to cite, never as instructions
+([Reader contract §12](https://github.com/openmoca/moca-spec/blob/main/spec/moca-reader-contract.md#12-handing-content-to-a-model)).
+Show users the source (`moca_node_ref`, the package version) with each answer.
+
+The async path (`ainvoke`) runs the same search.
+
+## Licence
+
+Apache-2.0.

moca_reader_langchain-0.6.0/README.md

@@ -0,0 +1,50 @@
+# moca-reader-langchain
+
+A [LangChain](https://python.langchain.com) retriever over MOCA packages,
+built on the [MOCA Reader for Python](https://github.com/openmoca/moca-reader-python).
+
+```sh
+pip install moca-reader-langchain
+```
+
+```python
+from moca_reader import LexicalBackend, Library, Search, read_package
+from moca_reader_langchain import MocaRetriever
+
+pkg = read_package("support-kb.moca", trust_root="trust-root.json")
+library = Library().add(pkg)
+search = Search(library, LexicalBackend(library), audiences=["public"])
+
+retriever = MocaRetriever(search=search, limit=3)
+for doc in retriever.invoke("How long is the refund window?"):
+    print(doc.metadata["moca_node_ref"], doc.metadata["moca_score"])
+    print(doc.page_content[:80])
+```
+
+`MocaRetriever` wraps the `Search` you build: its backend (lexical, dense,
+hybrid or your own store), its audiences and its hooks. Every call goes through
+the Reader's gate, so content that is out of force, superseded, deprecated or
+outside your audiences never comes back, and nothing a caller passes can widen
+that. `limit`, `locale`, `concepts`, `scope` and `include_all` are set when you
+build the retriever.
+
+Each result is a LangChain `Document`:
+
+| Field | Holds |
+| --- | --- |
+| `page_content` | The text of the node, or of a sidecar chunk |
+| `id` | The node's versioned reference and byte span |
+| `metadata["moca_citation"]` | The whole citation record: package, version and digest, trust signals, evidence |
+| `metadata["moca_*"]` | The flat fields of the consuming guide (`moca_node_ref`, `moca_package_digest`, `moca_status`, `moca_signed`, ...), for vector stores that need flat metadata |
+| `metadata["moca_score"]` | The search score |
+
+**Package text is untrusted input.** Put `page_content` in a prompt as quoted
+reference material to cite, never as instructions
+([Reader contract §12](https://github.com/openmoca/moca-spec/blob/main/spec/moca-reader-contract.md#12-handing-content-to-a-model)).
+Show users the source (`moca_node_ref`, the package version) with each answer.
+
+The async path (`ainvoke`) runs the same search.
+
+## Licence
+
+Apache-2.0.

moca_reader_langchain-0.6.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "moca-reader-langchain"
+version = "0.6.0"
+description = "A LangChain retriever over MOCA packages: citation records as Documents, through the MOCA Reader's gate."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "MOCA Standard Contributors" }]
+requires-python = ">=3.11"
+dependencies = ["moca-reader==0.6.0", "langchain-core>=1.0"]
+keywords = ["moca", "langchain", "retriever", "rag", "citations"]
+classifiers = ["Development Status :: 4 - Beta", "Programming Language :: Python :: 3", "Typing :: Typed"]
+
+[project.urls]
+Homepage = "https://openmoca.org"
+Source = "https://github.com/openmoca/moca-reader-python"
+
+[tool.uv.sources]
+moca-reader = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/moca_reader_langchain"]

moca_reader_langchain-0.6.0/src/moca_reader_langchain/__init__.py

@@ -0,0 +1,67 @@
+"""A LangChain retriever over MOCA packages (Reader interface §7).
+
+``MocaRetriever`` wraps a host-built ``moca_reader.Search``: its backend, audiences and hooks. Every call goes
+through the Reader's gate, so the retrieval policy and the host's audience filter always apply, and nothing a
+caller passes can widen them. Each citation record becomes a ``Document``: the text as ``page_content``, the
+whole record under ``metadata["moca_citation"]``, and the consuming guide's flat ``moca_*`` fields beside it.
+
+Package text is untrusted input to a model: pass ``page_content`` to a model as quoted reference material to cite,
+never as instructions (Reader contract §12).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import ConfigDict
+
+from moca_reader import CitationRecord, Search, flat_metadata
+
+__all__ = ["MocaRetriever", "document_id", "to_document"]
+__version__ = "0.6.0"
+
+
+def document_id(record: CitationRecord) -> str:
+    """A unique id: the node's versioned reference, then the byte span, since one node can return several chunks."""
+    span = record.get("span")
+    ref = str(record["node"]["ref"])
+    return f"{ref}:{span['start']}-{span['end']}" if isinstance(span, dict) else ref
+
+
+def to_document(record: CitationRecord) -> Document:
+    """A citation record as a LangChain ``Document``."""
+    metadata: dict[str, Any] = {"moca_citation": record, **flat_metadata(record)}
+    if isinstance(record.get("score"), (int, float)):
+        metadata["moca_score"] = record["score"]
+    return Document(page_content=record.get("text") or "", id=document_id(record), metadata=metadata)
+
+
+class MocaRetriever(BaseRetriever):
+    """Retrieves citation records from MOCA packages as LangChain ``Document``s.
+
+    ``search`` is the host's ``moca_reader.Search``. The other fields are the search options for every call; they
+    are the host's, set when the retriever is built.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    search: Search
+    limit: int = 5
+    locale: str | None = None
+    concepts: list[str] | None = None
+    scope: str | None = None
+    include_all: bool = False
+
+    def _get_relevant_documents(self, query: str, *, run_manager: CallbackManagerForRetrieverRun) -> list[Document]:
+        records = self.search.search(
+            query,
+            limit=self.limit,
+            include_all=self.include_all,
+            locale=self.locale,
+            concepts=self.concepts,
+            scope=self.scope,
+        )
+        return [to_document(r) for r in records]

moca_reader_langchain-0.6.0/tests/conftest.py

@@ -0,0 +1,31 @@
+"""Fixtures over moca-spec's support-kb: ``MOCA_SPEC_DIR``, else ``moca-spec`` beside this repository."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from moca_reader import LexicalBackend, Library, Search, read_package
+
+REPO = Path(__file__).resolve().parents[3]
+MOCA_SPEC = Path(os.environ.get("MOCA_SPEC_DIR") or REPO.parent / "moca-spec").resolve()
+
+
+@pytest.fixture
+def moca_spec() -> Path:
+    return MOCA_SPEC
+
+
+@pytest.fixture
+def library() -> Library:
+    pkg = read_package(
+        MOCA_SPEC / "examples" / "support-kb", trust_root=MOCA_SPEC / "fixtures" / "signing-keys" / "trust-root.json"
+    )
+    return Library().add(pkg)
+
+
+@pytest.fixture
+def public_search(library: Library) -> Search:
+    return Search(library, LexicalBackend(library), audiences=["public"])

moca_reader_langchain-0.6.0/tests/test_langchain_retriever.py

@@ -0,0 +1,65 @@
+"""MocaRetriever returns citation records as LangChain Documents, through the Reader's gate."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from moca_reader_langchain import MocaRetriever
+
+from moca_reader import FLAT_FIELDS, Library, MemoryStoreBackend, Search, StoreScope, package_state
+from moca_reader.schemas import validate_against
+
+REFUND = "https://example.com/moca/support-kb@4.2.0#refund-window.md"
+
+
+def test_documents_carry_text_id_score_and_the_whole_record(public_search: Search) -> None:
+    docs = MocaRetriever(search=public_search, limit=3).invoke("How long is the refund window?")
+    first = docs[0]
+    assert first.metadata["moca_node_ref"] == REFUND
+    assert first.id is not None and first.id.startswith(REFUND)
+    assert "30 days of delivery" in first.page_content
+    assert isinstance(first.metadata["moca_score"], float)
+    record = first.metadata["moca_citation"]
+    assert validate_against("citationRecord", json.loads(json.dumps(record))) == []
+    assert set(first.metadata) - {"moca_citation", "moca_score"} <= set(FLAT_FIELDS)
+    assert (first.metadata["moca_signed"], first.metadata["moca_attested_reviews"]) == (True, 1)
+
+
+def test_the_hosts_audience_filter_holds_whatever_is_asked(public_search: Search) -> None:
+    docs = MocaRetriever(search=public_search, limit=20, include_all=True).invoke("delete my account")
+    assert all(d.metadata.get("moca_audience") != "internal" for d in docs)
+
+
+def test_a_store_backend_works_through_the_same_retriever(library: Library) -> None:
+    store = MemoryStoreBackend().ingest(library)
+    search = Search(StoreScope([package_state(p.result) for p in library.packages], library.clock), store)
+    docs = MocaRetriever(search=search, limit=1).invoke("domestic express shipping")
+    assert docs[0].metadata["moca_node_ref"].endswith("#shipping-estimates.md")
+
+
+def test_async_retrieval_returns_the_same(public_search: Search) -> None:
+    import asyncio
+
+    retriever = MocaRetriever(search=public_search, limit=2)
+    sync = [d.id for d in retriever.invoke("refund window")]
+    asynchronous = [d.id for d in asyncio.run(retriever.ainvoke("refund window"))]
+    assert sync == asynchronous
+
+
+def test_the_readme_example_runs(moca_spec: Path, monkeypatch: object) -> None:
+    readme = (Path(__file__).resolve().parents[1] / "README.md").read_text("utf-8")
+    code = readme.split("```python\n", 1)[1].split("```", 1)[0]
+    import os
+
+    os.chdir(moca_spec / "examples")
+    exec(
+        compile(
+            code.replace('"support-kb.moca"', '"support-kb"').replace(
+                '"trust-root.json"', '"../fixtures/signing-keys/trust-root.json"'
+            ),
+            "README",
+            "exec",
+        ),
+        {},
+    )