kitaru-importer-builder

Kitaru インポータービルダー

代表的なプロバイダーデータを、静的エクスポートや範囲を限定した API クエリ向けの、ローカルで検証済みの Kitaru インポーターに変換します。ソースの根拠から正規化されたセッションに至るまでの経路を明確にし、何が保持され、何が近似され、何が利用できないのかをユーザーが確認できるようにします。

デフォルトではローカルで完了します。ユーザーが求め、それぞれの操作を個別に承認した場合にのみ、コードを登録するかトレースデータをアップロードします。

基本契約

• インストール済みの Kitaru バージョンとオフラインスキーマを信頼できる情報源として扱います。リポジトリの例はパターンとして参照し、コマンドやフィールドがインストール済みであることの証拠とはみなしません。
• トレースの内容は機密情報として扱います。生のエクスポートをバージョン管理に含めず、フィクスチャを対象リポジトリに書き込む前に機密情報を削除します。
• 解析と取得を分離します。パーサーはネットワーク呼び出し、ファイルシステムへの書き込み、サブプロセスの起動、認証情報の読み取りを行わず、バイト列とパラメーターを処理します。オプションの fetch(query) メソッドでは、プロバイダーの認証情報を読み取り、API ペイロードをリクエストできます。
• コードを書く前にソースをマッピングします。受け付けるペイロードの形式、識別情報、階層、順序、ノードのフィールド、ステータス、完全性、意図的にサポートしないデータを記録します。
• プライベートな単一ファイルのスクリプトインポーターを優先します。ユーザーに配布上の理由がすでにあり、ワーカーがバージョンを正確に固定した単一バージョンをインストールできる場合にのみ、パッケージを使用します。
• 不完全でも有用な根拠は保持します。読み取り不能なペイロード、無効な項目、有効だが不完全なセッションを区別します。
• トレースは慎重に結合します。共通キーがあっても、ソースインスタンスのスコープと意味のあるターン順序がなければ不十分です。
• 明示的なチェックポイントを得ずに、既存のインポーターファイルを上書きしたり、実行可能コードを登録したり、トレースデータをアップロードしたり、部分インポートを再試行したりしません。
• インポーターの依存関係を正確なバージョンでインストールする前と、ローカルのインポーターテストを実行する前に、それぞれ個別に確認を求めます。
• 現在のタスクで作成したコードも含め、信頼されていない、または新たに生成したインポーターのローカルテストは、認証情報のない隔離環境でのみ実行します。その隔離が利用できない場合は中止します。
• ローカルでのインポーターテストは、限定された子プロセス内でのコード実行であり、セキュリティサンドボックスではないものとして扱います。
• ローカルでの成功後にのみ、パッケージ化や上流への貢献を提案します。どちらも完了要件にはしません。
• Kitaru CLI コマンドと SDK スクリプトはすべて、KITARU_ACTIVE_SKILL=kitaru-importer-builder を設定して実行し、サーバーがその結果のアクティビティをこのスキルに関連付けられるようにします。
• ユーザーが管理するワーカーを起動または再起動するときは、--concurrency 10 を指定します。起動方法で環境変数によるワーカー設定のみが公開されている場合に限り、KITARU_WORKER_CONCURRENCY=10 を使用します。

明確でわかりやすい体験を維持する

• 現在の状態と次の判断事項を最初に伝えます。
• リポジトリ、プロバイダーのドキュメント、サンプル、またはインストール済みの Kitaru スキーマから確認できない根拠だけを求めます。
• ソースレコードをそのまま大量に出力するのではなく、マッピングと忠実度に関する判断を簡潔な表で示します。
• 正確な ID、バージョン、警告、復旧識別子を確認できる状態にします。
• 各主張がプロバイダーのドキュメント、サンプルエクスポート、インストール済みの Kitaru、または推論のどれに基づくかを明示します。
• 機能、権限、ソースサンプル、またはワーカーへの経路が不足している場合は、有用なローカルチェックポイントで停止します。

必要なときだけリファレンスを読み込む

• 足場の作成、テスト、登録、インポートの前に、references/importer-contract.md を読みます。パーサーの契約、機能のフィンガープリント、インストール方法、コマンド、識別情報に関する影響、リモート状態の境界が記載されています。
• ソースレコードのマッピング、グラフの再構築、ターンの結合、ステータスの導出、忠実度の報告の前に、references/normalization-patterns.md を読みます。
• フィクスチャとアサーションの作成、不慣れなコードの実行、不正な形式または不完全なトレースへの対応、部分的なリモートインポートからの復旧の前に、references/failure-and-validation.md を読みます。

