Download lumen_rag/engine.py from WickTech/lumen-rag: direct link, hf CLI and curl.
- Browser
- Download file 6.59 kB
-
https://huggingface.co/spaces/WickTech/lumen-rag/resolve/main/lumen_rag/engine.py
- Command line
-
hf download hf://spaces/WickTech/lumen-rag/lumen_rag/engine.py
-
curl -L -o engine.py https://huggingface.co/spaces/WickTech/lumen-rag/resolve/main/lumen_rag/engine.py
6.59 kB
| """High-level facade tying ingestion, retrieval, and answering together.""" | |
| from __future__ import annotations | |
| import asyncio | |
| from dataclasses import dataclass | |
| from pathlib import Path | |
| from . import tracing | |
| from .config import settings | |
| from .embeddings import get_embedder | |
| from .ingestion import ingest_documents | |
| from .llm import Answer, abstain, answer, answer_async | |
| from .reader import Reading, get_reader | |
| from .retrieval import RetrievalMode, Retriever | |
| from .store import ScoredChunk, Store, VectorStore, get_store | |
| class Retrieval: | |
| chunks: list[ScoredChunk] | |
| # Retrieval confidence; None unless LUMEN_ABSTAIN_THRESHOLD is set. | |
| confidence: float | None | |
| # Below the retrieval or the reader threshold: refuse instead of answering. | |
| abstained: bool | |
| # The reader's verdict; None unless LUMEN_READER is set. | |
| reading: Reading | None = None | |
| def refusal(self) -> Answer: | |
| result = abstain(self.confidence) | |
| result.answerability = self.reading.answerability if self.reading else None | |
| return result | |
| class RagEngine: | |
| def __init__(self, store: Store | None = None) -> None: | |
| self.embedder = get_embedder() | |
| # Explicit None check: an empty store is falsy (``__len__`` == 0), so ``store or ...`` | |
| # would silently replace a freshly created pgvector store with an in-memory one. | |
| self.store = store if store is not None else get_store(self.embedder.dim) | |
| self.retriever = Retriever(self.store, self.embedder) | |
| def add_documents(self, documents: list[dict], **kwargs) -> int: | |
| ingest_documents(documents, store=self.store, embedder=self.embedder, **kwargs) | |
| self.retriever._bm25 = None # invalidate cached BM25 index | |
| return len(self.store) | |
| def retrieve(self, question: str, k: int = 5, mode: RetrievalMode = "hybrid") -> Retrieval: | |
| """Retrieve context and decide whether to abstain. | |
| Two optional gates, cheapest first. ``LUMEN_ABSTAIN_THRESHOLD`` refuses when | |
| the question is not similar enough to anything indexed; ``LUMEN_READER`` reads | |
| the retrieved passages and refuses when none of them contains an answer. | |
| With neither set this is plain retrieval and never abstains. | |
| """ | |
| threshold = settings.abstain_threshold | |
| if threshold is None: | |
| chunks, confidence = self.retriever.retrieve(question, k=k, mode=mode), None | |
| else: | |
| chunks, confidence = self.retriever.retrieve_with_confidence(question, k=k, mode=mode) | |
| if confidence < threshold: | |
| return Retrieval(chunks, confidence, True) | |
| reader = get_reader() | |
| if reader is None or not chunks: | |
| return Retrieval(chunks, confidence, False) | |
| with tracing.span("lumen.read", **{"lumen.reader": reader.model_id}) as span: | |
| reading = reader.read(question, chunks) | |
| tracing.set_attr(span, "lumen.answerability", round(reading.answerability, 3)) | |
| return Retrieval(chunks, confidence, reading.answerability < settings.reader_threshold, reading) | |
| def _answer_reading(r: Retrieval) -> Reading | None: | |
| # The reader always gates; its span shapes the answer only when asked to. | |
| return r.reading if settings.reader_answers else None | |
| def _finish(self, r: Retrieval, result: Answer, span) -> Answer: | |
| result.confidence = r.confidence | |
| if r.reading is not None: | |
| result.answerability = r.reading.answerability | |
| tracing.set_attr(span, "lumen.chunks", len(r.chunks)) | |
| tracing.set_attr(span, "lumen.abstained", r.abstained) | |
| return result | |
| def answer_with_context( | |
| self, question: str, k: int = 5, mode: RetrievalMode = "hybrid" | |
| ) -> tuple[list[ScoredChunk], Answer]: | |
| """``query`` that also returns the retrieved chunks (for evaluation).""" | |
| with tracing.span("lumen.query", **self._query_attrs(question, k, mode)) as span: | |
| r = self.retrieve(question, k=k, mode=mode) | |
| result = r.refusal() if r.abstained else answer(question, r.chunks, reading=self._answer_reading(r)) | |
| return r.chunks, self._finish(r, result, span) | |
| def query(self, question: str, k: int = 5, mode: RetrievalMode = "hybrid") -> Answer: | |
| return self.answer_with_context(question, k=k, mode=mode)[1] | |
| async def aquery(self, question: str, k: int = 5, mode: RetrievalMode = "hybrid") -> Answer: | |
| """``query`` for use inside an event loop. | |
| Retrieval (CPU, or a database / embedding-API round trip) and reading run in a | |
| worker thread; the model call is awaited on the async client. Neither blocks the loop. | |
| """ | |
| with tracing.span("lumen.query", **self._query_attrs(question, k, mode)) as span: | |
| # to_thread copies the context, so retrieval spans stay children of lumen.query. | |
| r = await asyncio.to_thread(self.retrieve, question, k, mode) | |
| result = ( | |
| r.refusal() | |
| if r.abstained | |
| else await answer_async(question, r.chunks, reading=self._answer_reading(r)) | |
| ) | |
| return self._finish(r, result, span) | |
| def _query_attrs(question: str, k: int, mode: str) -> dict: | |
| return { | |
| "lumen.k": k, | |
| "lumen.mode": mode, | |
| "lumen.question.chars": len(question), | |
| "lumen.question.text": tracing.content_attr(question), | |
| } | |
| # --- persistence ------------------------------------------------------- | |
| def save(self, directory: str | Path | None = None) -> None: | |
| self.store.save(directory or settings.index_dir) | |
| def load(cls, directory: str | Path | None = None) -> RagEngine: | |
| if settings.store.lower() != "memory": | |
| # Database-backed stores persist themselves: reconnect instead of reading files. | |
| return cls() | |
| store = VectorStore.load(directory or settings.index_dir) | |
| engine = cls(store=store) | |
| if store.dim != engine.embedder.dim: | |
| if len(store): | |
| raise RuntimeError( | |
| f"The index in {directory or settings.index_dir} has {store.dim}-dim vectors but the " | |
| f"configured embedder ({settings.embedder}) produces {engine.embedder.dim}-dim ones. " | |
| "Re-ingest with this embedder (lumen ingest) or set LUMEN_EMBEDDER to the one used." | |
| ) | |
| engine = cls() # empty saved index: start fresh at the right dim | |
| return engine | |