dirag 0.1.0__tar.gz

dirag-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.sqlite3

dirag-0.1.0/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+dirag is a public, local-first tool: index a folder of PDF books, search it, and
+read the page each result comes from. `README.md` is usage for people; this file
+is how to work on the code.
+
+## Writing rules
+
+- **Public project.** No personal names, machines, paths, libraries or usage
+  anywhere: code, comments, docs, examples, test data.
+- **Current state, procedural.** Comments and docs say what the code does and
+  how to use it now. No history, no "used to", no reasons that only made sense
+  for an earlier version. Git keeps the story.
+- **ASCII only** in code comments and Markdown. Check with
+  `LC_ALL=C grep -rn '[^ -~]' --include='*.py' --include='*.md' --include='*.js' --include='*.css' --include='*.html' .`
+- **Minimal UI text.** Labels are one or two words; no instructions on screen.
+  Icons are Bootstrap Icons 1.11.3, paths copied verbatim from the upstream file
+  into `static/icons.js` with the icon's name beside each; never draw one.
+
+## Layout
+
+```text
+src/dirag/
+  cli.py         dirag [serve] | index | find | where | toc
+  config.py      DIRAG_HOME, DIRAG_STATE, the library folder, per-folder index path
+  jobs.py        the indexing job: job.json, start/stop from the app, stop checks
+  toc.py         a PDF's table of contents -> page-partitioned sections
+  index.py       update | reindex | rechunk: PDFs -> sections -> passages -> sqlite
+  embed.py       the local models' device (GPU when it works, else CPU), embeddings
+  search.py      modes (lexical, semantic, hybrid), rerank hook, per-book cap, chapters
+  rerank.py      neural (fastembed cross-encoder) and llm rerankers
+  llm.py         Ollama client: live availability, model pull, chat with an 8k context
+  answer.py      quotes chosen by the model, verified, located on their pages
+  state.py       positions, bookmarks, cards; per-key writes
+  server.py      stdlib HTTP server and the JSON API
+  static/        index.html, app.js, app.css, icons.js, favicon.svg
+    vendor/      pdf.js (pdf.min.mjs, pdf.worker.min.mjs, LICENSE.pdfjs)
+```
+
+## Invariants
+
+- **Books are keyed by path relative to the library folder**, in the index and
+  in every state file. Index ids are for requests only; they change on rebuild.
+- **A request never names a file.** Books by id, passages by chunk id, static
+  files from the list built at startup.
+- **State writes are per key**, merged into the file on disk, written through a
+  temp file and rename. Never accept a whole document from a client.
+- **The stored passage text is verbatim.** The chapter header is embedded with
+  the passage but never stored on it or shown.
+- **Two BM25 indexes**: `chunks_fts` (passage text) and `sections_fts` (section
+  titles). Do not fold titles into the passage index.
+- **Pipeline order**: retrieve -> dedupe -> rerank -> per-book cap. The cap
+  comes last so it applies to the final order.
+- **A language model never writes text shown as a source.** The llm reranker
+  returns passage numbers only; numbers out of range or repeated are ignored,
+  and the passages it leaves out stay in the list marked `dropped`. An answer
+  quote is shown only as the passage's own text for the span it matched (on
+  letters and digits); the model's response (one to three sentences) loses
+  citations to anything not quoted and is dropped when none remain.
+- **Marks are rectangles in PDF points** (`rects`): a result's passage bbox, or
+  an answer quote's line boxes found through the page's words. The page image
+  and the reader draw the same list.
+- **One install, no setup.** The dependencies are the GPU build of onnxruntime
+  (CPU build on macOS); `embed.build` uses the GPU only when nvidia-smi names
+  one and a first inference succeeds without onnxruntime falling back, and
+  otherwise runs on the CPU with the CPU provider named explicitly. The AI
+  features exist only while Ollama answers with the model; nothing else
+  depends on them.
+- **No build step.** The browser loads `static/` as is; pdf.js is vendored. To
+  update pdf.js, copy `build/pdf.min.mjs`, `build/pdf.worker.min.mjs` and
+  `LICENSE` from the `pdfjs-dist` npm package into `static/vendor/`.
+- **Indexing is resumable**: one commit per book; a book is skipped when its
+  size and mtime match, else when its content hash matches; cached page blocks
+  in `pages` mean `--rechunk` never re-parses.
+- **One indexing job at a time**, recorded in `job.json` by the indexer itself,
+  so the app shows and stops a run started from either place. Stop is a request
+  checked before each book and after each embedding batch; the book in progress
+  rolls back. Liveness is checked through /proc (not a zombie, still a dirag
+  indexer), so a crashed run reads as failed.
+- **One index per library folder** (`indexes/<name>-<hash>.sqlite3`); switching
+  folders never touches another folder's index.
+- **The folder picker is confined** to the browse root, and `DIRAG_LIBRARY`
+  disables changing the folder from the app.
+
+## Running from a checkout
+
+```sh
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python -e .
+.venv/bin/dirag
+```
+
+Release: `uv build`, then `uv publish` (version in `pyproject.toml` and
+`src/dirag/__init__.py`). Check the wheel carries `static/` and `static/vendor/`.