開始状態を確認する

まずは読み取り専用で開始します。

1. 対象のリポジトリ、プロバイダーまたは形式、代表的なエクスポート、およびインポートしたセッションの用途を特定します。
2. インストール済みの Kitaru のバージョン、オフラインコマンドのスキーマ、およびパーサーのインポートパスを確認します。
3. references/importer-contract.md に能力フィンガープリントを作成します。
4. 既存のローカルインポーターのファイルを確認します。Kitaru 接続がすでに設定されている場合は、インストール済みのインポーターカタログも確認します。独自開発の前に、静的解析とサポートされている API 取得の両方を確認してください。適切な完全一致バージョンのインポーターが観測されたペイロード形式を受け入れるか、要求されたトレースを取得できる場合は、足場を新たに作成せず、呼び出し元のワークフローに返して終了します。接続を利用できない場合は、レジストリの探索を必須とせずにローカルワークフローを続行します。
5. それ以外の場合は、既存のカスタムインポーターにバージョンを追加するか、新しいプライベート名を作成するかを判断します。
6. パスを上書きしたり、インストール済みの Kitaru のバージョンを変更したりする前に停止します。

インポーターの足場作成、ローカルテスト、登録、完全一致バージョンでのインポート、または必要なパーサー型に対応していない場合は、不足している機能を明示します。リリース済みであるかのように、ドラフトのコマンドを提示しないでください。ユーザーは別途、互換性のある Kitaru 環境を選択できます。

kitaru-investigation がユーザーをここに案内した場合は、エージェントと調査のコンテキストを維持します。関連セッションが実際に利用可能になってから、調査に戻ります。

ソースがライブの Langfuse、Braintrust、LangSmith、Logfire、または Arize Phoenix の Python エントリーポイントの背後にある場合は、まず kitaru-adapter-builder を使って、プロバイダーのインポーターパッケージにある [adapter] エクストラを確認します。このサポートされている方法では、実行ごとにプロバイダーのトレースが記録されます。カスタムパーサーではありません。リポジトリとリビジョン、プロバイダー、公開エントリーポイント、インストール済みの Kitaru のバージョン、対象エージェントとバージョン、要求された証拠を引き継ぎます。

静的エクスポートもプロバイダー API データも利用できず、目的を達成するにはプロセス内での新たな記録が必要な場合は、kitaru-adapter-builder を使って続行します。リポジトリとリビジョン、公開エントリーポイント、言語、インストール済みのフレームワークと Kitaru のバージョン、要求された証拠、対象エージェントとバージョン、調査の目的を引き継ぎます。この方法を一度選択したら、アダプターがインポーターを代替手段として挙げているという理由だけで、インポーターに戻らないでください。

安全な代表サンプルを取得する

パーサーのテストには、既存の秘匿化済みエクスポートを優先します。API ソースの場合は、まずインストール済みインポーターの取得機能とプロバイダー接続のスキーマを確認します。その方法では不十分な場合に限り、カスタム取得メソッドを作成します。ローカルテストにはモックしたプロバイダー応答を使用します。ライブ取得には、認可された範囲限定のクエリと、プロバイダーの認証情報、ページネーション、レート制限、リトライの制御が必要です。

フィクスチャを書き込む前に、以下を行います。

1. 生のエクスポートはリポジトリの外に保管します。
2. テスト対象の動作を維持する、最小限のレコードに絞ります。
3. プロンプト、補完、ツールの引数と結果、エンドユーザーの識別子、認証情報、プロバイダー固有の秘密情報、スパンおよびリソースの属性、リクエストとレスポンスのヘッダー、URL とクエリー文字列、ファイルの内容と添付ファイル、エラーや例外の詳細を秘匿化します。
4. 縮小したフィクスチャを確認し、残存する秘密情報や直接的な識別子がないことを確かめます。
5. アサーションに必要なフィールド形式、関連性、順序を示す情報を保持します。

プロバイダーの認証情報を、シェル引数、インポーターのパラメーター、フィクスチャ、インラインの依存関係メタデータ、アップロードするソース、ログに含めないでください。

ソースマップを記録する

実装の前に、次のチェックポイントを作成します。

