executorch 0.1.0

data/ext/executorch/extconf.rb

@@ -0,0 +1,208 @@
+require 'mkmf-rice'
+
+$CXXFLAGS += ' -std=c++17'
+$CXXFLAGS += ' -DC10_USING_CUSTOM_GENERATED_MACROS'
+$CXXFLAGS += ' -Wno-deprecated-declarations'
+
+# ==============================================================================
+# ExecuTorch Path Detection
+# ==============================================================================
+#
+# 1. --with-executorch-dir flag (bundle config or gem install)
+# 2. EXECUTORCH_DIR environment variable
+#
+
+include_dirs = []
+lib_dirs = []
+
+# Helper to add prefix paths
+def add_prefix_paths(prefix, include_dirs, lib_dirs)
+  return false unless prefix && File.directory?(prefix)
+
+  inc = File.join(prefix, 'include')
+  lib = File.join(prefix, 'lib')
+
+  if File.directory?(inc) && File.directory?(lib)
+    include_dirs << inc
+    lib_dirs << lib
+    true
+  else
+    false
+  end
+end
+
+# Priority 1: --with-executorch-dir flag (standard Ruby gem pattern)
+# Usage: bundle config set --local build.executorch --with-executorch-dir=/path/to/executorch
+#    or: gem install executorch -- --with-executorch-dir=/path/to/executorch
+executorch_dir = arg_config('--with-executorch-dir')
+if executorch_dir
+  if add_prefix_paths(executorch_dir, include_dirs, lib_dirs)
+    puts "Using --with-executorch-dir: #{executorch_dir}"
+  else
+    abort "Error: --with-executorch-dir path is invalid: #{executorch_dir}"
+  end
+end
+
+# Priority 2: Environment variable (for CI/scripting)
+if include_dirs.empty?
+  executorch_prefix = ENV['EXECUTORCH_DIR']
+  if add_prefix_paths(executorch_prefix, include_dirs, lib_dirs)
+    puts "Using EXECUTORCH_DIR: #{executorch_prefix}"
+  end
+end
+
+include_dirs.compact!
+include_dirs.uniq!
+lib_dirs.compact!
+lib_dirs.uniq!
+
+if include_dirs.empty? || lib_dirs.empty?
+  abort <<~ERROR
+    ExecuTorch installation not found!
+
+    Configure the path using one of these methods:
+
+    1. Bundle config (recommended - set once per project):
+       bundle config set --local build.executorch --with-executorch-dir=/path/to/executorch
+
+    2. Environment variable (useful for CI):
+       EXECUTORCH_DIR=/path/to/executorch bundle install
+
+    Need to build ExecuTorch first? See: https://pytorch.org/executorch/
+  ERROR
+end
+
+# Validate headers exist
+include_dir = include_dirs.first
+lib_dir = lib_dirs.first
+
+unless File.exist?(File.join(include_dir, 'executorch', 'extension', 'module', 'module.h'))
+  abort <<~ERROR
+    ExecuTorch module.h header not found at: #{include_dir}
+    Make sure EXECUTORCH_BUILD_EXTENSION_MODULE=ON was set during build.
+  ERROR
+end
+
+puts "Include directory: #{include_dir}"
+puts "Library directory: #{lib_dir}"
+
+# Configure include paths
+# Also add the portable c10 headers path for standalone builds
+portable_c10_dir = File.join(include_dir, 'executorch', 'runtime', 'core', 'portable_type', 'c10')
+$INCFLAGS = "-I#{include_dir} -I#{portable_c10_dir} #{$INCFLAGS}"
+
+# Configure library paths
+$LDFLAGS += " -L#{lib_dir}"
+
+# Add rpath for runtime library loading
+$LDFLAGS += if RUBY_PLATFORM =~ /darwin/
+              " -Wl,-rpath,#{lib_dir}"
+            else
+              " -Wl,-rpath,#{lib_dir}"
+            end
+
+# ==============================================================================
+# Library Linking Configuration
+# ==============================================================================
+
+# Default libraries required for basic operation
+DEFAULT_LIBS = %w[
+  extension_module_static
+  extension_data_loader
+  extension_tensor
+  extension_named_data_map
+  extension_flat_tensor
+  extension_threadpool
+  executorch
+  executorch_core
+].freeze
+
+# Determine which libraries to link
+libs = if ENV['EXECUTORCH_LIBS']
+         # User-specified library list (overrides defaults)
+         user_libs = ENV['EXECUTORCH_LIBS'].split(',').map(&:strip).reject(&:empty?)
+         puts "Using custom library list: #{user_libs.join(', ')}"
+         user_libs
+       else
+         DEFAULT_LIBS.dup
+       end
+
+# Link extension libraries first (order matters for static linking)
+libs.each do |lib|
+  lib_file = File.join(lib_dir, "lib#{lib}.a")
+  if File.exist?(lib_file)
+    $LDFLAGS += " -l#{lib}"
+    puts "  Linking: #{lib}"
+  else
+    # Try without _static suffix
+    alt_lib = lib.sub(/_static$/, '')
+    alt_file = File.join(lib_dir, "lib#{alt_lib}.a")
+    if File.exist?(alt_file)
+      $LDFLAGS += " -l#{alt_lib}"
+      puts "  Linking: #{alt_lib} (alternative)"
+    elsif lib.include?('extension_')
+      # Extension libraries are optional
+      puts "  Skipping optional: #{lib} (not found)"
+    else
+      # Core libraries should exist
+      abort "Required library not found: #{lib} (looked for #{lib_file})"
+    end
+  end
+end
+
+# Check for portable kernels (if available)
+# Use -force_load on macOS to include global constructors that register kernels
+portable_ops_lib = File.join(lib_dir, 'libportable_ops_lib.a')
+if File.exist?(portable_ops_lib)
+  $LDFLAGS += if RUBY_PLATFORM =~ /darwin/
+                # macOS: -force_load pulls in all symbols including global constructors
+                " -Wl,-force_load,#{portable_ops_lib}"
+              else
+                # Linux: --whole-archive achieves the same effect
+                ' -Wl,--whole-archive -lportable_ops_lib -Wl,--no-whole-archive'
+              end
+  puts '  Linking: portable_ops_lib (force_load)'
+
+  # Portable kernels
+  if File.exist?(File.join(lib_dir, 'libportable_kernels.a'))
+    $LDFLAGS += ' -lportable_kernels'
+    puts '  Linking: portable_kernels'
+  end
+end
+
+# CPU info and pthreadpool (often required)
+%w[cpuinfo pthreadpool].each do |lib|
+  if File.exist?(File.join(lib_dir, "lib#{lib}.a"))
+    $LDFLAGS += " -l#{lib}"
+    puts "  Linking: #{lib}"
+  end
+end
+
+# Extra libraries from environment (consolidated from version B)
+if ENV['EXECUTORCH_EXTRA_LIBS']
+  extra_libs = ENV['EXECUTORCH_EXTRA_LIBS'].split(',').map(&:strip).reject(&:empty?)
+  extra_libs.each do |lib|
+    if File.exist?(File.join(lib_dir, "lib#{lib}.a"))
+      $LDFLAGS += " -l#{lib}"
+      puts "  Linking extra: #{lib}"
+    else
+      puts "  Warning: extra library not found: #{lib}"
+    end
+  end
+end
+
+# ==============================================================================
+# Platform-Specific Configuration
+# ==============================================================================
+
+if (RUBY_PLATFORM =~ /darwin/) && (RUBY_PLATFORM =~ /arm64/)
+  # Apple Silicon specific
+  puts 'Building for Apple Silicon (arm64)'
+end
+
+$LDFLAGS += ' -lpthread' if RUBY_PLATFORM =~ /linux/
+
+# Create Makefile
+create_makefile('executorch/executorch')
+
+puts "\nConfiguration complete. Run 'make' to build."

