python-api

python-api

インストール済みの任意の Python パッケージの公開 API を調べ、重要な情報をキャッシュして、学習データの記憶を決して信頼しないでください。

長期的に守るべきルールは 3 つです。

1. 記憶ではなく、インストール済みバージョンを調べます。 見覚えがあることは、調べたことにはなりません。覚えているシンボルが、バージョンによって改名、シグネチャ変更、非推奨化されている可能性があります。
2. scratch/api/<lib>/<version>/<topic>.md にキャッシュします。 そうすれば、次のエージェントが同じ調査を繰り返さずに済みます。
3. 同梱の references/ ≠ ワークスペースキャッシュです。 同梱の参照資料は長期的に使えるワークフローのパターンで、キャッシュファイルはバージョンごとの抜粋です。

このターンでの契約（ツールを使えない評価を含む）

チェックリストの項目には [x]、[ ]、[n/a] のいずれかだけを使います。[~]、pending、deferred は使わないでください。

キャッシュが存在する場合は、決して BLOCKED にしません。 ワークスペースの状態に scratch/api/<lib>/<version>/<topic>.md がディスク上にあると記載されている場合、今回 Read を実行できなくても、Cache file lands on disk を [n/a] — cache hit, file already on disk とします。次のアクションとして Read scratch/api/<lib>/<version>/<topic>.md を指定してください。BLOCKED は出力しないでください。ワークスペースの状態に記載されたバージョンは、解決済みとして扱います。

ツールが使えない場合でも、計画を書きます。 Shape、調査用のパス（scratch/<ts>_….py — バージョン確認では scratch/<ts>_version_<pkg>.py を正確に使用）、キャッシュ先、そして（Shape 3 では）バージョンを含む WebSearch クエリを明記してください。BLOCKED とは、調べた事実（シグネチャ、引数リスト、戻り値の型、インポート、呼び出し）を出力しないという意味です。これらのパスを明記しないという意味ではありません。

記憶した内容を先に示さないでください。 学習データの記憶に基づいて戻り値の型やシグネチャを書かないでください。調査用ファイルまたはキャッシュファイルが存在してから、それらを引用してください。調査後、返信内の使用例は、調べたシグネチャに一致させてください。

Python の実行には、必ず scratch ファイルを使います。 __version__ の 1 行確認を含め、インラインの python -c は禁止です。-c 形式は断り、scratch/<ts>_version_<pkg>.py（または Shape 1 の調査用ファイル）を提案してください。この拒否は BLOCKED ではありません。

write_file / run_python が使える場合は、今回のターンで調査を実行してください。 フェンス付きの pixi run python scratch/… という手順だけで止めないでください。scratch ファイルを作成して実行し、その後に調査結果を引用してください。BLOCKED／計画のみが適用されるのは、これらのツールが使えない場合だけです。

ここに挙げた落とし穴は手がかりであり、調査結果ではありません。 このスキル内の改名（tabular_learner → tabular_pipeline）だけでは、インストール済みのパッケージで確認されたことにはなりません。置き換え後の名前を確認済みとして扱う前に、必ず Shape 1（または Shape 2 の dir）を提案してください。落とし穴の表だけを根拠に ImportError と断定しないでください。スタックの構成を示す文章でエントリーポイントに言及してもかまいませんが、調査方法を提案する前に呼び出しを出力しないでください。

次のステップへの案内

ここに来た理由…	調査後の次のステップ…
これから書くコードのシンボルシグネチャ	→ 呼び出し元のフローを続けます（例：build-ml-pipeline の § 次のステップ）
「どのライブラリか／どのエントリーか？」	→ 選んだシンボルで続けます。キャッシュが作成されます
ブートストラップのターン（最初のワークスペース）	→ 必要最小限のキャッシュを作成します。references/bootstrap_cache.md を参照してください
失敗のデバッグ（KeyError / AttributeError）	→ 停止条件「Lookup failure ≠ artifact missing」を参照してください

どの種類の質問ですか？→ 形

ツールを選ぶ前に、質問の種類に基づいて形を選んでください。形を間違えると、不適切なキャッシュファイルができ、1 ターンを無駄にします。

