[ESI][Runtime] Port Python bindings from pybind11 to nanobind (#9322)

This PR migrates the ESI Runtime Python bindings (esiaccel package) from pybind11 to nanobind for consistency with CIRCT and upstream MLIR. The migration updates binding APIs, build configuration, and dependency management while maintaining the same Python interface functionality.

Author: Copilot

.github/workflows/esiRuntimePublish.yml

@@ -17,8 +17,6 @@ jobs:
       fail-fast: false
       matrix:
         config:
-          - os: ubuntu-24.04
-            cibw_build: cp38-manylinux_x86_64
           - os: ubuntu-24.04
             cibw_build: cp39-manylinux_x86_64
           - os: ubuntu-24.04
@@ -29,8 +27,8 @@ jobs:
             cibw_build: cp312-manylinux_x86_64
           - os: ubuntu-24.04
             cibw_build: cp313-manylinux_x86_64
-          - os: windows-2022
-            cibw_build: cp38-win_amd64
+          - os: ubuntu-24.04
+            cibw_build: cp314-manylinux_x86_64
           - os: windows-2022
             cibw_build: cp39-win_amd64
           - os: windows-2022
@@ -41,6 +39,8 @@ jobs:
             cibw_build: cp312-win_amd64
           - os: windows-2022
             cibw_build: cp313-win_amd64
+          - os: windows-2022
+            cibw_build: cp314-win_amd64
 
     steps:
       - name: Get CIRCT
@@ -68,7 +68,7 @@ jobs:
           & "${env:VCPKG_INSTALLATION_ROOT}/vcpkg" --triplet x64-windows install zlib grpc
 
       - name: Install cibuildwheel
-        run: python -m pip install cibuildwheel==2.23.3
+        run: python -m pip install cibuildwheel==3.3.0
 
       - name: Build wheels
         if: runner.os != 'Windows'

frontends/PyCDE/pyproject.toml

@@ -8,8 +8,7 @@ requires = [
 
   # MLIR build depends.
   "numpy",
-  "pybind11>=2.11,<=2.12",
-  "nanobind==2.9.2",
+  "nanobind>=2.2",
   "PyYAML",
 
   # PyCDE depends

lib/Dialect/ESI/runtime/CMakeLists.txt

@@ -11,7 +11,7 @@
 ## themselves since it needs to be compiled for each Python version and OS then
 ## packed together. Eventually, we'll just be distributing (lots of) binaries.
 ##
-## We require Python development package and pybind11 to compile the Python API.
+## We require Python development package and nanobind to compile the Python API.
 ##
 ## ESI cosimulation requires Cap'nProto as we use it for our RPC with the
 ## simulator. It must be fetched separately, but is optional if you don't want

lib/Dialect/ESI/runtime/cpp/include/esi/Accelerator.h

@@ -65,8 +65,8 @@ class Accelerator : public HWModule {
   Accelerator(std::optional<ModuleInfo> info,
               std::vector<std::unique_ptr<Instance>> children,
               std::vector<services::Service *> services,
-              std::vector<std::unique_ptr<BundlePort>> &ports)
-      : HWModule(info, std::move(children), services, ports) {}
+              std::vector<std::unique_ptr<BundlePort>> &&ports)
+      : HWModule(info, std::move(children), services, std::move(ports)) {}
 };
 
 //===----------------------------------------------------------------------===//

lib/Dialect/ESI/runtime/cpp/include/esi/Design.h

@@ -45,11 +45,15 @@ class Service;
 
 /// Represents either the top level or an instance of a hardware module.
 class HWModule {
+public:
+  HWModule(const HWModule &) = delete;
+  HWModule &operator=(const HWModule &) = delete;
+
 protected:
   HWModule(std::optional<ModuleInfo> info,
            std::vector<std::unique_ptr<Instance>> children,
            std::vector<services::Service *> services,
-           std::vector<std::unique_ptr<BundlePort>> &ports);
+           std::vector<std::unique_ptr<BundlePort>> &&ports);
 
 public:
   virtual ~HWModule() = default;
@@ -112,11 +116,12 @@ class Instance : public HWModule {
   Instance(AppID id, std::optional<ModuleInfo> info,
            std::vector<std::unique_ptr<Instance>> children,
            std::vector<services::Service *> services,
-           std::vector<std::unique_ptr<BundlePort>> &ports)
-      : HWModule(info, std::move(children), services, ports), id(id) {}
+           std::vector<std::unique_ptr<BundlePort>> &&ports)
+      : HWModule(info, std::move(children), services, std::move(ports)),
+        id(id) {}
 
   /// Get the instance's ID, which it will always have.
-  const AppID getID() const { return id; }
+  AppID getID() const { return id; }
 
 protected:
   const AppID id;

lib/Dialect/ESI/runtime/cpp/lib/Design.cpp

@@ -42,7 +42,7 @@ buildIndex(const std::vector<std::unique_ptr<BundlePort>> &ports) {
 HWModule::HWModule(std::optional<ModuleInfo> info,
                    std::vector<std::unique_ptr<Instance>> children,
                    std::vector<services::Service *> services,
-                   std::vector<std::unique_ptr<BundlePort>> &ports)
+                   std::vector<std::unique_ptr<BundlePort>> &&ports)
     : info(info), children(std::move(children)),
       childIndex(buildIndex(this->children)), services(services),
       ports(std::move(ports)), portIndex(buildIndex(this->ports)) {}

lib/Dialect/ESI/runtime/cpp/lib/Manifest.cpp

@@ -16,10 +16,14 @@
 #include "esi/Accelerator.h"
 #include "esi/Services.h"
 
+#if defined(__GNUC__)
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wcovered-switch-default"
+#endif
 #include <nlohmann/json.hpp>
+#if defined(__GNUC__)
 #pragma GCC diagnostic pop
+#endif
 #include <sstream>
 
 using namespace ::esi;
@@ -302,7 +306,8 @@ Manifest::Impl::buildAccelerator(AcceleratorConnection &acc) const {
 
   return std::make_unique<Accelerator>(
       getModInfo(designJson),
-      getChildInstances({}, acc, activeSvcs, designJson), services, ports);
+      getChildInstances({}, acc, activeSvcs, designJson), services,
+      std::move(ports));
 }
 
 std::optional<ModuleInfo>
