Parse-Flow：オープンソースのビジュアルドキュメントインテリジェンスワークフローデザイナー

非構造化ドキュメントは、企業が情報を保存・共有する主要な手段であり続けています。契約書、請求書、レポートなど、これらのドキュメントに共通するのは、レイアウト、言語、コンテキストが混在しており、下流システムが直接消費できないことです。ドキュメントインテリジェンス（ドキュメントを構造化された機械可読データに変換する学問分野）は、現代のAIスタックを企業にとって真に有用にするための重要な層です。堅牢な解析、分類、分割、抽出なしには、あらゆる検索パイプライン、エージェント、分析ダッシュボードは脆弱な基盤の上に構築されることになります。

Parse-Flow は、4つのドキュメント処理プリミティブ（解析、抽出、分類、分割）をビジュアルワークフローデザイナー、非同期ワーカー、ライブイベントダッシュボードの中心に据えた小規模なオープンソースプロジェクトです。ユーザーはステップをキャンバスにドラッグし、ドキュメントをドロップすると、パイプラインの実行に伴ってイベントがストリーミングされるのを確認できます。この記事では、その構築方法、特にバックエンドワークフローが llama-agents ワークフロー上でどのように設計されているかに焦点を当てます。

システムの形状

Parse-Flow は4つの連携プロセスで構成されます：

• React フロントエンド：ノードベースのワークフローデザイナー、実行ビュー、ジョブダッシュボードをホスト。
• Bun サーバー：アップロードを受け付け、LlamaParse プラットフォームと通信し、ジョブをキューに追加し、Postgres から履歴を読み取り、サーバー送信イベントでイベントストリームをブラウザにブリッジ。
• Python ワーカー：ジョブを消費し、実際のドキュメントワークフローを実行。
• Redis：ジョブキューとイベントバスとして機能。Postgres はジョブとそのイベント履歴のシステムオブレコード。

通信パターンは次のとおり：Bun サーバーはジョブを Redis リストにプッシュし、ワーカーがそれをプル。ジョブ実行中、すべてのイベントがジョブごとの Redis ストリームに追加されると同時に Postgres に永続化されます。Bun サーバーは専用のサブスクライバー接続を作成してそのストリームをブラウザにブリッジし、キープアライブを送信し、最終イベントを観測すると接続を閉じます。

この分離により2つの主な利点が得られます：ワーカーは HTTP 層をブロックせずに低速で実行可能。すべてのイベントが2回（ライブストリームと永続ストレージ）キャプチャされるため、ページをリロードしたユーザーは Postgres から再構築された完全な履歴を表示・リプレイできます。

4つのプリミティブ、任意の組み合わせ

ワークフロー語彙は意図的に LlamaParse プラットフォームのサービスに焦点を絞っています：

• 解析：Parse を使用してドキュメントをクリーンな Markdown とテキストに変換。階層とオプションのプロンプトを選択可能。
• 分類：ユーザー定義のルールセットに基づき、推論と信頼度スコア付きでドキュメントにカテゴリを割り当て。
• 分割：カテゴリのリストに従ってドキュメントを型付きチャンクに分割。
• 抽出：ユーザー提供の JSON スキーマに基づき、ドキュメントから構造化 JSON を抽出。

システムの表現力を生み出すのはプリミティブ自体ではなく、それらを連鎖させる方法を制約する「許可ペアグラフ」です。すべての遷移が意味を持つわけではありません：抽出は常に終端、解析は他の3つのいずれかに引き継げ、分類と分割は一致したルールやカテゴリに応じて解析または抽出にルーティングできます。フロントエンドは送信前にこのグラフに対してフローを検証し、バックエンドも受信時に再検証します。

結果として、JSON ベースの小さなドメイン固有言語が生まれます：順序付けられたステップと型付きハンドオフからなる FlowDefinition は、ほとんどの現実のドキュメントパイプライン（解析→抽出、分類→正しいスキーマへのルーティング、セクションごとに分割→それぞれ異なる方法で解析）を記述するのに十分な表現力を持ちながら、網羅的に推論できるほど小さく保たれています。

コアの LlamaAgent ワークフロー

興味深い設計作業はワーカーにあり、単一の LlamaAgent Workflow が実行時にユーザー定義のフローを解釈します。

llama-agents フレームワークはイベント駆動型で、意見を押し付けないワークフローエンジンを提供します：各 @step は非同期関数で、イベントを受け取り1つ以上のイベントを返します。ランタイムはイベントを型シグネチャが一致する任意のステップにルーティングします。状態は型付き Context ストアに保持され、ステップはトランザクション的に読み書きできます。ctx.write_event_to_stream で書き込まれたイベントは、実行を監視している人（この場合はワーカーで、イベントを Redis と Postgres に転送します）に公開されます。

