accelerate-python-resolvers

Accelerate Chalk Python resolvers

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.

The loop

1. From anywhere inside the Chalk project (the directory tree containing chalk.yaml or chalk.yml), run:

   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.

2. 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.

3. 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.

4. Re-run the script. Repeat until it prints All resolvers are statically accelerable. and exits 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:

@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.

Unsupported library or 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:

1. 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).
2. Inline small pure helpers into the resolver body, or make sure helpers are module-level functions the accelerator can capture.
3. If the dependency is essential, leave the resolver un-accelerated and tell the user why; do not fake the behavior.

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.

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.