lumen-rag / lumen_rag /engine.py
WickTech's picture
Deploy from push.sh
710fe08 verified
Raw History Blame Contribute Delete
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
@dataclass
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)
@staticmethod
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)
@staticmethod
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)
@classmethod
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