完全版用語集

英語版が原文です。

indx のユビキタス言語です。用語ごとに 1 エントリで、そのモノが何であるかを定義します。近縁語が ある場合は、避けるべき語 の行で名指しします。契約は packages/indx-interfaces にあり、 プロトコルドキュメントが各ポートを詳述します。

2 つのステージ

plan(): ステージ 1 — 入力を低コストで観察し、バージョン付き機能スナップショットに束縛された、シリアライズ 可能で説明可能な RoutePlan を返します。計画は高価な処理を決して呼び出しません。 避けるべき語: 「decide」（計画を生成する内部のポリシー関数であり、公開ステージではありません）。

encode(): ステージ 2 — 供給された、または新規作成された計画を実行し、ブロックツリー、埋め込み、使用量、 実行トレースを返します。実行は、計画がすでに名指ししたルートとフォールバックしか使えません。 補足: 「encode」には他に 2 つの意味があります — VectorEncoder.encode()（ベクトルの生成）と、 HTTP 操作の POST /v1/encode です。修飾なしではステージを指します。

embed(): テキストまたは画像のクエリを、名前付き埋め込み空間へエンコードします。クエリ側専用です。 ドキュメントベクトルは encode() の中で生成されます。

ソース

Source: 宣言された入力 — UriSource と InlineSource の判別可能ユニオンです。取得されたものではなく、 呼び出し側が述べたものです。 避けるべき語: input、document（ドキュメントは、ソースの中身が結果としてそうであったものです）。

LoadedSource: 入力の内部作業コピー: ダイジェスト、メディアタイプ、サイズ、バイト列。indx-source に閉じており、 ワイヤを越えることはありません。 避けるべき語: 「source snapshot」 — スナップショットは機能だけに属する語です。

source digest: ロードされたバイト列の sha256: プレフィックス付きコンテンツハッシュで、入力上限を強制するのと 同じパスで indx-source が発行します。計画はこれに束縛され、実行は不一致を 409 で拒否します。 避けるべき語: checksum — それは UriSource 上の呼び出し側が供給する期待ダイジェストで、 その不一致は 422 checksum_mismatch です。

input ceiling: デプロイメントが許容するバイト数上限（limits.max_input_bytes、環境変数 INDX_MAX_INPUT_BYTES）。indx-source がストリームの途中で強制し、スナップショット上で 広告されます。スナップショットハッシュからは除外されます。

media-type detection: バイト列が実際に何であるかの判定: インストール済みオブザーバーの sniff が認識したもの、次に 宣言された Content-Type、次にファイル名の優先順です。indx-source が持つのは優先順位だけで 表は持ちません。どのバイト列が認識可能かは、何がインストールされているかの性質です。 避けるべき語: signature detection — そちらはドキュメントタイプを認識するもので、メディア タイプではありません。

resolvable / plannable / routable: インストール構成が持つ 3 段階の能力: resolvable — ローダーがその URI スキームを取得できる。 plannable — オブザーバーがそのメディアタイプを観察できる。routable（または readable）— 機能がそれを実行できる。それぞれディストリビューションのインストールによって増えます。resolvable と plannable はスナップショットハッシュから除外されます。素の pip install indx は、どの スキームも解決せず、バイト列から何も認識せず、何も観察しません。

機能

capability: 安定したプロバイダー中立の ID を持つ処理作業の単位です。ルーティングはそのパッケージに依存せず、 この ID で参照します。

CapabilityKind: 機能が自分の役割を宣言する enum: native_extraction、ocr、parser、model、embedder、 manual_review。ポリシーは kind の上でルーティングし、機能 ID の上では決してルーティング しません。2 つのメンバーは意図的にラダーの外にあります: parser はシグネチャによる ノミネーション（指名）を通じてのみ、embedder は計画の embedding_space_ids を通じてのみ 到達されます。ポートではなく、判断によって閉じています: kind は価格とフォールバック位置を 持つポリシー上の位置なので、インストールで増えることはありません — 6 つのどれでもない作業は 最も近い kind を宣言し、デプロイ側が数値を補正します。 避けるべき語: 「lane」（非公式。埋め込みでも二重に使われています。role / modality / lane を 参照）。