@@ -374,7 +379,7 @@ Manifest::Impl::getChildInstance(AppIDPath idPath, AcceleratorConnection &acc,
   auto ports = getBundlePorts(acc, idPath, activeServices, child);
   return std::make_unique<Instance>(parseIDChecked(child.at("appID")),
                                     getModInfo(child), std::move(children),
-                                    services, ports);
+                                    services, std::move(ports));
 }
 
 services::Service *Manifest::Impl::getService(AppIDPath idPath,

lib/Dialect/ESI/runtime/cpp/tools/esiquery.cpp

@@ -21,10 +21,14 @@
 #include <algorithm>
 #include <iostream>
 #include <map>
+#if defined(__GNUC__)
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wcovered-switch-default"
+#endif
 #include <nlohmann/json.hpp>
+#if defined(__GNUC__)
 #pragma GCC diagnostic pop
+#endif
 #include <stdexcept>
 #include <string>
 

lib/Dialect/ESI/runtime/pyproject.toml

@@ -4,9 +4,9 @@ requires = [
   "setuptools_scm>=8.0",
   "wheel",
   "cmake>=3.31",
-  "pybind11>=2.9",
-  "pybind11_stubgen",
+  "nanobind>=2.2",
   "ninja>=1.13.0",
+  "typing_extensions",
 ]
 build-backend = "setuptools.build_meta"
 

lib/Dialect/ESI/runtime/python/CMakeLists.txt

@@ -13,88 +13,81 @@ set(ESIPythonRuntimeSources
   esiaccel/cosim/verilator.py
 )
 
-# Pybind11 is used to wrap the ESICppRuntime APIs.
+# Nanobind is used to wrap the ESICppRuntime APIs.
 find_package(Python3 COMPONENTS Interpreter Development.Module)
 if(Python3_FOUND)
   IF(MSVC)
-    # Work around an issue with pybind11 and cmake incompatibility on Windows in debug mode.
+    # Work around an issue with nanobind and cmake incompatibility on Windows in debug mode.
     set_target_properties(Python3::Module PROPERTIES
           MAP_IMPORTED_CONFIG_DEBUG ";RELEASE")
   ENDIF(MSVC)
 
-  if(pybind11_DIR)
-    message(STATUS "Using explicit pybind11 cmake directory: ${pybind11_DIR} (-Dpybind11_DIR to change)")
+  if(nanobind_DIR)
+    message(STATUS "Using explicit nanobind cmake directory: ${nanobind_DIR} (-Dnanobind_DIR to change)")
   else()
-    message(STATUS "Checking for pybind11 in python path...")
+    message(STATUS "Checking for nanobind in python path...")
     execute_process(
       COMMAND "${Python3_EXECUTABLE}"
-      -c "import pybind11;print(pybind11.get_cmake_dir(), end='')"
+      -c "import nanobind;print(nanobind.cmake_dir(), end='')"
       WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
       RESULT_VARIABLE STATUS
       OUTPUT_VARIABLE PACKAGE_DIR
       ERROR_QUIET)
     if(NOT STATUS EQUAL "0")
-      message(FATAL_ERROR "pybind11 not found (install via 'pip install pybind11' or set pybind11_DIR)")
+      message(FATAL_ERROR "nanobind not found (install via 'pip install nanobind' or set nanobind_DIR)")
     endif()
     message(STATUS "found (${PACKAGE_DIR})")
-    set(pybind11_DIR "${PACKAGE_DIR}")
+    set(nanobind_DIR "${PACKAGE_DIR}")
   endif()
 
-  # Now, find pybind11.
-  find_package(pybind11 CONFIG)
-  if (NOT pybind11_FOUND)
-    message (STATUS "Could not find pybind11. Disabling Python API.")
+  # Now, find nanobind.
+  find_package(Python COMPONENTS Interpreter Development.Module)
+  find_package(nanobind CONFIG)
+  if (NOT nanobind_FOUND)
+    message (STATUS "Could not find nanobind. Disabling Python API.")
     if (WHEEL_BUILD)
-      message (FATAL_ERROR "pybind11 is required for a wheel build.")
+      message (FATAL_ERROR "nanobind is required for a wheel build.")
     endif()
   else()
-    # Compile Pybind11 module and copy to the correct python directory.
-    pybind11_add_module(esiCppAccel
+    # Compile nanobind module and copy to the correct python directory.
+    nanobind_add_module(esiCppAccel
       ${CMAKE_CURRENT_SOURCE_DIR}/esiaccel/esiCppAccel.cpp)
     target_link_libraries(esiCppAccel PRIVATE ESICppRuntime)
     set_target_properties(esiCppAccel PROPERTIES
       LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/esiaccel"
     )
 
-    # Check for stubgen and generate stubs if available.
-    find_program(STUBGEN pybind11-stubgen)
-    if ("${STUBGEN}" STREQUAL "STUBGEN-NOTFOUND")
-      message(STATUS "pybind11_stubgen not found. Skipping stub generation.")
+    # Use nanobind's built-in stubgen for stub generation.
+    if(WIN32)
+      # I just wasted all day trying to figure out the DLL search path on
+      # Windows both locally and in the runner. I'm done. Windows wheels
+      # won't have a stub until somebody else figures this out.
+      # TODO: have the patience to make this work.
+      message(WARNING "Stub generation is not supported on Windows.")
     else()
-      if(WIN32)
-        # I just wasted all day trying to figure out the DLL search path on
-        # Windows both locally and in the runner. I'm done. Windows wheels
-        # won't have a stub until somebody else figures this out.
-        # TODO: have the patience to make this work.
-        message(WARNING "pybind11-stubgen is not supported on Windows.")
+      set(stubgen_python_path "$ENV{PYTHONPATH}:${CMAKE_CURRENT_BINARY_DIR}")
+      add_custom_command(
+          TARGET esiCppAccel
+          POST_BUILD
+          COMMAND ${CMAKE_COMMAND} -E env PYTHONPATH="${stubgen_python_path}"
+              "${Python3_EXECUTABLE}" -m nanobind.stubgen
+                -m esiaccel.esiCppAccel
+                -o "${CMAKE_CURRENT_BINARY_DIR}/esiaccel/esiCppAccel.pyi"
+      )
+      if (WHEEL_BUILD)
+        install(FILES "${CMAKE_CURRENT_BINARY_DIR}/esiaccel/esiCppAccel.pyi"
+          DESTINATION .
+          COMPONENT ESIRuntime
+        )
       else()
-        set(stubgen_python_path "$ENV{PYTHONPATH}:${CMAKE_CURRENT_BINARY_DIR}")
-        add_custom_command(
-            TARGET esiCppAccel
-            POST_BUILD
-            COMMAND ${CMAKE_COMMAND} -E env PYTHONPATH="${stubgen_python_path}"
-                ${STUBGEN}
-                  -o "${CMAKE_CURRENT_BINARY_DIR}"
-                  esiaccel.esiCppAccel
+        install(FILES "${CMAKE_CURRENT_BINARY_DIR}/esiaccel/esiCppAccel.pyi"
+          DESTINATION python/esiaccel
+          COMPONENT ESIRuntime
         )
-        if (WHEEL_BUILD)
-          install(FILES "${CMAKE_CURRENT_BINARY_DIR}/esiaccel/esiCppAccel.pyi"
-            DESTINATION .
-            COMPONENT ESIRuntime
-          )
-        else()
-          install(FILES "${CMAKE_CURRENT_BINARY_DIR}/esiaccel/esiCppAccel.pyi"
-            DESTINATION python/esiaccel
-            COMPONENT ESIRuntime
-          )
-        endif()
       endif()
     endif()
 
     if (WHEEL_BUILD)
-      if ("${STUBGEN}" STREQUAL "STUBGEN-NOTFOUND")
-        message (FATAL_ERROR "pybind11_stubgen is required for a wheel build.")
-      endif()
       set_target_properties(esiCppAccel PROPERTIES
         INSTALL_RPATH "$ORIGIN/lib")
     else()
@@ -144,7 +137,7 @@ if(Python3_FOUND)
     endforeach()
 
     # Custom target for the Python runtime just aggregates the python sources
-    # and Pybind11 module.
+    # and nanobind module.
     add_custom_target(ESIPythonRuntime
       DEPENDS
         ${ESIPythonRuntimeSources}