accelerate-python-resolvers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accelerate Chalk Python resolvers

加速 Chalk Python resolver

Chalk's static accelerator translates Python resolver functions into native columnar expressions via symbolic execution of the function's bytecode. Accelerated resolvers run orders of magnitude faster than interpreted Python. A resolver can only be accelerated when every operation it performs can be proven safe and is supported by the accelerator.

This skill drives a feedback loop against the Chalk static accelerator service: get diagnostics, rewrite the offending resolvers, repeat until clean.

Chalk 的静态加速器通过符号执行 resolver 函数的 bytecode，将 Python resolver 函数转换为原生列式表达式。加速后的 resolver 比解释执行的 Python 快几个数量级。只有当 resolver 执行的每项操作都能被证明是安全的，且得到加速器支持时，该 resolver 才能被加速。

此技能会与 Chalk 静态加速器服务形成一个反馈循环：获取诊断结果，重写有问题的 resolver，然后重复操作，直至结果干净。

The loop

执行循环

From anywhere inside the Chalk project (the directory tree containing
```
chalk.yaml
```
or
```
chalk.yml
```
), run:
sh
```
python "${CLAUDE_PLUGIN_ROOT}/bin/accelerator-diagnostics.py"
```
Use the same Python environment the project uses (it must be able to
```
import chalk
```
). If the project uses a venv, activate it first or invoke the venv's
```
python
```
explicitly.
Read the diagnostics. Each line is
```
file:line: severity: message
```
and the message explains exactly which operation blocked acceleration, e.g.:
- ```
'int.__add__(int)' is only supported for non-null values; guard this 'option<int>' argument against None
```
  — a nullable input (annotated
```
int | None
```
  /
```
Optional[int]
```
  on the feature class) flows into an operation that requires a non-null value.
- ```
reference to possibly-unbound name 'uuid'
```
  — the resolver uses an import or helper the accelerator cannot capture (an unsupported library), or a local variable that is not assigned on every path.
Rewrite the resolver to remove the failure point (see recipes below). Preserve the resolver's signature, output feature, and Python semantics — the accelerated version must compute the same values the Python version would.
Re-run the script. Repeat until it prints
```
All resolvers are statically accelerable.
```
and exits 0.

在 Chalk 项目（包含
```
chalk.yaml
```
或
```
chalk.yml
```
的目录树）内的任意位置，运行：
sh
```
python "${CLAUDE_PLUGIN_ROOT}/bin/accelerator-diagnostics.py"
```
使用项目所用的同一 Python 环境（该环境必须能够
```
import chalk
```
）。如果项目使用 venv，请先激活它，或显式调用该 venv 的
```
python
```
。
读取诊断结果。每行格式为
```
file:line: severity: message
```
，消息会准确说明是哪项操作阻止了加速，例如：
- ```
'int.__add__(int)' is only supported for non-null values; guard this 'option<int>' argument against None
```
  ——一个可空输入（在 feature 类上标注为
```
int | None
```
  或
```
Optional[int]
```
  ）流入了要求非空值的操作。
- ```
reference to possibly-unbound name 'uuid'
```
  ——resolver 使用了加速器无法捕获的 import 或 helper（不支持的库），或使用了并非在每条路径上都会赋值的局部变量。
重写 resolver 以移除失败点（参见下方的改写方案）。保留 resolver 的签名、输出 feature 和 Python 语义——加速版本必须计算出与 Python 版本相同的值。
重新运行脚本。重复操作，直到脚本输出
```
All resolvers are statically accelerable.
```
并以 0 退出。

Rewrite recipes

改写方案

Nullable input used where a non-null value is required

在需要非空值的位置使用了可空输入

The most common diagnostic. A feature annotated

int | None

may be None at runtime; operations like

, comparisons, and most method calls require proven-non-null operands. Add an explicit guard so the symbolic executor can narrow the type:

python

@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

Both

if a is None: return <default>

early-returns and

x = 0 if a is None else a