ユーザーの質問の形…	形
「scratch/api/<lib>/<version>/には何がありますか？」（必ず最初に確認）	0 キャッシュヒット
「<task>にはどのエントリーポイントを使いますか？」	スタックの概要を参照し、その後に形 1 / 1b で確認
「X のシグネチャは何ですか？」／「X はどの引数を取りますか？」／「戻り値の型は何ですか？」	1b LSP ホバー（高速）→ 情報が少なければ 1 に進む
「X は何をしますか？」／「X の完全な docstring は？」（Parameters / Examples / See Also が必要）	1 シンボルカード（pydoc）
「モジュール Y には何がありますか？」（自由形式の調査）	2 モジュールの概要
「環境全体から foo* に一致するシンボルを検索する」	2b LSP ワークスペースシンボル
「X はどのように動作しますか？」／「A と B のどちらを使うべきですか？」	3 説明
「<arg> が <value> のとき、X は何を返しますか？」	3 説明
「…の推奨パターンは何ですか？」	3 説明

質問が引数に対する条件に依存する場合、形 3 が適切です。 help() には Returns セクションがありますが、通常、引数の値ごとのディスパッチ動作までは列挙されていません。その情報は説明ドキュメントにあります。

形 1 では形 3 の質問に答えられません。 このターンの調査で、戻り値のユニオン（EstimatorReport | CrossValidationReport | …）を保留中のキャッシュに記録する場合があります。しかし、「<arg> が <value> のとき、X は何を返しますか？」という質問に対する事実としての回答に使ってはいけません。pydoc からでも、docstring から推測したディスパッチテーブルからでも同様です。バージョンを指定した WebFetch によって scratch/api/<lib>/<version>/<topic>.md が作成されるまで、そのディスパッチ情報は取得不可です。このターンで WebSearch を使わない場合 → 計画を立てて停止し、形 1 で質問への回答を確定してはいけません。

形 1b と形 1 の違い。 Pyright のホバーでは、型シグネチャ（inspect.signature より推論された戻り値の型が豊富）と docstring の最初の段落が得られます。高速で、Python を実行する必要はありません。pydoc では、すべてのセクションを含む完全な docstring が得られます。時間はかかりますが、信頼性があります。既定の段階的な確認方法：シグネチャについてはまず 1b を使い、ホバー結果が空または 1 行だけの場合は 1 に進みます。

形 1b / 2b（LSP の形）の前提条件。 opencode LSP 経由で Pyright を利用でき、pyrightconfig.json が lsp 環境を参照していること。どちらかが欠けている場合、LSP の形は利用できません。形 1 / 2 を直接使ってください。JOURNAL.md の Status Workspace decisions にある agent feature: installed の行が前提条件です。python-env-manager § Agent feature を参照してください。

停止条件 — 調査の前に読む

• メモリの情報に頼ってシンボルを使わないでください。 すべての関数／クラス／メソッド／引数は、このターンでの検索（inspect.signature、scratch/api/<lib>/<version>/ ファイル、または新たに実行した WebFetch）から取得する必要があります。知っているだけでは不十分です。注意が必要な既知のケースの全リストは references/named_traps.md にあります。
  • skrub：0.7 以降では tabular_learner が tabular_pipeline に変更されています。
  • skrub：0.9 以降、mark_as_y(target_column) のシグネチャから位置引数が削除されています。マークする前に .skb.select("...") を使用してください。
  • skore：Project.get(...) はユーザー向けの key ではなく id で検索します。まず project.summarize() で列挙してください。その後は何もしないでください。復旧方法として experiments/NN_*.py に言及することは、仮定の話であっても禁止です。