CapabilityDescriptor: 1 つの機能の軽量な公開メタデータ: ID、バージョン、kind、デバイス、メディアタイプ、要件、 可用性、unavailable_reason。モジュールスコープは低コストのまま保たれ、実際のエンジンは create() でロードされます。

capability snapshot: 計画の判断対象となる、機能、埋め込み空間、limits、resolvable 集合の決定的でコンテンツ アドレス化されたインベントリです。スナップショット ID はそのコンテンツハッシュです。 limits と resolvable は意図的にハッシュから除外されており、ローダーやオブザーバーの インストールが発行済みの計画を無効化しないようになっています。 避けるべき語: registry（スナップショットはレジストリが公開するものであり、レジストリ そのものではありません）。

provider: プラグイン側の契約（CapabilityProvider）: descriptors() が広告し、create() がランタイム 実装を遅延構築します。source_observers() と source_loaders() も宣言できます。 避けるべき語: EmbedderConfig.provider — 別の意味で、モデルベンダーの文字列です。

entry-point group: indx.capabilities — インストール済みディストリビューションがプロバイダーを広告する importlib.metadata のグループです。1 つのグループが 3 種類の拡張（機能、オブザーバー、 ローダー）すべてをカバーします。

registry: プロバイダーを発見し、宣言を検証し、重複 ID を拒否し、決定的に順序付け、スナップショット ID を 発行します。機能 ID から、それを実行できるモノへ戻る唯一の経路です。

builtin: indx が同梱するオブザーバーとローダーに付く、省略可能な builtin = True フラグです。 レジストリはインストールされたものをビルトインより前に順序付けるため、拡張はファーストパーティの フォーマットを意図的にオーバーライドできます。このフラグを名乗ることで優先順位を失うことは あっても、得ることは決してありません。

extras: 重いエンジンをゲートする省略可能な依存関係セット（--extra ocr、--extra vlm、 --extra fastembed、--extra hosted）。欠けている extra は利用不可のディスクリプタとして 表面化し、ラダーはそれを通り過ぎて降下します。

Device: cpu / gpu / external / manual。gpu_allowed と data_residency の制約を駆動します。 ホステッドモデルは external です。CapabilityKind と同様に閉じており、機能が複数のデバイスを 提供する場合、ルーターは cpu、gpu、external、manual の順で最初のものを記録します — かつてのアルファベット順の偶然ではなく、明示された優先順位です。

計画

RoutePlan: 永続的でシリアライズ可能な計画アーティファクト: plan_id、source_digest、media_type、 capability_snapshot_id、policy_version、ステータス、ルート、シグネチャ一致、見積もり。 避けるべき語: 「the route」（1 つの計画は多数のルート割り当てを保持します）。

plan_id: 計画の決定済み内容の決定的な sha256: ハッシュで、plan_id と request_id は除外されます — 同一の入力・ポリシー・スナップショットは同一の計画を生みます。 避けるべき語: request_id（呼び出し側の相関 ID で、ハッシュから除外）と X-Request-ID ヘッダー（レスポンスごとのトランスポート相関）— 3 つは別々の識別子です。

routing ladder: CapabilityKind 上のエスカレーション順: ネイティブテキスト層 → OCR → VLM → 手動レビュー。 rung（ラング）は 1 段であり、選択されたラングより下のすべてのラングはフォールバックとして 計画に残ります。順序とその構成メンバーはファーストパーティです。ラングの追加は POLICY_VERSION の更新であって、インストールでは決してありません。 避けるべき語: escalation chain、waterfall。

fallback: 計画内で宣言された、順序付きの代替候補です。実行は選択されたルートか、その宣言済み フォールバックしか使えません — 黙った再計画は決してありません。terminal fallback （終端フォールバック）は手動レビューで、フェイルオーバーできない唯一のラングです。

