ルーティング

ルートへの 4 つの扉 — 汎用ラダー、シグネチャによるノミネーション、名前で指定する埋め込み空間、受け渡した計画。

ルーティングは、インストール済みのどの機能が各ページを読むかを決めます。判断は機能の kind に対して行われ、機能 ID に対しては決して行われません。そのため、サードパーティの OCR ディストリビューションはファーストパーティのものとまったく同じようにルーティングされます。機能がルートに入る扉はちょうど 4 つあり、宣言した kind がどの扉かを決めます。

扉	受け入れる kind	適用される条件	適用されない場合
汎用ラダー	`native_extraction`, `ocr`, `model`, `manual_review`	すべての計画。ページ証拠が最初の段を選び、それより下の段はすべてフォールバックとして計画に残ります。	何もインストールされていない kind の段はスキップされ、ラダーは次の段へ降ります。
シグネチャによるノミネーション	`parser`	リクエストが `signature_detection` を指定し、パーサー自身の `detect()` がドキュメントを認識した場合。	一致しなければ汎用ラダーだけになります。パーサーだけが宣言するメディアタイプを検出なしで計画すると、パーサー名とフラグを明記した unsatisfied なプランが返ります。
名前で指定する埋め込み空間	`embedder`	リクエストが `embedding_space_ids` を列挙した場合。	フォールバックはありません。スナップショットにない空間は `422`、いま実行できない埋め込み器は `503` です。
受け渡した計画	計画がすでに指名しているものすべて	`encode(plan=...)` が以前の判断を再実行する場合。	ソースダイジェストまたはスナップショットの不一致は `409` です。実行が黙って再計画することはありません。

汎用ラダー

ラダーは既定ポリシーのエスカレーション順序です。下の段ほど正しく読むための費用が上がります。

ネイティブテキスト層 → ocr → ビジョンモデル → 手動レビュー

事前観察の証拠がページごとに最初の段を選びます。利用可能なテキスト層を持つページや空に見えるページは無料のネイティブ抽出から、スキャンページは認識処理から始まります。選ばれた段より下の段はすべて順序付きフォールバックとして計画に残るため、機能の失敗 1 回で失われるのはページではなく 1 回の試行です。手動レビューは終端です。人間は何でも読めるためメディアタイプを宣言せず、他へフォールバックすることもできません。それが、読めないコンテンツを黙って落とさずに見える状態に保つ仕組みです。

可用性は意図的に参照されません。計画は記録済みインベントリに対する作業の提案であり、機能がいま実行できるかどうかは実行時の問いです。実行時には 503 と次のフォールバックへの降下で答えられます。

ラダーは閉じています

kind に対してルーティングすることが、拡張をルーティング可能にしています。それは同時に限界でもあります。kind の集合は 6 つ、エスカレーションの段は 3 つ、ポリシーが読む signal は 2 つに固定されています。ディストリビューションをインストールするとルーティング先が増えますが、段や kind や signal の意味が増えることは決してありません。それらはいずれも「indx が何にいくら払うか、どの順序で払うか」という判断だからです。これを変えるのはファーストパーティのポリシー変更であり、POLICY_VERSION の更新を伴います。

あなたの機能が 6 つのどれでもない場合 — 分類、秘匿処理、翻訳、音声、表構造など — 最も近い kind を宣言し、その段の位置を引き継ぎます。コスト・品質・レイテンシはデプロイ側が INDX_ROUTING_ECONOMICS で補正します。この数値がコア所有なのは段と同じ理由です。自分で価格を宣言できる機能は、その価格でルートを買えてしまいます。その代償は隠されていません。1 ページ $0.05 を課金するホスト型 OCR も、運用者が実際の数値を書き込むまでは OCR の既定値 $0.0005 で受理され、見積もられます。

同じ閉鎖性は事前観察の signal にも当てはまります。PageEvidence.signals は観察器が見たものを報告できるよう自由文字列のタプルですが、ラダーが読むのはそのうち 2 つだけです。観察器が handwriting を出しても、誤りではなく無効です。手書きがベンチマークで唯一残るルート精度の取りこぼしであるのは、そのためです。

mixed-multipage.pdf
  document  [native-extraction, generic-ocr, generic-vlm, manual-review]   # 利用可能なテキスト層
  page:2    [generic-ocr, generic-vlm, manual-review]                      # スキャンページ

シグネチャによるノミネーション

parser は「何かが先に認識したドキュメントに対してのみ正しい」専用機能なので、ラダーには決して入りません。リクエストが signature_detection でオプトインすると、インストール済みの各パーサーの detect() が計画時に低コストで問い合わせられます(OCR、モデル、レンダリング、ネットワークは使いません)。一致したパーサーは汎用ラダーの前にノミネートされ、ラダーを置き換えることはありません。シグネチャは推測です。専用機能の後ろにラダーを残すことで、誤った推測の代償はドキュメント全体ではなく低コストな試行 1 回になります。

invoice-anthropic.pdf, signature_detection=true
  document  [invoice-parser, native-extraction, generic-ocr, generic-vlm, manual-review]

リージョンスコープのシグネチャは何もノミネートしません。それはページの一部についての主張であり、計画が保持するのはドキュメントとページの割り当てだけです。これを昇格させると「このリージョンに請求書の表がある」を「このページは請求書である」と読み替え、ページ全体を専用機能へ送ってしまいます。一致自体は計画に残るので、何が認識されたかは呼び出し側に伝わります。

ノミネーションはパーサーの唯一の扉です。パーサーだけが宣言するメディアタイプを検出なしで計画すると、パーサー名とフラグを制約として明記した unsatisfied なプランが返ります。黙って手動レビューへ送られることはありません。フォーマットを汎用的に読み取れる機能であれば native_extraction として宣言し、パーサーを併せて同梱してください。詳細は専用パーサーを参照してください。

名前で指定する埋め込み空間

embedder はページを読まないため、どの段からも到達しません。呼び出し側が空間を名前で指定したときに実行されます。

result = service.encode(
    EncodeRequest(..., embedding_space_ids=("default-text",))
)

ここにフォールバックのラダーが存在しないのは意図的です。空間を名指しした呼び出し側はまさにその空間を求めており、黙って別の空間に差し替えれば下流のあらゆるベクトル比較が壊れます。スナップショットにない空間は 422、実行できない埋め込み器は 503 であり、代替は行われません。詳細は埋め込み空間を参照してください。

受け渡した計画

計画はシリアライズ可能な成果物なので、一度決めたルートを検査し、承認し、保存し、後から実行できます。encode() が計画を受け取ると、Executor はソースダイジェスト、メディアタイプ、機能スナップショットを検証し(不一致は型付きの 409)、選択済みの機能とその計画がすでに指名しているフォールバックだけを実行します。実行が黙って再計画することはありません。上記の扉を通って計画に入ったものだけが、実行を許されるものの全部です。詳細はインターフェースと API を参照してください。