HTPD

[HTPD - Hyper Text Portable Document]

[release] [PyPI] [MCP registry] [tests] [Apache-2.0]

Turn long PDFs into documents AI reads correctly - exact text, every answer with its page.

[Open HTPD Studio]   [Download]

In plain words  ·  See it work  ·  Install  ·  Use with your AI  ·  For developers  ·  Quality  

[A PDF becomes an HTPD file; a question uses only the sections it needs; the answer is exact text with its page]

In plain words

You have a long PDF - a 300-page datasheet, a 5000-page reference manual, a policy, a report - and a question about it. Given the whole PDF, an AI often answers slowly, misses details, mixes up tables and cannot show where its answer comes from.

HTPD prepares the document for the AI. The converter turns the PDF into one .htpd file: the same text, word for word, cut into the document's own chapters and sections, with the page of every paragraph, the tables as rows, and the figures as pictures. The AI then reads only the few sections a question needs and answers from the exact text - with the page, so you can check it.

[Exact text - Every fact has a page - Honest answers - 100 % local]

Try it in the browser: HTPD Studio.

See it work

Real commands and their output on a public 109-page data sheet (NXP i.MX 93, shortened where long).

1. Convert the PDF once - about a second for 100 pages:

[htpd convert turns the 109-page data sheet into one .htpd file in 1.2 seconds]

2. Ask in your own words - the exact line from the document, with its page and section:

[htpd-read shows the contents and answers two questions with the exact table row and page]

3. Figures stay pictures - an AI that can see images looks at the diagram itself:

[htpd-read figure writes the block diagram of the data sheet as a picture]

In daily use you do not type these commands: you give the .htpd file to your AI, or let the plugin, the skill or the MCP server do it for you.

Install in one minute

The converter and the reader run on your computer. What reaches an AI is only the text you give it.

Use it with your AI

/plugin marketplace add narendrachampaneri/htpd/plugin install htpd@htpd

pip install htpd-reader                                   # htpd-read and htpd-mcp, nothing else neededclaude mcp add htpd -- htpd-mcp --bundles ~/manuals       # Claude Code

For developers

How it works

flowchart LR    PDF["📄 PDF<br/>scanned or digital"] -->|htpd convert| H["HTPD<br/>sections · pages · tables · figures"]    H -->|upload| CHAT["AI chat<br/>(file + reading rules)"]    H -->|skill · plugin · MCP| AGENT["AI agent<br/>(Claude, Antigravity, Codex)"]    CHAT --> ANS["Answer from the exact text<br/>with page numbers"]    AGENT --> ANS

[A PDF page becomes a clean HTPD section with its place in the document and page marks]

Quick start

Download (no build needed) from the release page:

tar xzf htpd-0.1.2-linux-x64.tar.gzcd htpd-0.1.2-linux-x64./htpd convert manual.pdf --single           # writes manual.htpdsudo apt install tesseract-ocr               # optional: read scanned pages too

Build from source - Linux (Ubuntu 24.04, also WSL), g++ 13+, make or CMake, Python 3.10+:

git clone https://github.com/narendrachampaneri/htpd.git && cd htpd./scripts/get_pdfium.sh        # the PDF engine, once (about 4 MB)make                           # builds build/htpdmake test                      # the C++ tests

Convert and ask:

./build/htpd convert manual.pdf --single     # one file: manual.htpd  (for AI chats)./build/htpd convert manual.pdf              # a folder: manual.htpd/ (for tools and agents)
pip install htpd-reader                      # or: python3 -m pip install -e .htpd-read ask examples/single-file/sample.htpd "What is the maximum bus voltage?"

[page 2, 2.1.1 Limits]  Parameter | Min | Typ | Max | Unit  Bus voltage | 200 | 400 | 480 | V

Every answer line is copied word for word from the file; --context adds the whole sections for the AI. More commands: contents, section, search, figure, check - see reader/README.md.

The format

An HTPD document is plain UTF-8 text: Markdown with a few fields. Any model, editor or grep can read it.

<!-- htpd section {"n":14,"id":"sections/0014-4-1-5-maximum-frequency-of-main-modules","number":"4.1.5","level":3,"pages":[18,18,18],"parent":"sections/0008-4-1-chip-level-conditions"} -->## [S14] 4.1.5 Maximum frequency of main modules
Path: 4 Electrical characteristics > 4.1 Chip-level conditions > 4.1.5 Maximum frequency of main modules - page 18
<!-- page 18 -->
```textCortex®-A55 cores | 0.9 GHz | 1.4 GHz | 1.7 GHzDRAM | 933 MHz | 1400 MHz | 1866 MHzNPU | 500 MHz | 800 MHz | 1000 MHz```

• Sections follow the document's own headings and form a tree: parent, children, previous, next.
• Page marks <!-- page N --> stand above the text of every page.
• Tables are rows with | between cells (a cell over columns or rows is marked [>] / [=] where the page draws the lines of the table); code and listings keep their spacing.
• Figures are PNG pictures with caption and page, stored inside the file.
• Two forms, same content: a single .htpd file (for chats) and a folder with one file per section (for tools), which is also a valid Open Knowledge Format bundle.

The full specification is docs/FORMAT.md. Examples: examples/single-file/sample.htpd and examples/sample.htpd/.

Quality

Speed and size - single file, figures and OCR on, a 2-core cloud machine:

Most of a file with figures is their pictures, at its very end; the text comes first. --figures off leaves them out.

Finding the answer - 133 test questions about two public manuals (eval/report.md, written by the evaluation harness):

The text handed to the AI is about 6 % of the whole document, and the reader correctly says "not in this file" for 95 % of the questions the manuals do not answer.

Many kinds of PDF - 45 PDFs of known text, made by Word, LaTeX, Chrome, wkhtmltopdf and slide software, scanned, and with letters drawn as shapes (tests/zoo): 99 % of the text in order, 96 % of the headings, 89 % of the table rows exact.

Robustness - a stress test of 34 difficult PDFs (two columns, sideways tables, rotated pages, 1500 pages, encrypted, truncated and corrupted files): no crash, no hang, every file valid, no word lost. 102 C++ tests and 155 Python tests run on every change.

Project layout

include/ src/ cli/      the converter (C++23, PDFium is used in one file only)reader/htpd_reader/     the reader: bundle, check, search, retriever, re-ranker, packer, answer, MCP serverskills/htpd/            the skill for AI apps (scripts/build_skill.py packs it)skills/convert/         the plugin's skill that converts PDFs.claude-plugin/         the Claude Code plugin and its marketplace (this repository is both)eval/                   evaluation harness, baselines, reportmodel/                  the training of the re-rankertests/                  C++ tests, test PDFs, the stress test, the document zoodocs/                   FORMAT.md · CONVERTER.md · READER.md · AI-APPS.md · BACKGROUND.mdexamples/               a converted document in both forms

Contributing

Issues and pull requests are welcome. Before you change anything, read AGENTS.md; the short version:

• All tests pass before a change is merged: make test and python3 -m pytest.
• Every new rule in the code comes with a test that fails without it.
• Never lose text and never make text up.
• A change to what is written into an HTPD file updates docs/FORMAT.md in the same commit.

License

HTPD is open source under the Apache License 2.0: you may use, change and share it, also in commercial products, as long as you keep the copyright and license notices (NOTICE) and mark what you changed. The license includes a patent grant from every contributor.

PDFium, which the converter uses, is not part of this repository and has its own license (BSD-style with an Apache-2.0 part); after scripts/get_pdfium.sh its license texts are in third_party/pdfium/licenses/. If you give the program to others together with libpdfium.so, give them those files too.