[python] Split Python packages and add standalone AOT runtime

[derek-gerstmann]

Summary

Rework Halide's Python distribution into three coordinated packages, add a standalone runtime API for calling precompiled AOT kernels without the compiler, and harden the shared Python binding/marshalling layer.

The full pip install halide experience remains intact: package managers install the matching binary and runtime distributions automatically. Deployment environments that only execute precompiled pipelines can install halide-runtime by itself and avoid libHalide and LLVM entirely.

Package layout

Distribution	Contents	Wheel shape
halide-bin	libHalide, autoschedulers, generator tools, headers, and CMake package files	Python-independent platform wheel, built once per platform
halide-runtime	halide.runtime, its lightweight Buffer, and the Halide runtime needed to invoke AOT kernels	Small CPython platform wheel with no libHalide dependency
halide	The compiler-facing pybind11 extension, Python helpers, and image I/O	CPython wheel depending on matching halide-bin and halide-runtime versions

This avoids rebuilding and bundling the LLVM-linked compiler once per CPython ABI. The repository root is now a uv workspace; source builds target the individual distribution directories rather than treating the root as the halide distribution. The Python bindings are organized as workspace packages with shared versioning and reproducible, packaged build dependencies.

Standalone halide.runtime

halide.runtime can load and call a precompiled Halide AOT shared library without importing the compiler extension:

import halide.runtime as hlr

kernel = hlr.load("my_filter.so", name="my_filter")
kernel(input_array, output_array)

The module provides:

• load(path, name=None), accepting normal Python path-like objects and resolving <name>_argv and <name>_metadata from a shared library.
• Callable Kernel objects with metadata-driven scalar and buffer argument marshalling plus name, target, and argument introspection.
• A lightweight halide.runtime.Buffer with zero-copy Python buffer/NumPy views, shape transformations, element access, and device operations.
• Zero-copy interop between compiler halide.Buffer, runtime halide.runtime.Buffer, and generated Python extensions through versioned typed capsules with explicit ownership.
• Per-thread runtime error capture and output copy-back failures reported as Python exceptions instead of aborting the interpreter.
• Lazy compiler imports so import halide.runtime never loads libHalide; runtime-only installations produce a clear error if compiler APIs are requested.

Shared marshalling and binding correctness

Move the generated-extension buffer marshalling code into src/PythonExtensionRuntime.template.cpp, which is both embedded into generated Python extensions and reused by the standalone runtime module. This removes duplicated conversion logic and keeps generated extensions self-contained.

The shared and compiler binding paths are also hardened to:

• Preserve exceptions raised by capsule providers and retain capsules for the lifetime of borrowed pointers.
• Preserve Python buffer-exporter errors, including read-only output diagnostics.
• Reject non-native-endian multi-byte buffers, non-integral element strides, out-of-range dimensions/strides, and inconsistent format/item-size metadata rather than silently misaddressing or corrupting data.
• Propagate warnings promoted to exceptions instead of returning with a pending Python error.
• Catch only pybind11 conversion failures during manual overload dispatch so genuine Halide errors are not replaced with generic ValueErrors.
• Use pybind11's std::filesystem::path support instead of a custom raw-Python path caster.

Build, packaging, and CI

• Add dedicated CMake targets/install components for the compiler and runtime Python modules.
• Install the shared runtime template next to the Halide runtime headers for out-of-tree builds.
• Build the bundled runtime for the native target and keep the runtime binding independent of libHalide.
• Update wheel build, repair, publication, dependency discovery, and Windows shared-package handling for all three distributions.
• Keep project-wide version bumping and disabled-Python-binding configurations working.
• Remove obsolete archive packaging scripts and modernize the Python workspace/pre-commit configuration.

Tests and documentation

Coverage includes:

• Loading and invoking real AOT kernels without importing the compiler.
• Every supported scalar calling-convention type, multidimensional buffers, tuple outputs, keyword arguments, and compile-time GeneratorParam variants.
• CPU and available Metal/OpenCL/CUDA/Vulkan execution paths.
• Compiler/runtime/generated-extension Buffer interop and ownership behavior.
• Capsule exception propagation, warnings-as-errors, endian/stride validation, read-only buffers, path-like inputs, and Halide error preservation.
• A binary dependency check proving the runtime module does not link libHalide.
• Updated package documentation, Python API documentation, and a standalone runtime tutorial covering AOT generation, shared-library linking, loading, and execution.

Co-authored by @alexreinking

Checklist

• Tests added or updated
• Documentation updated
• Python bindings updated
• Benchmarks included (not performance-oriented)
• Commits include AI attribution where applicable

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.01%. Comparing base (5c21c82) to head (ad25832).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9272      +/-   ##
==========================================
- Coverage   70.08%   70.01%   -0.08%     
==========================================
  Files         260      260              
  Lines       79287    79229      -58     
  Branches    19327    19327              
==========================================
- Hits        55569    55470      -99     
- Misses      17923    17929       +6     
- Partials     5795     5830      +35     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[alexreinking]

This took some work, but with everything in place, we were able to pay off some longstanding tech debt.

[derek-gerstmann]

@alexreinking Amazing! Thanks for all your help on this!

[alexreinking]

Looks like I broke Python stubs. Will fix.