ragkit-dev 0.1.0__py3-none-any.whl

rag_kit/step06_vector_store.py

@@ -0,0 +1,251 @@
+"""STEP 6 - Store in Qdrant.
+
+Two ways to run Qdrant:
+  server : docker run -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
+  local  : set QDRANT_PATH=qdrant_data in .env (no server needed; one process
+           at a time)
+
+Write side (`store_chunks`) creates the collection if needed. Read side
+(`open_vector_store`) never creates anything: a missing store or collection, or
+one built with a different embedding size, is an error with a fix in the message.
+
+Re-indexing: every chunk gets a deterministic point ID built from its file name,
+content hash and position. Ingesting a file again overwrites those points and
+then deletes any older chunks of the same file name that were not overwritten,
+so a document is *replaced*, never duplicated. `delete_document` removes one
+document; `--recreate` drops the whole collection.
+"""
+
+import logging
+import time
+import uuid
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from langchain_core.documents import Document
+from langchain_qdrant import QdrantVectorStore
+from qdrant_client import QdrantClient
+from qdrant_client.http import models
+
+from rag_kit.errors import EmptyDocumentError, RagError, VectorStoreError
+from rag_kit.settings import Settings, default_settings
+from rag_kit.step05_embedding import detect_dimension
+
+logger = logging.getLogger(__name__)
+
+# Fixed namespace so the same chunk always maps to the same point ID.
+_ID_NAMESPACE = uuid.UUID("8d2f1c3e-5b7a-4e0f-9c61-2a4b6d8e0f13")
+_SOURCE_KEY = "metadata.source_file"
+
+
+def describe_location(settings: Optional[Settings] = None) -> str:
+    settings = settings or default_settings()
+    if settings.qdrant_path:
+        return f"local Qdrant store {settings.qdrant_path}"
+    return f"Qdrant server {settings.qdrant_url}"
+
+
+def get_client(create: bool = True, settings: Optional[Settings] = None) -> QdrantClient:
+    """Open Qdrant. With create=False a missing local store is an error instead
+    of being silently created empty."""
+    settings = settings or default_settings()
+    if settings.qdrant_path:
+        path = Path(settings.qdrant_path)
+        if not create and not path.exists():
+            raise VectorStoreError(
+                f"No local Qdrant store at {path}. Run `rag-kit ingest <file>` first, "
+                f"or point QDRANT_PATH at the existing store (relative paths are resolved "
+                f"from {settings.project_dir})."
+            )
+        try:
+            return QdrantClient(path=str(path))
+        except RuntimeError as exc:
+            if "already accessed" in str(exc):
+                raise VectorStoreError(
+                    f"The local Qdrant store at {path} is in use by another process (the "
+                    "API server, the Streamlit UI or another CLI command). Embedded Qdrant "
+                    "allows one process at a time: stop the other one, or run a Qdrant "
+                    "server and set QDRANT_URL instead of QDRANT_PATH."
+                ) from exc
+            raise VectorStoreError(f"Could not open {describe_location(settings)}: {exc}") from exc
+    return QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+
+
+def collection_exists(client: QdrantClient, name: str,
+                      settings: Optional[Settings] = None) -> bool:
+    try:
+        return client.collection_exists(name)
+    except Exception as exc:
+        raise VectorStoreError(
+            f"Cannot reach {describe_location(settings)}: {exc}. Start the server "
+            "(docker run -p 6333:6333 qdrant/qdrant) or set QDRANT_PATH for local mode."
+        ) from exc
+
+
+def collection_dimension(client: QdrantClient, name: str) -> int:
+    vectors = client.get_collection(name).config.params.vectors
+    if isinstance(vectors, dict):  # named vectors; LangChain uses the unnamed one
+        vectors = vectors.get("") or next(iter(vectors.values()))
+    return vectors.size
+
+
+def check_dimension(client: QdrantClient, name: str, expected: int,
+                    settings: Optional[Settings] = None) -> None:
+    actual = collection_dimension(client, name)
+    if actual != expected:
+        raise VectorStoreError(
+            f"Collection '{name}' holds {actual}-dimensional vectors, but "
+            f"{(settings or default_settings()).embedding_model} produces {expected}. "
+            "Vectors from different models "
+            "are not comparable: set EMBEDDING_MODEL back to the model that built this "
+            "collection, use another COLLECTION_NAME, or rebuild it with --recreate."
+        )
+
+
+def ensure_collection(client: QdrantClient, dimension: int, recreate: bool = False,
+                      collection: Optional[str] = None,
+                      settings: Optional[Settings] = None) -> None:
+    settings = settings or default_settings()
+    name = collection or settings.collection_name
+    exists = collection_exists(client, name, settings)
+
+    if exists and recreate:
+        client.delete_collection(name)
+        exists = False
+        logger.info(f"    dropped old collection '{name}'")
+
+    if exists:
+        check_dimension(client, name, dimension, settings)
+        return
+
+    client.create_collection(
+        collection_name=name,
+        vectors_config=models.VectorParams(size=dimension, distance=models.Distance.COSINE),
+    )
+    logger.info(f"    created collection '{name}' (dim={dimension}, cosine)")
+
+
+def get_vector_store(embeddings, client: QdrantClient = None,
+                     collection: Optional[str] = None,
+                     settings: Optional[Settings] = None) -> QdrantVectorStore:
+    settings = settings or default_settings()
+    return QdrantVectorStore(
+        client=client or get_client(settings=settings),
+        collection_name=collection or settings.collection_name,
+        embedding=embeddings,
+    )
+
+
+def open_vector_store(embeddings, client: QdrantClient,
+                      collection: Optional[str] = None,
+                      settings: Optional[Settings] = None) -> QdrantVectorStore:
+    """Read side: validate that the collection exists and matches the model."""
+    settings = settings or default_settings()
+    name = collection or settings.collection_name
+    if not collection_exists(client, name, settings):
+        found = [c.name for c in client.get_collections().collections]
+        raise VectorStoreError(
+            f"Collection '{name}' does not exist in {describe_location(settings)} "
+            f"(found: {', '.join(found) or 'none'}). Ingest a document first, or fix "
+            "COLLECTION_NAME."
+        )
+    check_dimension(client, name, detect_dimension(embeddings, settings), settings)
+    return get_vector_store(embeddings, client, name, settings)
+
+
+def chunk_point_id(metadata: dict) -> str:
+    key = f"{metadata['source_file']}|{metadata.get('doc_id')}|{metadata['chunk_id']}"
+    return str(uuid.uuid5(_ID_NAMESPACE, key))
+
+
+def _source_filter(source_file: str, keep_ids: Optional[List[str]] = None) -> models.Filter:
+    return models.Filter(
+        must=[models.FieldCondition(key=_SOURCE_KEY, match=models.MatchValue(value=source_file))],
+        must_not=[models.HasIdCondition(has_id=keep_ids)] if keep_ids else None,
+    )
+
+
+def store_chunks(chunks: List[Document], embeddings, recreate: bool = False,
+                 client: QdrantClient = None, collection: Optional[str] = None,
+                 settings: Optional[Settings] = None) -> dict:
+    if not chunks:
+        raise EmptyDocumentError("Nothing to store: the document produced no chunks.")
+
+    settings = settings or default_settings()
+    client = client or get_client(settings=settings)
+    name = collection or settings.collection_name
+    ensure_collection(client, detect_dimension(embeddings, settings), recreate=recreate,
+                      collection=name, settings=settings)
+    store = get_vector_store(embeddings, client, name, settings)
+    ids = [chunk_point_id(c.metadata) for c in chunks]
+
+    # Gemini caps a single embed call at 100 texts, so send in batches.
+    # On the free tier it also caps ~100 texts/minute, so pause between batches.
+    batch = settings.embed_batch_size
+    for i, start in enumerate(range(0, len(chunks), batch)):
+        if i > 0 and settings.embed_sleep:
+            time.sleep(settings.embed_sleep)
+        try:
+            store.add_documents(chunks[start:start + batch], ids=ids[start:start + batch])
+        except RagError:
+            raise
+        except Exception as exc:
+            raise VectorStoreError(
+                f"Storing chunks failed after {start}/{len(chunks)}: {exc}. Running ingest "
+                "again is safe - chunks are keyed by file and position, so nothing is "
+                "duplicated."
+            ) from exc
+        logger.info(f"    stored {min(start + batch, len(chunks))}/{len(chunks)} chunks")
+
+    # Replace, not append: drop older chunks of the same file that this run
+    # did not overwrite (e.g. the file shrank or its content changed).
+    replaced = 0
+    for source in sorted({c.metadata["source_file"] for c in chunks}):
+        source_ids = [pid for pid, c in zip(ids, chunks) if c.metadata["source_file"] == source]
+        stale = _source_filter(source, keep_ids=source_ids)
+        count = client.count(name, count_filter=stale, exact=True).count
+        if count:
+            client.delete(name, points_selector=models.FilterSelector(filter=stale))
+            replaced += count
+
+    total = client.count(name, exact=True).count
+    note = f", {replaced} outdated chunks removed" if replaced else ""
+    logger.info(f"[6] Qdrant     : collection '{name}' now holds {total} vectors{note}")
+    return {"collection": name, "stored": len(chunks), "removed_outdated": replaced,
+            "total": total}
+
+
+def delete_document(client: QdrantClient, source_file: str,
+                    collection: Optional[str] = None,
+                    settings: Optional[Settings] = None) -> int:
+    """Remove every chunk of one file. Returns how many were deleted."""
+    settings = settings or default_settings()
+    name = collection or settings.collection_name
+    if not collection_exists(client, name, settings):
+        raise VectorStoreError(
+            f"Collection '{name}' does not exist in {describe_location(settings)}.")
+    selector = _source_filter(source_file)
+    count = client.count(name, count_filter=selector, exact=True).count
+    if count:
+        client.delete(name, points_selector=models.FilterSelector(filter=selector))
+    return count
+
+
+def list_documents(client: QdrantClient, collection: Optional[str] = None,
+                   settings: Optional[Settings] = None) -> Dict[str, int]:
+    """File name -> number of chunks stored for it."""
+    settings = settings or default_settings()
+    name = collection or settings.collection_name
+    if not collection_exists(client, name, settings):
+        raise VectorStoreError(
+            f"Collection '{name}' does not exist in {describe_location(settings)}.")
+    counts: Dict[str, int] = {}
+    offset = None
+    while True:
+        points, offset = client.scroll(name, limit=512, offset=offset,
+                                       with_payload=True, with_vectors=False)
+        for point in points:
+            source = (point.payload or {}).get("metadata", {}).get("source_file", "(unknown)")
+            counts[source] = counts.get(source, 0) + 1
+        if offset is None:
+            return dict(sorted(counts.items()))

