ragfabric-server 0.3.1__tar.gz

ragfabric_server-0.3.1/.gitignore

@@ -0,0 +1,49 @@
+# Environment
+.env
+.env.*
+!.env.example
+
+# local configuration (copy of ragfabric.example.yaml)
+ragfabric.yaml
+
+# OS
+.DS_Store
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+
+# Local data / databases
+*.db
+backend/data/uploads/
+
+# Node / Angular
+node_modules/
+dist/
+.angular/
+npm-debug.log*
+
+# Editors
+.idea/
+.vscode/
+
+# Frontend test artifacts
+coverage/
+out-tsc/
+
+# Local planning notes and scratch (never committed)
+MEMORY*.md
+*.local.md
+.notes/
+.scratch/
+
+# Secrets and keys (belt and braces; .env already excluded above)
+*.pem
+*.key
+*.p12
+secrets/

ragfabric_server-0.3.1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: ragfabric-server
+Version: 0.3.1
+Summary: RagFabric HTTP API (FastAPI).
+Project-URL: Homepage, https://github.com/ranjan-del/ragfabric
+Project-URL: Repository, https://github.com/ranjan-del/ragfabric
+Project-URL: Documentation, https://github.com/ranjan-del/ragfabric/tree/main/docs
+Project-URL: Changelog, https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ranjan-del/ragfabric/issues
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: <3.14,>=3.13
+Requires-Dist: fastapi>=0.141
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: ragfabric-core==0.3.1
+Requires-Dist: uvicorn[standard]>=0.52
+Description-Content-Type: text/markdown
+
+# ragfabric-server
+
+The RagFabric HTTP API. See the repository README.

ragfabric_server-0.3.1/README.md

@@ -0,0 +1,3 @@
+# ragfabric-server
+
+The RagFabric HTTP API. See the repository README.

ragfabric_server-0.3.1/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "ragfabric-server"
+version = "0.3.1"
+description = "RagFabric HTTP API (FastAPI)."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13,<3.14"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: FastAPI",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+  "ragfabric-core==0.3.1",
+  "fastapi>=0.141",
+  "uvicorn[standard]>=0.52",
+  "python-multipart>=0.0.32",
+]
+
+[project.urls]
+Homepage = "https://github.com/ranjan-del/ragfabric"
+Repository = "https://github.com/ranjan-del/ragfabric"
+Documentation = "https://github.com/ranjan-del/ragfabric/tree/main/docs"
+Changelog = "https://github.com/ranjan-del/ragfabric/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ranjan-del/ragfabric/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragfabric_server"]

ragfabric_server-0.3.1/src/ragfabric_server/__init__.py

@@ -0,0 +1 @@
+"""RagFabric HTTP API."""

ragfabric_server-0.3.1/src/ragfabric_server/api/routes/access.py

