pagecite 2.0.0__py3-none-any.whl

pagecite/__init__.py

@@ -0,0 +1,3 @@
+"""pagecite: summarise research PDFs where every claim cites its page and is checked against the text."""
+
+__version__ = "2.0.0"

pagecite/__main__.py

@@ -0,0 +1,203 @@
+"""pagecite: summarise research PDFs where every claim cites its page and is checked against the text."""
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import DATA_DIR, Settings, load_env
+
+
+def fail(message: str) -> int:
+    print(f"Error: {message}", file=sys.stderr)
+    return 1
+
+
+def open_store(settings: Settings):
+    from .store import Store
+
+    return Store(settings.db_path)
+
+
+def expand(sources: list[str]) -> list[str]:
+    """Folders become the PDFs inside them; files and URLs pass through."""
+    from .pdf import find_pdfs, is_url
+
+    out = []
+    for s in sources:
+        path = Path(s).expanduser()
+        if not is_url(s) and path.is_dir():
+            found = find_pdfs(path)
+            if not found:
+                print(f"No PDFs in {s}", file=sys.stderr)
+            out += [str(p) for p in found]
+        else:
+            out.append(s)
+    return out
+
+
+def cmd_summarize(args, settings: Settings) -> int:
+    from . import library, render
+    from .pdf import PDFError
+    from .summarize import ClaudeError, Summarizer
+
+    store, summarizer = open_store(settings), Summarizer(model=settings.model)
+    notes = Path(args.output).expanduser() if args.output else settings.notes_dir
+    sources, failed = expand(args.sources), 0
+    for i, source in enumerate(sources):
+        if len(sources) > 1:
+            print(f"[{i + 1}/{len(sources)}] {source}", file=sys.stderr)
+        try:
+            result = library.summarize(source, store, summarizer, args.refresh)
+        except (PDFError, ClaudeError) as e:
+            failed += 1
+            fail(str(e))
+            continue
+        doc, pages = store.doc(result.doc_id), store.pages(result.doc_id)
+        if i:
+            print("\n" + "─" * 60 + "\n")
+        print(render.terminal(result.summary, doc, pages, color=sys.stdout.isatty()))
+        if result.cached:
+            print(f"\n(from your library, #{result.doc_id}; --refresh to summarise again)", file=sys.stderr)
+        if notes:
+            print(f"Note: {render.write_note(result.summary, doc, pages, notes)}", file=sys.stderr)
+    return 1 if failed else 0
+
+
+def cmd_ask(args, settings: Settings) -> int:
+    from .ask import Asker
+
+    answer = Asker(open_store(settings), model=settings.model).ask(" ".join(args.question), args.doc)
+    sources = answer.sources()
+    index = {(c.doc_id, c.page): n for n, c in enumerate(sources, 1)}
+    text = ""
+    for part in answer.parts:
+        marks = sorted({index[(c.doc_id, c.page)] for c in part.cites})
+        text += part.text + "".join(f"[{m}]" for m in marks)
+    print(text.strip())
+    if sources:
+        print("\nSources")
+        for n, c in enumerate(sources, 1):
+            excerpt = " ".join(c.text.split())
+            print(f"  [{n}] {c.title}, p. {c.page} (#{c.doc_id}): “{excerpt[:160]}{'…' if len(excerpt) > 160 else ''}”")
+    return 0
+
+
+def cmd_list(args, settings: Settings) -> int:
+    docs = open_store(settings).docs()
+    if not docs:
+        print("Your library is empty. Start with: pagecite summarize paper.pdf")
+    for d in docs:
+        mark = "" if d["summary"] else "  (not summarised)"
+        print(f"#{d['id']:<4} {d['title']}  ·  {d['page_count']} pages  ·  {d['added_at'][:10]}{mark}")
+    return 0
+
+
+def cmd_show(args, settings: Settings) -> int:
+    from . import render
+
+    store = open_store(settings)
+    doc, summary = store.doc(args.id), store.summary(args.id)
+    if doc is None:
+        return fail(f"No document #{args.id}. See `pagecite list`.")
+    if summary is None:
+        return fail(f"#{args.id} has no summary yet: pagecite summarize {doc['source']}")
+    pages = store.pages(args.id)
+    print(render.markdown(summary, doc, pages) if args.markdown else
+          render.terminal(summary, doc, pages, color=sys.stdout.isatty()))
+    return 0
+
+
+def cmd_search(args, settings: Settings) -> int:
+    hits = open_store(settings).search(" ".join(args.query), args.limit, args.doc)
+    if not hits:
+        print("No matching pages.")
+    for h in hits:
+        print(f"#{h['doc_id']} {h['title']}, p. {h['n']}\n    {' '.join(h['snippet'].split())}")
+    return 0
+
+
+def cmd_mcp(args, settings: Settings) -> int:
+    if importlib.util.find_spec("mcp") is None:
+        return fail("The MCP server needs the mcp extra: pipx install 'pagecite[mcp]'")
+    from .ask import Asker
+    from .mcp_server import build_server
+    from .summarize import Summarizer
+
+    store = open_store(settings)
+    build_server(store, Summarizer(model=settings.model), Asker(store, model=settings.model)).run("stdio")
+    return 0
+
+
+def cmd_demo(args, settings: Settings) -> int:
+    from . import render
+    from .demo import sample
+
+    doc, summary = sample()
+    meta = {"title": doc.title, "source": doc.source, "page_count": doc.page_count}
+    print("Demo: a fictional 4-page report and a sample summary bundled with pagecite (no API call).\n"
+          "The checks are real: two sample claims are deliberately wrong.\n", file=sys.stderr)
+    print(render.terminal(summary, meta, doc.pages, color=sys.stdout.isatty()))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pagecite", description=__doc__)
+    p.add_argument("--version", action="version", version=f"pagecite {__version__}")
+    p.add_argument("--db", help=f"library file (default {DATA_DIR / 'library.db'})")
+    sub = p.add_subparsers(dest="command")
+
+    s = sub.add_parser("summarize", aliases=["sum"], help="summarise PDFs: files, folders or http(s) URLs")
+    s.add_argument("sources", nargs="+")
+    s.add_argument("-o", "--output", help="also write each summary as a Markdown note into this folder")
+    s.add_argument("--refresh", action="store_true", help="summarise again even if the file is in your library")
+
+    a = sub.add_parser("ask", help="ask your library (or one document) a question; the answer cites pages")
+    a.add_argument("question", nargs="+")
+    a.add_argument("--doc", type=int, help="only this document (id from `pagecite list`)")
+
+    sub.add_parser("list", aliases=["ls"], help="the PDFs in your library")
+
+    sh = sub.add_parser("show", help="print a stored summary")
+    sh.add_argument("id", type=int)
+    sh.add_argument("--markdown", action="store_true", help="as an Obsidian note")
+
+    se = sub.add_parser("search", help="full-text search over every page you've read")
+    se.add_argument("query", nargs="+")
+    se.add_argument("--doc", type=int, help="only this document")
+    se.add_argument("-n", "--limit", type=int, default=10)
+
+    sub.add_parser("mcp", help="run the MCP server over stdio (for Claude Desktop, Claude Code, …)")
+    sub.add_parser("demo", help="see a checked summary on a fictional report (no API key needed)")
+    return p
+
+
+COMMANDS = {"summarize": cmd_summarize, "sum": cmd_summarize, "ask": cmd_ask, "list": cmd_list, "ls": cmd_list,
+            "show": cmd_show, "search": cmd_search, "mcp": cmd_mcp, "demo": cmd_demo}
+
+
+def main(argv: list[str] | None = None) -> int:
+    load_env(Path.cwd() / ".env")
+    load_env(DATA_DIR / ".env")
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    settings = Settings.from_env()
+    if args.db:
+        settings.db_path = Path(args.db).expanduser()
+
+    from .summarize import ClaudeError
+
+    try:
+        return COMMANDS[args.command](args, settings)
+    except ClaudeError as e:
+        return fail(str(e))
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pagecite/ask.py