rag_kit/step08_query_embedding.py

@@ -0,0 +1,17 @@
+"""STEP 8 - Query embedding.
+
+The question is turned into a vector with the same model used in step 5.
+LangChain's retriever would do this internally, but doing it explicitly keeps
+the pipeline visible and lets you inspect or cache the vector.
+"""
+
+import logging
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+
+def embed_question(embeddings, question: str) -> List[float]:
+    vector = embeddings.embed_query(question)
+    logger.info(f"[8] Query vec  : {len(vector)} dimensions")
+    return vector

rag_kit/step09_retrieve.py

@@ -0,0 +1,34 @@
+"""STEP 9 - Retrieve relevant chunks.
+
+Cosine similarity search in Qdrant against the query vector from step 8.
+Returns (Document, score) pairs, highest score first. With a `min_score`
+(MIN_SCORE in .env), weaker hits are dropped, and an empty result means
+"nothing relevant" rather than "the k least-bad chunks".
+"""
+
+import logging
+from typing import List, Optional, Tuple
+
+from langchain_core.documents import Document
+
+logger = logging.getLogger(__name__)
+
+
+def retrieve(vector_store, query_vector: List[float], k: int,
+             min_score: Optional[float] = None) -> List[Tuple[Document, float]]:
+    results = vector_store.similarity_search_with_score_by_vector(query_vector, k=k)
+
+    dropped = 0
+    if min_score is not None:
+        kept = [(doc, score) for doc, score in results if score >= min_score]
+        dropped = len(results) - len(kept)
+        results = kept
+
+    note = f" ({dropped} below min score {min_score})" if dropped else ""
+    logger.info(f"[9] Retrieved  : {len(results)} chunks{note}")
+    for i, (doc, score) in enumerate(results, start=1):
+        page = doc.metadata.get("page_number") or "-"
+        preview = doc.page_content[:70].replace("\n", " ")
+        logger.info(f"    S{i} page {page} | score {score:.3f} | {preview}...")
+
+    return results