Parse-Flow の DocumentWorkflow は正確に3つのステップを公開し、実行システムの鍵は、それらが協調して任意の長さのフローを辿る方法にあります。

ステップ 1 — ブートストラップ

最初のステップは、解析済みの FlowDefinition と LlamaCloud ファイル ID を運ぶ RedisInitialEvent を受け取ります。フローをワークフロー状態に書き込み、現在のインデックスがゼロであることを記録し、最初のステップに対応する型付き入力イベント（ParsingInputEvent、ClassifyInputEvent、SplitInputEvent、ExtractInputEvent のいずれか）を発行します。この時点以降、ワークフローはデータ駆動型となり、ブートストラップステップは二度と実行されません。

ステップ 2 — ワーカー

ワーカーステップは意図的に広い入力型（任意の InputEvent）を持ちます。イベントタイプに基づいてパターンマッチングを行い、ステップインデックスを進め、LlamaParse プラットフォーム上の対応する操作にディスパッチします。各操作は Rust 風の Result を返し、解析済み Markdown、分類判定、分割チャンク、抽出 JSON のいずれかを含む型付き成功イベント、またはエラーメッセージを含む ErrorOutputEvent に展開されます。

小さな重要事項：解析ステップが parse_job_id を生成すると、後続の分類・抽出操作は raw ファイルよりもその ID を優先します。つまり、ユーザーが解析 → 抽出と連鎖させた場合、抽出ステップは既に解析済みの表現を操作するため、ファイルをゼロから解析し直す必要がなく、ステップ間で状態を共有することによる無料のレイテンシーとコスト削減が得られます。

ステップ 3 — ルーター

後処理ステップは、実行時に実際に許可ペアグラフを強制する場所です。最後の出力イベント、フロー内の現在のステップ、前のステップに記録されたハンドオフ記述子を確認します。これら3つの情報から、次に何を発行するかを決定します：

• フローの終端に達した場合、最後の出力を WrapperStopEvent でラップし、ワークフローは終了。
• 出力がエラーの場合、ショートサーキットして停止。
• それ以外の場合、ハンドオフ（classify-extract、parse-classify、split-parse など）に従って次の入力イベントを構築します。ルーティングハンドオフの場合、前のステップが一致したルールに対応する JSON スキーマ、解析階層とプロンプト、またはカテゴリをルックアップし、次の入力イベントにパッケージします。

次に、そのルーターが再び InputEvent を発行し、ワーカーステップにループバックします。ブートストラップ-ワーカー-ルーターの三重奏は、ユーザーのフローを1ステップずつ辿るステートマシンとなり、すべての遷移は型付き、すべてのハンドオフは検証済み、すべてのイベントは観測可能です。

Parse-Flow 実行中のイベントを表示するダッシュボード

このデザインが有効な理由

3つの特性がこのデザインを快適なものにしています：

1. フローはコードではなくイベントに存在する。同じ DocumentWorkflow がすべてのジョブを実行します。新しいパイプラインには新しい Python コードは不要で、新しい JSON フロー定義があれば十分です。これにより、その上にビジュアルデザイナーを構築することが可能になります。
2. すべての遷移が観測可能。各ステップは戻る前にイベントをストリームに書き込むため、ダッシュボードはワークフロー自身が見るのと同じワークフローを見ることができます。現実と同期がずれる別個のログ層はありません。
3. 失敗は値である。エラーは第一級の出力イベントであり、ルーターはそれをクリーンな停止に変換する方法を知っています。ユーザーは実際のメッセージを含む最終イベントを受け取ります。システムが黙ってハングすることはありません。

ドキュメントインテリジェンスが重要な層である理由

2026年において、解析と抽出をモデル呼び出しの背後に隠れた解決済み問題として扱うのは魅力的ですが、そうではありません。間違ったスキーマで請求書を分類したり、間違った境界で契約書を分割したり、間違ったページから日付を抽出するパイプラインは、下流で回復不可能な方法で失敗します。耐久性のあるシステムは、ドキュメントインテリジェンスを第一級の工学的関心事として真剣に扱うシステムです：組成可能なプリミティブ、検証済みの遷移、観測可能な実行、永続的な履歴。

Parse-Flow は、ワークフロー層を適切に設計することを許されたときにどのようなものができるかを示す小さな例です：4つのプリミティブ、型付きハンドオフグラフ、そしてそれを辿ることだけを仕事とする LlamaAgent ワークフロー。

試してみる

完全なソースコードはオープンです。クローンして、LlamaCloud キーを指定し、独自のドキュメントを持ち込みましょう。 → github.com/run-llama/parse-flow