pdf-redpen 0.2.0__tar.gz

pdf_redpen-0.2.0/.env.example

@@ -0,0 +1,8 @@
+# Only needed for a real `pdf-redpen review` (demo, apply, clear and --mock need none of this).
+# Load with:  set -a; source .env; set +a
+PDF_REDPEN_BASE_URL=http://localhost:11434/v1
+PDF_REDPEN_MODEL=
+PDF_REDPEN_API_KEY=
+PDF_REDPEN_TIMEOUT=120
+# Screen language: en or ko (empty = follow the locale)
+PDF_REDPEN_LANG=

pdf_redpen-0.2.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,22 @@
+name: 버그 / Bug
+description: README대로 했는데 다르게 동작해요 / Something does not work as the README says
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: 무엇이 일어났나요? / What happened?
+      description: 실행한 명령과 나온 메시지를 그대로 붙여 주세요. / Paste the command and the output.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 기대한 결과 / Expected
+  - type: input
+    id: env
+    attributes:
+      label: 환경 / Environment
+      placeholder: "macOS 15 (M3) · Ubuntu 24.04 · Windows 11 / uv 0.x / mock or real mode"
+    validations:
+      required: true

pdf_redpen-0.2.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,11 @@
+name: 질문 / Question
+description: 이해가 안 되는 부분이나 더 알고 싶은 점 / Something unclear or worth explaining
+labels: [question]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: 질문 / Question
+      description: README의 어느 부분(절 제목)에 대한 질문인지 알려 주세요. / Which README section is this about?
+    validations:
+      required: true

pdf_redpen-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+# 키·모델 없이 mock 모드로 전체 흐름을 검증한다.
+name: ci
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "17 3 * * 1"   # 매주 월요일 — 의존성·런타임이 바뀌어 깨지지 않았는지 정기 확인
+  workflow_dispatch:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run --python ${{ matrix.python }} pytest -q
+      - run: uv run --python ${{ matrix.python }} pdf-redpen demo --out out

pdf_redpen-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# 실행 산출물·모델·데이터 캐시
+runs/
+outputs/
+.cache/
+*.safetensors
+*.gguf
+*.bin
+
+# 환경·비밀
+.env
+.env.*
+!.env.example
+
+# OS·에디터
+.DS_Store
+.vscode/
+.idea/

pdf_redpen-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