manual review: 終端のラング（manual_review、デバイス manual）。人間は何でも読めるため、メディアタイプを 宣言しません。これを取り除いたインストール構成は、ラダーが尽きたとき 503 を返します。

RouteAssignment / RouteCandidate: 割り当て（assignment）は、スコープを 1 つの selected 候補と順序付き fallbacks に 束縛します。候補（candidate）は、機能 ID、デバイス、その判断理由です。

ScopeRef: ルートが適用される場所: document、page（1 始まり）、region（ScopeKind）。計画は ドキュメントスコープの割り当てを 1 つ持ち — document default（ドキュメント既定）— それと食い違う各ページには page override（ページオーバーライド）が付きます。

DecisionReason: 選択の公開説明: 安定した code（text_layer_usable、page_appears_empty、 escalation_fallback、terminal_fallback、signature_match、…）と、人間可読の detail。

PlanStatus: ready または unsatisfied。unsatisfied な計画は unsatisfied_constraints を列挙し、 例外として送出されるのではなく報告されます（HTTP 200）。

RoutingConstraints: 呼び出し側のビジネス制約: minimum_quality、deadline_ms、maximum_cost_usd、 gpu_allowed、data_residency。加えてリーダーを名指しする capability_ids (許可リスト。空ならラダーが決める) と fallbacks_allowed。data_residency は external デバイスを拒否します。

policy version: POLICY_VERSION。すべての計画に刻印され、ルーティングの判断または計画アーティファクトが 変わるたびに更新されます。

economics: kind ごとのルーティング入力 — 品質、ページあたりコスト、ページあたりレイテンシ — で、 ルーターの内部にあり、デプロイメントごとに INDX_ROUTING_ECONOMICS でオーバーライドできます。 計画の公開 estimates を動かします。判断によりコアが所有します: ディスクリプタは価格を 宣言しないため、実コストが kind の既定値と異なる機能も受け入れられ、オペレーターが補正するまで 既定値で見積もられます。 避けるべき語: actuals、usage（実行側。下記参照）。

admission: 機能の制約がデバイスと予算を残すかどうか。機能を除外した制約の名前が unsatisfied_constraints になります。

事前観察と観測

preflight: ルーティングの前の、低コストでローカルかつ決定的な証拠収集ステージ: OCR なし、モデルなし、 レンダリングなし、ネットワークなし。「事前観察の予算」は、オブザーバーとシグネチャ ディテクターが守るべき基準です。

SourceObserver: あるメディアタイプについて、低コストなページ単位の証拠を生成するポートです。証拠を返すことで メディアタイプをクレームし、空のタプルを返すことで辞退します（「自分のものではない」）。その media_types 属性は広告であって、ディスパッチのゲートでは決してありません。これを インストールすることで、メディアタイプは plannable になります。

SourceLoader: URI スキームの背後のバイト列を、チャンク単位で取得するポートです。オブザーバーと違い、その schemes 属性は実際に効力を持ちます: 選択、415 での列挙、スナップショットでの広告に 使われます。ローダーはダイジェストを発行せず、入力上限も強制しません — どちらも indx-source が所有します。

PageEvidence: 1 ページ分の観測結果（1 始まり）: テキスト層の状態、オープンな文字列の signal、省略可能な RegionEvidence。

TextLayerState: usable_without_ocr / missing / unusable — ラダーの最初のラングが立脚する一次的な 証拠です。

signals: ポリシーが照合する、共有されたオープン文字列の証拠語彙: font、image、empty。 オブザーバーがドリフトしないよう indx-interfaces に置かれています。empty は不在を 主張するため、より高い立証責任を負います。形式はオープン、意味は閉じています: ラダーが読むのは empty とテキスト層の状態だけなので、オブザーバーが発明した signal は誤りではなく無効です。

PreflightContext: ソース全体の事前観察アーティファクト（ダイジェスト、ページ数、ページ群）で、ルーターの内部に あります — これが、計画の束縛先となる識別子をオブザーバーが偽造することを防ぎます。 オブザーバーが返すのは PageEvidence だけです。

