拡張プロトコル

英語版が原文です。

indx_interfaces.protocols のプロトコルは、indx パッケージ間の安定したポートです。interfaces パッケージをルーター、エグゼキューター、モデルプロバイダー、アプリケーションに依存させることなく、協調相手が提供すべき振る舞いを記述します。

Python のプロトコルは構造的型付けを使います。実装は、要求されるシグネチャを持つメソッドを公開することでこれらの契約を満たします。プロトコルを継承する必要はありません。多くは粗い統合チェックのために実行時チェック可能であり、メソッドシグネチャは静的型検査が検証します。

下の一覧で Executor と Embedder だけは例外です。協調相手が埋めるポートではなく、1 つのデプロイ可能なシステムのステージなので、実装は 1 つだけで、プロトコルは宣言されていません。一覧に載っているのは、この地図がリクエストの道筋を示すものだからであって、ワークスペースの外から実装が供給されるからではありません。

プロトコルの連携

installed CapabilityProviders
             │
             ▼
      CapabilityRegistry ──► CapabilitySnapshot
             │                        │
             ├──► SourceLoaders ──────┤
             ├──► SourceObservers ────┤
             │                        │
source + constraints ────────────────►│
             │                        ▼
             │                     Planner
             │                        │
             │                        ▼
             │                    RoutePlan
             │                        │
             │                        ▼
             ├──► Chunkers ──────► Executor ──► blocks + trace + usage
             ├──► LanguageDetectors ──┤
             ├──► Classifiers ────────┤
             └──► EntityExtractors ───┘

query + embedding-space ID ─────────► Embedder ──► query vectors

スナップショットは計画に再現可能なインベントリを与えます。ローダーはソースがどの URI から到着できるかを示し、オブザーバーはそもそもどのメディアタイプに適用できるかを示します。どちらも ID を持たず、それらが解決できるものはコンテンツハッシュの外側で、広告としてのみスナップショットに届きます。それらが変えるのは何を計画できるかであり、スナップショットが記録するのは何を実行できるかだからです。計画は、ルートの選択に使ったスナップショットとポリシーのバージョンを記録します。実行はそのルートと宣言済みフォールバックに従い、すべてを読み終えた後にチャンクとは何かをインストール済みチャンカーに問い合わせ、テキストが結局どの言語で書かれていたかをインストール済み言語検出器に問い合わせます。境界も言語も実行の出力であってルーティングの判断ではないため、どちらもまったく広告されません。そして、リクエストが ID で有効にした注釈ポートに、テキストが何を述べているかを尋ねます。それらのポートは 2 つの軸の格子です。渡される単位 — 文書、ページ、チャンク — と、戻り値の形 — 分類器が答えるラベルか、エンティティ抽出器が答えるスパンか。6 つのセルのうち 5 つが出荷されます。文書全体の抽出器は意図的に存在しません。ページがすでに隙間なく文書を敷き詰めているからです。注釈の ID はハッシュの外側で広告されます。リクエストがそれを名指ししなければならないからで、ID は 5 つすべてにまたがる 1 つの名前空間を共有します。一方、クエリ埋め込みは、ドキュメント埋め込みと同じ宣言済み空間でベクトルを生成します。

プロトコル一覧

