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

moca_reader_llamaindex/__init__.py

@@ -0,0 +1,77 @@
+"""A LlamaIndex 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 ``NodeWithScore``: a ``TextNode`` with the text, the
+whole record under ``metadata["moca_citation"]`` and the consuming guide's flat ``moca_*`` fields beside it, and
+the record's score. The MOCA keys are excluded from the text LlamaIndex sends to a model or an embedder.
+
+Package text is untrusted input to a model: pass it to a model as quoted reference material to cite, never as
+instructions (Reader contract §12).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from llama_index.core.callbacks import CallbackManager
+from llama_index.core.retrievers import BaseRetriever
+from llama_index.core.schema import NodeWithScore, QueryBundle, TextNode
+
+from moca_reader import CitationRecord, Search, flat_metadata
+
+__all__ = ["MocaRetriever", "node_id", "to_node"]
+__version__ = "0.6.0"
+
+
+def node_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_node(record: CitationRecord) -> NodeWithScore:
+    """A citation record as a LlamaIndex ``NodeWithScore``."""
+    metadata: dict[str, Any] = {"moca_citation": record, **flat_metadata(record)}
+    keys = list(metadata)
+    node = TextNode(
+        id_=node_id(record),
+        text=record.get("text") or "",
+        metadata=metadata,
+        excluded_llm_metadata_keys=keys,
+        excluded_embed_metadata_keys=keys,
+    )
+    score = record.get("score")
+    return NodeWithScore(node=node, score=float(score) if isinstance(score, (int, float)) else None)
+
+
+class MocaRetriever(BaseRetriever):
+    """Retrieves citation records from MOCA packages as LlamaIndex ``NodeWithScore``s.
+
+    ``search`` is the host's ``moca_reader.Search``; the other arguments are the search options for every call.
+    """
+
+    def __init__(
+        self,
+        search: Search,
+        *,
+        limit: int = 5,
+        locale: str | None = None,
+        concepts: list[str] | None = None,
+        scope: str | None = None,
+        include_all: bool = False,
+        callback_manager: CallbackManager | None = None,
+    ) -> None:
+        super().__init__(callback_manager=callback_manager)
+        self._search = search
+        self._options: dict[str, Any] = {
+            "limit": limit,
+            "include_all": include_all,
+            "locale": locale,
+            "concepts": concepts,
+            "scope": scope,
+        }
+
+    def _retrieve(self, query_bundle: QueryBundle) -> list[NodeWithScore]:
+        return [to_node(r) for r in self._search.search(query_bundle.query_str, **self._options)]

moca_reader_llamaindex-0.6.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: moca-reader-llamaindex
+Version: 0.6.0
+Summary: A LlamaIndex retriever over MOCA packages: citation records as scored nodes, 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,llama-index,llamaindex,moca,rag,retriever
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: llama-index-core>=0.14
+Requires-Dist: moca-reader==0.6.0
+Description-Content-Type: text/markdown
+
+# moca-reader-llamaindex
+
+A [LlamaIndex](https://www.llamaindex.ai) retriever over MOCA packages, built
+on the [MOCA Reader for Python](https://github.com/openmoca/moca-reader-python).
+
+```sh
+pip install moca-reader-llamaindex
+```
+
+```python
+from moca_reader import LexicalBackend, Library, Search, read_package
+from moca_reader_llamaindex 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, limit=3)
+for result in retriever.retrieve("How long is the refund window?"):
+    print(result.node.metadata["moca_node_ref"], result.score)
+    print(result.node.get_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. Use it anywhere LlamaIndex takes a retriever, such as a
+`RetrieverQueryEngine`.
+
+Each result is a `NodeWithScore` holding a `TextNode`:
+
+| Field | Holds |
+| --- | --- |
+| `text` | The text of the node, or of a sidecar chunk |
+| `node_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`, ...) |
+| `score` | The search score |
+
+The MOCA metadata keys are excluded from the text LlamaIndex sends to a model
+or an embedder, so they travel with the node without filling the prompt.
+
+**Package text is untrusted input.** Present it to a model 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.
+
+## Licence
+
+Apache-2.0.

moca_reader_llamaindex-0.6.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+moca_reader_llamaindex/__init__.py,sha256=eDjRlNdRQEBlFIMh5AP_No5wuQl6XDkUU9PNm5mtF58,3068
+moca_reader_llamaindex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+moca_reader_llamaindex-0.6.0.dist-info/METADATA,sha256=J2jJkfB7Gt8i7lSJWCHu1gss0ZtudCvuV96hLfKRy7I,2835
+moca_reader_llamaindex-0.6.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+moca_reader_llamaindex-0.6.0.dist-info/RECORD,,

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