pdf_redpen-0.2.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+uses [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-11-12
+
+### Added
+- Screen language: English and Korean. Pick it with the global option `pdf-redpen --lang en|ko <command>`, the `PDF_REDPEN_LANG` environment variable, or the locale (`LC_ALL`, `LC_MESSAGES`, `LANG`; a value starting with `ko` means Korean, anything else English). It covers `--help`, progress and summary lines, error messages and the Markdown report.
+- File problems (read-only output folder, permission denied, disk full) now print a clear `error: cannot access <path>: <reason>` message with exit code 2 instead of `unexpected error: PermissionError`.
+- `annotate_pdf(..., lang=)` and `pdf_redpen.i18n` (message table, `set_lang`).
+
+### Changed
+- The notes written into the PDF follow the screen language: `[not found]` / `[over cap]` / `(loose match)` in English, `[위치 못 찾음]` / `[상한 초과]` / `(느슨 일치)` in Korean. Before, they were always Korean, so English users now see English tags.
+- `review --lang` is unchanged: it is still the prompt language (default `ko`), not the screen language. Its help text says so.
+- `InputError` and `LLMError` carry a message id and parameters; `str(exc)` is still the English text.
+
+### Unchanged
+- `report.json` (always English), exit codes, environment variable names, prompts and the bundled data.
+
+## [0.1.4] - 2026-11-10
+
+### Fixed
+- Find quotes written as `fi`/`fl` on PDFs whose text layer stores ligatures (U+FB00..U+FB06, common in LaTeX papers). Page text and quotes now share one compatibility normalisation; Hangul compatibility jamo are left as they are.
+
+## [0.1.3] - 2026-11-10
+
+### Changed
+- Docs: replace the tool comparison table with a short when-to-use section.
+
+## [0.1.2] - 2026-11-09
+
+### Changed
+- Docs: list Pillow in the license section and NOTICE, explain `clear --author`, note that `apply` also writes report files.
+
+## [0.1.1] - 2026-11-09
+
+### Security
+- Require `pillow>=13.0.0` (transitive via pdfplumber); fixes all open Pillow advisories, whose first patched version is 13.0.0.
+
+### Changed
+- Minimum Python is now 3.11 (Pillow 13 requires it).
+
+## [0.1.0] - 2026-11-09
+
+### Added
+- `review`: OpenAI-compatible chat client (urllib), `--mock DIR` replay, `--record DIR`, `--recall-pass`.
+- `apply`: mark findings from a JSON file without any model.
+- `clear`: remove only annotations whose author is `pdf-redpen`.
+- `demo`: bundled 3-page sample with recorded (practice mock) answers.
+- Five-stage quote grounding with duplicate avoidance and neighbour-page search.
+- Standard `/Highlight` and `/Text` annotations with `/AP` appearance streams.
+- Per-page highlight cap with a page memo, progressive save (`.part` + atomic replace).
+- JSON and Markdown reports.

pdf_redpen-0.2.0/LICENSE

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

pdf_redpen-0.2.0/NOTICE.md

@@ -0,0 +1,23 @@
+# Notices
+
+## Sample PDFs
+
+`src/pdf_redpen/data/sample_report.pdf` and `examples/sample_embedded.pdf` contain text
+written for this repository (fictional report sentences, no real company or person).
+`sample_report.pdf` only references a CJK font by name and embeds no font file.
+`examples/sample_embedded.pdf` embeds a subset of "Droid Sans Fallback Regular", the font
+bundled with PyMuPDF (https://pymupdf.readthedocs.io/en/latest/font.html, checked 2026-11-09),
+which is an Android distribution font under the Apache License 2.0.
+Both files are generated by `scripts/make_sample_pdf.py`.
+
+## Dependencies
+
+| Package | Version | License |
+|---|---|---|
+| pdfplumber | 0.11.10 | MIT |
+| pypdf | 7.0.0 | BSD-3-Clause |
+| Pillow | >=13.0.0 | MIT-CMU |
+| pytest (dev only) | 9.2.0 | MIT |
+
+PyMuPDF (AGPL-3.0) is **not** a dependency. It is only needed to regenerate the sample PDFs
+with `scripts/make_sample_pdf.py`, a development script that the package never imports.

pdf_redpen-0.2.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.5
+Name: pdf-redpen
+Version: 0.2.0
+Summary: Ground quotes from an LLM review to real PDF coordinates and mark them as standard highlight + note annotations.
+Project-URL: Homepage, https://github.com/LeeGyeongPil/pdf-redpen
+Project-URL: Repository, https://github.com/LeeGyeongPil/pdf-redpen
+Project-URL: Issues, https://github.com/LeeGyeongPil/pdf-redpen/issues
+Author: LeeGyeongPil
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotation,grounding,highlight,llm,pdf,review
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.11
+Requires-Dist: pdfplumber==0.11.10
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: pypdf==7.0.0
+Description-Content-Type: text/markdown
+
+# pdf-redpen
+
+**English** | [한국어](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/README.ko.md)
+
+pdf-redpen takes the sentences an LLM quoted while reviewing a PDF and finds them in the original file, even when the model changed spaces, punctuation or the page number. It then draws standard highlight + note annotations that open in any PDF viewer, turning a review note like "this sentence somewhere on page 3" into a highlighter mark and a sticky note at that exact spot. Try it with no API key: `uv tool install git+https://github.com/LeeGyeongPil/pdf-redpen && pdf-redpen demo --out out` (the demo replays hand-written recorded answers, a practice mock). MIT license.
+
+![Demo result page 1: the quoted sentences painted in severity colors (red = high, yellow = medium, green = low) on PDF page 1](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/01-hero.png)
+*A picture of page 1 of the `reviewed.pdf` made by `pdf-redpen demo`. Sentences that span several lines are painted line by line. (The image renderer draws the Korean font with a substitute typeface, so the letter spacing looks wide, but the painted positions follow the character coordinates exactly.)*
+
+## Who it is for
+- People who have an LLM do a first review of a report, proposal or paper PDF, and find it tedious to go back and forth between the list of remarks and the original to find sentences
+- People who have run into the problem that a sentence the model quoted "does not show up in search" (spaces, word spacing or punctuation changed, wrong page number)
+- Developers who want to show the findings JSON from other tools, such as spell or terminology checkers, on top of a PDF
+- People who want to see in numbers how many more findings appear when the LLM is asked once more, "did you miss anything?"
+
+## Why it is needed (a red-pen analogy)
+If a proofreader writes only "something is off somewhere on page 3", you end up rereading page 3. If they **draw a highlighter line on the odd sentence and stick a note beside it**, you can fix it right away. An LLM is good at the earlier part (finding a sentence and talking about it), but it cannot copy the quoted sentence **identically down to the last character**. This tool handles the follow-up work of tying that "nearly identical sentence" to the real character positions in the PDF.
+
+## Installation
+```bash
+# Prerequisite: uv (Python package manager). Skip if you already have it.
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Install the tool (Python 3.11 or later)
+uv tool install git+https://github.com/LeeGyeongPil/pdf-redpen
+```
+You can also clone it and use it without installing: `git clone https://github.com/LeeGyeongPil/pdf-redpen && cd pdf-redpen && uv sync && uv run pdf-redpen --version`
+
+On a minimal Linux (for example a slim container), `curl`, `git` and `ca-certificates` are needed. The PDF-processing dependencies (pdfplumber, pypdf, Pillow) are all installed as wheels, so no separate system libraries are needed.
+
+## Quick start
+No key or model is needed.
+
+```bash
+pdf-redpen demo --out out
+```
+
+![Terminal output: 9 findings: 8 highlighted, 1 page memo, 1 page skipped](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/02-demo-run.png)
+*The `demo` run screen (English; the screenshot adds `--lang en` to make the language explicit). Page 3 has no text layer, so the model is not called and the page is skipped. The quoted sentences in the sample report are Korean, so they stay Korean in every screen.*
+
+> **This is a practice mock mode.** The model's responses are replaced by recorded files bundled in the repository (`src/pdf_redpen/data/recorded/`, **written by hand by a person and not the real output of any particular model**). What happens after a response arrives (table parsing, recall merge, locating, writing annotations) is **the same code** as in the real mode. A real model will flag more or fewer items, and different ones. The real mode can be much slower because of the model calls.
+
+How to read it:
+
+| Output | Meaning |
+|---|---|
+| `9 findings` | 9 findings produced by the model (the recording) |
+| `8 highlighted` | 8 were located in the PDF and highlighted |
+| `1 page memo` | 1 could not be found in the body and was written into that page's corner memo |
+| `1 page skipped` | Pages without a text layer (scans, blank pages) are skipped |
+| `stages: exact=4 ...` | A tally of which stage's matching method found each finding |
+| `recall pass: first 8, added 1, ...` | 8 in the first pass, 1 added by asking again for "only what was missed", 1 duplicate removed |
+
+Open `out/reviewed.pdf` in any PDF viewer. A finding that was located becomes a highlight (`/Highlight`) and its explanation is in the highlight's note (`/Contents`), visible when you click or hover over the highlight. Findings that were not located are gathered under `[not found]` in a single note icon at the page corner.
+
+## Usage
+
+| Command | What it does | Example |
+|---|---|---|
+| `demo` | Reviews the 3 bundled sample pages with recorded responses | `pdf-redpen demo --out out` |
+| `review` | Reviews a PDF with a model and produces an annotated PDF and a report | `pdf-redpen review a.pdf --recall-pass -o a.reviewed.pdf` |
+| `apply` | Attaches a findings JSON to a PDF, without a model | `pdf-redpen apply a.pdf findings.json -o a.marked.pdf` |
+| `clear` | Removes only the annotations this tool added | `pdf-redpen clear a.marked.pdf -o a.clean.pdf` |
+
+`review` options: `--instructions FILE` (review guidelines), `--mock DIR` (replay recordings), `--record DIR` (save responses), `--recall-pass` (ask again for what was missed), `--max-highlights-per-page N` (default 20), `--pages 1-3,5`, `--author`, `--lang ko|en` (the **prompt** language sent to the model, default `ko`; not the screen language, see below).
+Exit codes:
+- `0` Normal. It is 0 even if no findings were located (reported in the report), and if only some pages fail it prints `warning: N page(s) failed ...` to stderr and is still 0.
+- `1` **All** pages sent to the model failed (`error: every page failed; ...`), or an unexpected error.
+- `2` Input error (nonexistent file, bad JSON, out-of-range `page`, unknown `severity`, no model configured, etc.) or a file you cannot read or write (`error: cannot access <path>: <reason>`, for example a read-only output folder).
+
+### Screen language (English / Korean)
+Everything you read in the terminal (help, progress and summary lines, error messages) and the Markdown report can be shown in English or Korean. The notes written into the PDF follow the same language. The first one that is set wins:
+
+| Priority | How | Example |
+|---|---|---|
+| 1 | Global option, placed **before** the command | `pdf-redpen --lang ko demo --out out` |
+| 2 | Environment variable | `PDF_REDPEN_LANG=ko pdf-redpen demo --out out` |
+| 3 | Locale: `LC_ALL`, then `LC_MESSAGES`, then `LANG` (a value starting with `ko` means Korean) | `LANG=ko_KR.UTF-8 pdf-redpen demo --out out` |
+| 4 | Nothing set, or any other value | English |
+
+![The help screen in English: usage, the four commands and the --lang option](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/09-lang-help.png)
+*`pdf-redpen --lang en --help`. With `--lang ko` the same screen is shown in Korean. argparse's own headings (`usage:`, `positional arguments:`, `options:`) and the description lines of `-h` and `--version` stay English.*
+
+- **`--lang` before the command is the screen language. `review --lang ko|en` after `review` is the prompt language** that is sent to the model (and it keeps its default `ko`). They are separate: `pdf-redpen --lang en review a.pdf --lang ko` shows English messages but asks the model in Korean.
+- The notes inside the PDF are `[not found]`, `[over cap]` and `(loose match)` in English, and `[위치 못 찾음]`, `[상한 초과]` and `(느슨 일치)` in Korean. Versions before 0.2.0 always wrote the Korean ones.
+- `report.json` is for machines and is always English, whatever the language. Status and stage codes (`highlighted`, `exact`, ...) are the same in both languages.
+
+### Scenario 1. Review your own document with a local model
+```bash
+export PDF_REDPEN_BASE_URL=http://localhost:11434/v1   # OpenAI-compatible endpoint (e.g. Ollama)
+export PDF_REDPEN_MODEL=<your-model-name>
+pdf-redpen review report.pdf --instructions review.md --recall-pass --record rec -o report.reviewed.pdf
+```
+(`<your-model-name>` is a placeholder for the name of the model you have pulled.)
+- It extracts the text of each page and sends it to the model, then picks the quotations from the response table and locates them.
+- With `--record rec`, the responses are saved to `rec/page{n}_turn{k}.md`, so later you can reproduce the same result with `--mock rec` without a key or network (for sharing with a team or regression checks). When you replay files you recorded yourself, the report still carries the "practice mock" notice, but the content is that model's response, not something a person wrote. `--mock` and `--record` cannot be used together (giving both is exit code 2).
+- This mode **sends the page text to the endpoint you specify.** For sensitive documents, use a local model.
+
+If the endpoint is not up or the model name is wrong, the cause is shown per page in the terminal. If all the pages sent fail, the exit code is 1. (The example below was produced with `PDF_REDPEN_TIMEOUT=2` and `PDF_REDPEN_BASE_URL=http://127.0.0.1:9/v1`; with the default you would see `now 120s`.)
+```text
+  page 1: error - LLMError: Could not reach http://127.0.0.1:9/v1/chat/completions (<urlopen error [Errno 61] Connection refused>). Is the server running? Local models can be slow; raise PDF_REDPEN_TIMEOUT (now 2s).
+  ...
+error: every page failed; see the causes above (or the Pages table in the report). Nothing was reviewed.
+```
+(With `--lang ko` the same lines appear in Korean.)
+
+If you do not specify a model, it stops like this (exit code 2).
+
+![Error message and exit code 2 when no model is configured](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/07-no-model.png)
+*An error screen shown on purpose (English). It tells you to set `PDF_REDPEN_MODEL` or use `demo` or `--mock`.*
+
+### Scenario 2. Attach another tool's findings to a PDF (`apply`)
+`findings.json` is an array like this (full example: [`examples/findings.json`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/examples/findings.json)).
+```json
+[
+  {"page": 1, "quote": "근거 표가 제시되지 않았습니다", "comment": "근거 표 추가 필요", "severity": "high"},
+  {"page": 2, "quote": "존재하지 않는 문장입니다", "comment": "못 찾으면 페이지 메모로", "severity": "high"}
+]
+```
+(In this sample, the first `quote` means "no supporting table is presented" and its `comment` is "supporting table needed"; the second `quote` is "a sentence that does not exist" and its `comment` is "if not found, as a page memo".)
+
+`severity` is `high`, `medium` or `low` (colors: red, yellow, green) and may be omitted. Common aliases such as `critical`, `major` and `높음` ("high") are accepted, but unknown values (typos and the like) are rejected instead of silently becoming yellow.
+
+If `page` exceeds the PDF's page count, **it stops with exit code 2 and does not create the output PDF**, so no finding disappears.
+
+![Out-of-range page error: item 0: page 99 but the PDF has 3 page(s), exit code 2](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/08-page-out-of-range.png)
+*An error screen shown on purpose (English). It tells you the item number (from 0) and the PDF's page count.*
+
+An unknown `severity` is rejected with `error: f.json: item 0: unknown severity 'urgnt'; use high, medium or low (or omit 'severity').` (exit code 2).
+
+### Scenario 3. A page with too many findings, and clearing to start over
+The paths in this command (`src/...`, `examples/findings.json`) assume you run it in the folder where you cloned the repository. If you installed only with `pip` or `uv tool`, replace them with your own PDF and JSON paths.
+
+```bash
+pdf-redpen apply src/pdf_redpen/data/sample_report.pdf examples/findings.json -o cap3.pdf --max-highlights-per-page 3
+pdf-redpen clear cap3.pdf -o clean.pdf
+```
+
+![The apply result tally and the output where clear removes 8 annotations](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/06-apply-clear.png)
+*Only up to 3 highlights are drawn on a page, and the rest are gathered into the page memo. `clear` removes only the 8 annotations whose author is `pdf-redpen` (6 highlights + 2 page memos, one per page).*
+
+![Page 1 after applying a cap of 3: 3 highlights and a page memo icon at the top right](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/05-cap3-page1.png)
+*Findings beyond the cap are gathered into a single yellow note icon at the top right as a `[over cap]` list.*
+
+`clear` removes only annotations whose `/T` (author) is `pdf-redpen`, so annotations added by people stay. If you attached them with a different author through `review --author name`, you must also give `pdf-redpen clear a.pdf -o b.pdf --author name` when clearing. Like `review`, `apply` also creates `<name>.report.json` and `<name>.report.md` next to the output PDF.
+
+## Reading the report
+`review` and `demo` create `<name>.report.json` (for machines) and `<name>.report.md` (for people) next to the output PDF (for example `out/reviewed.report.md`). Details not visible in the terminal are here.
+
+![The report's findings table: per finding, the asked page, the found page and the match stage](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/03-report-table.png)
+*Part of the Findings table of the English `reviewed.report.md` (only the columns `#`, `asked page`, `found page`, `stage` and `quote` are shown, cropped). Finding 8 was said to be on page 2 but was found on page 1, and 9 is `-` (not found), so it went to the page memo.*
+
+**Findings table columns**: `#` number / `source` (`turn1` = first query, `recall` = recall query, `apply` = JSON input) / `asked page` (the page the model said) / `found page` (the page actually found) / `stage` (which match stage, `-` if not found) / `status` / `severity` / `quote` / `comment`.
+
+| Finding `status` | Meaning | What you see in the PDF |
+|---|---|---|
+| `highlighted` | Located and painted | Highlight + note |
+| `memo_not_found` | Not found in the body | `[not found]` list in the page corner note |
+| `memo_overflow` | Exceeded the per-page highlight cap (`--max-highlights-per-page`) | `[over cap]` list in the page corner note |
+
+**Pages table**: for each page, `status`, plus `first` (number of first-pass findings), `recall added`, `duplicates dropped`, `broken rows`, and `note`.
+
+| Page `status` | Meaning |
+|---|---|
+| `ok` | Processed by calling the model |
+| `skipped_no_text_layer` | No text layer, so the model was not called (the reason is in `note`) |
+| `error` | The call for that page failed. The cause (for example `Could not reach ...`) is left in `note`, and the same cause also shows in the terminal |
+
+If `note` contains `page text truncated before sending`, that page's text was cut at 12000 characters per page before going to the model, so findings in the latter part may be missing. Also, findings whose `stage` is `prefix25` may be painted longer than the quotation (see the 5-stage explanation below), so check them by eye.
+
+## Configuration
+Environment variables (needed only for the real `review`; not needed for `demo`, `apply`, `clear` or `review --mock`). Example: [`.env.example`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/.env.example).
+
+| Variable | Default | Description |
+|---|---|---|
+| `PDF_REDPEN_BASE_URL` | `http://localhost:11434/v1` | The front part of an OpenAI-compatible `chat/completions` endpoint |
+| `PDF_REDPEN_MODEL` | (none, required) | Model name |
+| `PDF_REDPEN_API_KEY` | (none) | If set, sent as `Authorization: Bearer`. Not recorded in code, reports or recording files |
+| `PDF_REDPEN_TIMEOUT` | `120` | Seconds to wait for a response |
+| `PDF_REDPEN_LANG` | (none) | Screen language `en` or `ko`; the global `--lang` option wins over it. Works for every command, including `demo` and `apply` |
+
+## How it works
+There are two key parts: **locating (grounding)** and the **recall pass**.
+
+```mermaid
+flowchart LR
+  A["Extract page text"] --> B["Query the model"]
+  B --> C["Parse response table"]
+  C -.->|--recall-pass| D["Recall query: only what was missed"]
+  D -.-> E["Parse table + dedupe"]
+  C --> F["5-stage locating"]
+  E -.-> F
+  F -->|found| G["Highlight + note"]
+  F -->|not found| H["Page corner note"]
+  G --> I["Annotated PDF + report"]
+  H --> I
+```
+
+1. **Extract text**: it flattens a page's text into one line of string, and for each character of the string remembers "the original character box number". The text sent to the model and the target being searched are the same string, so a copied sentence is always found. Pages without a text layer are skipped.
+2. **Query**: for each page, the model is asked to answer in a "quoted original | finding | severity" table. Even if the table's header names or column order differ, or some rows are broken, it does not stop; it just counts each broken row and skips it.
+3. **Recall query** (`--recall-pass`, the dotted line): after parsing the first-pass response table, it asks once more in the same conversation, "the list I just flagged is this, so add only what was missed." The point is to **show** the first-pass findings in the prompt, so only new findings are added rather than repeating the same things. The tables of the two responses are merged and duplicates are removed.
+4. **5-stage locating**: it tries in order from strict to loose and uses the first stage that succeeds.
+5. **Write annotations**: it makes a standard `/Highlight` with one rectangle (quad) per line, and also writes appearance information (`/AP`) so the highlight does not look different in each viewer. It saves to a temporary file (`.part`) page by page and replaces the whole, so even if it fails midway, the annotations of finished pages remain.
+
+### 5-stage locating
+
+| Stage | How it matches | Variation it catches |
+|---|---|---|
+| `exact` | The text as is | A normal quotation |
+| `ws_collapse` | Runs of spaces and line breaks collapsed into one space | Double spaces, copied line breaks |
+| `no_space` | All whitespace removed | Korean word-spacing errors |
+| `alnum_only` | Compare letters and digits only | Punctuation and hyphen variations |
+| `prefix25` | Match only the first 25 characters and paint to the quotation's length | Paraphrase of the latter part |
+
+- If the same sentence appears twice, it avoids characters already painted and paints **the next occurrence** (findings 6 and 7 in the demo).
+- If the model gets the page number wrong, it also looks in the neighboring pages (finding 8 in the demo: said page 2 but found on page 1).
+- `prefix25` is the loosest, so it **can paint characters the model did not quote.** That is why it is the last resort, and the green tail ("ext") in the hero image above is an example. Check findings located at this stage by eye in the report.
+
+For what the table columns mean, see "Reading the report" above.
+
+### Why the recall pass is needed
+**Recall** is "the share of the problems that actually exist that the model found". The recall of a single query can be low, to the point that asking the same model about the same document twice gives different numbers of findings. The **recall pass** is a further query to raise it: it keeps the first answer in the same conversation as an assistant message, shows the first-pass finding list again in the user message, and asks for **only what was missed** (implementation: `prompts.recall_turn`). The report lists the first-pass count and the added and de-duplicated counts separately. This technique **does not guarantee** a number of findings, and figures such as `added 1` in the demo are hand-written recorded values. Below is the recall prompt the demo actually sent.
+
+![The recall prompt recorded in the report and the recall pass tally](https://raw.githubusercontent.com/LeeGyeongPil/pdf-redpen/v0.2.0/docs/images/04-recall-prompt.png)
+*The prompt "the list I just flagged is as follows … add only what was missed (missed only)." and `recall pass: first 8, added 1, duplicates dropped 1`. The prompt body is in Korean because the prompt language (`review --lang`, which `demo` uses) defaults to `ko` and is separate from the screen language; the screen language only changes the surrounding lines. The awk pattern in the command matches both languages' headings.*
+
+### A tour of the code
+- [`src/pdf_redpen/grounding.py`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/src/pdf_redpen/grounding.py): 5-stage locating (`ground`) and neighboring-page search (`ground_finding`).
+- [`src/pdf_redpen/recall.py`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/src/pdf_redpen/recall.py) and [`prompts.py`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/src/pdf_redpen/prompts.py): the recall query and merging.
+- [`src/pdf_redpen/writer.py`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/src/pdf_redpen/writer.py) and [`quads.py`](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/src/pdf_redpen/quads.py): annotations and quad coordinates (PDF puts the origin at the bottom left while extracted coordinates put it at the top left, so a conversion is needed).
+
+### Using it from Python
+The sample paths in the example below also assume you run it in the folder where you cloned the repository.
+
+```python
+from pdf_redpen import Finding, annotate_pdf
+
+report = annotate_pdf(
+    "src/pdf_redpen/data/sample_report.pdf",
+    [Finding(1, "근거 표가 제시되지 않았습니다", "근거 표 추가 필요"),
+     Finding(2, "존재하지 않는 문장입니다", "못 찾음")],
+    "marked.pdf",
+)
+for p in report.placements:
+    print(p.status, p.stage)   # highlighted exact / memo_not_found None
+```
+
+| Public name | Description |
+|---|---|
+| `annotate_pdf(src, findings, dst, *, max_per_page=20, author=..., lang=None)` | Attaches a list of findings to a PDF, saves it to `dst` and returns a `Report`. `lang` (`"en"` or `"ko"`) sets the language of the notes in the PDF; the default is English unless `pdf_redpen.i18n.set_lang("ko")` was called (the CLI does this for you) |
+| `Finding(page, quote, comment, severity=None)` | One finding |
+| `Report` | Tallies such as `placements` (`status` and `stage` per finding) and `pages` |
+| `ground(page, quote, used)` | Low-level function: it needs an internal `PageText`, so you normally use only `annotate_pdf` |
+| `Match`, `InputError` | The match result type, and the input error exception |
+
+## Limits
+- Scanned PDFs and PDFs with broken characters (`cid`) have no text layer and are skipped (no OCR).
+- In two-column layouts the character reading order can get mixed up, so multi-line quotations may not be found.
+- The look of highlights and notes can differ slightly between viewers.
+- The real mode depends on the model's speed, and the page text is sent to the endpoint.
+- Known limits of the screen language: the screen language option goes before the command (`pdf-redpen --lang ko demo`), the headings and `-h`/`--version` description lines that argparse adds stay English, and the library's default PDF notes are English unless you pass `lang=`. The Korean screen calls the recorded responses "녹음" files (the practice-mode files), which is a wording quirk, not audio.
+
+## When to use it
+- This tool fits if you want to attach findings from an LLM or another tool to a standalone PDF file as annotations at the original's positions. Findings whose position could not be found are left as a page memo.
+- If you handle several document formats or are in a .NET environment, look at [groupdocs ai-document-review-annotations-net](https://github.com/groupdocs-annotation/ai-document-review-annotations-net).
+- If you manage paper annotations inside a Zotero library, look at [zotero-mcp](https://github.com/54yyyu/zotero-mcp).
+- Other tools' features can change, so check the details yourself at each link. (The links were noted during the 2026-11-09 survey.)
+
+## Troubleshooting
+| Symptom | Cause | Fix |
+|---|---|---|
+| `error: No model configured ...` (exit code 2) | A real `review` without a model configured | Set `PDF_REDPEN_MODEL`, or use `demo` / `--mock DIR` |
+| `error: cannot access <path>: ...` (exit code 2) | The output folder is read-only, does not exist or is full | Choose another `-o` path and check the permissions |
+| The screen is in the wrong language | The locale or `PDF_REDPEN_LANG` decides it | Pass `--lang en` or `--lang ko` before the command |
+| `unrecognized arguments: --lang en` (exit code 2) | The screen language option was placed after the command | Put it before the command: `pdf-redpen --lang ko demo` |
+| A page is shown as `skipped_no_text_layer` | A scan, a blank page, or broken character mapping | Use a PDF with a text layer (OCR is not supported) |
+| A finding becomes `memo_not_found` | The model made up a sentence that is not in the body | Check the page corner note. If needed, use `--recall-pass` or strengthen the instructions |
+| The painted range is longer than the quotation | It was found at the `prefix25` stage | Check the stage in the report and inspect by eye |
+| Annotations overlap after running the same PDF again | The previous annotations remain | Run `pdf-redpen clear` first |
+
+## Development and contributing
+```bash
+git clone https://github.com/LeeGyeongPil/pdf-redpen && cd pdf-redpen
+uv sync
+uv run pytest
+```
+Only the script that regenerates the sample PDF (`scripts/make_sample_pdf.py`) needs PyMuPDF (AGPL-3.0), and the package does not use it. Please leave bugs and suggestions as issues. Change history is in [CHANGELOG.md](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/CHANGELOG.md).
+
+## Learn more
+Checked 2026-11-09.
+- pypdf, adding annotations: https://pypdf.readthedocs.io/en/stable/user/adding-pdf-annotations.html
+- pdfplumber: https://github.com/jsvine/pdfplumber
+- The concept of tying model quotations to document coordinates (grounding): https://artifex.com/blog/grounding-in-document-extraction
+- Tools in the same family: https://github.com/neuml/annotateai, https://github.com/onekin/AnnotateGPT
+
+## License
+MIT. Direct dependencies: pdfplumber (MIT), pypdf (BSD-3-Clause), Pillow (MIT-CMU) (indirect dependencies such as pypdfium2 and cryptography are Apache-2.0/BSD family). For the sample PDF's fonts and sources, see [NOTICE.md](https://github.com/LeeGyeongPil/pdf-redpen/blob/v0.2.0/NOTICE.md).