rag_kit/step10_generate.py

@@ -0,0 +1,84 @@
+"""STEP 10 - Gemini.
+
+The retrieved chunks become the context. The prompt forces the model to answer
+from that context only, and to tag every claim with the [S1]..[Sn] marker of
+the chunk it came from - that is what makes step 11's sources trustworthy.
+"""
+
+import logging
+from typing import List, Optional, Tuple
+
+from langchain_core.documents import Document
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+
+from rag_kit.errors import GenerationError
+from rag_kit.settings import Settings, default_settings
+
+logger = logging.getLogger(__name__)
+
+NO_RESULTS_ANSWER = "Nothing relevant was retrieved from the documents for this question."
+
+SYSTEM_PROMPT = """You answer questions about a set of documents.
+
+Rules:
+- Use ONLY the context below. Do not add outside knowledge.
+- After each claim, put the marker of the chunk it came from, like [S1] or [S2].
+- If the context does not contain the answer, say exactly that the document does
+  not cover it. Do not guess.
+- Answer in the same language the question was asked in.
+- Be direct. No preamble."""
+
+PROMPT = ChatPromptTemplate.from_messages([
+    ("system", SYSTEM_PROMPT),
+    ("human", "Context:\n{context}\n\nQuestion: {question}"),
+])
+
+
+def get_llm(settings: Optional[Settings] = None) -> "ChatGoogleGenerativeAI":  # noqa: F821
+    settings = settings or default_settings()
+    settings.require_api_key()
+    # Imported here so ingestion and retrieval work without the Gemini SDK.
+    try:
+        from langchain_google_genai import ChatGoogleGenerativeAI
+    except ImportError as exc:
+        raise GenerationError(
+            f'Answer generation needs the gemini extra: pip install "ragkit-dev[gemini]" ({exc}).'
+        ) from exc
+    return ChatGoogleGenerativeAI(
+        model=settings.llm_model,
+        google_api_key=settings.google_api_key,
+        temperature=settings.temperature,
+    )
+
+
+def format_context(scored_docs: List[Tuple[Document, float]]) -> str:
+    blocks = []
+    for i, (doc, _score) in enumerate(scored_docs, start=1):
+        page = doc.metadata.get("page_number")
+        source = doc.metadata.get("source_file", "document")
+        where = f"{source}, page {page}" if page else source
+        blocks.append(f"[S{i}] ({where})\n{doc.page_content}")
+    return "\n\n---\n\n".join(blocks)
+
+
+def generate_answer(question: str, scored_docs: List[Tuple[Document, float]], llm=None,
+                    settings: Optional[Settings] = None) -> str:
+    if not scored_docs:
+        return NO_RESULTS_ANSWER
+
+    settings = settings or default_settings()
+    chain = PROMPT | (llm or get_llm(settings)) | StrOutputParser()
+    try:
+        answer = chain.invoke({
+            "context": format_context(scored_docs),
+            "question": question,
+        })
+    except Exception as exc:
+        raise GenerationError(
+            f"{settings.llm_model} could not answer: {exc}. Check GOOGLE_API_KEY, the "
+            "LLM_MODEL name and your quota (HTTP 429 means rate-limited; wait and retry)."
+        ) from exc
+
+    logger.info(f"[10] Gemini    : {settings.llm_model} answered")
+    return answer.strip()

