AILANG Parse

AILANG Parse

AILANGによる、ドキュメントの汎用パースおよび生成機能です。DOCX、PPTX、XLSX、PDF、画像ファイルから構造化コンテンツを抽出し、JSONおよびMarkdownに変換します。また、9種類の形式でドキュメントを書き出せます。ドキュメントを作成するには、Markdownで記述して変換してください。詳しくはMarkdownでドキュメントを作成するをご覧ください。

Office形式（DOCX、PPTX、XLSX）には決定論的なXMLパースを使用するため、AIもクラウドも不要で、瞬時に結果が得られます。PDFはデフォルトで、決定論的なpdftotextバックエンド（poppler）を使用します。こちらもAIやクラウドは不要です。ローカルの代替手段としてdoclingとliteparseも利用でき、スキャンされたPDFや画像のみのPDFの場合は、ローカルのdocling OCRに自動的に切り替わります。プラグイン可能なAI（Gemini、Claude、ローカルのOllama）は--pdf-backend aiで利用できますが、自動的に選択されることはありません。画像の処理には、接続したAIモデルが使われます。AILANG ParseはAIに依存しません。--pdf-backend／--aiを切り替えるだけで、コードを変更せずにバックエンドを変更できます。

インストール

方法は2つあります。どちらも docparse コマンドを PATH に追加し、解析したファイルと同じ場所に出力を書き込みます（変更するには --output-dir DIR または DOCPARSE_OUTPUT_DIR を指定してください）。

すでに AILANG をお使いですか？（このパッケージの0.42.0以降、AILANG v0.40.0 dev以降）

ailang install sunholo/ailang_parse
docparse report.docx

パッケージの [bin] テーブルによって、レジストリキャッシュから直接実行するシムが ~/.ailang/bin に追加されます。ファイルを1つ解析するか、--convert で変換できます。意図的に機能を絞った方法のため、describe／summarize、バッチモード、PDFバックエンド、--install-backends は含まれません（詳細は以下を参照してください）。ailang bin list ／ ailang bin uninstall docparse で管理できます。

それ以外の場合、またはフルCLIを使う場合：

curl -fsSL https://www.sunholo.com/ailang-parse/install.sh | sh

公開済みパッケージ（約400 KB）を取得し、AILANGランタイムがない場合はインストールして、フル機能の docparse ラッパー（および docparse-audit、docparse-render）を ~/.local/bin にリンクします。--version、--prefix、--uninstall に対応しており、再実行しても何も変更されません。両方をインストールした場合は、どちらの docparse が解決されるかを ailang install が通知します。

これですべての決定論的な形式に対応できます。PDFには、見落としやすい追加の準備が2つ必要です。

brew install poppler        # pdftotext, the default PDF backend
                            # (apt install poppler-utils on Debian/Ubuntu)
docparse --install-backends # docling + liteparse, for scans and layout

--pdf-backend を指定しない場合でも、--install-backends は重要です。pdftotext でテキストレイヤーが見つからない場合、パーサーは自動的に docling に切り替えるため、これがないとデフォルトのバックエンドではスキャンされたPDFを処理できません。AIバックエンドの認証には、APIキーではなくGoogle ADC（gcloud auth application-default login）を使用します。

git clone https://github.com/sunholo-data/ailang-parse.git
ln -s "$(pwd)/ailang-parse/bin/docparse" /usr/local/bin/docparse

SDK

お好みの言語からAILANG Parseを使用できます。

pip install ailang-parse          # Python
npm install @ailang/parse         # JavaScript/TypeScript
go get github.com/sunholo-data/ailang-parse-go  # Go

クイックスタート

# Office documents (deterministic, no AI needed)
docparse report.docx
docparse slides.pptx
docparse spreadsheet.xlsx

# PDF (deterministic pdftotext by default — no AI); images (AI auto-enabled)
docparse document.pdf
docparse photo.png

# Options
docparse report.docx describe        # AI image descriptions
docparse report.docx summarize       # AI document summary
docparse contract.pdf                # PDF: deterministic pdftotext (default)
docparse scan.pdf                    # Scanned PDF: escalates to local docling OCR
docparse scan.pdf --pdf-backend ai --ai gemini-2.5-flash  # External AI (paid), opt-in only

# Format conversion
docparse report.docx --convert output.html
docparse data.csv --convert report.docx
docparse notes.md --convert slides.pptx
docparse notes.md --convert offer.docx --reference-doc letterhead.docx

# AI document generation
ailang run --entry main --caps IO,FS,Env,AI --ai gemini-2.5-flash \
  docparse/main.ail --generate report.docx --prompt "Q1 sales report with tables"