• プローブ結果を捏造しないでください。 プローブを実行していない場合、Signature／help() のセクションは空欄のままにするか、<pending probe execution> と記載してください。Shape 3 にも同じルールが適用されます。ドキュメントを記憶から言い換えてはいけません。キャッシュファイルには逐語的な抜粋を保存します。
• 同梱の references/ は、シグネチャや回答の情報源として使用できません。 ここには、インストール済みバージョンの API ではなく、長期的に使えるワークフローパターンが記載されています。そこからシグネチャ、引数リスト、戻り値の型を引用、言い換え、または「おおよその形」で示してはいけません。これは回答文だけでなく、キャッシュファイルにも適用されます。
• 断り書きがあっても、その内容を記載してよいことにはなりません。 「シグネチャではなく手がかりとして扱ってください」「⚠️ 未検証」「スクリプトに貼り付けないでください」などと書いても、読者は注意書きではなくコードブロックをコピーします。未検証のシグネチャや戻り値の型を出力すること自体が違反であり、免責事項を添えても解消されません。このターンで検索を実行していない場合、回答の該当セクションには <pending probe execution> を記載し、このターンは BLOCKED として報告してください（「§ ブロックされた検索」を参照）。
• 情報源を不採用にしても、そこから引用してよいことにはなりません。 メモリや同梱の参考資料を不採用にする理由を説明するときは、情報源の名前を挙げるだけにして、そこで止めてください。「同梱の概要図」「学習時の記憶」のように記載します。拒否する内容の断片であっても、そこから再現してはいけません。断り文の中に引数リストを書くことも、コピー可能な引数リストを掲載することに変わりはありません。
• まずバージョンを正しく特定してください。 検索する前に <pkg>.__version__ を確認してください。バージョンのサブフォルダーは、キャッシュの鮮度を判定するキーです。
• 新たに取得する前にキャッシュを確認してください。 Shape 1／2／3 を実行する前に、scratch/api/<lib>/<version>/ を一覧表示してください。
• 検索の失敗 ≠ 成果物が存在しない。 レジストリ形式の API（project.get(key)、getattr(obj, name)、dict[key]）での KeyError／AttributeError は、ほとんどの場合、検索方法の誤り（id と key の取り違え、アクセサーの誤り）によるものであり、成果物が存在しないことを意味しません。既知の例：skore.Project.get(...) はユーザー向けの key ではなく id で検索し、project.summarize() は (key, id) の組を列挙します。成果物を再作成して代用してはいけません。 重複した行が作成されます。
• Python の実行はすべて scratch/<YYYY-MM-DD>_<HHMMSS>_<short>.py に記録してください。例外はありません。 すべての Python コマンド（pixi run python -c、python -c、ヒアドキュメント形式の python << 'EOF'、その他のインライン Python）は、長さにかかわらず禁止されています。write_file でファイルを書き込み、その後、このターン中に run_python で実行してください。これらのツールが使える場合、コードブロックと pixi run python scratch/<ts>_<short>.py だけを残して終了してはいけません。それは検索ではなく、実行手順を示しただけです。バージョン確認、インポートのスモークテスト、シグネチャ検索、モジュールの API 一覧出力、docstring の抽出など、すべてに適用されます。python -c と入力しそうになったら、そこで止めてファイルを書き、実行してください。
• インラインで実行した inspect.signature／dir(...)／pydoc.render_doc／help(...) は、Python API の参照とは認められません。 これらは、このスキルが実行を求めている API そのものです。python -c 経由で実行しても、関連スキルの事前確認項目「python-api consulted」を満たしません。納品物として、このターンに scratch/api/<lib>/<version>/<topic>.md ファイルを書き込む必要があります。
• __doc__ ではなく pydoc.render_doc を使用してください。 プロパティ、ディスクリプター、デコレーターでラップされた呼び出し可能オブジェクト、アクセサーでは、__doc__ が空、または誤解を招く内容になっていることがあります。キャッシュによって、まさにこうしたケースを判別できます。
• 説明文から得た知見もキャッシュしてください。 WebFetch の結果を読み取った後、破棄することは禁止されています。取得元の URL を1行目に記載し、scratch/api/<lib>/<version>/<topic>.md に保存してください。
• キャッシュを書き込まないプローブは、検索を完了したことになりません。 プローブは調査内容を記録し、キャッシュファイルは結論を記録します。ターン終了時に scratch/api/<lib>/<version>/<topic>.md がディスク上に存在しない場合、未完了です。

ブロックされた検索

必須の検索をこのターンに実行できない場合（利用できるツールがない、プローブを実行できない、フェッチ先に到達できない場合）は、次を出力します。

BLOCKED: <symbol> needs a python-api lookup that cannot run this
turn (<why>). Run <probe or fetch> first.

続けて計画の名前（Shape、scratch/<ts>_….py、キャッシュのパス、WebSearch のクエリ）を示します。そこで終了してください。シグネチャ、引数リスト、戻り値の型、インポート、呼び出しは記載しません。控えめな表現を使ったものや、「フェッチで確認できること」も記載してはいけません。実行できない検索が、別の情報源から回答する許可になるわけではありません。

[~]、「保留中」、「ライブターンに延期」は有効なボックス状態ではありません。引き続き該当する行は、根拠が得られるまで [ ] のままにします。