@@ -0,0 +1,218 @@
+"""Admin API for groups, grants, overrides and API keys."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from ragfabric_core.auth import service
+from ragfabric_core.auth.api_keys import create_api_key
+from ragfabric_core.db.session import get_db
+from ragfabric_core.models.access import (
+    ApiKey,
+    CollectionGrant,
+    DocumentOverride,
+    Group,
+    GroupMember,
+)
+from ragfabric_core.models.document import Collection, Document
+from ragfabric_core.models.user import User
+from ragfabric_server.deps import require_role
+from ragfabric_server.schemas.access import (
+    ApiKeyCreate,
+    ApiKeyCreated,
+    ApiKeyOut,
+    GrantCreate,
+    GrantOut,
+    GroupCreate,
+    GroupOut,
+    GroupUpdate,
+    MemberAdd,
+    OverrideCreate,
+    OverrideOut,
+)
+from ragfabric_server.schemas.user import UserOut
+
+router = APIRouter(dependencies=[Depends(require_role("admin"))])
+
+
+def _get_or_404(db: Session, model, ident, name: str):
+    obj = db.get(model, ident)
+    if obj is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{name} not found.")
+    return obj
+
+
+@router.post("/groups", response_model=GroupOut, status_code=status.HTTP_201_CREATED)
+def create_group(payload: GroupCreate, db: Session = Depends(get_db)) -> Group:
+    if db.query(Group).filter(Group.name == payload.name).first() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="Group name already exists."
+        )
+    group = service.create_group(db, payload.name, payload.description)
+    db.commit()
+    db.refresh(group)
+    return group
+
+
+@router.get("/groups", response_model=list[GroupOut])
+def list_groups(db: Session = Depends(get_db)) -> list[Group]:
+    return db.query(Group).order_by(Group.name).all()
+
+
+@router.put("/groups/{group_id}", response_model=GroupOut)
+def update_group(group_id: int, payload: GroupUpdate, db: Session = Depends(get_db)) -> Group:
+    """Rename a group or change its description.
+
+    A group's name is the handle an operator uses everywhere else in the
+    console, so it has to be editable without recreating the group and
+    re-adding every member and grant.
+    """
+    group = _get_or_404(db, Group, group_id, "Group")
+    if payload.name is not None and payload.name != group.name:
+        clash = db.query(Group).filter(Group.name == payload.name).first()
+        if clash is not None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT, detail="Group name already exists."
+            )
+        group.name = payload.name
+    if payload.description is not None:
+        group.description = payload.description
+    db.commit()
+    db.refresh(group)
+    return group
+
+
+@router.delete("/groups/{group_id}", status_code=status.HTTP_200_OK)
+def delete_group(group_id: int, db: Session = Depends(get_db)) -> dict:
+    """Delete a group. Its memberships and grants go with it; its users do not.
+
+    Every foreign key pointing at ``groups.id`` is already declared
+    ``ON DELETE CASCADE``: ``group_members.group_id``,
+    ``collection_grants.group_id`` and ``document_overrides.group_id``. That
+    is the right choice for all three and it is left in place rather than
+    reimplemented here. A membership, a grant or an override belonging to a
+    group that no longer exists is not a fact about anything, and keeping any
+    of them would leave access rows the console can no longer show or revoke.
+
+    What must NOT cascade is the users themselves. ``group_members`` is the
+    join table, so deleting the group removes the membership rows and leaves
+    every user account untouched, which is what the test of this route
+    asserts directly.
+    """
+    group = _get_or_404(db, Group, group_id, "Group")
+    db.delete(group)
+    db.commit()
+    return {"detail": "Group deleted.", "id": group_id}
+
+
+@router.get("/groups/{group_id}/members", response_model=list[UserOut])
+def list_members(group_id: int, db: Session = Depends(get_db)) -> list[User]:
+    """List the users in a group.
+
+    Membership could be written but never read back, so the console had no
+    way to show who is in a group, which is the only question anyone asks of
+    one.
+    """
+    _get_or_404(db, Group, group_id, "Group")
+    return (
+        db.query(User)
+        .join(GroupMember, GroupMember.user_id == User.id)
+        .filter(GroupMember.group_id == group_id)
+        .order_by(User.email)
+        .all()
+    )
+
+
+@router.post("/groups/{group_id}/members", status_code=status.HTTP_200_OK)
+def add_member(group_id: int, payload: MemberAdd, db: Session = Depends(get_db)) -> dict:
+    _get_or_404(db, Group, group_id, "Group")
+    _get_or_404(db, User, payload.user_id, "User")
+    service.add_member(db, group_id, payload.user_id)
+    db.commit()
+    return {"detail": "Member added.", "group_id": group_id, "user_id": payload.user_id}
+
+
+@router.delete("/groups/{group_id}/members/{user_id}", status_code=status.HTTP_200_OK)
+def remove_member(group_id: int, user_id: int, db: Session = Depends(get_db)) -> dict:
+    service.remove_member(db, group_id, user_id)
+    db.commit()
+    return {"detail": "Member removed.", "group_id": group_id, "user_id": user_id}
+
+
+@router.post("/grants", response_model=GrantOut, status_code=status.HTTP_201_CREATED)
+def create_grant(payload: GrantCreate, db: Session = Depends(get_db)) -> CollectionGrant:
+    _get_or_404(db, Group, payload.group_id, "Group")
+    _get_or_404(db, Collection, payload.collection_id, "Collection")
+    grant = service.grant_collection(
+        db, payload.group_id, payload.collection_id, payload.permission
+    )
+    db.commit()
+    db.refresh(grant)
+    return grant
+
+
+@router.get("/grants", response_model=list[GrantOut])
+def list_grants(db: Session = Depends(get_db)) -> list[CollectionGrant]:
+    return db.query(CollectionGrant).order_by(CollectionGrant.id).all()
+
+
+@router.delete("/grants/{grant_id}", status_code=status.HTTP_200_OK)
+def delete_grant(grant_id: int, db: Session = Depends(get_db)) -> dict:
+    grant = _get_or_404(db, CollectionGrant, grant_id, "Grant")
+    db.delete(grant)
+    db.commit()
+    return {"detail": "Grant removed.", "id": grant_id}
+
+
+@router.post("/overrides", response_model=OverrideOut, status_code=status.HTTP_201_CREATED)
+def create_override(payload: OverrideCreate, db: Session = Depends(get_db)) -> DocumentOverride:
+    _get_or_404(db, Document, payload.document_id, "Document")
+    try:
+        override = service.set_document_override(
+            db,
+            payload.document_id,
+            group_id=payload.group_id,
+            user_id=payload.user_id,
+            permission=payload.permission,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    db.commit()
+    db.refresh(override)
+    return override
+
+
+@router.get("/overrides", response_model=list[OverrideOut])
+def list_overrides(db: Session = Depends(get_db)) -> list[DocumentOverride]:
+    return db.query(DocumentOverride).order_by(DocumentOverride.id).all()
+
+
+@router.post("/keys", response_model=ApiKeyCreated, status_code=status.HTTP_201_CREATED)
+def create_key(payload: ApiKeyCreate, db: Session = Depends(get_db)) -> ApiKeyCreated:
+    _get_or_404(db, User, payload.user_id, "User")
+    key, plaintext = create_api_key(
+        db,
+        name=payload.name,
+        user_id=payload.user_id,
+        collection_ids=payload.collection_ids,
+        strategies=payload.strategies,
+        rate_limit_per_minute=payload.rate_limit_per_minute,
+        expires_at=payload.expires_at,
+    )
+    db.commit()
+    db.refresh(key)
+    return ApiKeyCreated(**ApiKeyOut.model_validate(key).model_dump(), key=plaintext)
+
+
+@router.get("/keys", response_model=list[ApiKeyOut])
+def list_keys(db: Session = Depends(get_db)) -> list[ApiKey]:
+    return db.query(ApiKey).order_by(ApiKey.id).all()
+
+
+@router.delete("/keys/{key_id}", status_code=status.HTTP_200_OK)
+def revoke_key(key_id: int, db: Session = Depends(get_db)) -> dict:
+    key = _get_or_404(db, ApiKey, key_id, "API key")
+    key.is_active = False
+    db.commit()
+    return {"detail": "API key revoked.", "id": key_id}

ragfabric_server-0.3.1/src/ragfabric_server/api/routes/admin.py

@@ -0,0 +1,254 @@
+"""Admin routes (admin role required).
+
+Covers the admin controls from MEMORY.md: list and manage users' roles/activation,
+bump document versions, and hard-delete any document regardless of owner.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from sqlalchemy.orm import Session
+
+from ragfabric_core.db.session import get_db
+from ragfabric_core.graph.extract import detach_documents
+from ragfabric_core.ingest.parser import SUPPORTED_FORMATS
+from ragfabric_core.ingest.pipeline import reingest_document
+from ragfabric_core.ingest.storage import get_storage
+from ragfabric_core.models.access import ApiKey, AuditLog
+from ragfabric_core.models.document import Collection, Document, QueryLog
+from ragfabric_core.models.runs import Conversation, RetrievalRun
+from ragfabric_core.models.user import Role, User
+from ragfabric_core.runtime import get_config, get_session_factory
+from ragfabric_core.security import hash_password
+from ragfabric_core.stores.registry import build_lexical_store, build_vector_store
+from ragfabric_server.deps import require_role
+from ragfabric_server.schemas.document import DocumentOut
+from ragfabric_server.schemas.user import AdminUserCreate, PermissionUpdate, UserOut
+
+router = APIRouter()
+
+_VALID_ROLES = {Role.ADMIN.value, Role.USER.value}
+
+
+@router.get("/users", response_model=list[UserOut])
+def list_users(
+    db: Session = Depends(get_db),
+    _: User = Depends(require_role("admin")),
+) -> list[User]:
+    """List all users (admin only)."""
+    return db.query(User).order_by(User.created_at.desc()).all()
+
+
+@router.put("/users/{user_id}/permissions", response_model=UserOut)
+def set_permissions(
+    user_id: int,
+    payload: PermissionUpdate,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_role("admin")),
+) -> User:
+    """Update a user's role and/or active status (admin only)."""
+    user = db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found.")
+    if payload.role is not None:
+        if payload.role not in _VALID_ROLES:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid role. Allowed: {', '.join(sorted(_VALID_ROLES))}.",
+            )
+        user.role = payload.role
+    if payload.is_active is not None:
+        user.is_active = payload.is_active
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+@router.post("/users", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+def create_user(
+    payload: AdminUserCreate,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_role("admin")),
+) -> User:
+    """Create a user outright (admin only).
+
+    ``/api/auth/register`` exists for self service and hardcodes the ``user``
+    role, which is what stops anyone signing themselves up as an admin. This
+    route is behind the admin guard, so it may name the role and the initial
+    active state, and it is the reason an operator no longer has to insert a
+    row by hand to onboard somebody.
+    """
+    if payload.role not in _VALID_ROLES:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid role. Allowed: {', '.join(sorted(_VALID_ROLES))}.",
+        )
+    email = payload.email.lower()
+    if db.query(User).filter(User.email == email).first() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="A user with that email already exists.",
+        )
+    user = User(
+        email=email,
+        hashed_password=hash_password(payload.password),
+        role=payload.role,
+        is_active=payload.is_active,
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+@router.delete("/users/{user_id}", status_code=status.HTTP_200_OK)
+def delete_user(
+    user_id: int,
+    db: Session = Depends(get_db),
+    admin: User = Depends(require_role("admin")),
+) -> dict:
+    """Delete a user, settling every row that references them (admin only).
+
+    Nine tables carry a foreign key to ``users.id`` and each one is decided
+    here rather than left to whatever the database does by default. Two of
+    them already declare ``ON DELETE CASCADE`` on the column and are left to
+    it; the other seven are nullable with no cascade, which on PostgreSQL
+    (and on SQLite, where this project turns foreign keys on) means the
+    delete is REFUSED until they are settled. They are settled as follows.
+
+    Cascade, because the row means nothing without the user:
+
+    - ``group_members.user_id``: a membership of a deleted user is not a fact
+      about anything.
+    - ``document_overrides.user_id``: a per user grant or denial likewise.
+
+    Revoke and detach, because the row must not keep working but must not
+    vanish either:
+
+    - ``api_keys.principal_user_id``: the key is deactivated AND detached.
+      Deactivating alone would leave a live foreign key and the delete would
+      fail; deleting the key instead would break ``audit_log.api_key_id`` and
+      erase the record of what that key did. A deactivated, detached key
+      authenticates nobody and still anchors its own audit trail.
+
+    Preserve and anonymise, because the history is the product:
+
+    - ``audit_log.principal_user_id``, ``retrieval_runs.user_id``,
+      ``query_logs.user_id``, ``conversations.user_id``: measurement and
+      audit history outlives the account. The rows survive with the
+      reference cleared.
+
+    Preserve and disown, because the content belongs to the organisation:
+
+    - ``collections.owner_id``, ``documents.owner_id``: deleting a person
+      must never delete the corpus. Ownership is cleared and an admin can
+      reassign it.
+
+    Refusing to delete yourself is not a cascade decision, it is an
+    availability one: an admin who deletes their own account can lock the
+    last administrator out of the console.
+    """
+    user = db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found.")
+    if user.id == admin.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="You cannot delete your own account.",
+        )
+
+    db.query(ApiKey).filter(ApiKey.principal_user_id == user_id).update(
+        {"is_active": False, "principal_user_id": None}, synchronize_session=False
+    )
+    for model, column in (
+        (AuditLog, AuditLog.principal_user_id),
+        (RetrievalRun, RetrievalRun.user_id),
+        (Conversation, Conversation.user_id),
+        (QueryLog, QueryLog.user_id),
+        (Collection, Collection.owner_id),
+        (Document, Document.owner_id),
+    ):
+        db.query(model).filter(column == user_id).update(
+            {column.key: None}, synchronize_session=False
+        )
+
+    db.delete(user)
+    db.commit()
+    return {"detail": "User deleted.", "id": user_id}
+
+
+@router.post("/documents/{document_id}/versions", response_model=DocumentOut)
+async def create_version(
+    document_id: int,
+    file: UploadFile | None = File(default=None),
+    db: Session = Depends(get_db),
+    _: User = Depends(require_role("admin")),
+) -> Document:
+    """Publish a new version of a document (admin only).
+
+    With a ``file``, the document's content is REPLACED: the old chunks are
+    dropped from the database and the vector index, the new file is re-ingested
+    under the same document id, and the version counter advances. Keeping the id
+    means collection membership and any stored citation still resolve.
+
+    Without a file, this only advances the counter, which is the "mark a
+    reviewed revision" case where the content has not changed.
+    """
+    document = db.get(Document, document_id)
+    if document is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Document not found.")
+
+    if file is None:
+        document.version += 1
+        db.commit()
+        db.refresh(document)
+        return document
+
+    filename = file.filename or document.filename
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    if ext not in SUPPORTED_FORMATS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                f"Unsupported format '{ext or filename}'. "
+                f"Supported: {', '.join(SUPPORTED_FORMATS)}."
+            ),
+        )
+    data = await file.read()
+    if not data:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Uploaded file is empty."
+        )
+
+    return reingest_document(
+        db,
+        document,
+        filename=filename,
+        data=data,
+        content_type=file.content_type or "",
+    )
+
+
+@router.delete("/documents/{document_id}", status_code=status.HTTP_200_OK)
+def admin_delete_document(
+    document_id: int,
+    db: Session = Depends(get_db),
+    _: User = Depends(require_role("admin")),
+) -> dict:
+    """Hard-delete any document and its vectors (admin override)."""
+    document = db.get(Document, document_id)
+    if document is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Document not found.")
+    detach_documents(db, [document.id])  # recompute the graph first (R42)
+    db.delete(document)  # cascades to chunks
+    db.commit()
+    # As with the owner-facing delete route, the relational cascade does not
+    # reach the configured vector/lexical stores (SQLite does not enforce the
+    # chunk_embeddings/chunk_search foreign keys, and Chroma has none at all),
+    # so those rows must be dropped explicitly or they accumulate as orphans.
+    cfg = get_config()
+    sf = get_session_factory()
+    build_vector_store(cfg.vector_store, sf).delete_document(document_id)
+    build_lexical_store(cfg.lexical_store, sf).delete_document(document_id)
+    get_storage().delete(document_id)
+    return {"detail": "Document deleted.", "id": document_id}