プロトコル	メソッド	入力	出力	主な責務
Planner	plan	PlanRequest	RoutePlan	高価な処理を実行せずに、説明可能なルートを選択する
Executor	encode	EncodeRequest	EncodeResult	選択された機能を実行し、結果と実測値を報告する
Embedder	embed	EmbedRequest	EmbedResult	宣言済みの埋め込み空間でクエリをエンコードする
CapabilityRegistry	snapshot, create, observers, loaders, chunkers, language_detectors, document_classifiers, page_classifiers, chunk_classifiers, page_entity_extractors, chunk_entity_extractors, document_enrichers, page_enrichers, chunk_enrichers	省略可能なスナップショット ID。作成には機能 ID	CapabilitySnapshot、機能インスタンス、またはインストール済みのオブザーバー・ローダー・チャンカー・言語検出器・分類器・エンティティ抽出器・エンリッチャー	決定的でバージョン付けされた機能インベントリを公開し、その中の実装へ到達する
CapabilityProvider	descriptors, create	作成には機能 ID	ディスクリプタまたは機能インスタンス	プラグイン機能を広告し、遅延構築する
PageReader	read	ソースバイト列、メディアタイプ、ページ番号	ページごとの PageOutput	指名されたページを読む。読めなかったときはそれを明示的に伝える
SignatureDetector	detect	ソースバイト列、メディアタイプ	認識したスコープごとの SignatureMatch	ドキュメントタイプを低コストで認識し、計画が専用機能をノミネートできるようにする
SourceLoader	fetch	宣言したスキームの URI	チャンク単位のコンテンツ	このインストールが解決できると教えられた URI の背後にあるバイト列を取得する
SourceObserver	observe、sniff	ソースバイト列、メディアタイプ	ページごとの PageEvidence。担当しないタイプには何も返さない。バイト列から認識したメディアタイプ、または何も返さない	ルーティングの判断材料となる低コストな構造的証拠を生成し、その証拠が何についてのものかを認識する
Chunker	chunk	ソースバイト列、メディアタイプ、すべての PageOutput	担当ページごとの PageChunks。境界を持たないドキュメントには何も返さない	フラットなテキストが失った構造から、チャンクとは何かを決める
LanguageDetector	detect	リーダーが生成した一つのテキスト	言語ごとの LanguageScore（高い順）。判定するには短すぎるテキストには何も返さない	文字が支持する以上を主張せずに、ページが書かれている言語を名指しする
DocumentClassifier	classify	文書として読まれたテキスト全文	ファセットごとの LabelScore（高い順）。省かれたファセットは意見なし	リクエストがこの分類器を ID で有効にしたとき、文書が何であるかを述べる
PageClassifier	classify	1 ページのテキスト	ファセットごとの LabelScore（高い順）	混在した文書が必要とする単位で、1 ページが何であるかを述べる
ChunkClassifier	classify	1 チャンクのテキスト	ファセットごとの LabelScore（高い順）	1 チャンクが何であるかを述べる。チャンク粒度を要する
PageEntityExtractor	extract	1 ページのテキスト	ラベルごとの EntitySpan。そのページブロックの text を指す	ページの中の名前を見つけ、どこにあるかを述べる
ChunkEntityExtractor	extract	1 チャンクのテキスト	ラベルごとの EntitySpan。そのチャンクブロックの text を指す	チャンクの中の名前を見つける。チャンク粒度を要する
DocumentEnricher	enrich	1 つの文書の全文	Enrichment。要約、タグ、またはその両方	文書が何を述べ、何についてかを言う
PageEnricher	enrich	1 ページのテキスト	Enrichment	1 ページが何を述べ、何についてかを言う
ChunkEnricher	enrich	1 チャンクのテキスト	Enrichment	1 チャンクが何を述べ、何についてかを言う。チャンク粒度を要する
EmbeddingSpaceProvider	embedding_spaces	—	EmbeddingSpace ディスクリプタ	このプロバイダーの埋め込み器が形成するバージョン付き空間を宣言する
SourceLoaderProvider	source_loaders	—	SourceLoader 実装	このプロバイダーが同梱するローダーを宣言し、それによってどの URI スキームが解決可能になるかを決める
SourceObserverProvider	source_observers	—	SourceObserver 実装	このプロバイダーが同梱するオブザーバーを宣言し、それによってどのメディアタイプが計画可能になるかを決める
ChunkerProvider	chunkers	—	Chunker 実装	このプロバイダーが同梱するチャンカーを宣言し、それによってエンコード出力がどう切られるかを決める
LanguageDetectorProvider	language_detectors	—	LanguageDetector 実装	このプロバイダーが同梱する検出器を宣言し、それによってブロックが言語を持つかどうかを決める
DocumentClassifierProvider	document_classifiers	—	DocumentClassifier 実装	このプロバイダーが同梱する分類器を宣言し、それによってリクエストがどの ID を有効にできるかを決める
PageClassifierProvider	page_classifiers	—	PageClassifier 実装	このプロバイダーが同梱するページ分類器を宣言する
ChunkClassifierProvider	chunk_classifiers	—	ChunkClassifier 実装	このプロバイダーが同梱するチャンク分類器を宣言する
PageEntityExtractorProvider	page_entity_extractors	—	PageEntityExtractor 実装	このプロバイダーが同梱するページ抽出器を宣言する
ChunkEntityExtractorProvider	chunk_entity_extractors	—	ChunkEntityExtractor 実装	このプロバイダーが同梱するチャンク抽出器を宣言する
DocumentEnricherProvider	document_enrichers	—	DocumentEnricher 実装	このプロバイダーが同梱する文書エンリッチャーを宣言する
PageEnricherProvider	page_enrichers	—	PageEnricher 実装	このプロバイダーが同梱するページエンリッチャーを宣言する
ChunkEnricherProvider	chunk_enrichers	—	ChunkEnricher 実装	このプロバイダーが同梱するチャンクエンリッチャーを宣言する
VectorEncoder	encode	テキストまたは画像バイト列	入力ごとに 1 ベクトル	ドキュメントにもクエリにも、宣言済み空間でベクトルを生成する

共通の設計規則

• 公開の入出力は、indx-interfaces が所有する厳密な Pydantic 契約です。
• 計画は検査可能であり、高価な処理経路を呼び出しません。計画が到達するのはインストール済み実装の 2 つだけで、どちらも事前観察（preflight）の予算に縛られます — 低コスト、ローカル、決定的、OCR なし、モデルなし、レンダリングなし、ネットワークなし。SourceObserver はすべての計画で実行されます。何にも観察されないソースは、そもそもルーティングできないからです。signature_detection はリクエストごとのオプトインで、予算内に答えられないディテクターは「何もない」と答えます。
• ソースのバイト列はインストール済みローダーが取得し、インストール済みオブザーバーが認識しますが、上限の適用、ダイジェスト、タイプの優先順位付けは indx-source が行い、どちらも決して行いません。計画が束縛される上限と識別子は、コンテンツの到着経路や誰が認識したかによって変わってはならないからです。
• 計画は、ソースダイジェスト、メディアタイプ、ポリシーバージョン、機能スナップショットに束縛されます。
• 実行は受け渡された計画を黙って変更せず、選択済みルートと宣言済みフォールバックだけを使います。
• プロバイダーのメタデータは軽量に保たれます。高価な実装は、実行が必要とするときにのみ初期化されます。
• 実装は indx-interfaces の外に置かれ、ワークスペースの依存方向を保ちます。唯一の例外は柵つきです。標準ライブラリのみで、状態を持たず、I/O をせず、INDX_* を読まないヘルパーは、実装ではなく下のパッケージたちがすでに共有している規則であり、それらの下に置かれます（ADR-0034）。

関連資料

• ターゲットアーキテクチャ
• コアユーザー機能
• API コントラクト
• 公開の機能モデル
• 公開の事前観察証拠モデル
• 公開の計画モデル
• 公開のエンコードモデル
• 公開の埋め込みモデル