n/a は有効なボックス状態です。BLOCKED はその同義語ではありません。 このターンでは該当しない行には、[n/a] — <理由> と記載します。最も一般的なのはキャッシュヒットです。トピックのファイルがすでにディスク上にあるため、実行するプローブもフェッチもなく、その行は未チェックではなく n/a です。該当しない行を、ターンをブロックされたものとして報告するために、失敗した行へと定義し直してはいけません（「キャッシュファイルをこのターンに 読み込む」→未チェック→BLOCKED）。キャッシュヒットは、検索が満たされた状態です。

すでに実行できる作業ではなく、不足している入力を理由にブロックしてください。 BLOCKED は、利用できないツールや、把握していない事実に対して使います。このターンに必要な情報がすでにある場合（キャッシュヒット、プロンプトに貼り付けられたコンテンツ、ワークスペースの説明に記載された状態など）、ブロックされてはいません。書ける回答に BLOCKED のバナーを付けるのは、安全策ではなく拒否です。

禁止されている近道

近道	問題点
学習データからシンボル名を認識する → 呼び出しを書く	記憶は任意のバージョンに基づくものです。インストール時に名前やシグネチャが変更されている可能性があります
プローブを実行して回答が表示された → キャッシュを書かずに終了する	プローブは調査であり、キャッシュは結論です。次のセッションでプローブを繰り返すことになります
同梱の references/X.md がある → キャッシュとして扱う	リファレンスはワークフローのパターンであり、キャッシュはバージョンごとの抽出情報です。どちらも必要です
「手掛かりとして扱ってください」と断りを付け、references/X.md からシグネチャを引用する	記憶から引用するのと同じ欠陥があり、情報源が一つ置き換わっただけです。リファレンスはインストール済みバージョンに基づいておらず、断りを付けても読者がコピーするのを防げません
バージョンサブフォルダーがない → 既存の最新のものに書き込む	サブフォルダーは鮮度を示すキーです。正しいものを作成してください
複数のシンボル → 複数の inspect.signature を一つのインライン python -c にまとめる	Python の実行はすべて scratch に出力してください。インライン -c は認められません。複数シンボルの場合は、scratch ファイルを一つ作成し、統合したキャッシュファイルを一つ作成します
手早くバージョンを確認するために python -c "import <pkg>; print(<pkg>.__version__)" を使う	ルールは例外なく適用されます。基準は長さではなく、追跡可能性です。バージョン確認には scratch/<ts>_version_<pkg>.py を使います
トピックのキャッシュがあるのに、引数名を一つ再確認するためインラインで inspect.signature(X) を実行する	インラインで単一のシグネチャを確認する例外はありません。Shape 1 の検索はすべてプローブテンプレートを使います
Shape 1 のプローブを書かずに python -c "...inspect.signature..." を使う	プローブは調査を記録し、キャッシュは結論を記録します。次のセッションで必要なのはファイルであり、実行記録ではありません
ユーザーがドキュメントの URL を貼り付けた → それを回答として扱う	検索には引き続き inspect または WebFetch とキャッシュへの書き込みが必要です。URL は手掛かりです
pydoc.render_doc の代わりに __doc__ を使う	多くのアクセサでは __doc__ が空です。キャッシュファイルは単独で読める必要があります

最初のアクション — このスキルを適用するすべてのターン

1. バージョンを解決します。 scratch/<YYYY-MM-DD>_<HHMMSS>_version_<pkg>.py に import <pkg>; print(<pkg>.__version__) を記述し、 pixi run python scratch/<ts>_version_<pkg>.py で実行します。インラインの python -c は禁止です。
2. キャッシュを一覧表示します： ls scratch/api/<lib>/<version>/。
3. キャッシュヒットの場合： 該当するファイルを読みます。完了です。
4. キャッシュミスの場合： 質問を分類し（上の表を参照）、Shape 1 / 1b / 2 / 2b / 3 を実行します。
5. 各ボックスに印を付けたうえで、事前チェックリストを出力します。

事前チェック — 検索の前に出力

Pre-flight (python-api):
- [ ] Package version resolved this turn: <lib> <version>
      Evidence: Write scratch/<ts>_version_<lib>.py (this turn) +
                `pixi run python scratch/<ts>_version_<lib>.py` output.
                **Inline `python -c "..."` is NOT evidence.**
- [ ] Cache listed this turn (Shape 0): `ls scratch/api/<lib>/<version>/`
      Evidence: tool output (paste the listing, even if empty)
