jinko-protocol

Jinkō Protocol SDK ワークフロー

SDK を使ってプロトコル設計の仕組みを扱う際に、このスキルを使用します。関心の分離を明確に保ちます。モデルでは治療レジメンの関数と入力を定義し、プロトコルではアームごとにそれらの入力を設定します。

前提条件： このスキルには、初期化済みの jinko-sdk 接続と、metadata.requires_sdk の範囲を満たす SDK が必要です。jinko-sdk-setup スキル（../jinko-sdk-setup/SKILL.md）を実行し、そのチェックに合格してから先に進んでください。セッションコードを交換できるのは一度だけなので、このスキル独自の SDK プロセスを開始する前に、再度 get_session_code を呼び出してください。このスキルが見つからない場合は、novainsilico/jinko-skills からインストールしてください。

関心の分離

• プロトコル設計では、コンポーネントの値のみを上書きし、アームごとに異なる値を指定します。
• 投与機能はモデルレベルで定義します。スケジュールのパラメーター化、投与量のパラメーター化、カテゴリーパラメーターによる治療の有効化／無効化、カテゴリーパラメーターによる投与経路または投与方式の指定、それらの入力を解釈する数式が含まれます。
• モデルでは、治療レジメン関数とその入力コンポーネントを定義します。
• プロトコルでは、各アームの関数をインスタンス化するように、それらの入力に値を割り当てます。
• 必要な上書きキーがモデル入力として存在しない場合は、まず jinko-model に切り替えて、モデルコンポーネントまたは投与ロジックを追加してください。

基本ルール

• モデルが利用できる場合は、client.create_protocol_design(arms, model=model) を優先してください。
• アームがスプレッドシート由来の場合は、client.create_protocol_design_from_csv(csv_file_path=...) を使用してください。標準メタデータ列 arm、control、active、weight を使用します。それ以外の列はすべて、プラットフォームによってオーバーライドにマッピングされます。この方法では model 引数を受け付けません。必要な場合は、代わりに client.create_protocol_design(...) を使ってモデルをリンクしてください。サンプルファイルについては assets/toy_protocol_arms.csv を、SDK の呼び出し方法については references/protocol-design.md を参照してください。
• 可能な場合は、プロトコル設計をモデルにリンクし、プロトコル設計にモデルのスナップショット参照を含めてください。
• オーバーライドの key は、トイモデルの Dose や route のような、プロトコルで実行可能なモデル入力を対象にする必要があります。
• assets/protocol.json に示すように、アームごとに tMax キーと tStep キーで求解時間をオーバーライドできます。アームごとに異なる時間範囲や出力解像度が必要な場合に使用してください。たとえば、ある図では時間単位の解像度で7日間まで、別の図では日単位の解像度で56日間まで出力する場合です。
• 数式は文字列として指定してください。たとえば、対象コンポーネントに応じて "1.0"、"iv"、"PT24H" を指定します。
• アームを比較する場合は、対照関係を含めてください。比較対象のアームを示すには armControl を使用します。
• 既存の設計で個々のアームを編集するには、protocol.arms の get、create、set_control、set_active、set_weight、set_override、delete、compare_overrides を使用し、未加工の設計ペイロードを置き換えないでください。
• プロジェクト項目を作成または更新する前に、明示的な確認を求めるか、スクリプトで --apply を指定してください。

プロジェクトフォルダーの整理

• プロジェクトのルートではなく、専用の Jinkō フォルダー内にプロトコル設計を作成することを優先してください。ワークフローの開始時に、YYYY-MM-DD-<experiment-name> のようなフォルダー名を尋ねるか、提案してください。
• 可能な場合は、完全一致する既存のフォルダーを再利用してください：client.get_folder_by_name(name, exact_match_only=True)。
• フォルダーが存在しない場合は、ユーザーの確認後、またはスクリプトに --apply を指定して実行した場合にのみ作成してください。
• フォルダーオブジェクトまたはフォルダー ID を1つ解決し、対応する SDK の作成呼び出しに folder=folder を渡してください。

同梱アセット

• assets/toy_protocol_arms.json：2つの投与経路と3つの投与量を含む3つのアームです。iv の投与経路は2つのアームで繰り返し使用されています。
• assets/toy_protocol_arms.csv：同じ3つのアームを CSV 形式で表したもので、create_protocol_design_from_csv で使用するために、1行につき1つのアームを記載しています。
• assets/protocol.json：プロトコルのアーム形状に関する OpenAPI スキーマのサブセットです。

SDK スクリプト

SDK をインストールすると、これらはコンソールスクリプトとして PATH から実行でき、以下のように python -m を使って実行することもできます。

• jinko.cli.create_protocol_design：3 群のプロトコルデザインを作成します。モデルとの関連付けは任意です。
• jinko.cli.create_protocol_design_from_csv：群を記載した CSV ファイルからプロトコルデザインを作成します。
• jinko.cli.edit_protocol_design_arms：arms ミューテーターサービスを介して、既存のプロトコルデザインの群とオーバーライドを追加または更新します。入力にない群とオーバーライドは保持されます。削除するには、明示的に protocol.arms.delete(...) または arm.remove_override(...) を呼び出してください。
• jinko.cli.inspect_protocol_design：プロトコルの内容、または簡潔な群の概要を出力します。

例：

python -m jinko.cli.create_protocol_design --model-sid cm-...
python -m jinko.cli.create_protocol_design --model-sid cm-... --apply
python -m jinko.cli.create_protocol_design --model-sid cm-... --folder 2026-06-15-regimens --create-folder --apply
python -m jinko.cli.create_protocol_design_from_csv --csv skills/jinko-protocol/assets/toy_protocol_arms.csv --apply
python -m jinko.cli.edit_protocol_design_arms --protocol-design-sid pd-... --arms skills/jinko-protocol/assets/toy_protocol_arms.json --apply
python -m jinko.cli.inspect_protocol_design --protocol-design-sid pd-... --summary

群の形式

各群には次の項目を含めてください。

• armName：固定の群識別子です。
• armOverrides：{ "key": "<model-input-id>", "formula": "<arm-specific-value>" } 形式の項目のリストです。
• armIsActive：アクティブな群では通常 true にします。
• armWeight：キャリブレーション目的で重み付きシミュレーションを行う場合を除き、通常 1 にします。
• armControl：比較対象群では null、対照群と比較する群では対照群の名前を指定します。

デフォルトの簡易群：

• iv_low_dose：Dose=1.0、route=iv、対照群なし。
• po_mid_dose：Dose=2.0、route=po、iv_low_dose を対照群とします。
• iv_high_dose：Dose=3.0、route=iv、iv_low_dose を対照群とします。

参照先の案内

• 関心の分離と SDK のパターンについては、references/protocol-design.md を参照してください。
• 群のペイロード形式を検証する際は、assets/protocol.json を参照してください。