rag_kit/step11_answer.py

@@ -0,0 +1,60 @@
+"""STEP 11 - Answer + sources."""
+
+import re
+from typing import List, Tuple
+
+from langchain_core.documents import Document
+
+# Gemini tags claims with [S1], [S2]... (sometimes back-to-back).
+_MARKER_RE = re.compile(r"[ \t]*(?:\[S\d+\])+")
+
+
+def strip_markers(text: str) -> str:
+    """Remove [S1]-style citation markers, e.g. for a UI that lists sources separately."""
+    return _MARKER_RE.sub("", text).strip()
+
+
+def build_sources(scored_docs: List[Tuple[Document, float]]) -> List[dict]:
+    """One entry per retrieved chunk; `marker` matches the [S1].. tags in the answer."""
+    return [
+        {
+            "marker": f"S{i}",
+            "page": doc.metadata.get("page_number"),
+            "file": doc.metadata.get("source_file"),
+            "score": float(score),
+            "chunk_id": doc.metadata.get("chunk_id"),
+            "doc_id": doc.metadata.get("doc_id"),
+            "text": doc.page_content,
+        }
+        for i, (doc, score) in enumerate(scored_docs, start=1)
+    ]
+
+
+def format_sources(scored_docs: List[Tuple[Document, float]], preview_chars: int = 160) -> str:
+    lines = []
+    for i, (doc, score) in enumerate(scored_docs, start=1):
+        page = doc.metadata.get("page_number")
+        source = doc.metadata.get("source_file", "document")
+        where = f"{source}, page {page}" if page else source
+        preview = " ".join(doc.page_content[:preview_chars].split())
+        lines.append(f"  [S{i}] {where}  (score {score:.3f})\n       {preview}...")
+    return "\n".join(lines)
+
+
+def present(question: str, answer: str, scored_docs: List[Tuple[Document, float]]) -> dict:
+    print("\n" + "=" * 72)
+    print(f"Q: {question}")
+    print("-" * 72)
+    print(answer)
+    print("-" * 72)
+    print("Sources:" if scored_docs else "Sources: none (nothing relevant was retrieved)")
+    if scored_docs:
+        print(format_sources(scored_docs))
+    print("=" * 72)
+
+    return {
+        "question": question,
+        "answer": answer,
+        "status": "answered" if scored_docs else "no_results",
+        "sources": build_sources(scored_docs),
+    }

