moca-reader-langchain 0.6.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+moca_reader_langchain/__init__.py,sha256=X14-LUa5FFCfpKWsXy26F5ShWdjhe-uk0vgBog665k4,2722
+moca_reader_langchain/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moca_reader_langchain-0.6.0.dist-info/METADATA,sha256=oPYya2y07f9nsiWDP4yf138C8qBDmqBCv2ybXke0bC4,2781
+moca_reader_langchain-0.6.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+moca_reader_langchain-0.6.0.dist-info/RECORD,,

moca_reader_langchain-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any