signature detection: リクエストごとのオプトイン: ドキュメントタイプ（請求書、フォームなど）を低コストで認識し、 計画がスペシャリストをノミネートできるようにします。

signature nomination: SignatureMatch が、その candidate_capability_id を汎用ラダーの前に置くことです。 ラダーの代わりに置くことは決してありません。機能がインストールされていない一致も報告は されますが、ルートは変えません。confidence は一致した独立 signal の割合であり、signal が割合であるときは その分だけ数え、校正済みの確率ではありません。

process chart（工程系統図）: 記号の慣例で描かれた製造の流れです。三角は材料、楕円は加工、ひし形は検査、二重の三角は組立を 表し、記号どうしを結ぶコネクタが工程、大きな矩形が一つのラインの工程をまとめる枠です。 process-chart シグネチャがスライド単位で認識し、process-chart-parser が metadata.process_chart に読み出します。

layout（DXF）: CAD プログラムが図面のページとして示すもの。モデル空間と各ペーパー空間レイアウト、タブ順です。 indx-observer-dxf はこれを、ワークブックのシートやデッキのスライドと同じく形式が述べる区切りとして ページに数えます。

実行と出力

Block: フラットでアドレス可能な出力ツリーのノード: ID と親 ID、kind、インデックス、正規化 bbox、 テキスト、埋め込み、メタデータ、ステータス、provenance。

BlockKind / ScopeKind: 2 つの重なり合う enum。BlockKind（document/page/region/chunk）は granularities での リクエスト側の要求でもあり、ブロック上のレスポンス側の事実でもあります。フェーズ 3 で畳まれる までは 2 つの名前の下の 2 つの enum で、エグゼキューターは一方を他方へ翻訳していただけでした。 ScopeKind はルートが適用される場所（chunk なし）で、ルートとブロックは同じものではないので 別のままです。

BlockStatus: completed / unreadable / failed。読めなかったスコープは理由付きで報告され、省略される ことは決してありません。空の text は空白ページの完了した読み取りであり、何も生成しない ことこそが失敗です。PageOutput 上では、非 completed の 2 値はラダーにとって別の意味を 持ちます: failed は機能が「他をあたってほしい」と言うことでありラダーは降下し、 unreadable は内容についての判定であり保持されます。

output validation: あるラングが生成したものに対する、ページが読めたと数えられる前のエグゼキューターのチェック: 出力の不在、failed の宣言、または INDX_VALIDATION_MIN_CONFIDENCE 未満の自己申告 confidence。3 つのいずれかが、そのページだけを次のラングへ送り、拒否された出力を破棄します。 ポートではなく、判断によりファーストパーティです。 避けるべき語: 「quality gate」 — ここでは何も、出力を正解データと照合しません。

confidence: 1 つの語の下にある 2 つの異なる数値で、置き場所によって区別されます。SignatureMatch 上では、 計画時に一致した独立 signal の割合です。signal が割合であるときはその分だけ数えます。PageOutput.metadata（CONFIDENCE_METADATA_KEY） 上では、機能が自分の読み取りについて述べた値で、ExecutionActuals.quality に届き、検証の 下限を割ることがあります。どちらも校正済みの確率ではありません。

PageOutput: 1 つの機能が 1 ページに対して生成したものです。意図的に Block ではありません: ブロック ID と ツリーは、エグゼキューターが発行するものです。

PageReader: 読み取り機能に対して create() が返すランタイム実装 — read(content, media_type, pages) — で、すべての読み取り kind を 1 つのプロトコルでカバーします。

ExecutionTrace: スコープごとに試行されたすべての機能の記録で、失敗も含みます: 計画された機能と実際の機能、 デバイス、ステータス、fallback_index、レイテンシ、コスト。フォールバックを可視化するのは これです。

actuals / usage: ExecutionActuals — 1 回の実行で計測されたレイテンシ、コスト、品質、デバイス別ページ数。 Usage — バイト・ページ・コスト・レイテンシの集計ロールアップ。cost と quality は どちらも、機能が自分自身について報告した値でしかなく、誰も報告しなければ 0.0 / null です。 避けるべき語: estimates（計画側。economics から導出されます）。

