pdf-brain-ingest

PDF Brain Ingest v2 (ADR-0234)

耐久性のある NAS ストレージ、nomic 埋め込み、ワークロードキューのオーケストレーションを備えた、段階的なアーティファクトチェーンパイプラインです。

Pipeline v2 Architecture

PDF (source, immutable)
  → Stage 1: CONVERT — opendataloader-pdf → {docId}.md (NAS artifact)
  → Stage 2: CLASSIFY + SUMMARIZE — taxonomy + LLM summary → {docId}.meta.json (NAS artifact)
  → Stage 3: CHUNK — markdown-native headings, no overlap → {docId}.chunks.jsonl (NAS artifact)
  → Stage 4: INDEX — upsert to docs + docs_chunks_v2 (nomic-embed-text-v1.5, 768-dim)

主な特性：

• 耐久性：NAS RAID5 上のアーティファクトは、再起動やクラッシュ後も保持されます
• 再開可能：各ステージで既存のアーティファクトを確認し、存在する場合はスキップします
• 復旧可能：再抽出せず、既存のアーティファクトから任意のステージを再実行できます
• 可観測性：各書籍の各ステージで OTEL イベントが発生します

Artifacts dir：~/.config/system-bus.env のマシンローカル値を使用する ${DOCS_ARTIFACTS_DIR}/{docId}/

• {docId}.md — 構造化された Markdown 抽出データ
• {docId}.meta.json — 分類、要約、メタデータ
• {docId}.chunks.jsonl — 1 行につき 1 件のチャンクレコード

Core Workflow

1) Preflight

joelclaw status
joelclaw docs status

ステータスに v1 と v2 のコレクション統計と、アーティファクトの利用可否の両方が表示されます。

2) Single File Ingest (v1 pipeline)

joelclaw docs add "/absolute/path/to/file.pdf"
joelclaw docs add "/absolute/path/to/file.pdf" --title "Title" --tags "tag1,tag2" --category programming

3) Single File v2 Reindex (artifact pipeline)

joelclaw docs reindex-v2 "/absolute/path/to/file.pdf"
joelclaw docs reindex-v2 "/absolute/path/to/file.pdf" --title "Title" --skip-existing

docs/reindex-v2.requested を発行 → 4 ステージのアーティファクトパイプライン → NAS アーティファクトと docs_chunks_v2。

4) Batch Reindex (full library)

# Reindex all PDFs from the configured NAS book root
joelclaw docs batch-reindex --skip-existing

# Reindex from existing Typesense docs collection
joelclaw docs batch-reindex --from-collection --skip-existing

docs/reindex-batch.requested を発行 → NAS／コレクションをスキャン → 個別の reindex-v2 イベントを 10 件ずつ、並行数 3 でディスパッチします。

--skip-existing は、NAS 上に 3 つすべてのアーティファクトがすでにある書籍をスキップします（デフォルトは true）。

5) Monitor Progress

# Artifact count on NAS (load machine-local config without printing it)
set -a; . ~/.config/system-bus.env; set +a
find "$DOCS_ARTIFACTS_DIR" -mindepth 1 -maxdepth 1 -type d | wc -l

# v2 collection chunk count
joelclaw docs status

# OTEL events from pipeline
joelclaw otel search "docs.reindex" --hours 4
joelclaw o11y session system-bus --hours 4

# Individual run trace
joelclaw runs --count 10
joelclaw run <run-id>

6) Inspect Artifacts

# Read the extracted markdown
joelclaw docs markdown <doc-id>

# Read the summary + taxonomy metadata
joelclaw docs summary <doc-id>

# Or directly on NAS after loading machine-local config
set -a; . ~/.config/system-bus.env; set +a
cat "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.md"
cat "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.meta.json" | jq
wc -l "$DOCS_ARTIFACTS_DIR/<docId>/<docId>.chunks.jsonl"

7) Retrieval from v2

# Search uses docs_chunks_v2 (nomic 768-dim) by default
joelclaw docs search "distributed consensus" --limit 8

# Context expansion
joelclaw docs context <chunk-id> --mode snippet-window
joelclaw docs context <chunk-id> --mode parent-section
joelclaw docs context <chunk-id> --mode section-neighborhood

8) Coverage Reconcile

joelclaw docs reconcile --sample 20

9) Recovery

バッチが停止したり、書籍の処理に失敗したりした場合：

• Inngest が各ステップを自動的に再試行します（デフォルトの再試行ポリシー）
• --skip-existing により、バッチを再度発行しても未完了の書籍のみが処理されます
• エラーは OTEL で確認します：joelclaw otel list --level error --hours 4
• 個別に再試行します：joelclaw docs reindex-v2 "/path/to/failed.pdf"

Extraction Details

• 主処理：opendataloader-pdf v2.0.0（Java ベース、ベンチマークで 1 位、精度 0.90）
• フォールバック：pypdf（Java を利用できない場合の基本的なテキスト抽出）
• 要件：Java 11 以降（panda に OpenJDK 25 をインストール済み、worker start.sh で PATH を設定）
• 速度：M4 Pro で 1 冊あたり約 2.5 秒

Embedding Model

• v2：ollama 経由の nomic-embed-text（M4 Pro で GPU アクセラレーション、768 次元、検索向けに調整）。取り込み時に事前計算し、生の float[] ベクトルとして保存します。Typesense の CPU 自動埋め込みより約 150 倍高速です。
• v1：ts/all-MiniLM-L12-v2 — 384 次元、汎用、Typesense の自動埋め込み（レガシーですが、引き続き docs_chunks にあります）
• Ollama は panda の localhost:11434 で実行されます。System-bus-worker（ホストプロセス）が取り込み時に埋め込みを生成します。

Chunking Strategy (ADR-0234)

• Markdown ネイティブの見出し検出（ヒューリスティックではなく # マーカーを使用）
• 目標トークン数を超えるセクション内で再帰的に分割
• オーバーラップなし（arxiv R100-0 の調査結果：精度が 45％向上）
• 2 レベルの階層：セクションチャンクとスニペットのサブチャンク
• heading_path は実際の Markdown の見出しレベルから導出
• コンテキストの継承：retrieval_text には [DOC: title] [SUMMARY: ...] [PATH: heading > path] [CONCEPTS: ...] が含まれます

Acquisition Pipeline (aa-book → ingest)

joelclaw send pipeline/book.download -d '{
  "query": "designing data-intensive applications",
  "format": "pdf",
  "reason": "library expansion"
}'

aa-book 経由でダウンロード → NAS にバックアップ → 即時処理のため docs/ingest.requested を発行します。

Inngest Events

イベント	関数	用途
docs/ingest.requested	docs-ingest	v1 パイプライン（単一ファイル）
docs/reindex-v2.requested	docs-reindex-v2	v2 アーティファクトパイプライン（単一ファイル）
docs/reindex-batch.requested	docs-reindex-batch	バッチオーケストレーター（すべての PDF）
docs/backlog.requested	docs-backlog	レガシーのマニフェストベースのバックフィル
docs/enrich.requested	docs-enrich	既存のドキュメントのメタデータを再エンリッチ
pipeline/book.download	book-download	新しい書籍を取得して取り込み