accelerate-python-resolvers

Chalk の Python リゾルバーを高速化する

Chalk の静的アクセラレーターは、関数のバイトコードをシンボリック実行することで、Python のリゾルバー関数をネイティブな列指向の式に変換します。高速化されたリゾルバーは、インタープリターで実行する Python よりも桁違いに高速です。実行するすべての操作が安全であり、アクセラレーターでサポートされていると証明できる場合にのみ、リゾルバーを高速化できます。

このスキルでは、Chalk の静的アクセラレーターサービスを利用してフィードバックループを実行します。診断を取得し、問題のあるリゾルバーを書き換え、問題がなくなるまで繰り返します。

フィードバックループ

1. Chalk プロジェクト内の任意の場所（chalk.yaml または chalk.yml を含むディレクトリツリー内）から、次を実行します。

   python "${CLAUDE_PLUGIN_ROOT}/bin/accelerator-diagnostics.py"
   

   プロジェクトで使用しているものと同じ Python 環境を使用してください（chalk を import できる必要があります）。プロジェクトで venv を使用している場合は、先に有効化するか、venv の python を明示的に実行してください。

2. 診断を確認します。各行は file:line: severity: message の形式で、メッセージには高速化を妨げた操作が具体的に説明されています。例：

   • 'int.__add__(int)' is only supported for non-null values; guard this 'option<int>' argument against None — null 許容の入力（フィーチャークラスで int | None / Optional[int] と注釈されているもの）が、null 以外の値を必要とする操作に渡されています。
   • reference to possibly-unbound name 'uuid' — リゾルバーが、アクセラレーターで取り込めないインポートやヘルパー（未サポートのライブラリ）、またはすべての経路で代入されていないローカル変数を使用しています。

3. 失敗の原因を取り除くようにリゾルバーを書き換えます（以下のレシピを参照）。リゾルバーのシグネチャ、出力フィーチャー、Python のセマンティクスを維持してください。高速化したバージョンでも、Python 版と同じ値を計算する必要があります。

4. スクリプトを再実行します。All resolvers are statically accelerable. と出力され、終了コード 0 で終了するまで繰り返します。

書き換えのレシピ

null 以外の値が必要な箇所で使用される null 許容の入力

最もよくある診断です。int | None と注釈されたフィーチャーは、実行時に None である可能性があります。+、-、*、比較演算子、ほとんどのメソッド呼び出しなどの操作では、オペランドが null 以外であると証明されている必要があります。シンボリック実行で型を絞り込めるように、明示的なガードを追加します。

@online
def get_score(a: User.maybe_null_input) -> User.score:
    if a is None:
        return 0          # pick a semantically sensible default
    return a + 2          # `a` is now provably non-null

if a is None: return <default> のような早期リターンと、x = 0 if a is None else a のような条件式のどちらも使用できます。適切なデフォルト値がない場合は、None の場合に何を出力すべきかユーザーに確認してください。ビジネスロジックを独断で作らないでください。

未サポートのライブラリまたはヘルパー

アクセラレーターがサポートするのは、固定された組み込み機能とモジュールのセットです（math、statistics、re、hashlib、datetime、json、一般的な str / list / dict / set の各メソッド、numpy、pandas、protobuf メッセージへのアクセスなど）。それ以外のもの（例：uuid、requests 関連のヘルパー、カスタムクラス）を参照すると、「possibly-unbound name」または「Unsupported」診断が発生します。

優先度の高い順に、次の方法で対処します。

1. サポートされている操作でロジックを表現し直します（例：ユーザーがセマンティクスを許容できると合意した場合は、uuid.uuid5(...) をサポートされている hashlib のダイジェストに置き換えます）。
2. 小さな純粋ヘルパーをリゾルバー本体にインライン化するか、アクセラレーターが取り込めるモジュールレベルの関数にします。
3. 依存関係が不可欠な場合は、リゾルバーを高速化せず、その理由をユーザーに説明します。動作を偽装しないでください。

バインドされていない可能性のあるローカル変数

変数が条件分岐やループ内でのみ代入される場合は、すべての経路でバインドされるよう、条件分岐の前にデフォルト値を代入します。

設定

• CHALK_ACCELERATOR_HOST — アクセラレーターサービスのホストです。デフォルトは https://accelerator.chalk.ai です（Chalk がユーザーに代わって実行するサービス）。ローカルで実行中のサーバーを使用するには、--host http://127.0.0.1:8780 を渡すか、環境変数を設定します。
• CHALK_ACCELERATOR_TOKEN — ホスト型サービスで使用する任意のベアラートークンです。

注意事項

• このスクリプトはプロジェクト全体をエクスポートします（python -m chalk.cli export）。そのため、プロジェクト内のどこかに構文エラーやインポートエラーがあると、診断の実行前にチェックが失敗します。まずこれらを修正してください（終了コード 2）。
• 診断はプロジェクト内のすべてのリゾルバーを対象とします。ユーザーが特定のリゾルバーについて尋ねている場合は、そのリゾルバーを修正し、依頼されない限り無関係な診断はそのままにしてください。
• クリーンな実行とは、すべてのリゾルバーが完全に高速化されるか、作成者によって明示的に高速化しないと指定されている状態を指します。