rag_kit/ui/__init__.py

@@ -0,0 +1 @@
+"""The optional Streamlit test UI (`rag-kit ui`); app.py is run by streamlit."""

rag_kit/ui/app.py

@@ -0,0 +1,153 @@
+"""Optional Streamlit UI for testing the pipeline - not a production app.
+
+    pip install "ragkit-dev[ui]"
+    rag-kit ui                             # http://localhost:8501
+
+Upload and ingest documents, ask questions, and inspect the retrieved chunks.
+Uploads are saved under the project's uploads/ folder (git-ignored). Local
+Qdrant allows one process at a time, so stop `serve` or other CLI commands
+while this runs. `rag-kit ui` passes the project in RAG_PROJECT_DIR.
+"""
+
+from pathlib import Path
+
+import streamlit as st
+
+from rag_kit.env import export_env_file
+from rag_kit.errors import RagError
+from rag_kit.log import show_progress
+from rag_kit.pipeline import Pipeline
+from rag_kit.settings import SUPPORTED_EXTENSIONS, default_settings
+from rag_kit.step05_embedding import get_embeddings
+from rag_kit.step06_vector_store import describe_location, get_client
+
+st.set_page_config(page_title="RAG toolkit - test UI", layout="wide")
+show_progress()  # step progress in the terminal running streamlit, as before
+try:
+    settings = default_settings()
+except RagError as exc:  # no rag-kit project found
+    st.error(str(exc))
+    st.stop()
+export_env_file(settings)  # HF_HOME, proxies etc. before the model loads
+UPLOAD_DIR = settings.project_dir / "uploads"
+
+
+@st.cache_resource(show_spinner="Loading embedding model...")
+def shared_embeddings():
+    return get_embeddings(settings)
+
+
+@st.cache_resource(show_spinner="Opening Qdrant...")
+def shared_client():
+    return get_client(create=True, settings=settings)
+
+
+def pipeline_for(collection: str) -> Pipeline:
+    # One client and one model for the whole app; a Pipeline per collection.
+    cache = st.session_state.setdefault("pipelines", {})
+    if collection not in cache:
+        cache[collection] = Pipeline(collection=collection, embeddings=shared_embeddings(),
+                                     client=shared_client(), settings=settings)
+    return cache[collection]
+
+
+def show_error(exc: Exception) -> None:
+    st.error(str(exc) if isinstance(exc, (RagError, ValueError)) else f"Unexpected error: {exc!r}")
+
+
+# --- sidebar: settings + indexed documents -------------------------------------
+with st.sidebar:
+    st.header("Settings")
+    collection = st.text_input("Collection", value=settings.collection_name).strip()
+    top_k = st.slider("Chunks to retrieve (top k)", 1, 20, settings.top_k)
+    min_score = st.number_input("Min score (0 = keep all)", 0.0, 1.0,
+                                float(settings.min_score or 0.0), 0.05)
+    st.caption(f"Store: {describe_location(settings)}")
+    st.caption(f"Embedding: {settings.embedding_model}  \nLLM: {settings.llm_model}")
+    if not settings.google_api_key:
+        st.warning("GOOGLE_API_KEY is not set - retrieval works, answers will fail.")
+
+    st.header("Indexed documents")
+    try:
+        docs = pipeline_for(collection).documents()
+        if docs:
+            st.dataframe([{"file": k, "chunks": v} for k, v in docs.items()],
+                         hide_index=True, use_container_width=True)
+        else:
+            st.caption("Collection is empty.")
+    except RagError as exc:
+        st.caption(str(exc))
+
+if not collection:
+    st.stop()
+pipeline = pipeline_for(collection)
+
+st.title("RAG toolkit - test UI")
+tab_ask, tab_ingest = st.tabs(["Ask", "Ingest"])
+
+# --- ingest -----------------------------------------------------------------------
+with tab_ingest:
+    uploads = st.file_uploader("Documents", type=[e.lstrip(".") for e in SUPPORTED_EXTENSIONS],
+                               accept_multiple_files=True)
+    font_repair = st.checkbox("PDF font repair", value=settings.pdf_font_repair,
+                              help="Only for PDFs whose text extracts as scrambled glyphs.")
+    st.caption(f"Re-ingesting a file with the same name replaces its chunks in '{collection}'.")
+    if st.button("Ingest", disabled=not uploads, type="primary"):
+        UPLOAD_DIR.mkdir(exist_ok=True)
+        for upload in uploads:
+            path = UPLOAD_DIR / Path(upload.name).name
+            path.write_bytes(upload.getbuffer())
+            with st.status(f"Ingesting {path.name}...") as status:
+                try:
+                    report = pipeline.ingest(path, font_repair=font_repair)
+                    status.update(label=f"{path.name}: {report['stored']} chunks from "
+                                        f"{report['pages']} page(s), collection now holds "
+                                        f"{report['total']}", state="complete")
+                    if report["removed_outdated"]:
+                        st.caption(f"Removed {report['removed_outdated']} outdated chunks.")
+                except Exception as exc:  # noqa: BLE001 - shown in the UI
+                    status.update(label=f"{path.name}: failed", state="error")
+                    show_error(exc)
+
+# --- ask ----------------------------------------------------------------------------
+with tab_ask:
+    question = st.text_area("Question", placeholder="What does the document say about ...?")
+    col_ask, col_search = st.columns([1, 1])
+    run_ask = col_ask.button("Ask", type="primary", disabled=not question.strip())
+    run_search = col_search.button("Retrieve only (no LLM)", disabled=not question.strip())
+
+    if run_ask or run_search:
+        try:
+            with st.spinner("Working..."):
+                if run_ask:
+                    result = pipeline.ask(question, k=top_k, min_score=min_score or None)
+                    scored = result.scored_docs
+                else:
+                    result = None
+                    scored = pipeline.search(question, k=top_k, min_score=min_score or None)
+        except Exception as exc:  # noqa: BLE001 - shown in the UI
+            show_error(exc)
+            st.stop()
+
+        if result is not None:
+            st.subheader("Answer")
+            if result.status == "no_results":
+                st.info(result.answer)
+            else:
+                st.markdown(result.answer)
+
+        st.subheader(f"Retrieved chunks ({len(scored)})")
+        if not scored:
+            st.info("No chunks were retrieved. Lower the min score or ingest a document.")
+        st.dataframe([
+            {"marker": f"S{i}", "score": round(score, 4), "file": d.metadata.get("source_file"),
+             "page": d.metadata.get("page_number"), "chunk": d.metadata.get("chunk_id"),
+             "chars": len(d.page_content)}
+            for i, (d, score) in enumerate(scored, start=1)
+        ], hide_index=True, use_container_width=True)
+        for i, (doc, score) in enumerate(scored, start=1):
+            page = doc.metadata.get("page_number")
+            label = f"S{i} - {doc.metadata.get('source_file')}" + (f", page {page}" if page else "")
+            with st.expander(f"{label} (score {score:.3f})"):
+                st.text(doc.page_content)
+                st.json(doc.metadata, expanded=False)