決定事項	根拠と選択した動作
ペイロードの形式	対応するエクスポート形式と、代表的な匿名化済みファイル
ソースインスタンス	アカウント、ワークスペース、プロジェクト、コレクター、または明示的なオーバーライド
セッションの識別情報	ネイティブのセッション、スレッド、または会話 ID。フォールバックとしてトレースを使用
ターンの順序	プロバイダーのシーケンス、または信頼できる単一の時計ドメインと精度
ルートと階層	ルートの選択、親フィールド、親の欠落時と循環時の動作
ノードのマッピング	スパン、LLM、ツール、サブエージェントの各フィールドと、上限付きのメタデータ
ステータスとエラー	ルートの結果と、子孫の失敗の扱い
完全性	階層、ペイロード、ツール、使用量、コスト、タイムスタンプの欠落
安全性の上限	バイト数、レコード数、ネスト深度の数値上限
インストール	スクリプトの依存関係、または正確なパッケージとワーカールート

関連するソースフィールドはすべて、マッピング済み、上限付きメタデータとして保持、または意図的に未対応のいずれかとして示します。期待するマッピングの根拠には、プロバイダーのドキュメントまたは独立したレビュー済みサンプルを用い、実装自身の出力だけに頼らないでください。

一貫性を保った最小限のインポーターを実装する

1. インストール済みスキーマでコマンドと出力先を確認してから、スクリプトのひな形を作成します。
2. アップロード用の単一のパーサーを呼び出せるようにするか、インストール済みの契約に従い、parse と任意の fetch メソッドを持つインポーターオブジェクトを公開します。
3. ペイロード全体を決定的なソースグループに解析します。
4. セッションを生成する前に、識別情報とグラフ構造を検証します。
5. 有効なセッションと、個別に分離した項目の失敗を順次生成します。
6. パッケージモードがすでに正当化されていない限り、プロバイダー固有のヘルパーはファイル内に非公開で保持します。
7. 安全なデシリアライザーのみを使用します。安全でない形式は拒否するか、別の取得ステップで変換します。
8. デコード前に宣言済みのバイト数上限を適用し、完全なマテリアライズ前にトークン化またはデコード中に深度上限を適用し、高コストな正規化の前にレコード数上限を適用します。

識別情報、結合、トポロジー、ステータス、メタデータ、再生準備状況、コンテンツダイジェストには、references/normalization-patterns.md を使用します。

ローカルで検証する

次の2段階の根拠を用います。

1. プロバイダーに基づくアサーションで、正規化された値、識別情報、順序、トポロジー、ステータス、警告、再生準備状況、ダイジェストの動作を検証します。
2. インストール済みのローカルインポーターのテストで、Kitaru がエントリーポイントを読み込めることと、生成された値がランタイム型を満たすことを検証します。

references/failure-and-validation.md の該当するケースを網羅します。最低限、完全な項目、有効だが不完全な項目、無効な項目またはペイロード境界の各ケースを含めます。ソースが対応している場合は、結合、変更されたコンテンツ、グラフのケースも追加します。

ローカルのインポーターテストが成功しても、それを意味上の正しさの証明とみなさないでください。生成されたセッションを調べ、ソースマップと比較します。

ローカルチェックポイントを報告する

簡潔なレポートを返します。

領域	結果
インポーター	パスとエントリーポイント
対応するソース	プロバイダー、エクスポート形式、ソースインスタンスのルール
識別情報	セッション ID とノード ID の導出方法。再実行時の動作
結合	キー、スコープ、順序、フォールバック、または該当なし
忠実度	完全なフィールド、一部対応のフィールド、意図的に未対応のフィールド
再生準備状況	具体的な理由を添えた、準備完了、一部準備完了、または利用不可
検証	アサーションと、インストール済み Kitaru テストの結果
リモート状態	なし。ただし、別途承認された場合を除く

これは作成段階のチェックポイントが成功したことを示します。インポーターがリモートの Kitaru デプロイで利用可能になるのは、登録後にスモークインポートを実施し、その結果を確認してからです。

リモート登録のゲート

ユーザーから登録を依頼された場合にのみ進めます。

承認前に、以下を提示します。

• 有効な Kitaru プリンシパルと対象テナントまたはプロジェクト
• インポーター名、空でない安定したプロバイダー、正確なソースパス、エントリーポイント、依存関係の経路
• 親と最初のバージョンを作成するのか、別の不変バージョンを作成するのか
• 実行可能なソースまたはパッケージ参照がリモート状態になること
• 正確なインストール済みコマンドと、保持されるレシートのフィールド

