"""Search service for the documents assistant (FastAPI, e.g. on a Hugging Face Space). GET /health public: readiness and index size POST /search {query, k} → {results: [passage…]} (hybrid BM25 + embeddings) POST /index {upsert: [doc…], delete: [id…]} (pushed by the app on publish) POST /refresh re-read the app's full export now Every POST requires `Authorization: Bearer $RAG_SECRET` (the same secret as in the app). On start-up and every REFRESH_MINUTES the service reads `$APP_URL/api/rag/export` and re-embeds only documents whose hash changed. """ from __future__ import annotations import hmac import logging import os import threading import time from contextlib import asynccontextmanager from datetime import datetime, timezone import httpx from fastapi import Depends, FastAPI, Header, HTTPException from pydantic import BaseModel, Field from .index import Embedder, SearchIndex log = logging.getLogger("rag") logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") class SearchRequest(BaseModel): query: str = Field(min_length=1, max_length=2000) k: int = Field(default=6, ge=1, le=20) class IndexRequest(BaseModel): upsert: list[dict] = Field(default_factory=list, max_length=500) delete: list[str] = Field(default_factory=list, max_length=5000) class Sync: """Keeps the index equal to the app's export: at start-up, periodically and on /refresh.""" def __init__(self, index: SearchIndex, app_url: str, secret: str, every_minutes: float): self.index = index self.app_url = app_url.rstrip("/") self.secret = secret self.every = max(every_minutes, 1) * 60 self.ready = False self.last_sync: str | None = None self.last_error: str | None = None self._wake = threading.Event() self._stop = threading.Event() def start(self): """Start the background sync, or warn when the app to read from is not configured.""" if not (self.app_url and self.secret): log.warning("APP_URL or RAG_SECRET missing: the index only receives pushes from the app") return log.info("Reading the export from %s/api/rag/export", self.app_url) threading.Thread(target=self._run, name="rag-sync", daemon=True).start() def stop(self): self._stop.set() self._wake.set() def request(self): self._wake.set() def once(self): response = httpx.get( f"{self.app_url}/api/rag/export", headers={"authorization": f"Bearer {self.secret}"}, timeout=120, ) response.raise_for_status() documents = response.json()["documents"] started = time.monotonic() result = self.index.replace_all(documents) self.ready = True self.last_sync = datetime.now(timezone.utc).isoformat(timespec="seconds") self.last_error = None log.info("Synced %s documents in %.1fs: %s", len(documents), time.monotonic() - started, result) def _run(self): delay = 30.0 while not self._stop.is_set(): try: self.once() delay = 30.0 wait = self.every except Exception as error: # the app may be asleep or deploying: retry with backoff self.last_error = f"{type(error).__name__}: {error}" log.warning("Export sync failed (%s); retrying in %ss", self.last_error, int(delay)) wait, delay = delay, min(delay * 2, 600) self._wake.wait(wait) self._wake.clear() def create_app(embedder: Embedder | None = None, *, sync_on_start: bool = True) -> FastAPI: secret = os.environ.get("RAG_SECRET", "") app_url = os.environ.get("APP_URL", "") model = os.environ.get("EMBED_MODEL", "") if embedder is None: from .embeddings import model_name, no_embeddings model = model_name() if model == "none": # BM25 only: no torch needed, no paraphrase matching embedder = no_embeddings else: from .embeddings import SentenceEmbedder embedder = SentenceEmbedder(model) index = SearchIndex(embedder) sync = Sync(index, app_url, secret, float(os.environ.get("REFRESH_MINUTES", "360"))) @asynccontextmanager async def lifespan(_: FastAPI): if sync_on_start: sync.start() yield sync.stop() app = FastAPI(title="Documents assistant search", lifespan=lifespan) app.state.index = index app.state.sync = sync def authorized(authorization: str = Header(default="")): if not secret: raise HTTPException(503, "RAG_SECRET is not configured") token = authorization.removeprefix("Bearer ") if not hmac.compare_digest(token.encode(), secret.encode()): raise HTTPException(401, "Unauthorized") @app.get("/health") def health(): return { "status": "ready" if sync.ready or index.stats["documents"] else "loading", **index.stats, "model": model, "lastSync": sync.last_sync, "lastError": sync.last_error, } # Plain `def` endpoints run in a thread pool: embedding is CPU-bound. @app.post("/search", dependencies=[Depends(authorized)]) def search(body: SearchRequest): if not index.stats["chunks"] and not sync.ready: raise HTTPException(503, "Index is loading") return {"results": index.search(body.query, body.k)} @app.post("/index", dependencies=[Depends(authorized)]) def update(body: IndexRequest): return index.apply(body.upsert, body.delete) @app.post("/refresh", status_code=202, dependencies=[Depends(authorized)]) def refresh(): if not app_url: raise HTTPException(503, "APP_URL is not configured") sync.request() return {"status": "scheduled"} return app