annotheca 0.1.0__tar.gz

annotheca-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,19 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[test]'
+      - run: pytest

annotheca-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

annotheca-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Melissa Colin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

annotheca-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: annotheca
+Version: 0.1.0
+Summary: A local, bilingual reference manager for research projects: BibTeX, PDFs, highlights and sticky notes.
+Project-URL: Homepage, https://github.com/melissa-colin/annotheca
+Author: Melissa Colin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotation,bibliography,bibtex,pdf,reference-manager,research
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/src/annotheca/static/favicon.svg" width="72" alt="">
+</p>
+
+<h1 align="center">Annotheca</h1>
+
+<p align="center">
+  <b>A calm, local home for the bibliography of your research projects.</b><br>
+  Paste a reference, get the BibTeX and the PDF, highlight, take notes, export one clean <code>.bib</code>.<br>
+  Let Claude and other AI assistants file the papers they find, with verified metadata.
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/library.png" alt="The library view of Annotheca" width="900">
+</p>
+
+## Why
+
+Research projects live in stages (state of the art, method, experiments,
+writing) and the same paper often matters in several of them, for different
+reasons. Annotheca organises references the way the project is organised:
+
+- **Projects and stage folders.** Every project starts with a `SoA` (state of
+  the art) folder; add as many folders as your project has stages.
+- **Paste anything.** BibTeX (one or many entries), DOIs, arXiv IDs or URLs,
+  or a formatted citation copied from a paper (APA, IEEE, ...). Annotheca
+  resolves it into clean BibTeX through doi.org, arXiv and Crossref.
+- **PDFs found for you.** Open-access PDFs are downloaded automatically from
+  arXiv, Semantic Scholar and OpenAlex, following repository landing pages to
+  their PDF. Otherwise, drop the PDF on the paper.
+- **Highlights, sticky notes and general notes.** Highlight passages in five
+  colours, pin draggable post-its on the page, and keep general notes on each
+  paper, next to it in the list or beside the PDF.
+- **One paper, several folders, separate notes.** A paper filed in two folders
+  is stored once, but its highlights and notes are specific to each folder:
+  what you underline for the state of the art is not what you underline for
+  the method.
+- **Share a project.** *Share* downloads the project, with its folders,
+  notes, highlights and PDFs, as one `.annotheca` file; whoever receives it
+  opens it with the import button of the sidebar.
+- **Works with AI assistants.** Claude (or any MCP client) can file the papers
+  it finds into your projects, add notes, read yours and get the `.bib`. See
+  [AI assistants](#ai-assistants).
+- **One clean `.bib`.** Export the whole project in one click; papers filed in
+  several folders appear only once, with stable, unique citation keys.
+- **English and French**, light and dark themes, everything stored locally.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/reader.png" alt="Reading a paper with highlights and a sticky note" width="900">
+</p>
+
+## Install
+
+Annotheca needs Python 3.10 or newer. Install it as a command with
+[uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install annotheca
+# or
+pipx install annotheca
+```
+
+Then, to let Claude use it (optional, see [AI assistants](#ai-assistants)):
+
+```sh
+annotheca connect
+```
+
+Update later with `uv tool upgrade annotheca` (or `pipx upgrade annotheca`).
+
+## Use
+
+```sh
+annotheca
+```
+
+The interface opens in your browser at <http://127.0.0.1:8737>. Running the
+command again while Annotheca is running simply reopens it.
+
+| Option or command | Effect |
+| --- | --- |
+| `--port PORT` | Serve on another local port (default `8737`). |
+| `--data-dir DIR` | Keep the library somewhere else. |
+| `--no-browser` | Do not open the browser. |
+| `connect` | Make Annotheca available to Claude (see below). |
+| `mcp` | Serve the tools for AI assistants over stdio (used by `connect`). |
+
+Tips:
+
+- `Ctrl+Enter` adds what you pasted.
+- Click a citation key to copy `\cite{key}`.
+- Drop a PDF file on a paper to attach it.
+- In the reader, select text to highlight it; switch to *Sticky note* and
+  click on the page to pin a note; click a highlight to recolour or delete it;
+  `Esc` goes back.
+
+## AI assistants
+
+When an assistant writes references itself, it can get a title, an author or a
+year wrong. With Annotheca, the assistant only says *which* paper it means (a
+DOI, an arXiv ID, a citation); Annotheca fetches the metadata from doi.org,
+arXiv and Crossref, files the paper with its PDF, and answers with the exact
+citation key, title and authors to use. Every paper an assistant adds is marked
+with its name, so you can always see, and filter, what it relied on.
+
+`annotheca connect` registers Annotheca as an
+[MCP](https://modelcontextprotocol.io) server for **Claude Code** (in every
+project) and **Claude Desktop** when they are installed, and prints the
+configuration to paste into other MCP clients (Cursor, Codex, Gemini CLI...).
+The assistant then just needs to be asked:
+
+> Find recent papers on contact-implicit trajectory optimisation and add the
+> three most relevant to the SoA of my PhysProx project, with a note on each.
+
+> What did I highlight in posa2013direct? Write the related-work paragraph
+> citing the papers of the Method folder.
+
+| Tool | What the assistant can do |
+| --- | --- |
+| `list_projects` | See the projects and their folders. |
+| `create_project`, `create_folder` | Create them. |
+| `add_references` | File papers from DOIs, arXiv IDs, BibTeX or citations, with a note; get back verified metadata. |
+| `list_papers` | List the papers of a project with your notes. |
+| `read_paper` | Read a paper's BibTeX, your notes, highlights and sticky notes, and the path of its PDF. |
+| `add_note` | Add a signed paragraph to a paper's notes. |
+| `get_bibtex` | Get the project's `.bib`. |
+
+Nothing else is needed: the server explains itself to the assistant. Papers it
+adds appear in the interface as soon as you come back to the window.
+
+## Your data
+
+Everything stays on your machine, in `~/.local/share/annotheca` (or
+`$XDG_DATA_HOME/annotheca`, or `$ANNOTHECA_HOME`):
+
+```
+library.db   SQLite database: projects, folders, BibTeX, notes, annotations
+pdfs/        one PDF per paper
+```
+
+Back it up by copying that directory. The only network requests are the
+lookups of references and PDFs, sent to doi.org, arXiv, Crossref, Semantic
+Scholar, OpenAlex and the repositories they point to.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/library-dark.png" alt="Dark theme" width="700">
+</p>
+
+## Development
+
+```sh
+git clone https://github.com/melissa-colin/annotheca
+cd annotheca
+uv venv && uv pip install -e '.[test]'
+.venv/bin/pytest
+.venv/bin/annotheca --data-dir /tmp/annotheca-dev
+```
+
+The code follows the Google Python and JavaScript style guides. The backend is
+a small [FastAPI](https://fastapi.tiangolo.com/) app over SQLite
+(`src/annotheca`); the interface is dependency-free JavaScript modules with
+[pdf.js](https://mozilla.github.io/pdf.js/) vendored, so there is no build
+step.
+
+```
+src/annotheca/
+  cli.py         command line entry point
+  api.py         HTTP API and static files
+  library.py     storage: projects, folders, papers, placements, annotations
+  bundle.py      .annotheca files to share a project
+  mcp_server.py  tools for AI assistants (Model Context Protocol)
+  models.py      validated shapes shared by the API and the bundles
+  bibtex.py      BibTeX parsing, formatting, citation keys, identifiers
+  sources.py     doi.org, arXiv, Crossref, Semantic Scholar, OpenAlex lookups
+  static/        web interface
+```
+
+## License
+
+MIT. pdf.js is distributed under the Apache License 2.0
+(`src/annotheca/static/vendor/pdfjs/LICENSE`).

annotheca-0.1.0/README.md

@@ -0,0 +1,181 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/src/annotheca/static/favicon.svg" width="72" alt="">
+</p>
+
+<h1 align="center">Annotheca</h1>
+
+<p align="center">
+  <b>A calm, local home for the bibliography of your research projects.</b><br>
+  Paste a reference, get the BibTeX and the PDF, highlight, take notes, export one clean <code>.bib</code>.<br>
+  Let Claude and other AI assistants file the papers they find, with verified metadata.
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/library.png" alt="The library view of Annotheca" width="900">
+</p>
+
+## Why
+
+Research projects live in stages (state of the art, method, experiments,
+writing) and the same paper often matters in several of them, for different
+reasons. Annotheca organises references the way the project is organised:
+
+- **Projects and stage folders.** Every project starts with a `SoA` (state of
+  the art) folder; add as many folders as your project has stages.
+- **Paste anything.** BibTeX (one or many entries), DOIs, arXiv IDs or URLs,
+  or a formatted citation copied from a paper (APA, IEEE, ...). Annotheca
+  resolves it into clean BibTeX through doi.org, arXiv and Crossref.
+- **PDFs found for you.** Open-access PDFs are downloaded automatically from
+  arXiv, Semantic Scholar and OpenAlex, following repository landing pages to
+  their PDF. Otherwise, drop the PDF on the paper.
+- **Highlights, sticky notes and general notes.** Highlight passages in five
+  colours, pin draggable post-its on the page, and keep general notes on each
+  paper, next to it in the list or beside the PDF.
+- **One paper, several folders, separate notes.** A paper filed in two folders
+  is stored once, but its highlights and notes are specific to each folder:
+  what you underline for the state of the art is not what you underline for
+  the method.
+- **Share a project.** *Share* downloads the project, with its folders,
+  notes, highlights and PDFs, as one `.annotheca` file; whoever receives it
+  opens it with the import button of the sidebar.
+- **Works with AI assistants.** Claude (or any MCP client) can file the papers
+  it finds into your projects, add notes, read yours and get the `.bib`. See
+  [AI assistants](#ai-assistants).
+- **One clean `.bib`.** Export the whole project in one click; papers filed in
+  several folders appear only once, with stable, unique citation keys.
+- **English and French**, light and dark themes, everything stored locally.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/reader.png" alt="Reading a paper with highlights and a sticky note" width="900">
+</p>
+
+## Install
+
+Annotheca needs Python 3.10 or newer. Install it as a command with
+[uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install annotheca
+# or
+pipx install annotheca
+```
+
+Then, to let Claude use it (optional, see [AI assistants](#ai-assistants)):
+
+```sh
+annotheca connect
+```
+
+Update later with `uv tool upgrade annotheca` (or `pipx upgrade annotheca`).
+
+## Use
+
+```sh
+annotheca
+```
+
+The interface opens in your browser at <http://127.0.0.1:8737>. Running the
+command again while Annotheca is running simply reopens it.
+
+| Option or command | Effect |
+| --- | --- |
+| `--port PORT` | Serve on another local port (default `8737`). |
+| `--data-dir DIR` | Keep the library somewhere else. |
+| `--no-browser` | Do not open the browser. |
+| `connect` | Make Annotheca available to Claude (see below). |
+| `mcp` | Serve the tools for AI assistants over stdio (used by `connect`). |
+
+Tips:
+
+- `Ctrl+Enter` adds what you pasted.
+- Click a citation key to copy `\cite{key}`.
+- Drop a PDF file on a paper to attach it.
+- In the reader, select text to highlight it; switch to *Sticky note* and
+  click on the page to pin a note; click a highlight to recolour or delete it;
+  `Esc` goes back.
+
+## AI assistants
+
+When an assistant writes references itself, it can get a title, an author or a
+year wrong. With Annotheca, the assistant only says *which* paper it means (a
+DOI, an arXiv ID, a citation); Annotheca fetches the metadata from doi.org,
+arXiv and Crossref, files the paper with its PDF, and answers with the exact
+citation key, title and authors to use. Every paper an assistant adds is marked
+with its name, so you can always see, and filter, what it relied on.
+
+`annotheca connect` registers Annotheca as an
+[MCP](https://modelcontextprotocol.io) server for **Claude Code** (in every
+project) and **Claude Desktop** when they are installed, and prints the
+configuration to paste into other MCP clients (Cursor, Codex, Gemini CLI...).
+The assistant then just needs to be asked:
+
+> Find recent papers on contact-implicit trajectory optimisation and add the
+> three most relevant to the SoA of my PhysProx project, with a note on each.
+
+> What did I highlight in posa2013direct? Write the related-work paragraph
+> citing the papers of the Method folder.
+
+| Tool | What the assistant can do |
+| --- | --- |
+| `list_projects` | See the projects and their folders. |
+| `create_project`, `create_folder` | Create them. |
+| `add_references` | File papers from DOIs, arXiv IDs, BibTeX or citations, with a note; get back verified metadata. |
+| `list_papers` | List the papers of a project with your notes. |
+| `read_paper` | Read a paper's BibTeX, your notes, highlights and sticky notes, and the path of its PDF. |
+| `add_note` | Add a signed paragraph to a paper's notes. |
+| `get_bibtex` | Get the project's `.bib`. |
+
+Nothing else is needed: the server explains itself to the assistant. Papers it
+adds appear in the interface as soon as you come back to the window.
+
+## Your data
+
+Everything stays on your machine, in `~/.local/share/annotheca` (or
+`$XDG_DATA_HOME/annotheca`, or `$ANNOTHECA_HOME`):
+
+```
+library.db   SQLite database: projects, folders, BibTeX, notes, annotations
+pdfs/        one PDF per paper
+```
+
+Back it up by copying that directory. The only network requests are the
+lookups of references and PDFs, sent to doi.org, arXiv, Crossref, Semantic
+Scholar, OpenAlex and the repositories they point to.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/melissa-colin/annotheca/main/docs/library-dark.png" alt="Dark theme" width="700">
+</p>
+
+## Development
+
+```sh
+git clone https://github.com/melissa-colin/annotheca
+cd annotheca
+uv venv && uv pip install -e '.[test]'
+.venv/bin/pytest
+.venv/bin/annotheca --data-dir /tmp/annotheca-dev
+```
+
+The code follows the Google Python and JavaScript style guides. The backend is
+a small [FastAPI](https://fastapi.tiangolo.com/) app over SQLite
+(`src/annotheca`); the interface is dependency-free JavaScript modules with
+[pdf.js](https://mozilla.github.io/pdf.js/) vendored, so there is no build
+step.
+
+```
+src/annotheca/
+  cli.py         command line entry point
+  api.py         HTTP API and static files
+  library.py     storage: projects, folders, papers, placements, annotations
+  bundle.py      .annotheca files to share a project
+  mcp_server.py  tools for AI assistants (Model Context Protocol)
+  models.py      validated shapes shared by the API and the bundles
+  bibtex.py      BibTeX parsing, formatting, citation keys, identifiers
+  sources.py     doi.org, arXiv, Crossref, Semantic Scholar, OpenAlex lookups
+  static/        web interface
+```
+
+## License
+
+MIT. pdf.js is distributed under the Apache License 2.0
+(`src/annotheca/static/vendor/pdfjs/LICENSE`).

annotheca-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "annotheca"
+version = "0.1.0"
+description = "A local, bilingual reference manager for research projects: BibTeX, PDFs, highlights and sticky notes."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Melissa Colin" }]
+requires-python = ">=3.10"
+keywords = ["bibtex", "bibliography", "research", "pdf", "annotation", "reference-manager"]
+classifiers = [
+  "Environment :: Web Environment",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "fastapi>=0.110",
+  "httpx>=0.27",
+  "mcp>=2,<3",
+  "uvicorn>=0.29",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+annotheca = "annotheca.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/melissa-colin/annotheca"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

annotheca-0.1.0/src/annotheca/__init__.py

@@ -0,0 +1,3 @@
+"""Annotheca: a local reference manager for research projects."""
+
+__version__ = '0.1.0'

annotheca-0.1.0/src/annotheca/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python -m annotheca`."""
+
+from annotheca import cli
+
+cli.main()

annotheca-0.1.0/src/annotheca/api.py

@@ -0,0 +1,194 @@
+"""HTTP API and static web interface."""
+
+import mimetypes
+import pathlib
+from typing import Any
+from urllib import parse
+
+import fastapi
+import httpx
+import pydantic
+from fastapi import responses
+from fastapi import staticfiles
+
+from annotheca import bundle
+from annotheca import library as library_lib
+from annotheca import models
+from annotheca import sources
+
+_STATIC_DIR = pathlib.Path(__file__).parent / 'static'
+
+# Exception types mapped to an HTTP status and the error code the
+# interface translates for the user.
+_ERRORS = {
+    library_lib.NotFoundError: (404, 'not_found'),
+    library_lib.ConflictError: (409, 'name_taken'),
+    library_lib.InvalidPdfError: (422, 'not_pdf'),
+    bundle.InvalidBundleError: (422, 'not_bundle'),
+}
+
+
+class NameBody(pydantic.BaseModel):
+    name: models.Name
+
+
+class AddPapersBody(pydantic.BaseModel):
+    """Either pasted references or an already known paper to file."""
+    text: str | None = None
+    paper_id: int | None = None
+
+
+class NotesBody(pydantic.BaseModel):
+    notes: str
+
+
+class AnnotationChanges(pydantic.BaseModel):
+    color: models.Color | None = None
+    geometry: list[Any] | None = None
+    body: str | None = None
+
+
+def create_app(library: library_lib.Library,
+               client: httpx.Client | None = None) -> fastapi.FastAPI:
+    """Builds the web application.
+
+    Args:
+        library: Where everything is stored.
+        client: HTTP client for the scholarly sources; a default one is
+            created when omitted.
+    """
+    client = client or sources.make_client()
+    app = fastapi.FastAPI(title='Annotheca', docs_url=None, redoc_url=None)
+    api = fastapi.APIRouter(prefix='/api')
+
+    for error_type, (status, code) in _ERRORS.items():
+        app.add_exception_handler(error_type, _error_handler(status, code))
+
+    @app.exception_handler(sources.ResolveError)
+    def _resolve_error(request, error):
+        del request  # Unused.
+        return responses.JSONResponse({'detail': str(error)}, status_code=422)
+
+    @api.get('/projects')
+    def list_projects():
+        return library.list_projects()
+
+    @api.post('/projects', status_code=201)
+    def create_project(body: NameBody):
+        return library.create_project(body.name)
+
+    @api.get('/projects/{project_id}')
+    def get_project(project_id: int):
+        return library.get_project(project_id)
+
+    @api.get('/projects/{project_id}/bibtex')
+    def export_bibtex(project_id: int):
+        name, content = library.export_bibtex(project_id)
+        return _download(content, f'{name}.bib', 'application/x-bibtex')
+
+    @api.get('/projects/{project_id}/bundle')
+    def export_bundle(project_id: int):
+        """The project with its notes, annotations and PDFs, to share."""
+        name, content = bundle.export_project(library, project_id)
+        return _download(content, f'{name}.annotheca', 'application/zip')
+
+    @api.post('/projects/import', status_code=201)
+    async def import_bundle(request: fastapi.Request):
+        return bundle.import_project(library, await request.body())
+
+    @api.post('/projects/{project_id}/folders', status_code=201)
+    def create_folder(project_id: int, body: NameBody):
+        return library.create_folder(project_id, body.name)
+
+    @api.patch('/projects/{project_id}', status_code=204)
+    def rename_project(project_id: int, body: NameBody):
+        library.rename('project', project_id, body.name)
+
+    @api.delete('/projects/{project_id}', status_code=204)
+    def delete_project(project_id: int):
+        library.delete('project', project_id)
+
+    @api.patch('/folders/{folder_id}', status_code=204)
+    def rename_folder(folder_id: int, body: NameBody):
+        library.rename('folder', folder_id, body.name)
+
+    @api.delete('/folders/{folder_id}', status_code=204)
+    def delete_folder(folder_id: int):
+        library.delete('folder', folder_id)
+
+    @api.post('/folders/{folder_id}/papers')
+    def add_papers(folder_id: int, body: AddPapersBody):
+        """Files pasted references, or a known paper, in a folder."""
+        if body.paper_id is not None:
+            paper_ids = [body.paper_id]
+        elif body.text and body.text.strip():
+            entries = sources.resolve(body.text, client)
+            paper_ids = list(dict.fromkeys(map(library.add_paper, entries)))
+        else:
+            raise sources.ResolveError('unresolvable')
+        added = library.file_papers(folder_id, paper_ids)
+        return {'paper_ids': paper_ids, 'added': added,
+                'already_there': len(paper_ids) - added}
+
+    @api.put('/placements/{placement_id}/notes', status_code=204)
+    def set_notes(placement_id: int, body: NotesBody):
+        library.set_notes(placement_id, body.notes)
+
+    @api.delete('/placements/{placement_id}', status_code=204)
+    def remove_placement(placement_id: int):
+        library.remove_placement(placement_id)
+
+    @api.get('/papers/{paper_id}/pdf')
+    def get_pdf(paper_id: int):
+        path = library.pdf_path(paper_id)
+        if not path.exists():
+            raise library_lib.NotFoundError
+        return responses.FileResponse(path, media_type='application/pdf')
+
+    @api.put('/papers/{paper_id}/pdf', status_code=204)
+    async def upload_pdf(paper_id: int, request: fastapi.Request):
+        library.save_pdf(paper_id, await request.body())
+
+    @api.post('/papers/{paper_id}/pdf/fetch')
+    def fetch_pdf(paper_id: int):
+        """Looks for an open-access PDF; reports whether one was found."""
+        pdf = sources.find_pdf(library.get_paper(paper_id), client)
+        if pdf:
+            library.save_pdf(paper_id, pdf)
+        return {'found': pdf is not None}
+
+    @api.get('/placements/{placement_id}/annotations')
+    def list_annotations(placement_id: int):
+        return library.list_annotations(placement_id)
+
+    @api.post('/placements/{placement_id}/annotations', status_code=201)
+    def create_annotation(placement_id: int, body: models.Annotation):
+        return library.create_annotation(placement_id, body.model_dump())
+
+    @api.patch('/annotations/{annotation_id}')
+    def update_annotation(annotation_id: int, body: AnnotationChanges):
+        return library.update_annotation(
+            annotation_id, body.model_dump(exclude_none=True))
+
+    @api.delete('/annotations/{annotation_id}', status_code=204)
+    def delete_annotation(annotation_id: int):
+        library.delete_annotation(annotation_id)
+
+    app.include_router(api)
+    mimetypes.add_type('text/javascript', '.mjs')
+    app.mount('/', staticfiles.StaticFiles(directory=_STATIC_DIR, html=True))
+    return app
+
+
+def _download(content: str | bytes, filename: str,
+              media_type: str) -> responses.Response:
+    disposition = f"attachment; filename*=UTF-8''{parse.quote(filename)}"
+    return responses.Response(content, media_type=media_type,
+                              headers={'Content-Disposition': disposition})
+
+
+def _error_handler(status: int, code: str):
+    def handle(request: fastapi.Request, error: Exception):
+        del request, error  # Unused.
+        return responses.JSONResponse({'detail': code}, status_code=status)
+    return handle