出力

各実行では、実行元のディレクトリに次のファイルが生成されます（変更するには --output-dir DIR または DOCPARSE_OUTPUT_DIR を指定してください）。

• <filename>.json — 型付きブロックを含む構造化JSON
• <filename>.md — LLMでの利用に適したMarkdown

AILANG Parseが抽出する情報

OfficeDocBench v2（87ファイル、11形式、8指標）：AILANG Parse PR #115候補は、カバレッジ100.0%で複合スコア**97.7%**を達成しました。標準モードのLlamaParseを含む、9つのアダプターを比較しています。ソースで検証済みの構造アサーションにより、セルの位置、コメントの対象、リストの階層、書式、数式、色、スライドとノートの関係を測定するようになりました。方法論と結果。

対応形式

解析（16形式）： DOCX、PPTX、XLSX、ODT、ODP、ODS、HTML、Markdown、CSV、EPUB、EML、MBOX、TEX、RTF、PDF、画像（JPG/PNG）

生成（9形式）： DOCX、PPTX、XLSX、ODT、ODP、ODS、HTML、Markdown、QMD（Quarto）

Markdown でのドキュメント作成

LLM が入力として書けるのは Markdown なので、ドキュメントを生成する実用的な方法は、Markdown を書いて 9 種類の出力形式のいずれかに変換することです。

docparse report.md --convert report.docx

変換後も保持されるもの：YAML フロントマター（タイトル／著者／日付 → ドキュメントのプロパティ）、太字／斜体／コード／取り消し線の文字書式、実際のハイパーリンクとしてのリンク（ローカルパスの画像は読み込まれて埋め込まれます）、フェンス付きコードブロック、引用、入れ子のリスト、水平線、配置や列の結合に対応した表です。

ヘッダー、フッター、コメント、変更履歴には Markdown の構文がありません。これらは、すでに含まれているドキュメントから変換する場合に保持されます。

ローカルでのドキュメント検証（v0.41.2+）

docparse-audit と docparse-render は、CLI 用の AILANG コンパニオンです。AILANG Parse v0.41.2 には、AILANG 0.35.0 以降が必要です。これらはローカルで実行され、ホストされたアカウントは必要ありません。インストーラーは、インストールされたリリースに含まれている場合、これらへのリンクを設定します。チェックアウト内では、./bin/docparse-audit と ./bin/docparse-render を使用します。

docparse-audit report.docx --strict
docparse-render report.docx --output-dir qa/report
docparse-render before.docx --compare after.docx --output-dir qa/comparison

読み取り専用の DOCX 監査では、表のグリッドとヘッダー、見出しの抜け、画像の説明、リンク、コメント、フィールドについて、JSON 形式のインベントリと検出結果を出力します。終了コードは、監査完了時が 0、--strict を指定して検出結果がある場合が 1、入力を読み取れない場合が 2 です。これは範囲を限定した構造チェックであり、アクセシビリティを認定したり、任意のスタイル継承を解決したりするものではありません。

レンダリングは .docx、.odt、.pptx、.xlsx、.pdf に対応しています。Office 形式の入力には LibreOffice と Poppler をインストールしてください。PDF には Poppler のみが必要です。新たな Python 依存関係は必要ありません。--soffice／--pdftoppm（または DOCPARSE_SOFFICE／DOCPARSE_PDFTOPPM）でツールを選択します。--dpi のデフォルトは 144、--timeout のデフォルトはプロセスあたり 120 秒です。出力ディレクトリは新規のものである必要があります。各ドキュメントについて PDF と番号付きの PNG ページが生成され、マニフェストにはソースのハッシュ、ツールのパス、ページディレクトリが記録されます。比較では、非圧縮ラスターハッシュを使って変更・追加・削除されたページを特定します。2 組の PNG を並べて確認してください。差分のオーバーレイは生成されません。visual_review: pending は、ページ画像の確認がまだ必要であることを示します。

実装は docparse/services/document_render.ail と docparse/services/docx_audit.ail にあります。回帰検証も AILANG で行います。

ailang run --entry main --caps IO,FS,Env,Process \
  --process-allowlist "true,false,mktemp,mkdir,$(command -v soffice),$(command -v pdftoppm)" \
  --process-timeout 120s scripts/verify_document_quality.ail -- \
  /tmp/docparse-quality-new "$(command -v soffice)" "$(command -v pdftoppm)"

テンプレートを使った生成 DOCX のスタイル設定

--reference-doc は Quarto/Pandoc の reference-doc 機能です。既存の .docx が見た目を決め、Markdown が内容を提供します。