ragfabric_server-0.3.1/src/ragfabric_server/api/routes/analytics.py

@@ -0,0 +1,92 @@
+"""Analytics routes powering the dashboard tiles and usage view."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from ragfabric_core.db.session import get_db
+from ragfabric_core.models.document import Chunk, Collection, Document, QueryLog
+from ragfabric_core.models.user import User
+from ragfabric_core.runtime import get_config, get_session_factory
+from ragfabric_core.stores.registry import build_vector_store
+from ragfabric_server.deps import get_current_user
+
+router = APIRouter()
+
+
+@router.get("/overview")
+def overview(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> dict:
+    """Aggregate counts for the dashboard summary tiles."""
+    return {
+        "documents": db.query(Document).count(),
+        "collections": db.query(Collection).count(),
+        "chunks": db.query(Chunk).count(),
+        "users": db.query(User).count(),
+        "queries": db.query(QueryLog).count(),
+        "ready_documents": db.query(Document).filter(Document.status == "ready").count(),
+        # Live vector count from the configured store. Comparing this against
+        # ``chunks`` is the quickest way to spot the vector index drifting out
+        # of sync with the database.
+        "indexed_vectors": build_vector_store(
+            get_config().vector_store, get_session_factory()
+        ).count(),
+    }
+
+
+@router.get("/usage")
+def usage(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> dict:
+    """Recent questions, most-indexed documents, and most-cited documents."""
+    recent = db.query(QueryLog).order_by(QueryLog.created_at.desc()).limit(10).all()
+    recent_queries = [
+        {
+            "question": log.question,
+            "confidence": round(float(log.confidence), 4),
+            "created_at": log.created_at.isoformat(),
+        }
+        for log in recent
+    ]
+
+    top_docs = (
+        db.query(Document.id, Document.filename, func.count(Chunk.id).label("chunks"))
+        .join(Chunk, Chunk.document_id == Document.id)
+        .group_by(Document.id, Document.filename)
+        .order_by(func.count(Chunk.id).desc())
+        .limit(5)
+        .all()
+    )
+    top_documents = [
+        {"document_id": doc_id, "filename": filename, "chunks": chunks}
+        for doc_id, filename, chunks in top_docs
+    ]
+
+    # Citation counts are tallied in Python rather than SQL: the cited ids live
+    # in a JSON column and JSON aggregation is not portable between SQLite and
+    # PostgreSQL, both of which this app has to run on.
+    counts: dict[int, int] = {}
+    for (cited,) in db.query(QueryLog.cited_document_ids).all():
+        for document_id in cited or []:
+            counts[document_id] = counts.get(document_id, 0) + 1
+
+    names = dict(db.query(Document.id, Document.filename).all())
+    most_cited = [
+        {
+            "document_id": document_id,
+            "filename": names.get(document_id, "(deleted)"),
+            "citations": count,
+        }
+        for document_id, count in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:5]
+    ]
+
+    return {
+        "recent_queries": recent_queries,
+        "top_documents": top_documents,
+        "most_cited_documents": most_cited,
+    }