provenance: ブロックごとの、どの計画とどの機能がそれを生成したかの記録です。文書ブロックでは、 media_type と、バイト列が届いた source_uri または filename も名指しします。 避けるべき語: metadata — そちらは機能が抽出したもの（例: invoice キー）や 呼び出し側が渡したものを運ぶのであり、ブロックの出どころではありません。provenance の source_uri はリクエストを反映した文字列であり、正典としての Source は上記の宣言済み 入力モデルです。この二つは交換可能ではありません。

document metadata: 文書ブロックの metadata です。EncodeRequest.metadata で渡された呼び出し側自身のラベル （所有者、テナント、機密度）と、検出器がインストールされていれば languages、リクエストが 分類器を有効にしていれば classification、エンティティ抽出器を有効にしていれば entities を 含みます。運ぶだけで、強制はしません — そのベクトルを誰が読めるかはインデックス側の問いです。 避けるべき語: ACL、ポリシー — indx はこれらのラベルを運搬するだけで、評価は一切しません。

language detector: LanguageDetector。バイト列ではなくリーダーが生成したテキストで尋ねられ、それが書かれて いる言語を答えるポートです。チャンカーと同じようにインストールされ、どこにも公表されず、 既定では存在しません。 避けるべき語: 単独の「検出器」 — それは signature detector（バイト列に対する計画時の ポート）を指します。この二つが一語の下に並ぶことはありません。

LanguageScore: 検出器が見た一つの言語と、その確信度です。小文字の ISO 639-1 コードと [0, 1] の数値で、 languages メタデータキーの下に確信度の高い順に並びます。CONFIDENCE_METADATA_KEY と 同じ立場の、文字についての自己申告であり、主題についての主張では決してありません — それは 分類器のものです。

分類器（classifier）: DocumentClassifier、PageClassifier、ChunkClassifier — 1 つの文書・ページ・チャンクの全文で 尋ねられ、そのテキストが何であるかを答えるポート群。リクエストが EncodeRequest.classification で単位ごとに名前によって有効にするため、それぞれ ID を持ち、 スナップショットにハッシュの外で、エンティティ抽出器と共有する 1 つの名前空間で公表されます。 避ける: シグネチャ検出 — それは計画時にバイト列に対して行われ、パーサーをノミネートします。 また、この一族を指して単独の「文書分類器」も_避ける_ — それは 3 つのうちの 1 つの名前です。

ファセット（facet）: 分類器が文書について答える一つの問い — document_type、business_unit、industry —。 分類器が名付け、indx の何も列挙しません。あるファセットについて意見を持つ最初の有効化済み 分類器がそれを取ります。

LabelScore: 分類器があるファセットに与えた一つのラベルとその確信度。名前と [0, 1] の数値で、 classification メタデータキーの下にファセットごとに高い順に並びます。分類器が述べる範囲でしか 較正されていない自己申告です — 単語リストの比率、含意確率、モデル自身の数値。

エンティティ抽出器（entity extractor）: PageEntityExtractor または ChunkEntityExtractor。1 つのブロックのテキストで尋ねられ、その中の 名前とその位置を答えるポート。EncodeRequest.extraction で単位ごとに ID によって有効化されます。 避ける: 契約の言葉としての「NER」 — それは実装技法であり、ポートは単位と戻り値の形で名付け られています。

EntitySpan: 抽出器が見つけた一つの名前。表層のテキストと、それを名指しするブロックの text への [start, end) の文字範囲と、LabelScore と同じ自己申告の立場に立つ [0, 1] の信頼度。 避ける: バイトオフセット — この範囲は文字であり、UTF-8 の日本語では両者が 3 倍違います。

