executorch 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,70 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Executorch
4
+ # Immutable metadata describing a single input or output slot of a method.
5
+ class TensorInfo
6
+ attr_reader :tag, :dtype, :shape, :dim_order, :nbytes
7
+
8
+ def initialize(tag, dtype, shape, dim_order, nbytes, memory_planned)
9
+ @tag = tag
10
+ @dtype = dtype
11
+ @shape = shape&.freeze
12
+ @dim_order = dim_order&.freeze
13
+ @nbytes = nbytes
14
+ @memory_planned = !!memory_planned
15
+ freeze
16
+ end
17
+
18
+ def tensor?
19
+ @tag == :tensor
20
+ end
21
+
22
+ def memory_planned?
23
+ @memory_planned
24
+ end
25
+
26
+ def ==(other)
27
+ other.is_a?(TensorInfo) &&
28
+ @tag == other.tag &&
29
+ @dtype == other.dtype &&
30
+ @shape == other.shape &&
31
+ @dim_order == other.dim_order &&
32
+ @nbytes == other.nbytes &&
33
+ @memory_planned == other.memory_planned?
34
+ end
35
+ alias eql? ==
36
+
37
+ def inspect
38
+ if tensor?
39
+ "#<Executorch::TensorInfo dtype=#{@dtype.inspect} shape=#{@shape.inspect} nbytes=#{@nbytes}>"
40
+ else
41
+ "#<Executorch::TensorInfo tag=#{@tag.inspect}>"
42
+ end
43
+ end
44
+ alias to_s inspect
45
+ end
46
+
47
+ # Immutable metadata snapshot for an ExecuTorch method, readable without
48
+ # paying the memory-planning cost of loading the full method.
49
+ class MethodMeta
50
+ attr_reader :name, :inputs, :outputs, :backends, :planned_memory_bytes
51
+
52
+ def initialize(name, inputs, outputs, backends, planned_memory_bytes)
53
+ @name = name.dup.freeze
54
+ @inputs = inputs.freeze
55
+ @outputs = outputs.freeze
56
+ @backends = backends.freeze
57
+ @planned_memory_bytes = planned_memory_bytes
58
+ freeze
59
+ end
60
+
61
+ def uses_backend?(backend_name)
62
+ @backends.include?(backend_name.to_s)
63
+ end
64
+
65
+ def inspect
66
+ "#<Executorch::MethodMeta name=#{@name.inspect} inputs=#{@inputs.size} outputs=#{@outputs.size} backends=#{@backends.inspect} planned_memory_bytes=#{@planned_memory_bytes}>"
67
+ end
68
+ alias to_s inspect
69
+ end
70
+ end
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Executorch
4
+ class Module
5
+ class << self
6
+ # Open an ExecuTorch .pte program from disk.
7
+ # Defaults to :mmap for copy-on-write page sharing across forked workers.
8
+ # Supports an optional block for deterministic resource cleanup.
9
+ #
10
+ # @param path [String, Pathname] Path to .pte file
11
+ # @param load_mode [Symbol] :mmap (default), :file, :mmap_mlock,
12
+ # :mmap_mlock_ignore_errors, or :mmap_madvise
13
+ # @param data_files [Array<String, Pathname>, nil] Optional .ptd external weight files
14
+ def open(path, load_mode: :mmap, data_files: nil)
15
+ mod = _open_file(path, load_mode: load_mode, data_files: data_files)
16
+ return mod unless block_given?
17
+
18
+ begin
19
+ yield mod
20
+ ensure
21
+ mod.close
22
+ end
23
+ end
24
+ alias load open
25
+ end
26
+
27
+ # Execute a named method and always return an Array of outputs.
28
+ #
29
+ # @param method_name [String, Symbol] Method name (e.g. :forward, :encode)
30
+ # @param inputs [Array<Tensor, Integer, Float, Boolean, String, nil>]
31
+ # @param out [Tensor, Array<Tensor>, nil] Optional pre-allocated output tensor(s)
32
+ # @return [Array]
33
+ def execute(method_name, *inputs, out: nil)
34
+ _execute(method_name, inputs, out)
35
+ end
36
+
37
+ # Execute the "forward" method and always return an Array of outputs.
38
+ def forward(*inputs, out: nil)
39
+ _execute("forward", inputs, out)
40
+ end
41
+
42
+ # Ergonomic invocation of "forward": returns the single output directly when
43
+ # the method has 1 output, or an Array when it has 0 or >1 outputs.
44
+ def call(*inputs, out: nil)
45
+ outputs = _execute("forward", inputs, out)
46
+ outputs.size == 1 ? outputs.first : outputs
47
+ end
48
+
49
+ def inspect
50
+ return "#<Executorch::Module (closed)>" if closed?
51
+
52
+ "#<Executorch::Module source=#{source.inspect} methods=#{method_names.inspect}>"
53
+ end
54
+ alias to_s inspect
55
+ end
56
+ end
@@ -0,0 +1,251 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+ require "fileutils"
5
+ require "net/http"
6
+ require "rbconfig"
7
+ require "tmpdir"
8
+ require "uri"
9
+ require "zlib"
10
+
11
+ module Executorch
12
+ # Fetches and extracts the official prebuilt ExecuTorch C++ SDK (headers,
13
+ # shared runtime/backend/kernel libraries, pkg-config, and CMake configs)
14
+ # from official PyPI wheels with strict SHA-256 verification and zero
15
+ # non-stdlib dependencies.
16
+ module SDK
17
+ VERSION = File.read(File.expand_path("../../.executorch-version", __dir__)).strip.freeze
18
+
19
+ # Official ExecuTorch 1.6.0 PyPI wheel manifest (only include/, lib/, share/cmake/ are extracted).
20
+ MANIFEST = {
21
+ "x86_64-linux" => {
22
+ url: "https://files.pythonhosted.org/packages/ef/24/f8fde978e1e5fd629d68c74a3f4acee30acb05f4f90c433cc1a8e29d8eed/executorch-1.6.0-cp312-cp312-manylinux_2_28_x86_64.whl",
23
+ sha256: "d05efe9afe00495112ecf304ca548fcd3239d39e96ac25381b528cdbad948b54",
24
+ },
25
+ "aarch64-linux" => {
26
+ url: "https://files.pythonhosted.org/packages/d5/7f/9028996ec1dead9c57ed2c6384037e3567c2f514e4ed0c54480d2d3eeb48/executorch-1.6.0-cp312-cp312-manylinux_2_28_aarch64.whl",
27
+ sha256: "ff595d236f4052a196a03a867ca0f53d2e3b003d00ab871433660360e194e78e",
28
+ },
29
+ "arm64-darwin" => {
30
+ url: "https://files.pythonhosted.org/packages/c6/47/1e2120ca1ee178e81471d57255ea0f87b6e04272e32ba20e5ed60ebdb46d/executorch-1.6.0-cp312-cp312-macosx_14_0_arm64.whl",
31
+ sha256: "02c220037b41a0a6074a94499a747400ef1a5075a3f2b4d83911871c7291a341",
32
+ },
33
+ }.freeze
34
+
35
+ # Core runtime + CPU/hardware delegate shared libs bundled in fat gems.
36
+ VENDOR_LIBS = {
37
+ "x86_64-linux" => %w[
38
+ libexecutorch.so
39
+ libexecutorch_threadpool.so
40
+ libexecutorch_kernels_optimized.so
41
+ libexecutorch_kernels_quantized.so
42
+ libexecutorch_backend_xnnpack.so
43
+ libexecutorch_etdump.so
44
+ ],
45
+ "aarch64-linux" => %w[
46
+ libexecutorch.so
47
+ libexecutorch_threadpool.so
48
+ libexecutorch_kernels_optimized.so
49
+ libexecutorch_kernels_quantized.so
50
+ libexecutorch_kernels_torchao.so
51
+ libexecutorch_backend_xnnpack.so
52
+ libexecutorch_etdump.so
53
+ ],
54
+ "arm64-darwin" => %w[
55
+ libexecutorch.dylib
56
+ libexecutorch_threadpool.dylib
57
+ libexecutorch_kernels_optimized.dylib
58
+ libexecutorch_kernels_quantized.dylib
59
+ libexecutorch_kernels_torchao.dylib
60
+ libexecutorch_backend_xnnpack.dylib
61
+ libexecutorch_backend_coreml.dylib
62
+ libexecutorch_backend_mlx.dylib
63
+ libexecutorch_etdump.dylib
64
+ mlx.metallib
65
+ ],
66
+ }.freeze
67
+
68
+ module_function
69
+
70
+ def platform_key(os: RbConfig::CONFIG["target_os"], cpu: RbConfig::CONFIG["target_cpu"])
71
+ norm_cpu = case cpu
72
+ when /x86_64|amd64/i then "x86_64"
73
+ when /aarch64|arm64/i then os =~ /darwin/i ? "arm64" : "aarch64"
74
+ else cpu
75
+ end
76
+ norm_os = case os
77
+ when /darwin/i then "darwin"
78
+ when /linux/i then "linux"
79
+ else os
80
+ end
81
+ "#{norm_cpu}-#{norm_os}"
82
+ end
83
+
84
+ def default_cache_dir(key = platform_key)
85
+ base = ENV["XDG_CACHE_HOME"]
86
+ base = File.join(Dir.home, ".cache") if base.nil? || base.empty?
87
+ File.join(base, "executorch-ruby", "sdk-#{VERSION}-#{key}")
88
+ end
89
+
90
+ def valid_sdk?(dir)
91
+ return false unless dir && File.directory?(dir)
92
+
93
+ File.exist?(File.join(dir, "include", "executorch", "extension", "module", "module.h")) &&
94
+ File.directory?(File.join(dir, "lib"))
95
+ end
96
+
97
+ def ensure_sdk(dest_dir: nil, key: platform_key, io: $stdout)
98
+ dest = dest_dir || default_cache_dir(key)
99
+ return dest if valid_sdk?(dest)
100
+
101
+ entry = MANIFEST[key]
102
+ raise "No prebuilt ExecuTorch #{VERSION} SDK manifest for platform '#{key}'. Set --with-executorch-dir or EXECUTORCH_DIR." unless entry
103
+
104
+ io&.puts "Fetching official ExecuTorch #{VERSION} C++ SDK for #{key}..."
105
+ Dir.mktmpdir("executorch-sdk") do |tmp|
106
+ whl_path = File.join(tmp, "executorch.whl")
107
+ download_with_redirects(entry[:url], whl_path)
108
+ actual_sha = Digest::SHA256.file(whl_path).hexdigest
109
+ unless actual_sha == entry[:sha256]
110
+ raise "SHA-256 mismatch for ExecuTorch SDK (#{key}): expected #{entry[:sha256]}, got #{actual_sha}"
111
+ end
112
+
113
+ stage = File.join(tmp, "stage")
114
+ extract_sdk_from_wheel(whl_path, stage)
115
+ FileUtils.mkdir_p(File.dirname(dest))
116
+ FileUtils.rm_rf(dest)
117
+ FileUtils.mv(stage, dest)
118
+ end
119
+
120
+ raise "Extracted SDK at #{dest} is incomplete" unless valid_sdk?(dest)
121
+
122
+ io&.puts "Installed ExecuTorch #{VERSION} C++ SDK to #{dest}"
123
+ dest
124
+ end
125
+
126
+ def download_with_redirects(url, dest, limit = 5)
127
+ raise "Too many HTTP redirects downloading #{url}" if limit <= 0
128
+
129
+ uri = URI.parse(url)
130
+ Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 30, read_timeout: 120) do |http|
131
+ req = Net::HTTP::Get.new(uri)
132
+ http.request(req) do |res|
133
+ case res
134
+ when Net::HTTPSuccess
135
+ File.open(dest, "wb") { |f| res.read_body { |chunk| f.write(chunk) } }
136
+ when Net::HTTPRedirection
137
+ download_with_redirects(res["location"], dest, limit - 1)
138
+ else
139
+ raise "Failed downloading #{url}: HTTP #{res.code} #{res.message}"
140
+ end
141
+ end
142
+ end
143
+ end
144
+
145
+ # Minimal pure-Ruby ZIP reader (central directory) extracting ONLY
146
+ # executorch/{include,lib,share/cmake}/ from the wheel.
147
+ def extract_sdk_from_wheel(whl_path, dest_dir)
148
+ File.open(whl_path, "rb") do |f|
149
+ size = f.size
150
+ search_len = [size, 65_557].min
151
+ f.seek(size - search_len)
152
+ tail = f.read(search_len)
153
+ eocd_idx = tail.rindex("PK\x05\x06")
154
+ raise "Invalid wheel archive (missing EOCD)" unless eocd_idx
155
+
156
+ _sig, _disk, _cd_disk, _entries_disk, total_entries, cd_size, cd_offset =
157
+ tail.byteslice(eocd_idx, 22).unpack("a4vvvvVV")
158
+
159
+ # Handle ZIP64 if needed
160
+ if total_entries == 0xFFFF || cd_offset == 0xFFFFFFFF
161
+ loc_idx = tail.rindex("PK\x06\x07", eocd_idx)
162
+ raise "ZIP64 locator missing" unless loc_idx
163
+
164
+ zip64_offset = tail.byteslice(loc_idx + 8, 8).unpack1("Q<")
165
+ f.seek(zip64_offset)
166
+ z64 = f.read(56)
167
+ total_entries = z64.byteslice(32, 8).unpack1("Q<")
168
+ cd_size = z64.byteslice(40, 8).unpack1("Q<")
169
+ cd_offset = z64.byteslice(48, 8).unpack1("Q<")
170
+ end
171
+
172
+ f.seek(cd_offset)
173
+ cd = f.read(cd_size)
174
+ pos = 0
175
+
176
+ total_entries.times do
177
+ break if pos + 46 > cd.bytesize
178
+
179
+ sig = cd.byteslice(pos, 4)
180
+ raise "Invalid central directory header" unless sig == "PK\x01\x02"
181
+
182
+ method, _time, _date, _crc, comp_size, uncomp_size, name_len, extra_len, comment_len,
183
+ _disk_start, _int_attr, _ext_attr, local_offset =
184
+ cd.byteslice(pos + 10, 36).unpack("vvvVVVvvvvvVV")
185
+
186
+ name = cd.byteslice(pos + 46, name_len)
187
+ extra = cd.byteslice(pos + 46 + name_len, extra_len)
188
+ pos += 46 + name_len + extra_len + comment_len
189
+
190
+ next unless name.start_with?("executorch/include/", "executorch/lib/", "executorch/share/cmake/")
191
+ next if name.end_with?("/")
192
+
193
+ # Resolve ZIP64 extra fields if 32-bit fields overflowed
194
+ if comp_size == 0xFFFFFFFF || uncomp_size == 0xFFFFFFFF || local_offset == 0xFFFFFFFF
195
+ ep = 0
196
+ while ep + 4 <= extra.bytesize
197
+ eid, esz = extra.byteslice(ep, 4).unpack("vv")
198
+ if eid == 0x0001
199
+ ef = extra.byteslice(ep + 4, esz)
200
+ off = 0
201
+ if uncomp_size == 0xFFFFFFFF
202
+ uncomp_size = ef.byteslice(off, 8).unpack1("Q<")
203
+ off += 8
204
+ end
205
+ if comp_size == 0xFFFFFFFF
206
+ comp_size = ef.byteslice(off, 8).unpack1("Q<")
207
+ off += 8
208
+ end
209
+ if local_offset == 0xFFFFFFFF
210
+ local_offset = ef.byteslice(off, 8).unpack1("Q<")
211
+ end
212
+ break
213
+ end
214
+ ep += 4 + esz
215
+ end
216
+ end
217
+
218
+ rel = name.delete_prefix("executorch/")
219
+ # Prevent path traversal
220
+ raise "Unsafe archive path: #{rel}" if rel.include?("..") || rel.start_with?("/")
221
+
222
+ out_path = File.join(dest_dir, rel)
223
+ FileUtils.mkdir_p(File.dirname(out_path))
224
+
225
+ f.seek(local_offset)
226
+ lh = f.read(30)
227
+ raise "Invalid local file header for #{name}" unless lh&.start_with?("PK\x03\x04")
228
+
229
+ l_name_len, l_extra_len = lh.byteslice(26, 4).unpack("vv")
230
+ f.seek(local_offset + 30 + l_name_len + l_extra_len)
231
+ raw = f.read(comp_size)
232
+
233
+ data = case method
234
+ when 0 then raw
235
+ when 8
236
+ z = Zlib::Inflate.new(-Zlib::MAX_WBITS)
237
+ begin
238
+ z.inflate(raw)
239
+ ensure
240
+ z.close
241
+ end
242
+ else
243
+ raise "Unsupported ZIP compression method #{method} for #{name}"
244
+ end
245
+
246
+ File.binwrite(out_path, data)
247
+ end
248
+ end
249
+ end
250
+ end
251
+ end
@@ -0,0 +1,85 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Executorch
4
+ class Tensor
5
+ class << self
6
+ # Create a tensor filled with ones.
7
+ def ones(shape, dtype: :float32)
8
+ full(shape, 1, dtype: dtype)
9
+ end
10
+
11
+ # Create a tensor filled with a constant scalar value.
12
+ def full(shape, value, dtype: :float32)
13
+ raise TypeError, "shape must be an Array" unless shape.is_a?(Array)
14
+
15
+ numel = shape.empty? ? 1 : shape.reduce(1, :*)
16
+ raise ShapeError, "shape dimensions must be non-negative" if shape.any? { |d| !d.is_a?(Integer) || d < 0 }
17
+
18
+ new(Array.new(numel, value), shape: shape, dtype: dtype)
19
+ end
20
+
21
+ # Build a Tensor from a Numo::NArray (zero-copy byte path).
22
+ def from_numo(narray)
23
+ dtype = NUMO_TO_DTYPE[narray.class.name]
24
+ raise DTypeError, "Unsupported Numo::NArray type: #{narray.class.name}" unless dtype
25
+
26
+ from_bytes(narray.to_binary, shape: narray.shape, dtype: dtype)
27
+ end
28
+
29
+ # Build a Tensor from a Torch::Tensor (torch.rb interop).
30
+ def from_torch(torch_tensor)
31
+ dtype = TORCH_TO_DTYPE[torch_tensor.dtype]
32
+ raise DTypeError, "Unsupported Torch::Tensor dtype: #{torch_tensor.dtype.inspect}" unless dtype
33
+
34
+ new(torch_tensor.contiguous.to_a, shape: torch_tensor.shape, dtype: dtype)
35
+ end
36
+ end
37
+
38
+ NUMO_TO_DTYPE = {
39
+ "Numo::SFloat" => :float32,
40
+ "Numo::DFloat" => :float64,
41
+ "Numo::Int8" => :int8,
42
+ "Numo::Int16" => :int16,
43
+ "Numo::Int32" => :int32,
44
+ "Numo::Int64" => :int64,
45
+ "Numo::UInt8" => :uint8,
46
+ "Numo::UInt16" => :uint16,
47
+ "Numo::UInt32" => :uint32,
48
+ "Numo::UInt64" => :uint64,
49
+ }.freeze
50
+
51
+ TORCH_TO_DTYPE = {
52
+ float32: :float32,
53
+ float64: :float64,
54
+ float16: :float16,
55
+ bfloat16: :bfloat16,
56
+ int8: :int8,
57
+ int16: :int16,
58
+ int32: :int32,
59
+ int64: :int64,
60
+ uint8: :uint8,
61
+ bool: :bool,
62
+ }.freeze
63
+
64
+ def empty?
65
+ numel == 0
66
+ end
67
+
68
+ def to_numo
69
+ raise LoadError, "Numo::NArray is not loaded (require 'numo/narray')" unless defined?(::Numo::NArray)
70
+
71
+ klass_name = NUMO_TO_DTYPE.key(dtype)
72
+ raise DTypeError, "No Numo::NArray equivalent for dtype #{dtype.inspect}" unless klass_name
73
+
74
+ klass = Object.const_get(klass_name)
75
+ klass.from_binary(to_bytes, shape)
76
+ end
77
+
78
+ def inspect
79
+ return "#<Executorch::Tensor (closed)>" if closed?
80
+
81
+ "#<Executorch::Tensor shape=#{shape.inspect} dtype=#{dtype.inspect} nbytes=#{nbytes}>"
82
+ end
83
+ alias to_s inspect
84
+ end
85
+ end
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Executorch
2
- VERSION = "0.1.0"
4
+ VERSION = "1.0.0"
3
5
  end