dirag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baris Arat
+
+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.

dirag-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: dirag
+Version: 0.1.0
+Summary: Search a folder of PDF books, read the page each result comes from, and get answers quoted from the books.
+Project-URL: Homepage, https://github.com/barisarat/dirag
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bm25,books,embeddings,ollama,pdf,rag,search
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Requires-Dist: fastembed-gpu>=0.8; sys_platform == 'linux' or sys_platform == 'win32'
+Requires-Dist: fastembed>=0.8; sys_platform == 'darwin'
+Requires-Dist: onnxruntime-gpu[cuda,cudnn]>=1.22; sys_platform == 'linux' or sys_platform == 'win32'
+Requires-Dist: pymupdf
+Requires-Dist: sqlite-vec
+Description-Content-Type: text/markdown
+
+# dirag
+
+Search a folder of PDF books, read the page each result comes from, and get
+answers quoted from the books.
+
+dirag indexes a library of PDFs once, then answers a query with ranked passages:
+book, chapter, page and a snippet. Each result opens the rendered page with the
+passage marked on it, or the whole book in the built-in reader at that page.
+
+- Passages carry their chapter, taken from each PDF's table of contents.
+- Three retrieval modes: lexical (BM25), semantic (embeddings), and hybrid
+  (both, fused by rank). An optional rerank reads query and passage together:
+  neural (a local cross-encoder) or an LLM.
+- Results are capped per book, so one long series does not fill the list.
+- The AI answer quotes the books: a language model picks the passages and the
+  words, dirag checks every quote against the text and shows it in the book's
+  own words, marked on its page.
+- The reader remembers the page you stopped on in every book.
+- Everything runs locally. No account, no network after the first downloads.
+
+## Start
+
+```sh
+uvx dirag
+```
+
+That needs only [uv](https://docs.astral.sh/uv/). The browser opens on the app:
+choose the library folder (the folder button at the top of the shelf) and press
+**Index new**. Subfolders are included.
+
+dirag uses two things when they are there, with nothing to set:
+
+| When present | Gives |
+|---|---|
+| An NVIDIA GPU | indexing in minutes per hundred books instead of hours; a faster neural rerank |
+| [Ollama](https://ollama.com), running | the LLM rerank and the AI answer; dirag pulls `qwen2.5:7b-instruct` through it on the first start |
+
+Without them, search, the neural rerank and the reader work as usual; the AI
+button and the LLM rerank are hidden. The terminal shows what was found:
+
+```text
+dirag on http://127.0.0.1:8008
+  GPU   NVIDIA GeForce RTX 3060
+  AI    qwen2.5:7b-instruct via Ollama
+```
+
+The first start downloads the packages (about 2.5 GB on Linux and Windows,
+GPU libraries included), the embedding and rerank models (about 250 MB) and,
+with Ollama, the language model (about 4.7 GB). To keep dirag installed rather
+than run it through uvx: `uv tool install dirag`, then `dirag`.
+
+## Indexing
+
+Indexing is long by design: every page is parsed and every passage embedded.
+The library view shows progress, a time estimate and a stop button. Stopping
+keeps every finished book, and the next run continues from there. Search works
+on the finished books while a run is going. **Index new** adds new and changed
+PDFs and drops deleted ones; **Reindex all** parses and embeds everything again.
+
+## Search
+
+| Key | Does |
+|---|---|
+| typing | lists quick exact-word matches under the box; pick one (click, or arrows and Enter) to open its page |
+| Enter, or the search button | searches with the chosen mode and rerank |
+| Ctrl+Enter, or the AI button | answers from the books (see below) |
+
+The mode and rerank sit beside the search box:
+
+| Mode | Finds |
+|---|---|
+| Hybrid | both of the below, fused by rank (the default) |
+| Lexical | the exact words |
+| Semantic | passages close in meaning, without the words |
+
+| Rerank | Does |
+|---|---|
+| No rerank | keeps the retrieval order |
+| Neural | scores the top 30 with a local cross-encoder; about a second on a CPU |
+| LLM | asks the language model to order the top 20 and leave out the ones that do not help; those stay in the list, faded |
+
+The line under the search box names what produced the results, with the count
+and the time. While a search runs, the current results fade under a moving bar.
+
+## Answer
+
+Ctrl+Enter or the AI button runs the search, then asks the model which passages
+answer the question and which words to quote from each. Only what the model
+chose is shown, as one card marked with the AI icon:
+
+- its response, one to three sentences citing the quotes by number; citations
+  to anything not quoted are removed, and a response left with none is dropped;
+- the quotes, as quotations in the books' own words, each with its source: the
+  source opens the reader scrolled to the quote, marked on the page, and the
+  page icon shows the page image in place.
+
+Every quote is matched against its passage before it is shown; a quote that is
+not in the text is dropped. When no passage answers the question, the answer
+says so. The response is the model's reading, not the books; the quotes and
+their pages are what to check.
+
+## Terminal
+
+```sh
+dirag --port 9000 --no-browser   # serve on another port, without opening the browser
+dirag index --library ~/Books    # choose the folder (remembered) and index it
+dirag index                      # index new and changed PDFs, drop deleted ones
+dirag index --reindex            # parse and embed every PDF again
+dirag index --rechunk            # rebuild passages and vectors from cached pages
+dirag find "martingale" --mode semantic --rerank neural   # passages
+dirag where "instrumental variables"                      # chapters
+dirag toc book.pdf               # the chapter map dirag reads from one PDF
+```
+
+Ctrl-C stops an index run the same way the stop button does; press it twice to
+stop at once.
+
+## Settings
+
+All optional.
+
+| Variable | Default | Sets |
+|---|---|---|
+| `DIRAG_HOME` | `~/.local/share/dirag` | indexes (one per library folder), models, the job record |
+| `DIRAG_STATE` | `DIRAG_HOME` | `config.json`, `positions.json`, `bookmarks.json`, `cards.json` |
+| `DIRAG_LIBRARY` | chosen in the app | fixes the library folder; the app then cannot change it |
+| `DIRAG_BROWSE_ROOT` | the home directory | where the folder picker may browse |
+| `DIRAG_LLM_MODEL` | `qwen2.5:7b-instruct` | the Ollama model |
+| `DIRAG_LLM_URL` | `http://127.0.0.1:11434` | the Ollama server, which can be another machine |
+| `DIRAG_RERANK_MODEL` | `Xenova/ms-marco-MiniLM-L-12-v2` | the cross-encoder; `BAAI/bge-reranker-base` is larger and slower |
+| `DIRAG_DEVICE` | detected | `cpu` keeps the local models off the GPU |
+
+Books are stored by their path inside the library, so the folder can move as
+long as its contents keep their relative paths; a moved folder gets a new index
+unless its index file is renamed to match.
+
+`cards.json` overrides how a book is shown on the shelf. Keys are paths relative
+to the library:
+
+```json
+{"statistics/all-of-statistics.pdf": {"title": "All of Statistics", "subtitle": "A Concise Course",
+  "authors": ["Larry Wasserman"], "year": 2004, "pages": 442}}
+```
+
+## Running as a service
+
+Install it with `uv tool install dirag`, then a systemd unit:
+
+```ini
+[Unit]
+Description=dirag
+After=network-online.target
+
+[Service]
+ExecStart=%h/.local/bin/dirag --no-browser
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+As a user unit (`~/.config/systemd/user/dirag.service`, then
+`systemctl --user enable --now dirag`). Stopping the service stops a running
+index job the same way the stop button does.
+
+## Security
+
+The server binds 127.0.0.1 and has no login. Anyone who can reach the port can
+read every book in the library, choose another folder under the browse root and
+start indexing. Bind another address (`--host`) only on a network where every
+device is trusted, and set `DIRAG_LIBRARY` to fix the folder.
+
+## License
+
+MIT. pdf.js (Apache-2.0) and Bootstrap Icons (MIT) are included; see
+`src/dirag/static/vendor/LICENSE.pdfjs`.

dirag-0.1.0/README.md

@@ -0,0 +1,176 @@
+# dirag
+
+Search a folder of PDF books, read the page each result comes from, and get
+answers quoted from the books.
+
+dirag indexes a library of PDFs once, then answers a query with ranked passages:
+book, chapter, page and a snippet. Each result opens the rendered page with the
+passage marked on it, or the whole book in the built-in reader at that page.
+
+- Passages carry their chapter, taken from each PDF's table of contents.
+- Three retrieval modes: lexical (BM25), semantic (embeddings), and hybrid
+  (both, fused by rank). An optional rerank reads query and passage together:
+  neural (a local cross-encoder) or an LLM.
+- Results are capped per book, so one long series does not fill the list.
+- The AI answer quotes the books: a language model picks the passages and the
+  words, dirag checks every quote against the text and shows it in the book's
+  own words, marked on its page.
+- The reader remembers the page you stopped on in every book.
+- Everything runs locally. No account, no network after the first downloads.
+
+## Start
+
+```sh
+uvx dirag
+```
+
+That needs only [uv](https://docs.astral.sh/uv/). The browser opens on the app:
+choose the library folder (the folder button at the top of the shelf) and press
+**Index new**. Subfolders are included.
+
+dirag uses two things when they are there, with nothing to set:
+
+| When present | Gives |
+|---|---|
+| An NVIDIA GPU | indexing in minutes per hundred books instead of hours; a faster neural rerank |
+| [Ollama](https://ollama.com), running | the LLM rerank and the AI answer; dirag pulls `qwen2.5:7b-instruct` through it on the first start |
+
+Without them, search, the neural rerank and the reader work as usual; the AI
+button and the LLM rerank are hidden. The terminal shows what was found:
+
+```text
+dirag on http://127.0.0.1:8008
+  GPU   NVIDIA GeForce RTX 3060
+  AI    qwen2.5:7b-instruct via Ollama
+```
+
+The first start downloads the packages (about 2.5 GB on Linux and Windows,
+GPU libraries included), the embedding and rerank models (about 250 MB) and,
+with Ollama, the language model (about 4.7 GB). To keep dirag installed rather
+than run it through uvx: `uv tool install dirag`, then `dirag`.
+
+## Indexing
+
+Indexing is long by design: every page is parsed and every passage embedded.
+The library view shows progress, a time estimate and a stop button. Stopping
+keeps every finished book, and the next run continues from there. Search works
+on the finished books while a run is going. **Index new** adds new and changed
+PDFs and drops deleted ones; **Reindex all** parses and embeds everything again.
+
+## Search
+
+| Key | Does |
+|---|---|
+| typing | lists quick exact-word matches under the box; pick one (click, or arrows and Enter) to open its page |
+| Enter, or the search button | searches with the chosen mode and rerank |
+| Ctrl+Enter, or the AI button | answers from the books (see below) |
+
+The mode and rerank sit beside the search box:
+
+| Mode | Finds |
+|---|---|
+| Hybrid | both of the below, fused by rank (the default) |
+| Lexical | the exact words |
+| Semantic | passages close in meaning, without the words |
+
+| Rerank | Does |
+|---|---|
+| No rerank | keeps the retrieval order |
+| Neural | scores the top 30 with a local cross-encoder; about a second on a CPU |
+| LLM | asks the language model to order the top 20 and leave out the ones that do not help; those stay in the list, faded |
+
+The line under the search box names what produced the results, with the count
+and the time. While a search runs, the current results fade under a moving bar.
+
+## Answer
+
+Ctrl+Enter or the AI button runs the search, then asks the model which passages
+answer the question and which words to quote from each. Only what the model
+chose is shown, as one card marked with the AI icon:
+
+- its response, one to three sentences citing the quotes by number; citations
+  to anything not quoted are removed, and a response left with none is dropped;
+- the quotes, as quotations in the books' own words, each with its source: the
+  source opens the reader scrolled to the quote, marked on the page, and the
+  page icon shows the page image in place.
+
+Every quote is matched against its passage before it is shown; a quote that is
+not in the text is dropped. When no passage answers the question, the answer
+says so. The response is the model's reading, not the books; the quotes and
+their pages are what to check.
+
+## Terminal
+
+```sh
+dirag --port 9000 --no-browser   # serve on another port, without opening the browser
+dirag index --library ~/Books    # choose the folder (remembered) and index it
+dirag index                      # index new and changed PDFs, drop deleted ones
+dirag index --reindex            # parse and embed every PDF again
+dirag index --rechunk            # rebuild passages and vectors from cached pages
+dirag find "martingale" --mode semantic --rerank neural   # passages
+dirag where "instrumental variables"                      # chapters
+dirag toc book.pdf               # the chapter map dirag reads from one PDF
+```
+
+Ctrl-C stops an index run the same way the stop button does; press it twice to
+stop at once.
+
+## Settings
+
+All optional.
+
+| Variable | Default | Sets |
+|---|---|---|
+| `DIRAG_HOME` | `~/.local/share/dirag` | indexes (one per library folder), models, the job record |
+| `DIRAG_STATE` | `DIRAG_HOME` | `config.json`, `positions.json`, `bookmarks.json`, `cards.json` |
+| `DIRAG_LIBRARY` | chosen in the app | fixes the library folder; the app then cannot change it |
+| `DIRAG_BROWSE_ROOT` | the home directory | where the folder picker may browse |
+| `DIRAG_LLM_MODEL` | `qwen2.5:7b-instruct` | the Ollama model |
+| `DIRAG_LLM_URL` | `http://127.0.0.1:11434` | the Ollama server, which can be another machine |
+| `DIRAG_RERANK_MODEL` | `Xenova/ms-marco-MiniLM-L-12-v2` | the cross-encoder; `BAAI/bge-reranker-base` is larger and slower |
+| `DIRAG_DEVICE` | detected | `cpu` keeps the local models off the GPU |
+
+Books are stored by their path inside the library, so the folder can move as
+long as its contents keep their relative paths; a moved folder gets a new index
+unless its index file is renamed to match.
+
+`cards.json` overrides how a book is shown on the shelf. Keys are paths relative
+to the library:
+
+```json
+{"statistics/all-of-statistics.pdf": {"title": "All of Statistics", "subtitle": "A Concise Course",
+  "authors": ["Larry Wasserman"], "year": 2004, "pages": 442}}
+```
+
+## Running as a service
+
+Install it with `uv tool install dirag`, then a systemd unit:
+
+```ini
+[Unit]
+Description=dirag
+After=network-online.target
+
+[Service]
+ExecStart=%h/.local/bin/dirag --no-browser
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+As a user unit (`~/.config/systemd/user/dirag.service`, then
+`systemctl --user enable --now dirag`). Stopping the service stops a running
+index job the same way the stop button does.
+
+## Security
+
+The server binds 127.0.0.1 and has no login. Anyone who can reach the port can
+read every book in the library, choose another folder under the browse root and
+start indexing. Bind another address (`--host`) only on a network where every
+device is trusted, and set `DIRAG_LIBRARY` to fix the folder.
+
+## License
+
+MIT. pdf.js (Apache-2.0) and Bootstrap Icons (MIT) are included; see
+`src/dirag/static/vendor/LICENSE.pdfjs`.

dirag-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dirag"
+version = "0.1.0"
+description = "Search a folder of PDF books, read the page each result comes from, and get answers quoted from the books."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+# Linux and Windows get the GPU build of onnxruntime with CUDA and cuDNN as pip
+# packages; it runs on the CPU when there is no NVIDIA GPU. macOS gets the CPU build.
+dependencies = [
+    "pymupdf",
+    "sqlite-vec",
+    "fastembed-gpu>=0.8; sys_platform == 'linux' or sys_platform == 'win32'",
+    "onnxruntime-gpu[cuda,cudnn]>=1.22; sys_platform == 'linux' or sys_platform == 'win32'",
+    "fastembed>=0.8; sys_platform == 'darwin'",
+]
+keywords = ["pdf", "books", "search", "rag", "bm25", "embeddings", "ollama"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Web Environment",
+    "Topic :: Text Processing :: Indexing",
+]
+
+[project.urls]
+Homepage = "https://github.com/barisarat/dirag"
+
+[project.scripts]
+dirag = "dirag.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dirag"]

dirag-0.1.0/src/dirag/__init__.py

@@ -0,0 +1,3 @@
+"""dirag: search a folder of PDF books and read the page each result comes from."""
+
+__version__ = "0.1.0"

dirag-0.1.0/src/dirag/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

dirag-0.1.0/src/dirag/answer.py

@@ -0,0 +1,129 @@
+"""The answer: quotes chosen by a language model, verified against the passages and located on the page.
+
+The model sees the top passages of a search and returns passage numbers with
+the words it quotes from each, plus a response of one to three sentences citing
+them by number. Nothing
+it writes is shown as a quote:
+
+  - Each quote is matched against its passage on letters and digits only, so
+    case, punctuation, spacing and line-break hyphens do not matter. A quote
+    with "..." is matched part by part, in order. A quote that does not match
+    is dropped.
+  - The text shown for a quote is the passage's own text for the matched span.
+  - The quote is located on its page through the page's words, giving one
+    rectangle per line for the reader and the page image to mark.
+  - Citations in the response to passages with no kept quote are removed, the
+    rest renumbered to the quotes. The response is kept only when at least one
+    citation remains; otherwise only the quotes are shown. With no kept quote the answer
+    is empty.
+"""
+
+import json
+import re
+
+import pymupdf
+
+from . import llm
+
+DEPTH = 10
+MAX_QUOTES = 5
+MIN_ALNUM = 15
+
+SYSTEM = ("You answer a question using only the numbered book passages given. Reply with JSON only:\n"
+          '{"quotes": [{"n": <passage number>, "text": "<words copied exactly from that passage>"}], '
+          '"summary": "<one to three sentences answering the question, each citing passages like [2]>"}\n'
+          "Copy every quote word for word from its passage; use ... only to skip words inside a quote. "
+          "Cite only passages you quoted. "
+          f"Each quote is one to three sentences. Order quotes from most to least useful; at most {MAX_QUOTES}. "
+          'If no passage answers the question, reply {"quotes": [], "summary": ""}.')
+
+
+def _alnum(text):
+    """Letters and digits of `text`, lowercased, with the index in `text` of each one."""
+    chars, where = [], []
+    for i, c in enumerate(text):
+        if c.isalnum():
+            chars.append(c.lower())
+            where.append(i)
+    return "".join(chars), where
+
+
+def locate(quote, text):
+    """(start, end) of `quote` within `text`, matched on letters and digits, or None."""
+    haystack, where = _alnum(text)
+    parts = [p for p in (_alnum(part)[0] for part in re.split(r"\.\.\.|\u2026", quote)) if p]
+    if not parts or sum(len(p) for p in parts) < MIN_ALNUM:
+        return None
+    start, at = None, 0
+    for part in parts:
+        found = haystack.find(part, at)
+        if found == -1:
+            return None
+        start = found if start is None else start
+        at = found + len(part)
+    return where[start], where[at - 1] + 1
+
+
+def page_rects(path, page_number, span_text):
+    """Line rectangles of `span_text` on a page, in PDF points, found through the page's words."""
+    doc = pymupdf.open(path)
+    try:
+        words = doc.load_page(page_number - 1).get_text("words")
+    finally:
+        doc.close()
+    joined, owner = [], []
+    for index, word in enumerate(words):
+        letters = _alnum(word[4])[0]
+        joined.append(letters)
+        owner.extend([index] * len(letters))
+    needle = _alnum(span_text)[0]
+    found = "".join(joined).find(needle)
+    if found == -1 or not needle:
+        return []
+    lines = {}
+    for index in sorted(set(owner[found:found + len(needle)])):
+        x0, y0, x1, y1, _, block, line, _ = words[index]
+        box = lines.setdefault((block, line), [x0, y0, x1, y1])
+        box[:] = [min(box[0], x0), min(box[1], y0), max(box[2], x1), max(box[3], y1)]
+    return [[round(v, 2) for v in box] for box in lines.values()]
+
+
+def compose(question, rows, file_of):
+    """{"summary", "quotes"} for `rows` (search rows, best first). `file_of(rel)` gives a book's PDF path.
+
+    Raises llm.LLMError when the model call fails.
+    """
+    top = rows[:DEPTH]
+    listing = "\n\n".join(f"[{n}] {row['book']} > {row['section'] or ''}, p. {row['page']}\n{row['text']}"
+                          for n, row in enumerate(top, 1))
+    reply = llm.chat_json(SYSTEM, f"Question: {question}\n\nPassages:\n\n{listing}")
+    quotes, numbers = [], {}
+    for item in reply.get("quotes", []) if isinstance(reply, dict) else []:
+        try:
+            n, said = int(item["n"]), str(item["text"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        if not 1 <= n <= len(top) or len(quotes) >= MAX_QUOTES:
+            continue
+        row = top[n - 1]
+        span = locate(said, row["text"])
+        if span is None:
+            continue
+        text = row["text"][span[0]:span[1]]
+        if any(q["chunk_id"] == row["id"] and q["text"] == text for q in quotes):
+            continue
+        path = file_of(row["path"])
+        quotes.append({"n": len(quotes) + 1, "chunk_id": row["id"], "book_id": row["book_id"], "book": row["book"],
+                       "year": row["year"], "section": row["section"], "page": row["page"], "text": text,
+                       "rects": (page_rects(path, row["page"], text) if path else []) or _bbox(row)})
+        numbers.setdefault(n, quotes[-1]["n"])
+    summary = str(reply.get("summary") or "").strip() if quotes else ""
+    summary = re.sub(r"\s*\[(\d+)\]", lambda m: f" [{numbers[int(m.group(1))]}]" if int(m.group(1)) in numbers else "",
+                     summary).strip()
+    if not re.search(r"\[\d+\]", summary):
+        summary = ""
+    return {"summary": summary, "quotes": quotes}
+
+
+def _bbox(row):
+    return [json.loads(row["bbox_json"])] if row["bbox_json"] else []