conditional expressions work. If no sensible default exists, ask the user what the None case should produce — do not invent business logic silently.

这是最常见的诊断。标注为

int | None

的 feature 在运行时可能为 None；诸如

、

、比较以及大多数方法调用等操作，都要求操作数可证明为非空。添加显式 guard，使符号执行器能够收窄类型：

python

@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 情况应产生什么结果——不要在未告知的情况下臆造业务逻辑。

Unsupported library or helper

不支持的库或 helper

The accelerator supports a fixed set of builtins and modules (including

math

statistics

re

hashlib

datetime

json

, common

str

list

dict

set

methods,

numpy

pandas

, and protobuf message access). A reference to anything else (e.g.

uuid

requests

-adjacent helpers, custom classes) fails with a "possibly-unbound name" or "Unsupported" diagnostic.

Fixes, in order of preference:

Re-express the logic with supported operations (e.g. replace
```
uuid.uuid5(...)
```
with a supported
```
hashlib
```
digest if the user agrees the semantics are acceptable).
Inline small pure helpers into the resolver body, or make sure helpers are module-level functions the accelerator can capture.
If the dependency is essential, leave the resolver un-accelerated and tell the user why; do not fake the behavior.

加速器支持一组固定的内置函数和模块（包括

math

、

statistics

、

re

、

hashlib

、

datetime

、

json

、常见的

str

list

dict

set

方法、

numpy

、

pandas

以及 protobuf message 访问）。对其他任何内容的引用（例如

uuid

、与

requests

相关的 helper、自定义类）都会触发“possibly-unbound name”或“Unsupported”诊断。

修复方案按以下顺序优先选择：

使用受支持的操作重新表达逻辑（例如，在用户认可语义可接受的前提下，将
```
uuid.uuid5(...)
```
替换为受支持的
```
hashlib
```
digest）。
将小型纯 helper 内联到 resolver 主体中，或确保 helper 是加速器能够捕获的模块级函数。
如果依赖不可或缺，请让 resolver 保持未加速状态并告知用户原因；不要伪造行为。

Possibly-unbound local variable

可能未绑定的局部变量

If a variable is only assigned inside a conditional or loop, assign a default before the conditional so every path binds it.

如果变量仅在条件语句或循环中赋值，请在条件语句之前为其设置默认值，以确保每条路径都会绑定该变量。

Configuration

配置

```
CHALK_ACCELERATOR_HOST
```
— accelerator service host. Defaults to
```
https://accelerator.chalk.ai
```
(the service Chalk runs on your behalf). Pass
```
--host http://127.0.0.1:8780
```
or set the env var to use a locally-running server.
```
CHALK_ACCELERATOR_TOKEN
```
— optional bearer token for the hosted service.

```
CHALK_ACCELERATOR_HOST
```
——加速器服务主机。默认为
```
https://accelerator.chalk.ai
```
（Chalk 代你运行的服务）。传入
```
--host http://127.0.0.1:8780
```
或设置该环境变量，以使用本地运行的服务器。
```
CHALK_ACCELERATOR_TOKEN
```
——托管服务的可选 bearer token。

Notes

注意事项

The script exports the whole project (
```
python -m chalk.cli export
```
), so syntax errors or import failures anywhere in the project fail the check before diagnostics run; fix those first (exit code 2).
Diagnostics cover every resolver in the project. If the user asked about one resolver, fix that one and leave unrelated diagnostics alone unless asked.
A clean run means every resolver either accelerates fully or was explicitly marked never-accelerate by its author.

脚本会导出整个项目（
```
python -m chalk.cli export
```
），因此项目中任何位置的语法错误或导入失败都会在诊断运行前使检查失败；请先修复这些问题（退出码 2）。
诊断会覆盖项目中的每个 resolver。如果用户只询问某一个 resolver，请只修复该 resolver，除非用户另有要求，不要处理无关的诊断。
一次干净的运行意味着每个 resolver 要么完全加速，要么已由其作者显式标记为 never-accelerate。