@@ -0,0 +1,125 @@
+"""Ask a question of one document or your whole library. Pages go to Claude as search-result
+blocks with citations on, so every sentence of the answer points to a document and a page, and
+the cited text is returned by the API itself rather than written by the model.
+
+For one document every page is sent, with a cache breakpoint after the last one, so follow-up
+questions about the same PDF read the pages from the prompt cache. Across the library, only the
+best-matching pages (full-text search) are sent."""
+
+from dataclasses import dataclass, field
+
+import anthropic
+
+from .store import Store
+from .summarize import MAX_CHARS, ClaudeError, call_errors
+
+SYSTEM_PROMPT = """You answer questions about the user's documents using only the pages provided. Each
+search result is one page of one document. Be brief and concrete. If the pages don't answer the
+question, say so plainly instead of guessing. Keep the document's hedges: an estimate stays an
+estimate."""
+
+
+@dataclass
+class Cite:
+    doc_id: int
+    title: str
+    page: int
+    text: str
+
+
+@dataclass
+class Part:
+    text: str
+    cites: list[Cite] = field(default_factory=list)
+
+
+@dataclass
+class Answer:
+    parts: list[Part]
+    pages_sent: int = 0
+
+    @property
+    def text(self) -> str:
+        return "".join(p.text for p in self.parts)
+
+    def sources(self) -> list[Cite]:
+        """Distinct citations in the order they first appear."""
+        seen, out = set(), []
+        for p in self.parts:
+            for c in p.cites:
+                if (c.doc_id, c.page) not in seen:
+                    seen.add((c.doc_id, c.page))
+                    out.append(c)
+        return out
+
+
+def search_blocks(pages: list[dict], cache: bool = False) -> list[dict]:
+    blocks = [
+        {
+            "type": "search_result",
+            "source": f"doc:{p['doc_id']}#page={p['n']}",
+            "title": f"{p['title']}, p. {p['n']}",
+            "content": [{"type": "text", "text": p["text"].strip() or "(no text on this page)"}],
+            "citations": {"enabled": True},
+        }
+        for p in pages
+    ]
+    if cache and blocks:
+        blocks[-1]["cache_control"] = {"type": "ephemeral"}
+    return blocks
+
+
+def to_parts(content, pages: list[dict]) -> list[Part]:
+    parts = []
+    for block in content:
+        if block.type != "text":
+            continue
+        cites = []
+        for c in getattr(block, "citations", None) or []:
+            if getattr(c, "type", "") != "search_result_location" or not 0 <= c.search_result_index < len(pages):
+                continue
+            p = pages[c.search_result_index]
+            cites.append(Cite(p["doc_id"], p["title"], p["n"], c.cited_text))
+        parts.append(Part(block.text, cites))
+    return parts
+
+
+class Asker:
+    def __init__(self, store: Store, client: anthropic.Anthropic | None = None, model: str = "claude-opus-5-5"):
+        self.store = store
+        self._client = client
+        self.model = model
+
+    @property
+    def client(self) -> anthropic.Anthropic:
+        if self._client is None:
+            self._client = anthropic.Anthropic()
+        return self._client
+
+    def pages_for(self, question: str, doc_id: int | None, limit: int) -> tuple[list[dict], bool]:
+        """The pages to send, and whether they are a whole document (worth caching)."""
+        if doc_id is not None:
+            doc = self.store.doc(doc_id)
+            if doc is None:
+                raise ClaudeError(f"No document #{doc_id} in the library.")
+            texts = self.store.pages(doc_id)
+            if sum(len(t) for t in texts) <= MAX_CHARS:
+                return [{"doc_id": doc_id, "n": n, "text": t, "title": doc["title"]} for n, t in enumerate(texts, 1)], True
+        return self.store.search(question, limit, doc_id), False
+
+    def ask(self, question: str, doc_id: int | None = None, limit: int = 12) -> Answer:
+        pages, whole = self.pages_for(question, doc_id, limit)
+        if not pages:
+            return Answer([Part("Nothing in your library matches that question.")])
+        response = call_errors(lambda: self.client.beta.messages.create(
+            model=self.model,
+            max_tokens=4000,
+            system=SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": [*search_blocks(pages, cache=whole), {"type": "text", "text": question}]}],
+            output_config={"effort": "low"},
+            betas=["server-side-fallback-2026-07-01"],
+            fallbacks="default",
+        ))
+        if response.stop_reason == "refusal":
+            raise ClaudeError("Claude declined to answer this one.")
+        return Answer(to_parts(response.content, pages), len(pages))

