"""/v1/books/…/sections: books uploaded one reviewed section document at a time (docs/BOOK_STORAGE.md). A section is one Markdown document plus its page scans (`spread_018.png`, `page_018.png`) and figure images (`Figure_1.1.png`, `Table_2.3.png`). Every save of the document is a new revision; headings, passages and figure links are rebuilt from it. """ from __future__ import annotations import hashlib import shutil import tempfile import uuid from datetime import datetime from pathlib import Path from fastapi import APIRouter, Depends, File, Form, Request, Response, UploadFile from pydantic import BaseModel, Field from app.api.v1_books import BookInfo, JobInfo from app.auth.permissions import Perm, Principal from app.auth.web import request_meta, require from app.books import figure_summaries from app.books.library import copy_upload from app.books.section_library import UploadedFile, read_text from app.db.models import BookPart, PartFigure, PartNode, PartRevision, Passage, Summary router = APIRouter(prefix="/v1", tags=["book sections"]) class BookCreate(BaseModel): title: str = Field(max_length=300) kind: str = Field(default="book", pattern="^(book|handbook)$", description="'handbook': a surgical technique guide, read from its PDF by the handbook " "import") licence_note: str = Field(description="Confirms SeeMed may use this book, and on what terms.") subtitle: str | None = Field(default=None, max_length=300) short_title: str | None = Field(default=None, max_length=80, description="Used in citations") edition: str | None = Field(default=None, max_length=40) edition_number: int | None = Field(default=None, ge=1, le=100) volumes: int | None = Field(default=None, ge=1, le=50) authors: list[str] = [] contributors: list[dict] = Field(default=[], description='[{"name", "role", "affiliation"}]') publisher: str | None = Field(default=None, max_length=200) year: int | None = Field(default=None, ge=1800, le=2100) isbn: str | None = Field(default=None, max_length=32) isbns: list[str] = [] specialty: str | None = Field(default=None, max_length=100) language: str | None = Field(default="en", max_length=20) description: str | None = None class PartInfo(BaseModel): id: uuid.UUID book_id: uuid.UUID ordinal: int label: str title: str status: str revision: int pdf_pages: int node_count: int passage_count: int figure_count: int table_count: int report: dict review_note: str | None approved_at: datetime | None created_at: datetime updated_at: datetime @classmethod def of(cls, p: BookPart) -> PartInfo: return cls(id=p.id, book_id=p.book_id, ordinal=p.ordinal, label=p.label, title=p.title, status=p.status, revision=p.revision, pdf_pages=p.pdf_pages, node_count=p.node_count, passage_count=p.passage_count, figure_count=p.figure_count, table_count=p.table_count, report=p.report, review_note=p.review_note, approved_at=p.approved_at, created_at=p.created_at, updated_at=p.updated_at) class DocumentInfo(BaseModel): revision: int content_md: str sha256: str source: str note: str | None author_id: uuid.UUID | None created_at: datetime @classmethod def of(cls, r: PartRevision) -> DocumentInfo: return cls(revision=r.number, content_md=r.content_md, sha256=r.sha256, source=r.source, note=r.note, author_id=r.author_id, created_at=r.created_at) class RevisionInfo(BaseModel): revision: int source: str note: str | None author_id: uuid.UUID | None created_at: datetime class DocumentSave(BaseModel): content_md: str base_revision: int = Field(description="The revision the editor loaded; refused if someone saved since") note: str | None = Field(default=None, max_length=500) class StatusChange(BaseModel): status: str = Field(pattern="^(draft|in_review|approved)$") note: str | None = None class PrintedPages(BaseModel): first_pdf_page: int = Field(ge=1, description="This PDF page …") first_label: int = Field(ge=1, description="… is printed page number (left page for a spread)") spread: bool = Field(default=True, description="Each PDF page shows two printed pages") base_revision: int class NodeInfo(BaseModel): id: uuid.UUID parent_id: uuid.UUID | None kind: str level: int number: str | None title: str path_text: str path_key: str authors: list[str] char_start: int char_end: int pdf_page_start: int | None pdf_page_end: int | None @classmethod def of(cls, n: PartNode) -> NodeInfo: return cls(id=n.id, parent_id=n.parent_id, kind=n.kind, level=n.level, number=n.number, title=n.title, path_text=n.path_text, path_key=n.path_key, authors=n.authors, char_start=n.char_start, char_end=n.char_end, pdf_page_start=n.pdf_page_start, pdf_page_end=n.pdf_page_end) class PassageInfo(BaseModel): id: uuid.UUID node_id: uuid.UUID kind: str context: str content_md: str char_start: int char_end: int pdf_page_start: int | None pdf_page_end: int | None printed_pages: str | None figure_numbers: list[str] table_numbers: list[str] token_count: int @classmethod def of(cls, p: Passage) -> PassageInfo: return cls(id=p.id, node_id=p.node_id, kind=p.kind, context=p.context, content_md=p.content_md, char_start=p.char_start, char_end=p.char_end, pdf_page_start=p.pdf_page_start, pdf_page_end=p.pdf_page_end, printed_pages=p.printed_pages, figure_numbers=p.figure_numbers, table_numbers=p.table_numbers, token_count=p.token_count) class PageInfo(BaseModel): pdf_page: int printed_labels: list[str] width: int height: int image_url: str class SectionFigure(BaseModel): id: uuid.UUID part_id: uuid.UUID kind: str number: str label: str caption: str alt_text: str | None table_md: str | None pdf_page: int | None path_text: str | None in_document: bool width: int | None height: int | None image_url: str | None summary_md: str | None = None # what it shows or lists, for search and answers summary_terms: list[str] = [] summary_model: str | None = None summary_edited: bool = False summary_current: bool = False # written from its current caption, image and rows @classmethod def of(cls, f: PartFigure) -> SectionFigure: return cls(id=f.id, part_id=f.part_id, kind=f.kind, number=f.number, label=f.label, caption=f.caption, alt_text=f.alt_text, table_md=f.table_md, pdf_page=f.pdf_page, path_text=f.path_text, in_document=f.in_document, width=f.width, height=f.height, image_url=f"/v1/section-figures/{f.id}/image" if f.image_key else None, summary_md=f.summary_md, summary_terms=list(f.summary_terms or []), summary_model=f.summary_model, summary_edited=bool(f.summary_edited), summary_current=bool(f.summary_md) and f.summary_sha256 == figure_summaries.source_sha(f)) class FigureUpdate(BaseModel): alt_text: str | None = None summary_md: str | None = None # "" removes it; a summary set here is kept by later summary runs def _sections(request: Request): return request.app.state.sections def _spool(files: list[UploadFile], tmp: Path) -> list[UploadedFile]: out = [] for i, f in enumerate(files): dest = tmp / f"{i:05d}" with open(dest, "wb") as handle: shutil.copyfileobj(f.file, handle, length=1 << 20) out.append(UploadedFile(name=f.filename or dest.name, path=dest)) return out @router.post("/books/sectioned", response_model=BookInfo, status_code=201) def create_book(body: BookCreate, request: Request, principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> BookInfo: """Create a book whose sections are uploaded one at a time. It is a draft until published.""" book = _sections(request).create_book(principal, body.model_dump(), request_meta(request)) return BookInfo.of(book) @router.get("/books/{book_id}/sections", response_model=list[PartInfo]) def list_sections(book_id: uuid.UUID, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> list[PartInfo]: return [PartInfo.of(p) for p in _sections(request).parts(principal, book_id)] @router.post("/books/{book_id}/sections/check") def check_section(book_id: uuid.UUID, request: Request, document: UploadFile = File(...), file_names: list[str] = Form(default=[]), principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> dict: """Dry run: parse the document and compare it with the names of the images to be uploaded. Saves nothing.""" text = read_text(document.file.read()) return _sections(request).check(principal, book_id, text, file_names) @router.post("/books/{book_id}/sections", response_model=PartInfo, status_code=201) def upload_section(book_id: uuid.UUID, request: Request, document: UploadFile = File(...), files: list[UploadFile] = File(default=[], description="Page scans and figure images"), replace: bool = Form(False), principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> PartInfo: """Upload a section. The section number comes from its '# SECTION …' heading. `replace=true` replaces an uploaded section with a new revision; images not sent again are kept.""" text = read_text(document.file.read()) with tempfile.TemporaryDirectory() as tmp: part = _sections(request).upload(principal, book_id, text, _spool(files, Path(tmp)), replace=replace, request=request_meta(request)) return PartInfo.of(part) @router.get("/books/{book_id}/sections/{ordinal}", response_model=PartInfo) def get_section(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> PartInfo: return PartInfo.of(_sections(request).part(principal, book_id, ordinal)) @router.delete("/books/{book_id}/sections/{ordinal}", status_code=204) def delete_section(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.KB_DELETE))) -> Response: """Delete the section: its revisions, pages, figures and passages. The other sections are untouched.""" _sections(request).delete(principal, book_id, ordinal, request_meta(request)) return Response(status_code=204) @router.get("/books/{book_id}/sections/{ordinal}/document", response_model=DocumentInfo) def get_document(book_id: uuid.UUID, ordinal: int, request: Request, revision: int | None = None, principal: Principal = Depends(require(Perm.SEARCH))) -> DocumentInfo: """The section's Markdown document: the current revision, or an earlier one.""" return DocumentInfo.of(_sections(request).document(principal, book_id, ordinal, revision)) @router.get("/books/{book_id}/sections/{ordinal}/document.md", response_class=Response) def download_document(book_id: uuid.UUID, ordinal: int, request: Request, revision: int | None = None, principal: Principal = Depends(require(Perm.SEARCH))) -> Response: doc = _sections(request).document(principal, book_id, ordinal, revision) name = f"section-{ordinal}-r{doc.number}.md" return Response(doc.content_md, media_type="text/markdown; charset=utf-8", headers={"Content-Disposition": f'attachment; filename="{name}"'}) @router.put("/books/{book_id}/sections/{ordinal}/document", response_model=PartInfo) def save_document(book_id: uuid.UUID, ordinal: int, body: DocumentSave, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> PartInfo: """Save the edited document as a new revision (409 if someone saved since `base_revision`).""" part = _sections(request).save_document(principal, book_id, ordinal, body.content_md, body.base_revision, body.note, request_meta(request)) return PartInfo.of(part) @router.get("/books/{book_id}/sections/{ordinal}/revisions", response_model=list[RevisionInfo]) def list_revisions(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> list[RevisionInfo]: return [RevisionInfo(revision=r.number, source=r.source, note=r.note, author_id=r.author_id, created_at=r.created_at) for r in _sections(request).revisions(principal, book_id, ordinal)] @router.post("/books/{book_id}/sections/{ordinal}/status", response_model=PartInfo) def change_status(book_id: uuid.UUID, ordinal: int, body: StatusChange, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> PartInfo: """Move the section through review: draft → in_review → approved (approving needs 'kb:publish').""" return PartInfo.of(_sections(request).set_status(principal, book_id, ordinal, body.status, body.note, request_meta(request))) class MoveFrontMatter(BaseModel): base_revision: int = Field(description="The section revision the editor loaded") @router.post("/books/{book_id}/sections/{ordinal}/move-front-matter", response_model=PartInfo) def move_front_matter(book_id: uuid.UUID, ordinal: int, body: MoveFrontMatter, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> PartInfo: """Move the front matter (cover, contents, contributors, preface…) at the start of a section's document into the book's front matter part (section 0), with its page scans. The front matter is kept for reference but is not searched or summarized. Returns the front matter part.""" return PartInfo.of(_sections(request).move_front_matter(principal, book_id, ordinal, body.base_revision, request_meta(request))) @router.post("/books/{book_id}/sections/{ordinal}/printed-pages", response_model=PartInfo) def number_pages(book_id: uuid.UUID, ordinal: int, body: PrintedPages, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> PartInfo: """Write printed page numbers into the page markers, from one known page on (a new revision).""" part = _sections(request).set_printed_pages(principal, book_id, ordinal, body.first_pdf_page, body.first_label, body.spread, body.base_revision, request_meta(request)) return PartInfo.of(part) @router.get("/books/{book_id}/sections/{ordinal}/outline", response_model=list[NodeInfo]) def section_outline(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> list[NodeInfo]: """Headings of the current revision in document order, with their character spans.""" return [NodeInfo.of(n) for n in _sections(request).nodes(principal, book_id, ordinal)] @router.get("/books/{book_id}/sections/{ordinal}/passages", response_model=list[PassageInfo]) def section_passages(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> list[PassageInfo]: return [PassageInfo.of(p) for p in _sections(request).passages(principal, book_id, ordinal)] @router.get("/books/{book_id}/sections/{ordinal}/pages", response_model=list[PageInfo]) def section_pages(book_id: uuid.UUID, ordinal: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> list[PageInfo]: return [PageInfo(pdf_page=p.pdf_page, printed_labels=p.printed_labels, width=p.width, height=p.height, image_url=f"/v1/books/{book_id}/sections/{ordinal}/pages/{p.pdf_page}/image") for p in _sections(request).pages(principal, book_id, ordinal)] @router.get("/books/{book_id}/sections/{ordinal}/pages/{pdf_page}/image", response_class=Response) def section_page_image(book_id: uuid.UUID, ordinal: int, pdf_page: int, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> Response: data, media_type = _sections(request).page_image(principal, book_id, ordinal, pdf_page) return _image_response(data, media_type, request) def _image_response(data: bytes, media_type: str, request: Request) -> Response: """An image the browser keeps but checks on each use (304 when unchanged), so a replaced figure or page scan shows at once: its address stays the same.""" etag = f'"{hashlib.sha256(data).hexdigest()[:32]}"' headers = {"Cache-Control": "private, no-cache", "ETag": etag} if request.headers.get("if-none-match") == etag: return Response(status_code=304, headers=headers) return Response(data, media_type=media_type, headers=headers) @router.get("/books/{book_id}/section-figures", response_model=list[SectionFigure]) def section_figures(book_id: uuid.UUID, request: Request, ordinal: int | None = None, principal: Principal = Depends(require(Perm.SEARCH))) -> list[SectionFigure]: """Figures and tables of the book, or of one section (`ordinal`).""" return [SectionFigure.of(f) for f in _sections(request).figures(principal, book_id, ordinal)] @router.get("/section-figures/{figure_id}/image", response_class=Response) def section_figure_image(figure_id: uuid.UUID, request: Request, principal: Principal = Depends(require(Perm.SEARCH))) -> Response: data, media_type = _sections(request).figure_image(principal, figure_id) return _image_response(data, media_type, request) @router.patch("/section-figures/{figure_id}", response_model=SectionFigure) def update_figure(figure_id: uuid.UUID, body: FigureUpdate, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> SectionFigure: return SectionFigure.of(_sections(request).update_figure(principal, figure_id, alt_text=body.alt_text, summary_md=body.summary_md, request=request_meta(request))) @router.put("/section-figures/{figure_id}/image", response_model=SectionFigure) def replace_figure_image(figure_id: uuid.UUID, request: Request, file: UploadFile = File(...), principal: Principal = Depends(require(Perm.KB_EDIT))) -> SectionFigure: """Replace a figure's image, e.g. with a better crop.""" with tempfile.TemporaryDirectory() as tmp: [image] = _spool([file], Path(tmp)) figure = _sections(request).update_figure(principal, figure_id, image=image, request=request_meta(request)) return SectionFigure.of(figure) # ------------------------------------------------------------------ PDF → sections (OCR) class ImportInfo(BaseModel): id: uuid.UUID file_name: str pages: int status: str # reading | ready | failed result: dict | None # pages, spreads, text_layer_pages, scanned, outline, vision, suggestions{fields, sources} error: str | None class BookFromPdf(BookCreate): upload_id: uuid.UUID = Field(description="From POST /v1/ocr/imports") section_number: int | None = Field(default=None, ge=1, le=100, description="For a PDF of one section without a 'SECTION' title page") section_title: str | None = Field(default=None, max_length=300) use_vision: bool = Field(default=True, description="Use the vision model when one is configured") pages: str | None = Field(default=None, description="Only these PDF pages, e.g. 1-40") use_ocr: bool | None = Field(default=None, description="Read the pages from their images (scans) rather than " "from the PDF's text layer; by default on for books, off for handbooks") use_claude: bool | None = Field(default=None, description="A handbook: read by Claude when an API key is " "configured (the default then); false for the built-in conversion") class BookAndJob(BaseModel): book: BookInfo job: JobInfo class SummaryRequest(BaseModel): ordinal: int | None = Field(default=None, description="One section; omit for every section and the book") force: bool = Field(default=False, description="Rewrite summaries that were edited or approved too") model: str | None = Field(default=None, description="The model that writes them (GET /v1/summary-models); " "omit for the default. Summaries by another model are rewritten.") class SummaryInfo(BaseModel): id: uuid.UUID part_id: uuid.UUID | None level: str path_text: str summary_md: str key_terms: list[str] status: str model: str | None updated_at: datetime reviewed_at: datetime | None @classmethod def of(cls, r: Summary) -> SummaryInfo: return cls(id=r.id, part_id=r.part_id, level=r.level, path_text=r.path_text, summary_md=r.summary_md, key_terms=r.key_terms, status=r.status, model=r.model, updated_at=r.updated_at, reviewed_at=r.reviewed_at) class SummaryUpdate(BaseModel): summary_md: str | None = None key_terms: list[str] | None = None status: str | None = Field(default=None, pattern="^(edited|approved)$") @router.get("/ocr/status") def ocr_status(request: Request, principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> dict: """The OCR and summary engines this server can use.""" return _sections(request).status() @router.post("/ocr/imports", response_model=ImportInfo, status_code=202) def start_import(request: Request, file: UploadFile = File(..., description="The book, or one section, as PDF"), principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> ImportInfo: """Upload a PDF before creating its book. Its first pages are read in the background to suggest the book's details; poll GET /v1/ocr/imports/{id}, then create the book with POST /v1/books/from-pdf.""" with tempfile.TemporaryDirectory() as tmp: path = copy_upload(file.file, Path(tmp)) info = _sections(request).start_import(principal, path, file.filename or "book.pdf") return ImportInfo(**info) @router.get("/ocr/imports/{upload_id}", response_model=ImportInfo) def import_status(upload_id: uuid.UUID, request: Request, principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> ImportInfo: return ImportInfo(**_sections(request).import_status(principal, upload_id)) @router.post("/books/from-pdf", response_model=BookAndJob, status_code=201) def create_book_from_pdf(body: BookFromPdf, request: Request, principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> BookAndJob: """Create the book with the (edited) details, and read the uploaded PDF into section documents in the background. Follow the job with GET /v1/jobs/{id}; the sections appear as drafts for review.""" lib, meta = _sections(request), request_meta(request) fields = body.model_dump(exclude={"upload_id", "section_number", "section_title", "use_vision", "pages", "use_ocr", "use_claude"}) lib.import_status(principal, body.upload_id) # fails early if the upload is gone book = lib.create_book(principal, fields, meta) job = lib.queue_ocr(principal, book.id, upload_id=body.upload_id, section_number=body.section_number, section_title=body.section_title, use_vision=body.use_vision, pages=body.pages, use_ocr=body.use_ocr, use_claude=body.use_claude, request=meta) return BookAndJob(book=BookInfo.of(lib.lib.get(principal, book.id)), job=JobInfo.of(job)) @router.post("/books/{book_id}/sections/from-pdf", response_model=JobInfo, status_code=202) def section_from_pdf(book_id: uuid.UUID, request: Request, file: UploadFile = File(...), section_number: int | None = Form(None), section_title: str | None = Form(None), replace: bool = Form(False), use_vision: bool = Form(True), pages: str | None = Form(None), use_ocr: bool | None = Form(None), use_claude: bool | None = Form(None), principal: Principal = Depends(require(Perm.KB_UPLOAD))) -> JobInfo: """Read a PDF (one section, or several) into section documents of this book, in the background; a handbook's PDF into its document. `use_ocr` and `use_claude` as for POST /v1/books/from-pdf.""" with tempfile.TemporaryDirectory() as tmp: path = copy_upload(file.file, Path(tmp)) job = _sections(request).queue_ocr(principal, book_id, source=path, file_name=file.filename or "section.pdf", section_number=section_number, section_title=section_title, replace=replace, use_vision=use_vision, pages=pages or None, use_ocr=use_ocr, use_claude=use_claude, request=request_meta(request)) return JobInfo.of(job) @router.get("/books/{book_id}/jobs", response_model=list[JobInfo]) def book_jobs(book_id: uuid.UUID, request: Request, principal: Principal = Depends(require(Perm.INGEST_VIEW))) -> list[JobInfo]: """The book's recent jobs (OCR, summaries), newest first.""" return [JobInfo.of(j) for j in _sections(request).jobs(principal, book_id)] @router.post("/jobs/{job_id}/cancel", response_model=JobInfo) def cancel_job(job_id: uuid.UUID, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> JobInfo: """Stop a queued or running job. A running OCR job stops after its current page.""" return JobInfo.of(_sections(request).cancel_job(principal, job_id, request_meta(request))) # ------------------------------------------------------------------ summaries @router.post("/books/{book_id}/summaries", response_model=JobInfo, status_code=202) def generate_summaries(book_id: uuid.UUID, body: SummaryRequest, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> JobInfo: """Write summaries in the background: of one section's subheadings, headings, chapters and the section, or of every section and the book. Only what is missing, stale or written by another model is written.""" return JobInfo.of(_sections(request).queue_summaries(principal, book_id, body.ordinal, body.force, request_meta(request), model=body.model)) @router.get("/summary-models") def summary_models(request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> list[dict]: """Models that can write summaries: the summary server (default) and the registry's models.""" return _sections(request).summary_models() @router.get("/books/{book_id}/summaries", response_model=list[SummaryInfo]) def list_summaries(book_id: uuid.UUID, request: Request, ordinal: int | None = None, principal: Principal = Depends(require(Perm.SEARCH))) -> list[SummaryInfo]: return [SummaryInfo.of(r) for r in _sections(request).summaries(principal, book_id, ordinal)] @router.patch("/summaries/{summary_id}", response_model=SummaryInfo) def update_summary(summary_id: uuid.UUID, body: SummaryUpdate, request: Request, principal: Principal = Depends(require(Perm.KB_EDIT))) -> SummaryInfo: """Edit a summary (it becomes "edited") or approve it.""" return SummaryInfo.of(_sections(request).update_summary(principal, summary_id, summary_md=body.summary_md, key_terms=body.key_terms, status=body.status, request=request_meta(request)))