Metadata-Version: 2.4
Name: zotero-pdf2zh-pro
Version: 1.6.7
Summary: Minimal pdf2zh_next bridge for the Zotero plugin
Author: study-233
License-Expression: AGPL-3.0-or-later
Project-URL: Repository, https://github.com/study-233/zotero-pdf2zh-pro
Project-URL: Issues, https://github.com/study-233/zotero-pdf2zh-pro/issues
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSES/BabelDOC-AGPL-3.0.txt
License-File: LICENSES/RapidOCR-Apache-2.0.txt
License-File: LICENSES/pdf2zh-next-AGPL-3.0.txt
License-File: LICENSES/zotero-pdf2zh-pro-AGPL-3.0-or-later.txt
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: azure-ai-translation-text<=1.0.1
Requires-Dist: bitstring>=4.3.0
Requires-Dist: chardet>=5.2.0
Requires-Dist: charset-normalizer>=2.0.0
Requires-Dist: configargparse>=1.7
Requires-Dist: cryptography>=36.0.0
Requires-Dist: deepl
Requires-Dist: flask<4,>=3.1.0
Requires-Dist: fonttools
Requires-Dist: freetype-py>=2.5.1
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: huggingface-hub>=0.27.0
Requires-Dist: hyperscan>=0.7.13
Requires-Dist: levenshtein>=0.27.1
Requires-Dist: msgpack>=1.1.0
Requires-Dist: numpy<3,>=2.0.2
Requires-Dist: ollama
Requires-Dist: onnx>=1.18.0
Requires-Dist: onnxruntime>=1.16.1
Requires-Dist: openai<3,>=2.32.0
Requires-Dist: opencv-python-headless>=4.10.0.84
Requires-Dist: orjson>=3.10.14
Requires-Dist: peewee>=3.17.8
Requires-Dist: pillow
Requires-Dist: psutil>=7.0.0
Requires-Dist: pyclipper>=1.2.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pymupdf<1.25.3,>=1.25.1
Requires-Dist: pypdf<7,>=6.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: pyzstd>=0.17.0
Requires-Dist: requests
Requires-Dist: rich>=13.9.4
Requires-Dist: rtree>=1.4.0
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: scikit-learn>=1.7.1
Requires-Dist: scipy>=1.15.3
Requires-Dist: shapely!=2.0.4,>=1.7.1
Requires-Dist: six>=1.15.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: tencentcloud-sdk-python-tmt
Requires-Dist: tiktoken>=0.9.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tomlkit<1,>=0.13.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: truststore<1,>=0.10.4
Requires-Dist: uharfbuzz>=0.50.2
Requires-Dist: xinference-client
Requires-Dist: xsdata[lxml,soap]>=24.12
Dynamic: license-file

# zotero-pdf2zh-pro

Local Python server for the Zotero `zotero-pdf2zh-pro` plugin.

```bash
uv tool install --python 3.13 zotero-pdf2zh-pro
zotero-pdf2zh-pro
```

The default service URL is `http://127.0.0.1:8890`.

The server verifies HTTPS using the operating system's trusted certificates,
including trusted proxy CAs on macOS and Windows. Certificate and hostname
verification remain enabled. For Docker, install any required private CA in
the container's trust store; the host's trust store is not inherited.

## Model discovery

`POST /list-models` accepts `apiUrl`, optional `apiKey`, and optional
`apiProtocol` (`auto`, `chat_completions`, or `responses`). It strips a recognized
translation endpoint suffix and requests `<base>/models`, preserving custom
paths and never adding `/v1`. A successful response is
`{"status":"ok","models":["model-id"]}`; an empty list is valid.

Discovery uses a 15-second timeout and does not follow redirects, persist keys,
or echo upstream response bodies in errors. Errors return `status` and `message`
with HTTP 400 for invalid input, 502 for provider failures, or 504 for timeout.
Clients should allow manual model entry on failure. `/health` advertises
`supportsModelDiscovery: true`; existing translation endpoints are unchanged.

## Translation protocols and request options

The optional `llm_api.apiProtocol` field accepts `auto`, `chat_completions`, or
`responses`; `llm_api.requestOptions` accepts a JSON object of extra request
parameters. `/health` advertises `supportedApiProtocols`, and `/validate-config`
returns `resolvedProtocol`. Older servers support the Chat Completions fallback;
Responses and extra request options require a compatible server update.

New task metrics omit `cost`. Token and upstream cache values may be `null`, with
`availability` indicating `unavailable`, `partial`, or `complete`. Legacy cost
fields are ignored when reading historical records.

## Translation completeness and repair

Task details and SSE events expose `translationSummary`, `failedParagraphs`, and
`canRepair`. The `incomplete` status indicates that paragraphs requiring
translation are still unresolved; these results are not automatically imported
into Zotero.

`POST /tasks/{taskId}/repair` accepts incomplete, completed, and cancelled tasks
and returns the snapshot for the new attempt. Active tasks return HTTP 409.
Repair preserves validated translations and requests the remaining paragraphs,
using QPS 2 and concurrency 4 by default. Pure URL footnotes are preserved without
translation; ordinary body text containing a URL still requires translation.

Paragraph checkpoints are stored in `paragraph-recovery.json` inside the task
directory, allowing repair after a server restart. Deleting a task also removes
its checkpoints. JSON structure, paragraph IDs, nonempty translations, and
placeholders are validated before translations are cached.

## Runtime and data paths

Run `zotero-pdf2zh-pro --help` for supported options: `--host`, `--port`,
`--log-level`, `--data-dir`, and `--log-file`. The default listener is
`127.0.0.1:8890`. `/health` reports the effective `workspace.path`, writability,
free space, versions, and task counts. Inspect that path before backing up data
or uninstalling; its location depends on the installation method.

The corresponding environment variables are `PDF2ZH_HOST`, `PDF2ZH_PORT`,
`PDF2ZH_LOG_LEVEL`, `PDF2ZH_DATA_DIR`, and `PDF2ZH_LOG_FILE`. By default, task data
is stored in `translates` alongside the installed server module. The optional
log file rotates at 10 MiB with three backups.

For the Windows and macOS installation walkthrough, see the [main tutorial](../README.md).