data/lib/executorch.rb CHANGED
@@ -1,212 +1,16 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require_relative "executorch/version"
4
+ require_relative "executorch/method_meta"
4
5
 
5
- # Load the native extension
6
+ # Load precompiled Ruby-version-specific native extension first (fat gems),
7
+ # falling back to standard single-version native extension path.
6
8
  begin
9
+ ruby_abi = RUBY_VERSION[/\A\d+\.\d+/]
10
+ require_relative "executorch/#{ruby_abi}/executorch"
11
+ rescue LoadError
7
12
  require_relative "executorch/executorch"
8
- rescue LoadError => e
9
- warn "Failed to load ExecuTorch native extension: #{e.message}"
10
- warn "Make sure to run: bundle exec rake compile"
11
- raise
12
13
  end
13
14
 
14
- module Executorch
15
- # Extend Tensor with Ruby-friendly methods
16
- class Tensor
17
- class << self
18
- # Create a new tensor from data
19
- #
20
- # @param data [Array] Array of numeric values (can be nested or flat)
21
- # @param shape [Array<Integer>, nil] Shape of the tensor. If nil, inferred from data structure.
22
- # @param dtype [Symbol] Data type (:float, :double, :int, :long)
23
- # @return [Tensor]
24
- #
25
- # @example Create from nested array (shape inferred)
26
- # Tensor.new([[1.0, 2.0], [3.0, 4.0]]) # shape: [2, 2]
27
- #
28
- # @example Create from flat array with explicit shape
29
- # Tensor.new([1.0, 2.0, 3.0, 4.0], shape: [2, 2])
30
- #
31
- def new(data, shape: nil, dtype: :float)
32
- if shape.nil?
33
- # Infer shape from nested array structure
34
- shape = infer_shape(data)
35
- flat_data = flatten_nested(data, shape)
36
- else
37
- # Use flat data directly (backward compatibility)
38
- flat_data = data
39
- end
40
-
41
- create(flat_data, shape, dtype)
42
- end
43
-
44
- private
45
-
46
- # Infer the shape from a nested array structure
47
- # @param data [Array] Potentially nested array
48
- # @return [Array<Integer>] Inferred shape
49
- def infer_shape(data)
50
- return [0] if data.empty?
51
-
52
- shape = []
53
- current = data
54
-
55
- while current.is_a?(Array)
56
- shape << current.size
57
- break if current.empty?
58
- current = current.first
59
- end
60
-
61
- # Validate that all elements at each level have consistent sizes
62
- validate_shape(data, shape, 0)
63
-
64
- shape
65
- end
66
-
67
- # Validate that the array has consistent shape at all levels
68
- # @param data [Array] The data to validate
69
- # @param expected_shape [Array<Integer>] The expected shape
70
- # @param depth [Integer] Current depth in the array
71
- # @raise [ArgumentError] If the array is jagged or inconsistent
72
- def validate_shape(data, expected_shape, depth)
73
- return if depth >= expected_shape.size
74
- return if expected_shape[depth] == 0
75
-
76
- unless data.is_a?(Array)
77
- raise ArgumentError, "Inconsistent nesting depth at level #{depth}: expected Array, got #{data.class}"
78
- end
79
-
80
- unless data.size == expected_shape[depth]
81
- raise ArgumentError, "Jagged array at depth #{depth}: expected size #{expected_shape[depth]}, got #{data.size}"
82
- end
83
-
84
- data.each_with_index do |element, i|
85
- if depth + 1 < expected_shape.size
86
- # Expect more nesting
87
- unless element.is_a?(Array)
88
- raise ArgumentError, "Inconsistent nesting at depth #{depth}, index #{i}: expected Array, got #{element.class}"
89
- end
90
- validate_shape(element, expected_shape, depth + 1)
91
- else
92
- # At leaf level, should be numeric
93
- if element.is_a?(Array)
94
- raise ArgumentError, "Inconsistent nesting at depth #{depth}, index #{i}: unexpected Array at leaf level"
95
- end
96
- end
97
- end
98
- end
99
-
100
- # Flatten a nested array into a 1D array
101
- # @param data [Array] Potentially nested array
102
- # @param shape [Array<Integer>] The shape (used to handle empty arrays)
103
- # @return [Array] Flat array
104
- def flatten_nested(data, shape)
105
- return [] if shape.include?(0)
106
- deep_flatten(data)
107
- end
108
-
109
- # Recursively flatten an array
110
- # @param data [Array, Numeric] The data to flatten
111
- # @return [Array] Flat array
112
- def deep_flatten(data)
113
- return [data] unless data.is_a?(Array)
114
- data.flat_map { |element| deep_flatten(element) }
115
- end
116
- end
117
-
118
- # Convert tensor to a nested Ruby array matching the tensor's shape
119
- # @return [Array] Nested array with structure matching shape
120
- #
121
- # @example
122
- # tensor = Tensor.new([1, 2, 3, 4], shape: [2, 2])
123
- # tensor.to_a # => [[1.0, 2.0], [3.0, 4.0]]
124
- #
125
- def to_a
126
- flat = flat_to_a
127
- reshape_flat_to_nested(flat, shape)
128
- end
129
-
130
- # Convert tensor to a flat Ruby array (original behavior)
131
- # @return [Array] Flat array of all values
132
- alias_method :flat_to_a, :_original_to_a
133
-
134
- private
135
-
136
- # Reshape a flat array into nested arrays according to shape
137
- # @param flat [Array] Flat array of values
138
- # @param shape [Array<Integer>] Target shape
139
- # @return [Array] Nested array
140
- def reshape_flat_to_nested(flat, shape)
141
- return flat if shape.size <= 1
142
-
143
- # Handle empty dimensions
144
- if shape.include?(0)
145
- return build_empty_nested(shape)
146
- end
147
-
148
- # Calculate strides for each dimension
149
- build_nested(flat, shape, 0, 0).first
150
- end
151
-
152
- # Build nested array structure
153
- # @param flat [Array] Flat data
154
- # @param shape [Array<Integer>] Shape
155
- # @param dim [Integer] Current dimension
156
- # @param offset [Integer] Current offset in flat array
157
- # @return [Array] [nested_result, new_offset]
158
- def build_nested(flat, shape, dim, offset)
159
- if dim == shape.size - 1
160
- # Last dimension: slice the flat array
161
- result = flat[offset, shape[dim]]
162
- [result, offset + shape[dim]]
163
- else
164
- # Build sub-arrays
165
- result = []
166
- current_offset = offset
167
- shape[dim].times do
168
- sub_result, current_offset = build_nested(flat, shape, dim + 1, current_offset)
169
- result << sub_result
170
- end
171
- [result, current_offset]
172
- end
173
- end
174
-
175
- # Build empty nested structure for shapes with zero dimensions
176
- # @param shape [Array<Integer>] Shape with at least one zero
177
- # @return [Array] Empty nested structure
178
- def build_empty_nested(shape)
179
- return [] if shape.size == 1
180
-
181
- first_zero = shape.index(0)
182
-
183
- if first_zero == 0
184
- []
185
- else
186
- # Build arrays up to the zero dimension
187
- build_empty_recursive(shape, 0)
188
- end
189
- end
190
-
191
- # Recursively build empty nested arrays
192
- # @param shape [Array<Integer>] Shape
193
- # @param dim [Integer] Current dimension
194
- # @return [Array] Empty nested structure
195
- def build_empty_recursive(shape, dim)
196
- return [] if dim >= shape.size || shape[dim] == 0
197
-
198
- Array.new(shape[dim]) { build_empty_recursive(shape, dim + 1) }
199
- end
200
- end
201
-
202
- # Extend Model with Ruby-friendly methods
203
- class Model
204
- # Alias predict to forward for more intuitive API
205
- alias_method :predict, :forward
206
-
207
- # Make model callable
208
- def call(inputs)
209
- forward(inputs)
210
- end
211
- end
212
- end
15
+ require_relative "executorch/tensor"
16
+ require_relative "executorch/module"