# DocWeaver
[](https://github.com/wyh0626/doc-weaver/actions/workflows/tests.yml)
[](https://skills.sh/wyh0626/doc-weaver)
[](LICENSE)
Translate documents with your current AI agent, keeping their structure. **v0.1 supports selectable-text PDF only**, producing translated and side-by-side bilingual PDFs through [BabelDOC](https://github.com/funstory-ai/BabelDOC). PDF processing executes locally; content read by a cloud agent is still processed by that agent's model service.
[中文说明](README.zh-CN.md) · [How it works](skills/doc-weaver/references/implementation.md) · [Roadmap](ROADMAP.md)
## Install
Requires Node.js/npm for the skills installer. Install into the current project for Codex:
```sh
npx skills add wyh0626/doc-weaver --skill doc-weaver --agent codex --yes
```
To choose another supported agent interactively, omit `--agent codex --yes`. To install globally, add `--global`. Inspect available skills before installing:
```sh
npx skills add wyh0626/doc-weaver --list
```
Then ask your agent:
> Use $doc-weaver to translate /absolute/path/book.pdf into simplified Chinese. Preserve page structure, code, formulas and figures. Deliver a translated PDF and a side-by-side bilingual PDF, and visually check representative pages.
Or in Chinese:
> 用 $doc-weaver 翻译这份 PDF，保留排版和代码，输出中文版及中英对照版，并检查目录、代码和图表页。
Installation copies the skill; the agent then prepares its separate Python runtime and model/font cache. Python 3.12 is the tested interpreter. The helper accepts Python 3.10–3.13. The adapter requires **BabelDOC 0.6.4**, because it uses that version's internal PDF interfaces. Runtime setup and asset preparation need internet access; cached processing can then run without a translation API.
The [skills CLI](https://github.com/vercel-labs/skills) discovers `skills/doc-weaver/SKILL.md`. According to the [skills.sh FAQ](https://www.skills.sh/docs/faq), directory listing is driven by anonymous installation telemetry. Publication and an install command do not guarantee immediate listing; the badge links to the directory without claiming approval or immediate indexing.
## What happens
```text
PDF → BabelDOC layout/paragraph extraction → protected JSON batches
→ current agent writes translations → coverage/marker checks
→ BabelDOC layout replay → sample review/optional repairs
→ full PDF render → metadata/bookmarks → visual and structural review
```
The input is read-only. A source hash and extraction manifest prevent accidentally reusing translations after a source or parser configuration change. IDs include both source text and protected code/formula hints. Completed translation batches survive interruptions and re-batching.
The scripts **do not translate by themselves**: the agent writes every translation into JSON maps. No external translation service is selectable in the replay adapter. Instructions, URLs and shell commands inside the document are content to translate, never agent instructions to execute.
See the installed [SKILL.md](skills/doc-weaver/SKILL.md) and [command reference](skills/doc-weaver/references/workflow.md) for the complete workflow. Layout corrections start empty and must match reviewed source text; there are no book-specific repair rules in this repository.
## Scope and limits
- **PDF only in v0.1.** EPUB, HTML, TXT, JSON, DOCX, Markdown, SRT and VTT are planned, with no implemented adapters or delivery dates yet.
- Selectable text is required. Scanned PDFs need a separate OCR workflow. Text baked into images remains in the original image.
- Page structure and protected objects are retained, while translated prose reflows. Line breaks, font size, and substitute-font bold/italic styling can differ. Manual visual review is required for complex tables, columns, callouts and dense code.
- Visually preserved code may copy with different whitespace or missing PDF `ActualText` overrides. Verify copying separately if executable code matters; this release has no generic `ActualText` restoration.
- Internal BabelDOC APIs are pinned. Upgrading the dependency requires fresh extraction and representative layout tests. Only the CPU provider on macOS with Python 3.12 has been exercised for this release; other operating systems and providers need validation.
- The layout and overlap reports flag review candidates. Passing text checks cannot prove that a PDF has no clipping or overlap. Output files are complete only after visual review.
## Data handling
Dependency preparation downloads packages, models and fonts separately and accepts no document. Extraction/rendering disable Python socket connect/send operations and replay local JSON rather than calling a translation API. v0.1.1 additionally opts out of ONNX Runtime telemetry before native initialization and disables subsequent events through its API. These controls are defense in depth, **not an OS network sandbox** for native libraries or subprocesses, or evidence of historical zero egress.
The current agent may run in the cloud and receive extracted document text, hints, diagnostics and page images. For an entirely local workflow, supply offline translations or use a separately configured local model, perform review locally, and use OS isolation. Do not let a cloud agent read content-bearing files/images. No integrated local-model translator is shipped. Job checkpoints, inspection samples and reports contain document content; keep them private. This repository contains only code, documentation and original synthetic examples, with no user books, translations, caches or credentials. See [privacy and execution boundaries](skills/doc-weaver/references/privacy.md).
## Development
Fast regression tests use a small PyMuPDF dependency and generate their own PDFs:
```sh
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-test.txt
.venv/bin/python -m unittest discover -s tests -v
```
These checks cover protected-marker integrity, source/configuration changes, interrupted-job resumption, file alias safety and metadata/bookmark finalization without pixel changes. They do not download layout models or establish arbitrary PDF layout quality. See [examples](examples/README.md) for a separate native BabelDOC smoke workflow using prepared assets.
The [v0.1.0 validation record](VALIDATION.md) documents the complete synthetic smoke run, its explicit contents-page repair, visual checks and remaining coverage gaps.
Left: original synthetic source. Right: current-agent Chinese translation replayed through BabelDOC. Code-region pixels match; copied whitespace still requires separate validation.
## Sources and license
DocWeaver's PDF adapter is built around [BabelDOC 0.6.4](https://github.com/funstory-ai/BabelDOC/tree/v0.6.4), using its PDF intermediate representation, paragraph/style/formula processing, layout model, typesetting and writer. It adds agent-authored translation replay, resumable batches, source-bound repairs, safeguards and verification. BabelDOC does the underlying PDF parsing and layout work; this is an independent project, not an official BabelDOC release.
[PyMuPDF](https://pymupdf.readthedocs.io/en/latest/about.html#license-and-copyright) is used for PDF inspection, repairs, finalization and diagnostics. The packaging follows the [Agent Skills specification](https://agentskills.io/specification), and installation uses [Vercel's skills CLI](https://github.com/vercel-labs/skills).
DocWeaver is released under **AGPL-3.0-only**. BabelDOC's [license](https://github.com/funstory-ai/BabelDOC/blob/v0.6.4/LICENSE) and PyMuPDF's AGPL/commercial terms apply to those dependencies. Models and fonts have their own upstream terms and are not redistributed here. See [NOTICE](NOTICE.md) for attribution and source pointers.