data/ext/executorch/utils.h

@@ -0,0 +1,140 @@
+#ifndef EXECUTORCH_RUBY_UTILS_H
+#define EXECUTORCH_RUBY_UTILS_H
+
+#include <rice/rice.hpp>
+#include <rice/stl.hpp>
+#include <executorch/runtime/core/error.h>
+#include <executorch/runtime/core/result.h>
+
+// Error handling macros - translate C++ exceptions to Ruby exceptions
+#define HANDLE_ET_ERRORS try {
+
+#define END_HANDLE_ET_ERRORS                                                    \
+  }                                                                             \
+  catch (const Rice::Exception &ex) {                                           \
+    throw;                                                                      \
+  }                                                                             \
+  catch (const std::exception &ex) {                                            \
+    rb_raise(rb_eRuntimeError, "ExecuTorch error: %s", ex.what());              \
+  }
+
+namespace executorch_ruby {
+
+inline void check_error(executorch::runtime::Error error) {
+  if (error != executorch::runtime::Error::Ok) {
+    const char* error_name = "Unknown error";
+    switch (error) {
+      case executorch::runtime::Error::Ok:
+        return;
+      case executorch::runtime::Error::Internal:
+        error_name = "Internal error";
+        break;
+      case executorch::runtime::Error::InvalidState:
+        error_name = "Invalid state";
+        break;
+      case executorch::runtime::Error::InvalidArgument:
+        error_name = "Invalid argument";
+        break;
+      case executorch::runtime::Error::InvalidType:
+        error_name = "Invalid type";
+        break;
+      case executorch::runtime::Error::NotFound:
+        error_name = "Not found";
+        break;
+      case executorch::runtime::Error::MemoryAllocationFailed:
+        error_name = "Memory allocation failed";
+        break;
+      case executorch::runtime::Error::AccessFailed:
+        error_name = "Access failed";
+        break;
+      case executorch::runtime::Error::NotSupported:
+        error_name = "Not supported";
+        break;
+      case executorch::runtime::Error::DelegateInvalidCompatibility:
+        error_name = "Delegate invalid compatibility";
+        break;
+      case executorch::runtime::Error::DelegateMemoryAllocationFailed:
+        error_name = "Delegate memory allocation failed";
+        break;
+      case executorch::runtime::Error::DelegateInvalidHandle:
+        error_name = "Delegate invalid handle";
+        break;
+      default:
+        error_name = "Unknown error";
+        break;
+    }
+    rb_raise(rb_eRuntimeError, "ExecuTorch error: %s", error_name);
+  }
+}
+
+// Helper to unwrap Result<T> and raise Ruby exception on error
+template <typename T>
+T unwrap_result(executorch::runtime::Result<T>&& result) {
+  if (!result.ok()) {
+    check_error(result.error());
+    // Should never reach here, but just in case
+    rb_raise(rb_eRuntimeError, "ExecuTorch: unexpected error");
+  }
+  return std::move(result.get());
+}
+
+// Convert ExecuTorch ScalarType to Ruby symbol
+// Uses short names (:int, :long, :float) to match input symbols
+inline VALUE scalar_type_to_symbol(executorch::aten::ScalarType dtype) {
+  switch (dtype) {
+    case executorch::aten::ScalarType::Byte:
+      return ID2SYM(rb_intern("byte"));
+    case executorch::aten::ScalarType::Char:
+      return ID2SYM(rb_intern("char"));
+    case executorch::aten::ScalarType::Short:
+      return ID2SYM(rb_intern("short"));
+    case executorch::aten::ScalarType::Int:
+      return ID2SYM(rb_intern("int"));
+    case executorch::aten::ScalarType::Long:
+      return ID2SYM(rb_intern("long"));
+    case executorch::aten::ScalarType::Half:
+      return ID2SYM(rb_intern("half"));
+    case executorch::aten::ScalarType::Float:
+      return ID2SYM(rb_intern("float"));
+    case executorch::aten::ScalarType::Double:
+      return ID2SYM(rb_intern("double"));
+    case executorch::aten::ScalarType::Bool:
+      return ID2SYM(rb_intern("bool"));
+    default:
+      return ID2SYM(rb_intern("unknown"));
+  }
+}
+
+inline executorch::aten::ScalarType symbol_to_scalar_type(VALUE sym) {
+  if (!RB_TYPE_P(sym, T_SYMBOL)) {
+    rb_raise(rb_eTypeError, "Expected Symbol for dtype");
+  }
+
+  ID id = SYM2ID(sym);
+
+  if (id == rb_intern("uint8") || id == rb_intern("byte")) {
+    return executorch::aten::ScalarType::Byte;
+  } else if (id == rb_intern("int8") || id == rb_intern("char")) {
+    return executorch::aten::ScalarType::Char;
+  } else if (id == rb_intern("int16") || id == rb_intern("short")) {
+    return executorch::aten::ScalarType::Short;
+  } else if (id == rb_intern("int32") || id == rb_intern("int")) {
+    return executorch::aten::ScalarType::Int;
+  } else if (id == rb_intern("int64") || id == rb_intern("long")) {
+    return executorch::aten::ScalarType::Long;
+  } else if (id == rb_intern("float16") || id == rb_intern("half")) {
+    return executorch::aten::ScalarType::Half;
+  } else if (id == rb_intern("float32") || id == rb_intern("float")) {
+    return executorch::aten::ScalarType::Float;
+  } else if (id == rb_intern("float64") || id == rb_intern("double")) {
+    return executorch::aten::ScalarType::Double;
+  } else if (id == rb_intern("bool")) {
+    return executorch::aten::ScalarType::Bool;
+  } else {
+    rb_raise(rb_eArgError, "Unknown dtype: %s", rb_id2name(id));
+  }
+}
+
+} // namespace executorch_ruby
+
+#endif // EXECUTORCH_RUBY_UTILS_H

