fix/document-page-citations

src/agents/chat_handler.py

@@ -37,7 +37,7 @@ from typing import TYPE_CHECKING, Any
 from langchain_core.messages import BaseMessage
 
 from src.middlewares.logging import get_logger
-from src.retrieval.base import RetrievalResult
+from src.retrieval.base import RetrievalResult, citable_page
 from src.traceability import TraceabilityScratchpad, TraceabilityToolInvoker
 
 from ..charts import chart_envelopes
@@ -1080,8 +1080,9 @@ def _render_document_context(results: list[RetrievalResult]) -> str:
     for r in results:
         data = r.metadata.get("data", {}) if isinstance(r.metadata, dict) else {}
         where = data.get("filename") or "document"
-        if data.get("page_label") is not None:
-            where += f", p. {data['page_label']}"
+        page = citable_page(data)  # None for TXT (every chunk is "page 1")
+        if page is not None:
+            where += f", p. {page}"
         text = r.content.strip()
         if len(text) > _DOC_CONTEXT_MAX_CHARS:
             text = text[:_DOC_CONTEXT_MAX_CHARS].rstrip() + " …"
@@ -1110,12 +1111,12 @@ def _normalize_chunks(raw: Any) -> list[DocumentChunk]:
                 DocumentChunk(
                     content=str(item.get("content", "")),
                     filename=item.get("filename"),
-                    page_label=item.get("page_label"),
+                    page_label=citable_page(item),
                 )
             )
         elif isinstance(item, RetrievalResult):
             data = item.metadata.get("data", {})
-            page = data.get("page_label")
+            page = citable_page(data)  # None for TXT (every chunk is "page 1")
             chunks.append(DocumentChunk(
                 content=item.content,
                 filename=data.get("filename"),

src/agents/chatbot.py

@@ -93,7 +93,9 @@ def _format_document_chunks(chunks: list[DocumentChunk]) -> str:
         return ""
     blocks: list[str] = []
     for c in chunks:
-        label_parts = [p for p in (c.filename, c.page_label) if p]
+        # "p. N", not a bare number, so the model can cite the page (prompt rule 7).
+        page = f"p. {c.page_label}" if c.page_label else None
+        label_parts = [p for p in (c.filename, page) if p]
         label = ", ".join(label_parts) if label_parts else "Unknown source"
         blocks.append(f"[Source: {label}]\n{c.content}")
     return "\n\n".join(blocks)

src/config/prompts/chatbot_system.md

@@ -21,6 +21,11 @@ You are a friendly, precise data assistant for a user who has registered databas
 5. **Markdown is OK** for emphasis and small tables, but avoid heavy formatting (code fences, headers) unless the question genuinely calls for it.
 6. **Figures: copy the marker, never invent one.** A document chunk may contain a figure marker like `![](asset://3f2a9c0d1b4e5f60)`. When that figure helps answer the question, include its marker on its own line, copying the `asset://` id **character for character** — you may write a short caption inside the square brackets. Only use markers that appear in this turn's chunks; never write an image URL, never alter an id, and never mention "asset" or the id in your prose. The app turns the marker into the picture.
 
+7. **Cite the page for document answers — required.** Whenever your answer uses document chunks whose label has a page (`[Source: file.pdf, p. 7]`), the reader must be able to check it:
+   - put the page right after the point it supports, always written "(p. 7)" — in every reply language;
+   - **and** always make the very last line of the answer name the file and every page you used, always written "Source: file.pdf, p. 2, 7" — in every reply language. Both parts, every time: the inline pages do not replace the last line, and the last line does not replace the inline pages.
+   Cite only pages that appear in this turn's chunk labels; never guess one. Skip both when no chunk has a page.
+
 ## Context shapes you'll see
 
 - **Query result** — emitted when the user asked a data question that ran successfully. Contains `rows` (a list of dicts), `row_count`, the source/table that was queried, and any error string. If `error` is set, explain the failure plainly and suggest a next step.

src/retrieval/base.py

@@ -13,6 +13,26 @@ class RetrievalResult:
     source_type: str  # "document" | "database"
 
 
+# File types whose `page_label` is not a real page: TXT ingest stores every chunk as
+# page 1 (`document/ingest_v2.chunks_from_text`), so citing it would always say "p. 1".
+_NO_PAGE_TYPES = frozenset({"txt"})
+
+
+def citable_page(data: dict[str, Any]) -> Any:
+    """The chunk's page to show the user (chip label, answer citation), or None.
+
+    `data` is a chunk's `metadata["data"]`. None when there is no page, or when the
+    file type has no real pages (TXT).
+    """
+    file_type = str(data.get("file_type") or "").lower()
+    if not file_type:
+        name = str(data.get("filename") or "").lower()
+        file_type = name.rsplit(".", 1)[-1] if "." in name else ""
+    if file_type in _NO_PAGE_TYPES:
+        return None
+    return data.get("page_label")
+
+
 class BaseRetriever(ABC):
     @abstractmethod
     async def retrieve(

src/traceability/scratchpad.py

@@ -17,6 +17,7 @@ from typing import Any
 from pydantic import BaseModel
 
 from src.middlewares.logging import get_logger
+from src.retrieval.base import citable_page
 
 from .schemas import (
     KnowledgeUsed,
@@ -355,10 +356,16 @@ class TraceabilityScratchpad:
             if key == (None, None) or key in self._doc_seen:
                 continue
             self._doc_seen.add(key)
+            filename = data.get("filename", "Unknown")
+            page = citable_page(data)  # None for TXT (every chunk is "page 1")
             source: dict[str, Any] = {
                 "type": "document",
+                # Display label. The FE citation chip reads `name` (then title/source/
+                # id) and otherwise falls back to "Source N", so without it the page
+                # never shows (2026-11-11 dry run).
+                "name": f"{filename}, p. {page}" if page is not None else filename,
                 "document_id": data.get("document_id"),
-                "filename": data.get("filename", "Unknown"),
+                "filename": filename,
                 "page_label": data.get("page_label"),
                 "query": _truncate(query),
             }