- [ ] Question shape classified: signature | module surface | narrative
      Evidence: name the shape + one phrase from the question
- [ ] Lookup decision: cache hit (Read <file>) | Shape 1 | 1b | 2 | 2b | 3
      Evidence: name the file Read, probe script written, LSP
                operation requested, or URL fetched
- [ ] (Shape 1b / 2b only) LSP preconditions confirmed:
      `agent feature: installed` in JOURNAL.md AND
      `pyrightconfig.json` at project root pointing at the `lsp` env
      Evidence: Read journal/JOURNAL.md + Read pyrightconfig.json
                (this turn) | "n/a — not an LSP shape"
- [ ] Cache file lands on disk before turn end
      Evidence: Write scratch/api/<lib>/<version>/<topic>.md (this turn)
                | "n/a — cache hit, already on disk + Read this turn"
                | "n/a — Shape 2b ad-hoc discovery"
      **Inline `inspect.signature(...)` / `dir(...)` / `pydoc.render_doc(...)`
      WITHOUT a corresponding cache file is NOT evidence. Re-do as Shape 1.**
- [ ] If Shape 1 / 1b: Usage section filled in (Call / Don't call / Trap / Returns)
      Evidence: Edit scratch/api/<lib>/<version>/<topic>.md (this turn)
                | "n/a — cache hit / Shape 2 / 2b / 3"
- [ ] Pre-flight re-emitted with evidence before final message.
      Evidence: this checklist appears in the end-of-turn summary.

4 つの Shape

Shape 0 — キャッシュヒット

ls scratch/api/<lib>/<version>/ 2>/dev/null

トピックに一致するファイルが存在する場合 → そのファイルを Read します。最初の行にはソース URL または inspect: 参照が記載されています。不審な点がある場合は、ライブドキュメントと照合して再確認してください。キャッシュミスの場合 → Shape 1 / 2 / 3。

Shape 1 — シンボルカード（pydoc → キャッシュファイル）

1つのプローブスクリプトで、シンボルをイントロスペクションし、1回の実行でキャッシュファイルにも書き込みます。短い追加の Edit で Usage の箇条書き（Call / Don't call / Trap / Returns）を埋めます。

プローブのテンプレート：→ references/probe_templates.md § Shape 1。

複数シンボルの統合。 同じトピックを共有する複数のシンボル（例：project_local 配下の Project.put / Project.get / Project.summarize）の場合 → プローブ内でドット区切りパスのタプルを反復処理し、各セクションを連結して1つの <topic>.md にまとめます。ファイルはシンボルごとではなく、トピックごとに1つ作成します。 これら3つの Project メソッドは、1つのファイル scratch/api/skore/<ver>/project_local.md（または project.md）にまとめます。put.md / get.md / summarize.md にはしません。

単一シグネチャの確認に対するインラインの例外はありません。 キャッシュがあり、1つの引数だけを再確認したい場合でも、新しいプローブを実行するか、既存のキャッシュを Read してください。

Shape 1b — LSP ホバー（Python を実行しない）

opencode LSP 経由の Pyright は、file:line:character 位置にあるシンボルのホバー情報（型シグネチャと docstring の最初の段落）を返します。このセッションで Shape 1b が利用可能だと確認できている場合（以下の Step 0 を参照）、「シグネチャは何か」という質問に対する最初の手段として使用します。そうでない場合、またはホバー出力が不十分な場合は、Shape 1 に進みます。

Step 0 — LSP の利用可否を確認するプローブ（必須、セッションごとに1回）

opencode LSP サーバーは、セッション開始時に pyrightconfig.json を1回読み込みます。セッション中に編集しても再読み込みされません。LSP がすべての外部ライブラリに対して (import) <name>: Unknown を返す場合、LSP の初期化後に設定ファイルが書き込まれたため、このセッションでは Shape 1b を利用できません。この判断は次のセッションまで有効です。次の opencode セッションまで、すべてのシグネチャに関する質問には Shape 1 を使用してください。

プローブの手順、解釈表、すべての注意点（セッション開始時の順序、conda 形式の環境、文字オフセット、scratch の除外パス、C 拡張型）： → references/shape1b_lsp_setup.md。

利用可能だと確認できた後

1. プローブファイルを作成します（tests/ または src/<pkg>/ 配下。scratch/ は pyright の解析対象外です）。テンプレート： → references/probe_templates.md § Shape 1b。
2. lsp(operation="hover", filePath=..., line=..., character=...) を呼び出します。
3. 結果を scratch/api/<lib>/<version>/<topic>.md にキャッシュし、Source: lsp-hover: <lib>.<dotted> @ <version> と ## LSP hover セクションを記載します。
4. ホバーが空、または1行のみの場合は Shape 1 に進みます。

Shape 2 — モジュールの表面情報

トップレベルの表面情報とサブモジュール一覧を両方ダンプし、surface.md に直接書き込むスクラッチプローブです。インラインの python -c は使用しません。

プローブのテンプレート：→ references/probe_templates.md § Shape 2。

ファイルはトピックごとに1つ作成します。バージョンが上がった場合にのみ置き換えます。

Shape 2b — LSP ワークスペースシンボル（パッケージ横断検索）

クエリ文字列を指定すると、lsp 環境の site-packages 全体から一致するシンボルをすべて返します。ドット区切りパスを決める前の検索に使用します。候補となる各モジュールに対して dir() を実行するよりも高速です。

lsp(
    operation="workspaceSymbol",
    filePath="<any-existing-Python-file>",
    line=1, character=1,
    query="<symbol substring>",
)

（filePath / line / character は workspaceSymbol では pyright に無視されます。これらは LSP サーバーの選択にのみ使用されます。）

戻り値：(name, kind, location) タプルのリスト。Shape 2 の代替ではありません（モジュールの表面情報全体は列挙しません）。正しいドット区切りパスに対して Shape 1 / Shape 2 を実行する前の検索補助として使用します。検索が繰り返し行われるようになった場合にのみキャッシュしてください。

形状 3 — 説明

シグネチャだけでは答えられない概念的な質問です — 「X はどのように動作しますか？」「A と B のどちらを使うべきですか？」「<arg> が <value> の場合、X は何を返しますか？」などです。手順：

1. バージョン付きドキュメントの URL を WebSearch で検索します。検索クエリ： <library> <MAJOR.MINOR> docs <topic>。記憶を頼りに URL を組み立ててはいけません。

2. インストール済みのバージョン（/0.18/、/0.18.0/）を URL に含む、最も関連性の高い検索結果を WebFetch します。/latest/ または /stable/ を含む URL は 却下 します — 再公開時に内容が変わるためです。

3. 次のパスにそのままキャッシュします：scratch/api/<lib>/<version>/<topic>.md。ファイルの1行目は参照元 URL にします。 その後に：

   <full URL>
   
   # <topic>
   
   Source: <full URL>
   Fetched: <YYYY-MM-DD>
   
   <paste salient sections verbatim — do NOT paraphrase from
   memory. Skip nav chrome; keep prose that answers the question.>
   

キャッシュファイル名：ドキュメント URL のスラッグを snake_case にしたものです。1ファイルにつき1トピックです。バージョンが上がった場合に限り置き換えます。

このファイルが存在するまでは、条件によって変わる戻り値の型（KFold と holdout、同じものと異なるものなど）を断定してはいけません。形状 1 の出力は WebFetch の代わりにはなりません。

キャッシュファイルの規約

すべての scratch/api/<lib>/<version>/<topic>.md は、次の4セクション構成に従います：

# <topic>

Source: inspect: <lib>.<dotted> @ <version>  |  <docs URL>
Probed: <YYYY-MM-DD>

## Signature
<fenced block — exactly as inspect.signature returned it, Shape 1 only>

## help()  (or "## Docs extract" for Shape 3, "## LSP hover" for 1b)
<verbatim pydoc.render_doc / WebFetch extract / hover output.
 Never paraphrase.>

## Usage (agent synthesis)
- **Call:** import path + arg shape (2-3 line snippet)
- **Don't call:** named substitutes that look right from memory
- **Trap:** version-specific rename / deprecation / footgun (empty if none)
- **Returns:** return type + the one accessor the next caller needs

ブートストラップのターンでは、最低限必要なキャッシュを残す必要があります — ファイル一覧と監査手順はこちら：→ references/bootstrap_cache.md。

キャッシュの構成とライフサイクル

scratch/api/
├── skrub/0.9.0/
│   ├── data_ops.md          # Shape 3 narrative
│   ├── tabular_pipeline.md
│   └── surface.md           # Shape 2 dir() dump
├── skore/0.18.0/
│   ├── evaluate.md
│   └── project_local.md
└── sklearn/1.8.0/
    └── cv_splitters.md

• バージョンサブフォルダーは、正確に <pkg>.__version__ と一致させます。 省略形は使いません（0.18.0 ≠ 0.18）。
• 1行目は参照元 URL または inspect: 参照です。
• 既存の scratch/* ルールにより Git の追跡対象外 です。再生成できます。
• 成功時に追記します。 書き込み後は変更しません。バージョンが上がった場合に限り置き換えます（バージョンサブフォルダーの規約で対応します）。
• 古いサブフォルダーでキャッシュが見つからない状況は、構造上起こりません。 形状 0 はバージョンごとに読み込むため、古いサブフォルダーの内容は参照されません。

scratch/ の規約 — プローブとキャッシュ

scratch/ には構造化された用途が2つあり、どちらも Git の追跡対象外です：

	アドホックプローブ	API ドキュメントキャッシュ
パス	scratch/<YYYY-MM-DD>_<HHMMSS>_<short>.py	scratch/api/<lib>/<version>/<topic>.md
内容	複数行の inspect による確認、整合性チェック、メトリクスの抽出	トピックごとのシグネチャ／help()／ドキュメントの抜粋
命名	タイムスタンプ付き（時系列順）	トピック別
ライフサイクル	成功時は追記のみ。同じループ内でエラーが発生した場合は上書き	成功時に追記。バージョンが上がった場合に置き換え
インライン実行の上限	インラインの python -c は禁止。すべての実行を scratch に記録します	該当なし（プローブがキャッシュに書き込みます）

実験スクリプトを編集して、エージェント専用の print(...) による確認処理を追加してはいけません。 確認処理は scratch/ に記録します。

scratch プローブから実験／project.put を再実行してはいけません。 scratch から skore Project への操作は読み取り専用です（project.summarize() の後に project.get(id) を使用します）。

読み取り専用のルールは audit/ にも適用されます。 監査フローでは、各実験につき1つの # %% ファイルを audit/<NN>_<short_name>.py に配置し、同梱のランナーで実行します。同じ summarize() → get(id) → report.* の手順に従います。実行済みのダイジェストは scratch/audit/<stem>/ に保存されます（Git の追跡対象外）。成果物は2種類あり、ライフサイクルも異なります：

	API ドキュメントキャッシュ	監査実行済みダイジェスト
管理元	python-api	audit-ml-pipeline
ソース	inspect.signature / pydoc.render_doc / WebFetch	audit/<stem>.py の実行
ライフサイクル	成功時に追記。バージョンが上がった場合に置き換え	監査を再実行するたびに上書き
読み取り元	シンボルのシグネチャ／規約が必要なすべてのスキル	iterate-ml-experiment § 4 の説明作業中のエージェント

ワークスペースの scratch/ フォルダーには README.md がありません — このように重要なルールは、使用時に読み込まれるスキルに記載されています。

スタックの概要 — 各要素の場所

Tier-1 の名前付きエントリーポイントです。「X はどこにありますか？」という質問に対する形状 2 のサーフェスダンプの前に確認します — 名前付きエントリーがそのまま答えになることがよくあります。このセクションでは、シンボルがどこにあるかを示します。インポートや呼び出しを記述したり、この一覧から形状 3 の戻り値の型に関する質問に答えたりすることを許可するものではありません。説明文でシンボル名を示したら、次にプローブに進みます — 形状 1 のプローブを提示する前に from <lib> import … / fit / predict の記述に踏み込んではいけません。

scikit-learn

• sklearn.metrics — スコアリング（accuracy_score、roc_auc_score、 mean_absolute_error、make_scorer）。
• sklearn.preprocessing — 状態を保持するスケーラー／エンコーダー／欠損値補完器 （StandardScaler、OneHotEncoder、KBinsDiscretizer）。
• sklearn.pipeline／sklearn.compose — Pipeline、 make_pipeline、ColumnTransformer。
• sklearn.model_selection — 分割器（KFold、GroupKFold、 TimeSeriesSplit、train_test_split）＋探索（GridSearchCV）。
• 推定器：sklearn.linear_model／sklearn.ensemble など。

skrub

• ワンコールの特徴量化器／学習器：skrub.tabular_pipeline （トップレベル関数です。tabular_learner でも TabularLearner でもありません。0.7 以降で名前が変更されました）。
• 列ごとのエンコーダー（トップレベル）：TableVectorizer、 DatetimeEncoder、TextEncoder、StringEncoder。
• DataOps DSL（遅延パイプライングラフ）：すべてのノードにある .skb 名前空間 — X.skb.apply、X.skb.apply_func、 X.skb.mark_as_X、X.skb.mark_as_y、X.skb.make_learner、 .skb.preview、.skb.full_report。
• ソース／変数：skrub.var(name, value=...)、 skrub.as_data_op({...})。
• セレクター：skrub.selectors.{numeric, categorical, string, ...}。

skore

• 評価：skore.evaluate — シグネチャと、Shape 1／Shape 3 による戻り値の型の振り分けを確認してください。この一覧からレポートクラスの名前を挙げないでください。
• プロジェクト：skore.Project(name, *, mode="local", **kwargs) （モードごとの kwargs：ローカルディレクトリ／ハブのワークスペース名には workspace=、mlflow には tracking_uri=）。put(key, report)／ summarize()（id をインデックスとし、key 列を含み、date の昇順に並んだ DataFrame）／get(id) を使用します。get は id で取得するものであり、key ではありません。また、静的メソッド Project.delete(name, *, mode, **kwargs) があります。

各ライブラリの全サーフェスマップ（使用頻度の低いサブモジュール、アクセサー早見表）： → references/stack_orientation.md。

インストール済みパッケージが適切でない場合

「別バージョンの知識をもとに記憶で書く」以外に、次の 2 つの方法があります。

1. python-env-manager §「アップグレード／固定」に進み、アップグレードまたはバージョンを固定します。 新しいインストール環境を対象に、もう一度調べてください。
2. インストール済みの内容に合わせます — アプローチを変更してください。

関連スキル

スキル	関係
python-env-manager	バージョンを管理します（解決するバージョンが scratch/api/<lib>/<version>/ のキーになります）
data-science-python-stack	使用するライブラリを決定します。このスキルではライブラリは指定済みとして扱います
build-ml-pipeline / evaluate-ml-pipeline / iterate-from-skore / smoke-test-ml-pipeline	シンボルが必要な場合に、このスキルへ処理を振り分けるワークフロースキルです

このスキルが行わないこと

• スキルフォルダー内で、署名の事前作成済み一覧を管理すること。 バージョンごとの抽出データはワークスペースのキャッシュに保存され、スキルフォルダーには長期的に使えるワークフローパターンが含まれます。
• インストール時にキャッシュファイルを生成すること。キャッシュは必要に応じて作成されます。
• ライブラリの API を詳しく説明すること — 詳細は各ライブラリのドキュメントを参照してください。このスキルはドキュメントを案内し、保持する価値のある情報をキャッシュします。
• 参照資料を自動作成すること。新しい references/<topic>.md ファイルの作成には、AskUserQuestion によるユーザーの許可が必要です（references/authoring_protocol.md を参照）。

参考資料（必要に応じて読み込み）

再利用可能なワークフローパターン（スキルに同梱）：

• references/probe_templates.md — Shape 1（pydoc シンボルカード）、Shape 1b（LSP ホバープローブファイル）、Shape 2（モジュールサーフェスダンプ）のコード全文です。LIB／DOTTED／TOPIC をコピーして編集してください。
• references/shape1b_lsp_setup.md — Step 0 の利用可能性プローブ、解釈テーブル、注意点（セッション開始時の順序、conda 形式の環境、文字オフセット、スクラッチ対象外のパス、C 拡張型）。
• references/stack_orientation.md — ライブラリごとのサーフェスマップ全文（sklearn／skrub／skore）。
• references/pre_mark_alignment.md — 履歴依存パイプライン向けの、3 層構造の skrub DataOps パターンです。履歴依存コードを作成する前にお読みください。
• references/skrub_interop.md — SkrubLearner と skore.evaluate の連携方法です。experiments/NN_*.py を書く前にお読みください。
• references/bootstrap_cache.md — ブートストラップターンに必要なキャッシュファイルの最小要件と監査手順です。
• references/named_traps.md — エージェントが実際のトレースで遭遇した、バージョン固有の名前変更／非推奨事項です。
• references/authoring_protocol.md — 新しい参考資料を追加するタイミングと方法（AskUserQuestion によるユーザー承認が必要）です。