data/lib/executorch/version.rb

@@ -0,0 +1,3 @@
+module Executorch
+  VERSION = "0.1.0"
+end

data/lib/executorch.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative "executorch/version"
+
+# Load the native extension
+begin
+  require_relative "executorch/executorch"
+rescue LoadError => e
+  warn "Failed to load ExecuTorch native extension: #{e.message}"
+  warn "Make sure to run: bundle exec rake compile"
+  raise
+end
+
+module Executorch
+  # Extend Tensor with Ruby-friendly methods
+  class Tensor
+    class << self
+      # Create a new tensor from data
+      #
+      # @param data [Array] Array of numeric values (can be nested or flat)
+      # @param shape [Array<Integer>, nil] Shape of the tensor. If nil, inferred from data structure.
+      # @param dtype [Symbol] Data type (:float, :double, :int, :long)
+      # @return [Tensor]
+      #
+      # @example Create from nested array (shape inferred)
+      #   Tensor.new([[1.0, 2.0], [3.0, 4.0]])  # shape: [2, 2]
+      #
+      # @example Create from flat array with explicit shape
+      #   Tensor.new([1.0, 2.0, 3.0, 4.0], shape: [2, 2])
+      #
+      def new(data, shape: nil, dtype: :float)
+        if shape.nil?
+          # Infer shape from nested array structure
+          shape = infer_shape(data)
+          flat_data = flatten_nested(data, shape)
+        else
+          # Use flat data directly (backward compatibility)
+          flat_data = data
+        end
+
+        create(flat_data, shape, dtype)
+      end
+
+      private
+
+      # Infer the shape from a nested array structure
+      # @param data [Array] Potentially nested array
+      # @return [Array<Integer>] Inferred shape
+      def infer_shape(data)
+        return [0] if data.empty?
+
+        shape = []
+        current = data
+
+        while current.is_a?(Array)
+          shape << current.size
+          break if current.empty?
+          current = current.first
+        end
+
+        # Validate that all elements at each level have consistent sizes
+        validate_shape(data, shape, 0)
+
+        shape
+      end
+
+      # Validate that the array has consistent shape at all levels
+      # @param data [Array] The data to validate
+      # @param expected_shape [Array<Integer>] The expected shape
+      # @param depth [Integer] Current depth in the array
+      # @raise [ArgumentError] If the array is jagged or inconsistent
+      def validate_shape(data, expected_shape, depth)
+        return if depth >= expected_shape.size
+        return if expected_shape[depth] == 0
+
+        unless data.is_a?(Array)
+          raise ArgumentError, "Inconsistent nesting depth at level #{depth}: expected Array, got #{data.class}"
+        end
+
+        unless data.size == expected_shape[depth]
+          raise ArgumentError, "Jagged array at depth #{depth}: expected size #{expected_shape[depth]}, got #{data.size}"
+        end
+
+        data.each_with_index do |element, i|
+          if depth + 1 < expected_shape.size
+            # Expect more nesting
+            unless element.is_a?(Array)
+              raise ArgumentError, "Inconsistent nesting at depth #{depth}, index #{i}: expected Array, got #{element.class}"
+            end
+            validate_shape(element, expected_shape, depth + 1)
+          else
+            # At leaf level, should be numeric
+            if element.is_a?(Array)
+              raise ArgumentError, "Inconsistent nesting at depth #{depth}, index #{i}: unexpected Array at leaf level"
+            end
+          end
+        end
+      end
+
+      # Flatten a nested array into a 1D array
+      # @param data [Array] Potentially nested array
+      # @param shape [Array<Integer>] The shape (used to handle empty arrays)
+      # @return [Array] Flat array
+      def flatten_nested(data, shape)
+        return [] if shape.include?(0)
+        deep_flatten(data)
+      end
+
+      # Recursively flatten an array
+      # @param data [Array, Numeric] The data to flatten
+      # @return [Array] Flat array
+      def deep_flatten(data)
+        return [data] unless data.is_a?(Array)
+        data.flat_map { |element| deep_flatten(element) }
+      end
+    end
+
+    # Convert tensor to a nested Ruby array matching the tensor's shape
+    # @return [Array] Nested array with structure matching shape
+    #
+    # @example
+    #   tensor = Tensor.new([1, 2, 3, 4], shape: [2, 2])
+    #   tensor.to_a  # => [[1.0, 2.0], [3.0, 4.0]]
+    #
+    def to_a
+      flat = flat_to_a
+      reshape_flat_to_nested(flat, shape)
+    end
+
+    # Convert tensor to a flat Ruby array (original behavior)
+    # @return [Array] Flat array of all values
+    alias_method :flat_to_a, :_original_to_a
+
+    private
+
+    # Reshape a flat array into nested arrays according to shape
+    # @param flat [Array] Flat array of values
+    # @param shape [Array<Integer>] Target shape
+    # @return [Array] Nested array
+    def reshape_flat_to_nested(flat, shape)
+      return flat if shape.size <= 1
+
+      # Handle empty dimensions
+      if shape.include?(0)
+        return build_empty_nested(shape)
+      end
+
+      # Calculate strides for each dimension
+      build_nested(flat, shape, 0, 0).first
+    end
+
+    # Build nested array structure
+    # @param flat [Array] Flat data
+    # @param shape [Array<Integer>] Shape
+    # @param dim [Integer] Current dimension
+    # @param offset [Integer] Current offset in flat array
+    # @return [Array] [nested_result, new_offset]
+    def build_nested(flat, shape, dim, offset)
+      if dim == shape.size - 1
+        # Last dimension: slice the flat array
+        result = flat[offset, shape[dim]]
+        [result, offset + shape[dim]]
+      else
+        # Build sub-arrays
+        result = []
+        current_offset = offset
+        shape[dim].times do
+          sub_result, current_offset = build_nested(flat, shape, dim + 1, current_offset)
+          result << sub_result
+        end
+        [result, current_offset]
+      end
+    end
+
+    # Build empty nested structure for shapes with zero dimensions
+    # @param shape [Array<Integer>] Shape with at least one zero
+    # @return [Array] Empty nested structure
+    def build_empty_nested(shape)
+      return [] if shape.size == 1
+
+      first_zero = shape.index(0)
+
+      if first_zero == 0
+        []
+      else
+        # Build arrays up to the zero dimension
+        build_empty_recursive(shape, 0)
+      end
+    end
+
+    # Recursively build empty nested arrays
+    # @param shape [Array<Integer>] Shape
+    # @param dim [Integer] Current dimension
+    # @return [Array] Empty nested structure
+    def build_empty_recursive(shape, dim)
+      return [] if dim >= shape.size || shape[dim] == 0
+
+      Array.new(shape[dim]) { build_empty_recursive(shape, dim + 1) }
+    end
+  end
+
+  # Extend Model with Ruby-friendly methods
+  class Model
+    # Alias predict to forward for more intuitive API
+    alias_method :predict, :forward
+
+    # Make model callable
+    def call(inputs)
+      forward(inputs)
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: executorch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benjamin Garcia
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rice
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+description: Run PyTorch models exported with ExecuTorch in Ruby
+email:
+- hey@bengarcia.dev
+executables: []
+extensions:
+- ext/executorch/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/executorch/executorch.cpp
+- ext/executorch/extconf.rb
+- ext/executorch/utils.h
+- lib/executorch.rb
+- lib/executorch/version.rb
+homepage: https://github.com/benngarcia/executorch-ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/benngarcia/executorch-ruby
+  source_code_uri: https://github.com/benngarcia/executorch-ruby
+  changelog_uri: https://github.com/benngarcia/executorch-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for ExecuTorch
+test_files: []