pagecite/config.py

@@ -0,0 +1,35 @@
+"""Settings come from environment variables, optionally loaded from a .env file."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DATA_DIR = Path(os.environ.get("PAGECITE_HOME", Path.home() / ".pagecite"))
+
+
+def load_env(path: Path) -> None:
+    """Load KEY=VALUE lines into os.environ without overriding variables already set."""
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, _, value = line.partition("=")
+            os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+@dataclass
+class Settings:
+    db_path: Path = DATA_DIR / "library.db"
+    model: str = "claude-opus-5-5"
+    notes_dir: Path | None = None  # where `summarize` writes Markdown notes when no -o is given
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        e = os.environ.get
+        notes = e("PAGECITE_NOTES_DIR", "").strip()
+        return cls(
+            db_path=Path(e("PAGECITE_DB", str(DATA_DIR / "library.db"))).expanduser(),
+            model=e("PAGECITE_MODEL", "claude-opus-5-5"),
+            notes_dir=Path(notes).expanduser() if notes else None,
+        )

pagecite/demo.py

@@ -0,0 +1,82 @@
+"""`pagecite demo`: a fictional four-page report, built as a real PDF, and a sample summary written
+for the demo (no API call). The verification that runs on it is the real one: two of the sample
+claims are deliberately wrong, so you can see what a flagged claim looks like."""
+
+import pymupdf
+
+from .pdf import Document, from_bytes
+from .summarize import Summary
+
+PAGES = [
+    """The State of Urban Cargo Bikes 2026
+Northside Mobility Lab - Annual Report (fictional demo document)
+
+Executive summary
+Cargo bikes moved from niche to mainstream in European city logistics this year. Across the 14 cities
+we tracked, operators made 2.3 million deliveries by cargo bike, up from 1.6 million in 2025.
+Our central finding is that cargo bikes now beat vans on cost per parcel in dense city centres,
+but only where cities provide loading space and protected lanes.""",
+    """Market size
+We estimate the European cargo bike logistics market at EUR 1.9bn in 2026, growing at roughly 18% a year.
+This estimate is based on operator surveys and should be read as a range rather than a point figure.
+
+Cost per parcel
+In the densest districts the average cost per parcel was EUR 1.42 by cargo bike against EUR 2.10 by van.
+Outside the city centre the advantage disappears: vans were cheaper beyond a 6 km delivery radius.""",
+    """What holds adoption back
+Operators named the lack of loading bays as the single biggest obstacle, ahead of theft and weather.
+Insurance premiums rose 22% year on year, which several smaller operators said threatens their margins.
+Where cities built protected lanes, delivery times fell by 11% on average.""",
+    """Outlook
+We expect growth to continue but slow, as the easiest routes have already been converted.
+The open question is whether cities will reallocate kerb space from parking to loading at the pace
+operators need. Without that, the cost advantage we measured may not survive outside a few showcase districts.""",
+]
+
+SAMPLE = {
+    "title": "The State of Urban Cargo Bikes 2026",
+    "model": "sample summary (written for the demo, not by Claude)",
+    "tldr": "A fictional annual report on cargo-bike delivery in 14 European cities: volumes grew sharply and cargo "
+            "bikes now undercut vans on cost per parcel in dense centres, but only with loading space and protected lanes.",
+    "tldr_pages": [1, 2],
+    "arguments": [
+        {"text": "Cargo bikes are cheaper than vans per parcel in dense city centres, conditional on city infrastructure.",
+         "pages": [1], "quote": "cargo bikes now beat vans on cost per parcel in dense city centres"},
+        {"text": "Beyond a short delivery radius the cost advantage reverses in favour of vans.",
+         "pages": [2], "quote": "vans were cheaper beyond a 6 km delivery radius"},
+        {"text": "Missing loading bays are the main barrier to adoption.",
+         "pages": [1], "quote": "the lack of loading bays as the single biggest obstacle"},
+    ],
+    "data_points": [
+        {"text": "Cargo-bike deliveries across the 14 cities in 2026 (1.6 million in 2025).", "value": "2.3 million",
+         "pages": [1], "quote": "operators made 2.3 million deliveries by cargo bike"},
+        {"text": "Estimated European market size, an estimate from operator surveys.", "value": "EUR 1.9bn",
+         "pages": [2], "quote": "European cargo bike logistics market at EUR 1.9bn in 2026"},
+        {"text": "Rise in insurance premiums year on year.", "value": "27%",
+         "pages": [3], "quote": "Insurance premiums rose 22% year on year"},
+    ],
+    "quotes": [
+        {"quote": "Without that, the cost advantage we measured may not survive outside a few showcase districts.",
+         "pages": [4], "why": "The report's own caveat on its headline finding."},
+    ],
+    "open_questions": [
+        {"text": "Will cities reallocate kerb space from parking to loading fast enough?", "pages": [4]},
+        {"text": "How wide is the range around the EUR 1.9bn market estimate?", "pages": [2]},
+    ],
+    "tags": ["cargo-bikes", "urban-logistics", "last-mile", "transport-policy"],
+}
+
+
+def sample_pdf() -> bytes:
+    doc = pymupdf.open()
+    for text in PAGES:
+        page = doc.new_page()
+        page.insert_textbox(pymupdf.Rect(60, 60, 540, 780), text, fontsize=11)
+    doc.set_metadata({"title": "The State of Urban Cargo Bikes 2026"})
+    data = doc.tobytes()
+    doc.close()
+    return data
+
+
+def sample() -> tuple[Document, Summary]:
+    return from_bytes(sample_pdf(), "cargo-bikes-2026.pdf (demo)"), Summary.from_json(SAMPLE)

pagecite/library.py

@@ -0,0 +1,27 @@
+"""Read a PDF into the library and summarise it, reusing the stored summary when the same file
+(same SHA-256) was summarised before."""
+
+from dataclasses import dataclass
+
+from . import pdf
+from .store import Store
+from .summarize import Summarizer, Summary
+
+
+@dataclass
+class Result:
+    doc_id: int
+    summary: Summary
+    cached: bool
+
+
+def summarize(source: str, store: Store, summarizer: Summarizer, refresh: bool = False) -> Result:
+    doc = pdf.load(source)
+    doc_id = store.add(doc)
+    if not refresh:
+        cached = store.summary(doc_id)
+        if cached is not None:
+            return Result(doc_id, cached, True)
+    summary = summarizer.summarize(doc)
+    store.save_summary(doc_id, summary)
+    return Result(doc_id, summary, False)

pagecite/mcp_server.py

@@ -0,0 +1,105 @@
+"""An MCP server over your PDF library, so Claude Desktop, Claude Code or any MCP client can
+summarise PDFs with checked citations, search every page you've read, and ask cited questions.
+Runs locally over stdio: `pagecite mcp`.
+
+search, documents and read_pages need no Anthropic key: they return page text and the client's own
+model does the reasoning. summarize (for a new file) and ask call Claude.
+"""
+
+from . import library
+from .ask import Asker
+from .pdf import PDFError
+from .store import Store
+from .summarize import Summarizer
+
+
+class ToolError(Exception):
+    pass
+
+
+def _claim(claim, check) -> dict:
+    out = {k: v for k, v in vars(claim).items() if v not in ("", [])}
+    out["check"] = check.status
+    if check.reason:
+        out["reason"] = check.reason
+    return out
+
+
+def _checked(store: Store, doc_id: int) -> dict:
+    doc, summary, pages = store.doc(doc_id), store.summary(doc_id), store.pages(doc_id)
+    out = {"id": doc_id, "title": summary.title or doc["title"], "source": doc["source"], "pages": doc["page_count"],
+           "tldr": summary.tldr, "tldr_pages": summary.tldr_pages, "tags": summary.tags, "counts": summary.counts(pages)}
+    for section, rows in summary.checked(pages).items():
+        out[section] = [_claim(c, check) for c, check in rows]
+    return out
+
+
+def list_documents(store: Store) -> list[dict]:
+    return [{"id": d["id"], "title": d["title"], "source": d["source"], "pages": d["page_count"],
+             "summarized": bool(d["summary"])} for d in store.docs()]
+
+
+def search_pages(store: Store, query: str, limit: int = 10, doc_id: int | None = None) -> list[dict]:
+    hits = store.search(query, max(1, min(limit, 50)), doc_id)
+    return [{"doc_id": h["doc_id"], "title": h["title"], "page": h["n"], "snippet": h["snippet"]} for h in hits]
+
+
+def read_pages(store: Store, doc_id: int, pages: list[int]) -> list[dict]:
+    doc = store.doc(doc_id)
+    if doc is None:
+        raise ToolError(f"No document #{doc_id}.")
+    texts = store.pages(doc_id)
+    wanted = [p for p in dict.fromkeys(pages) if 1 <= p <= len(texts)][:20]
+    if not wanted:
+        raise ToolError(f"Document #{doc_id} has pages 1-{len(texts)}.")
+    return [{"page": p, "text": texts[p - 1]} for p in wanted]
+
+
+def summarize(store: Store, summarizer: Summarizer, source: str, refresh: bool = False) -> dict:
+    try:
+        result = library.summarize(source, store, summarizer, refresh)
+    except PDFError as e:
+        raise ToolError(str(e)) from e
+    return _checked(store, result.doc_id) | {"from_cache": result.cached}
+
+
+def ask(asker: Asker, question: str, doc_id: int | None = None) -> dict:
+    answer = asker.ask(question, doc_id)
+    return {"answer": answer.text,
+            "sources": [{"doc_id": c.doc_id, "title": c.title, "page": c.page, "cited_text": c.text} for c in answer.sources()]}
+
+
+def build_server(store: Store, summarizer: Summarizer, asker: Asker):
+    from mcp.server.mcpserver import MCPServer
+
+    server = MCPServer(
+        "pagecite",
+        instructions=(
+            "The user's library of PDFs (papers, reports, decks) with page-level text and summaries. Every "
+            "summary claim cites pages; check='verified' means its quote and numbers were found on that page, "
+            "'flagged' means they were not (reason given). Cite documents by title and page as p. N."
+        ),
+    )
+
+    @server.tool(description="List the PDFs in the library, newest first.")
+    def documents() -> list[dict]:
+        return list_documents(store)
+
+    @server.tool(description="Full-text search over every page of every PDF (or one document). Returns doc id, title, page and a snippet.")
+    def search(query: str, limit: int = 10, doc_id: int | None = None) -> list[dict]:
+        return search_pages(store, query, limit, doc_id)
+
+    @server.tool(description="The full text of up to 20 pages of one document.")
+    def read(doc_id: int, pages: list[int]) -> list[dict]:
+        return read_pages(store, doc_id, pages)
+
+    @server.tool(description="Summarise a PDF (local path or http(s) URL): TL;DR, arguments, data points, quotes, open "
+                             "questions, each with pages and a verification result. Reuses the stored summary unless refresh.")
+    def summarize_pdf(source: str, refresh: bool = False) -> dict:
+        return summarize(store, summarizer, source, refresh)
+
+    @server.tool(description="Ask a question of one document (doc_id) or the whole library. The answer cites document and page.")
+    def ask_library(question: str, doc_id: int | None = None) -> dict:
+        return ask(asker, question, doc_id)
+
+    return server

pagecite/pdf.py

@@ -0,0 +1,80 @@
+"""Load a PDF from a file, a URL or raw bytes and split it into page texts (pages are 1-indexed)."""
+
+import hashlib
+import ssl
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+import pymupdf
+import truststore
+
+MAX_BYTES = 100 * 1024 * 1024  # refuse anything bigger than this from a URL
+
+
+class PDFError(Exception):
+    pass
+
+
+@dataclass
+class Document:
+    sha: str
+    title: str
+    source: str
+    pages: list[str]
+
+    @property
+    def page_count(self) -> int:
+        return len(self.pages)
+
+    def has_text(self) -> bool:
+        return any(p.strip() for p in self.pages)
+
+
+def is_url(source: str) -> bool:
+    return source.startswith(("http://", "https://"))
+
+
+def fetch(url: str, timeout: float = 30) -> bytes:
+    request = urllib.request.Request(url, headers={"User-Agent": "pagecite (+https://github.com/owen-alderson/pagecite)"})
+    try:
+        # The OS trust store, so downloads work on python.org builds that ship without CA certificates.
+        context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
+            data = response.read(MAX_BYTES + 1)
+    except (urllib.error.URLError, TimeoutError, ValueError) as e:
+        raise PDFError(f"Could not download {url}: {getattr(e, 'reason', e)}") from e
+    if len(data) > MAX_BYTES:
+        raise PDFError(f"{url} is larger than {MAX_BYTES // (1024 * 1024)} MB.")
+    return data
+
+
+def from_bytes(data: bytes, source: str, name: str = "") -> Document:
+    if not data.lstrip()[:5].startswith(b"%PDF"):
+        raise PDFError(f"{source} is not a PDF.")
+    try:
+        doc = pymupdf.open(stream=data, filetype="pdf")
+    except Exception as e:  # pymupdf raises its own error types for damaged files
+        raise PDFError(f"Could not read {source}: {e}") from e
+    if doc.needs_pass:
+        raise PDFError(f"{source} is password-protected.")
+    with doc:
+        pages = [page.get_text() for page in doc]
+        title = ((doc.metadata or {}).get("title") or "").strip()
+    return Document(hashlib.sha256(data).hexdigest(), title or name or source, source, pages)
+
+
+def load(source: str) -> Document:
+    """A path or an http(s) URL."""
+    if is_url(source):
+        name = source.rstrip("/").rsplit("/", 1)[-1].split("?")[0]
+        return from_bytes(fetch(source), source, name[:-4] if name.lower().endswith(".pdf") else name)
+    path = Path(source).expanduser()
+    if not path.is_file():
+        raise PDFError(f"No such file: {source}")
+    return from_bytes(path.read_bytes(), str(path), path.stem)
+
+
+def find_pdfs(folder: Path) -> list[Path]:
+    return sorted(p for p in folder.iterdir() if p.is_file() and p.suffix.lower() == ".pdf")