docparse annex.md --convert annex.docx --reference-doc letterhead.docx

生成される表では、選択したセクションの使用可能な幅が使われます。列には上限付きのコンテンツ比率が適用され、意味を持つヘッダーは繰り返し表示されます。結合セルの幅は、そのセルがまたぐ列の幅の合計になります。

テンプレートの styles.xml、numbering.xml、テーマ、埋め込みフォント、ヘッダー、フッター、ページ設定が新しいコンテンツに適用されます。マージ処理で再生成されないものはすべてバイト単位でそのまま引き継がれるため、レターヘッド、ロゴ、ライセンスされたフォントも、元のまま正確に出力されます。

各要素の由来：

知っておくべき注意点が 2 つあります。

• テンプレートのヘッダーとフッターが優先されます。 ソースドキュメント独自のヘッダーはレターヘッドと混合されず、破棄されます。ページの付属要素はすべてテンプレートの本文にある <w:sectPr> に含まれており、これが一括して引き継がれます。
• テンプレートのコメントは本文とともに破棄され、 commentsExtended.xml と people.xml も同様に破棄されます。ソースドキュメント内のコメントは引き継がれます。

複数セクションのテンプレートでは、2 つのフラグで詳細を指定できます。

• --reference-section N は、ページ設定、ヘッダー、フッターを提供するテンプレートのセクションを選択します。1 は Word の番号付けで最初のセクションです。デフォルトは最後のセクションです（本文レベルのセクションで、フラグを指定しない場合に常に引き継がれてきたものです）。複数セクションのテンプレートでは、必要なページ付属要素が前のセクションにあることがよくあります。たとえば、Annex のフッターがない場合に、master agreement の CONFIDENTIAL フッターを使う場合です。
• --table-style NAME は、生成される表をテンプレートで定義された表スタイルに結び付けます（styleId、次にスタイル名で照合します）。指定しない場合、テンプレートに Table という名前のスタイルがあればそれが使われ、なければ暗黙の Normal Table 以外で最初の表スタイルが使われます。スタイルを指定すると、ジェネレーターはハードコードされた罫線の出力を停止し、罫線はそのスタイルで設定されます。

読み取り不能、または DOCX ではない参照ファイルはエラーとなり、何も書き込みません。組み込みスタイルへの無言のフォールバックでは、指定されたレターヘッドだけがない一見もっともらしいファイルが生成されてしまうためです。DOCX 出力のみ対応しています。

アーキテクチャ

docparse/
├── types/document.ail           # Block ADT (11 variants)
├── services/
│   ├── format_router.ail        # Format detection (36 inline tests)
│   ├── zip_extract.ail          # ZIP layer (9 inline tests)
│   ├── docx_parser.ail          # DOCX XML → Blocks (6 inline tests)
│   ├── pptx_parser.ail          # PPTX slides → Blocks
│   ├── xlsx_parser.ail          # XLSX worksheets → Blocks
│   ├── direct_ai_parser.ail     # PDF/image → Blocks (AI)
│   ├── layout_ai.ail            # AI self-healing (optional)
│   ├── output_formatter.ail     # JSON + markdown output
│   └── docparse_browser.ail     # WASM browser adapter
└── main.ail                     # CLI entry point

コントラクトは 91 件、インラインテストは 50 件以上あります。91 件のうち、14 件は Z3 で完全に証明されます。残りは CI で --prove／--verify-contracts のもと実行時にチェックされますが、パーサーのコードが再帰的かつ高階であり、Z3 の決定可能な断片の範囲外であるため、静的チェックはスキップされます。

AI の設定

AILANG Parse は AILANG の AI エフェクトを使用します。AILANG がサポートするモデルであれば、どれでも動作します。

docparse scan.pdf --ai gemini-2.5-flash          # Google (default; fast)
docparse scan.pdf --ai gemini-3-flash-preview    # Google (slower; thinking model)
docparse scan.pdf --ai granite-docling           # Local Ollama (free)
docparse scan.pdf --ai claude-haiku-4-5          # Anthropic

AI の使用量は機能の予算（main の AI @limit=200）によって制限されるため、コストを予測できます。

開発コマンド

docparse --check       # Type-check all modules
docparse --test        # Run inline tests
docparse --prove       # Static Z3 contract verification

ベンチマーク

uv run benchmarks/run_benchmarks.py --suite office     # Structural (no API, instant)
uv run benchmarks/run_benchmarks.py --suite pdf         # PDF extraction (needs AI)
uv run benchmarks/run_benchmarks.py --competitors       # Compare to Docling etc.

詳細については benchmarks/ を参照してください。

ライセンス

Apache 2.0