エンリッチャー（enricher）: DocumentEnricher、PageEnricher、ChunkEnricher。1 つの文書・ページ・チャンクの全文で尋ねられ、 それが何を述べ、何についてかを答えるポート。EncodeRequest.enrichment で単位ごとに ID によって 有効化され、分類器・抽出器と共有する 1 つの名前空間に入ります。 避ける: ポートを指しての「要約器」「タグ付け器」 — 1 つのエンリッチャーはどちらか一方も両方も出せます。

Enrichment: エンリッチャーが答えたもの。summary（テキスト自身の言語で書かれた散文）と tags（語彙がファセットの ものではなくエンリッチャー自身のものである LabelScore の並び）。各部分は省略可能で、省かれた部分は 意見なしであり、それぞれについて意見を持つ最初の有効化済みエンリッチャーが取ります。文書ブロックまたは ページブロックの enrichment メタデータキーに、チャンクについては文書ブロックの chunk_enrichment に 書かれます。

エンティティ数（entity count）: entities の下にある文書ブロックの集約。(ラベル, NFKC 正規化した表層形) の組が何回現れたかと、 その傍らに残された生の表層形です。 避ける: 同一性、言及の解決 — 正規化された文字列の上の数は同一性ではなく、indx は共参照解析を 一切行いません。

chunk: 埋め込み可能な単位です。チャンクブロックだけがドキュメントベクトルを持ち、ページブロックと ドキュメントブロックは持ちません。

埋め込み

EmbeddingSpace: ベクトルの次元、メトリック、正規化、そして空間を構成する埋め込み器の、バージョン付き宣言です。 1 つのプロバイダーが空間全体を宣言し、2 つのプロバイダーが 1 つの空間 ID を共有することは できません。

embedder fingerprint: EmbedderConfig（ベンダー、モデル、リビジョン、ロール、モダリティ、前処理）のコンテンツ アドレス化された sha256: ハッシュ — 2 つのインストール構成が、互いのベクトルが比較可能かを 知るために突き合わせる文字列です。

role / modality / lane: EmbedderRole は document/query、EmbedderModality は text/image です。空間内の 各 role×modality の lane は、ちょうど 1 つの埋め込み器に解決されなければなりません。 補足: 「lane」は機能 kind の非公式な呼び方（「OCR レーン」）にも使われますが、埋め込みの 文脈では常に role×modality を意味します。

DOCUMENT_EMBEDDING_MODALITIES: 実行がドキュメント埋め込み器に渡すモダリティを、優先順に並べたもの — (text, image) です。 テキストを持つチャンクにはテキストを、テキストとして誰も読めなかったページの代わりに立つ チャンクにはレンダリング済みのページを渡します。ルーター側の拒否とエグゼキューター側の 選択の両方が読む唯一の記述であり、これが覆うドキュメントレーンを一つも宣言しない空間は 何も埋め込みません。クエリレーンはこの制約を受けません。

VectorEncoder: embedder kind の機能に対して create() が返すもの: テキストも画像も、同じ 1 つの encode() で扱います。

エラーとトランスポート

error envelope: 単一の型付き失敗形状: type、code、message、省略可能な param、省略可能な request_id。param は失敗したフィールドのドット区切り pydantic ロケーションで、 判別可能ユニオンのメンバーはタグをセグメントとして含みます（source.uri.uri）。

the three refusals: インストール構成に依存する、意図的に区別可能な 3 つの拒否: unsupported_source — スキームを 解決するローダーがない（415）。source_unreadable — メディアタイプを観察できる オブザーバーがない（422）。source_forbidden — ローダーのガードが宛先を拒否する （422）。

Deadline: モノトニックな期限とキャンセルフラグで、作業単位の合間にチェックされます — 機能呼び出しの 内部では決してチェックされません。

StrictModel: 公開契約の Pydantic 基底: extra="forbid"、strict=True、validate_assignment=True。 すべてのワイヤ型はこれを継承します。

typed IDs: indx_interfaces.ids にある NewType の文字列エイリアス（PlanId、CapabilityId、 SourceDigest、BlockId、…）— シグネチャ上では名目的に区別され、ワイヤ上ではただの 文字列です。