リモートでの重複排除または再試行の安全性が重要な場合は、登録前に空でない安定したプロバイダーを必須とします。現在の Kitaru ではプロバイダーを省略できますが、プロバイダーなしのインポートでは重複が確実に排除されません。承認後、登録は一度だけ行います。インポーター ID、正確なバージョン、ソースダイジェスト、各種 blob またはタスク ID を保持します。親の作成が成功してバージョンの作成に失敗した場合、親の作成コマンドを安易に再実行しないでください。

最初のスモークインポートは個別にゲートする

上限を設けて編集済みのペイロードをアップロードするか、上限を設けてプロバイダーから選択した項目を取得する権限がある場合にのみ進めます。ライブ取得の場合、まずインポーターを確認し、承認済みのワーカー環境で意図したプロバイダーの認証情報のみを使用します。ローカルでの生成コードテストでは、引き続き認証情報を使用しません。

正確なインポーターバージョン、エージェントバージョン、対象テナントまたはプロジェクト、ペイロードまたはクエリと接続、パラメーター、永続化、想定されるセッション ID、およびこのスキルには自動クリーンアップの手段がないことを提示します。インストール済みスキーマで --tag が使える場合は、一意で永続的なスモークタグを必須にし、現在はインポート後のタグ付けに必要なため、--wait も含めます。タグ付けが使えない場合は、使い捨てのエージェントか、明確にマークされた隔離済みのソース ID を代わりに必須とします。調査フローで除外できるマーカーなしに、最小化したスモーク用フィクスチャを通常の本番セッション群へ書き込まないでください。

インポートジョブを1つ作成し、インストール済みのサポート対象の方法でのみ待機します。ローカルの待機タイムアウトでは、リモートジョブは停止しません。スモークタグに加え、blob、ジョブ、タスク、セッション、最終レシートの ID を保持します。セッションのインポートが成功した後にタグの適用が失敗することがあるため、セッションのレシートを保持し、インポートを再実行するのではなく、その部分的な状態を報告します。

結果を、作成済み、重複のためスキップ、失敗、実行中のいずれかに分類します。件数だけを信頼せず、代表的なインポート済みセッションを確認します。

部分状態を悪化させずに復旧する

再試行を提案する前に、関連する各外部 ID の状態を分類します。

状態	意味
未処理	セッションが存在せず、その項目も実行されていません
完了	セッションと想定されるノードが存在します
重複のためスキップ	同じ空でないプロバイダーと外部 ID がすでに存在します
古い重複	既存のダイジェストが異なるか、ローカルの結合済みエクスポートの方がターン数が多くなっています
不完全	セッションは存在しますが、想定されるノードの取り込みが完了していません
ここでは復旧不能	インストール済み Kitaru には、安全な修復または削除の手段がありません

ノードの取り込みに失敗する前にセッションの作成が成功する場合があることに注意してください。登録済みの安定した空でないプロバイダーがある場合、その後の直接再実行では既存の外部 ID が修復されず、スキップされることがあります。プロバイダーがない場合は、代わりに別のセッションが作成されることがあります。成長する結合済み会話ではスキップされても、既存のセッションに含まれるターン数が少ない場合があります。スキップを分類する前に、読み取り可能なダイジェストとトレース件数のメタデータを比較してください。インストール済みのインターフェースでそのメタデータを確認できない場合は、結合済み会話の差分インポートを行わないでください。証拠を保持し、必要に応じてインポーターをローカルで修正してバージョンを更新し、実際にインストール済み製品で提供されている復旧操作のみを提案します。

完了

ローカル検証または依頼されたスモークインポートが成功した場合：

1. 正確なアーティファクト、サポートされるソース形式、再現性の限界、検証結果を返します。
2. 永続的なスモークタグ、すべてのスモークテストのセッション ID、使い捨てエージェントまたは分離されたソースを示すマーカーを返します。使用可能な非スモークセッションが存在する場合は、除外セットを引き継いだうえで、ユーザーを kitaru-investigation に戻します。
3. インポーターを非公開のままにするか、利用環境向けにパッケージ化するか、上流への貢献を検討するかを尋ねます。
4. 個別の依頼がない限り、公開、貢献、プロバイダーのサポート拡大は行いません。