HTPD

長い PDF を、AI が正確に読み取れるドキュメントに変換します。テキストは原文どおり、回答にはページ番号が付いています。

かんたんに説明すると  ·  動作を見る  ·  インストール  ·  AI で使う  ·  開発者向け  ·  品質  

平易な言葉で

長い PDF をお持ちだとします。300 ページのデータシート、5000 ページのリファレンスマニュアル、ポリシー、レポートなどです。それについて質問があるとき、PDF 全体を渡すと、AI は回答に時間がかかったり、詳細を見落としたり、表を混同したり、回答の根拠を示せなかったりすることがあります。

HTPD は、AI が扱いやすいように文書を準備します。 コンバーターは PDF を 1 つの .htpd ファイルに変換します。そこには元の文章が一字一句そのまま、文書独自の章や節ごとに分割されて収録され、すべての段落にページ番号が付き、表は行として、図は画像として保存されます。AI は質問に必要なわずかな節だけを読み、正確な文章に基づいてページ番号付きで回答するため、内容を確認できます。

ブラウザーで試す： HTPD Studio。

動作を見る

一般公開されている 109 ページのデータシート（NXP i.MX 93）で実行したコマンドと出力です（長い部分は短縮しています）。

1. PDF を一度だけ変換 - 100 ページなら約 1 秒です。

2. 自分の言葉で質問 - 文書内の正確な一文を、ページ番号と節名とともに確認できます。

3. 図は画像のまま - 画像を認識できる AI が図そのものを確認します。

普段の利用では、これらのコマンドを入力する必要はありません。.htpd ファイルを AI に渡すか、プラグイン、スキル、MCP サーバーに処理を任せられます。

1 分でインストール

コンバーターとリーダーはお使いのコンピューター上で動作します。AI に渡るのは、AI に提供したテキストだけです。

AI で使う

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

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

開発者向け

仕組み

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

リリースページからダウンロードできます（ビルド不要）。

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

ソースからビルド - Linux（Ubuntu 24.04、WSL も対応）、g++ 13 以降、make または 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/htpd
make test                      # the C++ tests

変換して質問する：

./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

回答の各行は、ファイルから一字一句そのままコピーされます。--context を指定すると、AI にセクション全体が追加されます。その他のコマンド：contents、section、search、figure、check - 詳しくは reader/README.mdをご覧ください。

形式

HTPD ドキュメントは、いくつかのフィールドを含む Markdown のプレーン UTF-8 テキストです。どのモデル、エディター、grep でも読み取れます。

## [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



```text
Cortex®-A55 cores | 0.9 GHz | 1.4 GHz | 1.7 GHz
DRAM | 933 MHz | 1400 MHz | 1866 MHz
NPU | 500 MHz | 800 MHz | 1000 MHz
```

• セクションはドキュメント自体の見出しに従ってツリーを形成し、親、子、前、次の関係を持ちます。
• ページマーク `` は各ページのテキストの前に置かれます。
• 表はセルを | で区切った行で構成されます。コードとリストの間隔はそのまま保持されます。
• 図はキャプションとページ番号を含む PNG 画像で、ファイル内に保存されます。
• 2 つの形式で同じ内容を保持： 単一の .htpd ファイル（チャット用）と、セクションごとに 1 ファイルを含むフォルダー（ツール用）。後者は有効なオープンナレッジ形式バンドルでもあります。

仕様の全文はdocs/FORMAT.mdをご覧ください。 例：examples/single-file/sample.htpdおよび examples/sample.htpd/。

品質

速度とサイズ - 図と OCR を有効にした単一ファイル、2 コアのクラウドマシンでの測定：

図を含むファイルでは、その大部分を占めるのがファイル末尾の画像です。テキストはその前にあります。--figures off を指定すると、図は除外されます。

回答の検索 - 2 つの公開マニュアルに関するテスト質問 133 件（評価ハーネスが作成。詳細はeval/report.md）：

AI に渡すテキストはドキュメント全体の約 6 % です。また、マニュアルに答えがない質問の 95 % に対して、リーダーは「このファイルにはありません」と正しく回答します。

さまざまな PDF に対応 - Word、LaTeX、Chrome、wkhtmltopdf、スライドソフトウェアで作成された、既知のテキストを含む 45 件の PDF。スキャンしたものや、文字が図形として描画されたものも含みます（tests/zoo）：テキストの 99 % が順序どおり、見出しの 96 %、表の行の 89 % が完全に一致します。

堅牢性 - 2 段組み、横向きの表、回転したページ、1500 ページ、暗号化、途中で切り詰められたファイル、破損したファイルなど、難しい PDF 34 件でストレステストを実施：クラッシュやハングはなく、すべてのファイルが有効で、単語の欠落もありません。変更のたびに C++ テスト 102 件と Python テスト 155 件を実行します。

プロジェクトの構成

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 server
skills/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, report
model/                  the training of the re-ranker
tests/                  C++ tests, test PDFs, the stress test, the document zoo
docs/                   FORMAT.md · CONVERTER.md · READER.md · AI-APPS.md · BACKGROUND.md
examples/               a converted document in both forms

貢献

イシューやプルリクエストを歓迎します。変更を加える前に、 AGENTS.md をお読みください。要点は次のとおりです。

• 変更をマージする前に、すべてのテストに合格する必要があります：make test と python3 -m pytest。
• コードに新しいルールを追加する場合は、そのルールがなければ失敗するテストも追加してください。
• テキストを失わせたり、テキストを捏造したりしないでください。
• HTPD ファイルへの書き込み内容を変更する場合は、同じコミットで docs/FORMAT.md も更新してください。

ライセンス

HTPD は Apache License 2.0 に基づくオープンソースです。著作権表示とライセンス表示（NOTICE）を保持し、変更内容を明記すれば、商用製品を含め、使用、変更、共有できます。 このライセンスには、すべてのコントリビューターによる特許の使用許諾が含まれています。

コンバーターが使用する PDFium はこのリポジトリには含まれておらず、独自のライセンス（BSD スタイルで、Apache-2.0 の条項を含む）があります。scripts/get_pdfium.sh の実行後、そのライセンス文書は third_party/pdfium/licenses/ にあります。libpdfium.so とともにこのプログラムを他の人に渡す場合は、これらのファイルも渡してください。