Class: Cohere::Transcribe::ASR::NativeLibrary

Inherits:
Object
  • Object
show all
Defined in:
lib/cohere/transcribe/asr/native.rb

Overview

Thin, process-local binding to CrispASR's stable C session ABI. The extension owns model execution; no Python process or Python runtime is involved. Loading remains lazy so configuration and CLI help stay light.

Constant Summary collapse

OPEN_PARAM_VERSION = 
2
OPEN_PARAM_INTEGER_COUNT = 
12
NATIVE_ERROR_NAMES = 
{
  0 => "none",
  1 => "invalid_argument",
  2 => "out_of_memory",
  3 => "invariant",
  4 => "runtime",
  5 => "cancelled"
}.freeze
FUNCTIONS = 
{
  last_error_kind: [[], :int],
  last_error_message: [[], :voidp],
  runtime_resolve_device: [[:voidp], :voidp],
  runtime_supports_bf16: [[:voidp], :int],
  set_gpu_backend: [[:voidp], :void],
  session_open_with_params: [%i[voidp voidp voidp], :voidp],
  session_backend: [[:voidp], :voidp],
  session_compute_backend: [[:voidp], :voidp],
  session_memory: [%i[voidp voidp voidp], :int],
  session_batch_capacity: [[:voidp], :int],
  session_cancel: [[:voidp], :int],
  session_transcribe_lang: [%i[voidp voidp int voidp], :voidp],
  session_transcribe_batch_lang: [%i[voidp voidp voidp int voidp], :voidp],
  session_batch_result_count: [[:voidp], :int],
  session_batch_result_at: [%i[voidp int], :voidp],
  session_batch_result_free: [[:voidp], :void],
  session_result_n_segments: [[:voidp], :int],
  session_result_segment_text: [%i[voidp int], :voidp],
  session_result_segment_t0: [%i[voidp int], :int64],
  session_result_segment_t1: [%i[voidp int], :int64],
  session_result_n_words: [%i[voidp int], :int],
  session_result_word_text: [%i[voidp int int], :voidp],
  session_result_word_t0: [%i[voidp int int], :int64],
  session_result_word_t1: [%i[voidp int int], :int64],
  session_result_word_p: [%i[voidp int int], :float],
  session_result_generated_tokens: [[:voidp], :int],
  session_result_generation_limit: [[:voidp], :int],
  session_result_generation_capacity: [[:voidp], :int],
  session_result_stopped_by_max_tokens: [[:voidp], :int],
  session_result_repetition_stopped: [[:voidp], :int],
  session_result_free: [[:voidp], :void],
  session_close: [[:voidp], :void],
  session_set_max_new_tokens: [%i[voidp int], :int],
  session_set_beam_size: [%i[voidp int], :int],
  session_set_repetition_loop_guard: [%i[voidp int], :int]
}.freeze
OPTIONAL_FUNCTIONS = 
{
  session_batch_result_stats_v1: [%i[voidp voidp int], :int]
}.freeze
TYPE_MAP = 
{
  void: Fiddle::TYPE_VOID,
  voidp: Fiddle::TYPE_VOIDP,
  int: Fiddle::TYPE_INT,
  int64: Fiddle::TYPE_LONG_LONG,
  float: Fiddle::TYPE_FLOAT
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path) ⇒ NativeLibrary

Returns a new instance of NativeLibrary.



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/cohere/transcribe/asr/native.rb', line 155

def initialize(path)
  @path = path
  preload_sibling_libraries(path) if File.absolute_path(path) == path && File.file?(path)
  flags = Fiddle::RTLD_NOW | Fiddle::RTLD_GLOBAL
  @handle = Fiddle::Handle.new(path, flags)
  @functions = FUNCTIONS.to_h do |name, (arguments, result)|
    symbol = "crispasr_#{name}"
    address = @handle[symbol]
    [name, Fiddle::Function.new(address, arguments.map { |type| TYPE_MAP.fetch(type) }, TYPE_MAP.fetch(result))]
  end
  OPTIONAL_FUNCTIONS.each do |name, (arguments, result)|
    symbol = "crispasr_#{name}"
    address = @handle[symbol]
    @functions[name] = Fiddle::Function.new(
      address,
      arguments.map { |type| TYPE_MAP.fetch(type) },
      TYPE_MAP.fetch(result)
    )
  rescue Fiddle::DLError
    next
  end
  @functions.freeze
end

Instance Attribute Details

#path ⇒ Object (readonly)

Returns the value of attribute path.



153
154
155
 
# File 'lib/cohere/transcribe/asr/native.rb', line 153

def path
  @path
end

Class Method Details

.available? ⇒ Boolean

Returns:

  • (Boolean) 


96
97
98
99
100
101
 
# File 'lib/cohere/transcribe/asr/native.rb', line 96

def available?
  load
  true
rescue TranscriptionRuntimeError
  false
end

.candidate_paths ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/cohere/transcribe/asr/native.rb', line 103

def candidate_paths
  explicit = ENV.fetch("COHERE_TRANSCRIBE_NATIVE_LIBRARY", nil)
  return [explicit] if explicit && !explicit.empty?

  root = File.expand_path("../../../..", __dir__)
  packaged = File.join(root, "lib", "cohere", "transcribe", "native")
  patterns = case RbConfig::CONFIG["host_os"]
             when /darwin/
               ["libcrispasr*.dylib"]
             when /mswin|mingw|cygwin/
               ["crispasr*.dll", "libcrispasr*.dll"]
             else
               ["libcrispasr.so", "libcrispasr.so.*"]
             end

  paths = [packaged].flat_map do |directory|
    patterns.flat_map { |pattern| Dir.glob(File.join(directory, pattern)) }.sort
  end
  paths.concat(system_library_names)
  paths.uniq
end

.load ⇒ Object 



91
92
93
94
 
# File 'lib/cohere/transcribe/asr/native.rb', line 91

def load
  @mutex ||= Mutex.new
  @mutex.synchronize { @instance ||= load_uncached }
end

Instance Method Details

#call(name) ⇒ Object 



179
180
181
 
# File 'lib/cohere/transcribe/asr/native.rb', line 179

def call(name, *)
  @functions.fetch(name).call(*)
end

#function?(name) ⇒ Boolean

Returns:

  • (Boolean) 


183
184
185
 
# File 'lib/cohere/transcribe/asr/native.rb', line 183

def function?(name)
  @functions.key?(name)
end

#null_pointer?(pointer) ⇒ Boolean

Returns:

  • (Boolean) 


249
250
251
 
# File 'lib/cohere/transcribe/asr/native.rb', line 249

def null_pointer?(pointer)
  pointer.nil? || pointer == 0 || (pointer.respond_to?(:null?) && pointer.null?)
end

#open_session(model_path:, device:, threads:) ⇒ Object

Raises:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/cohere/transcribe/asr/native.rb', line 187

def open_session(model_path:, device:, threads:)
  gpu_backend = case device
                when "cuda" then "cuda"
                when "mps" then "metal"
                else ""
                end
  call(:set_gpu_backend, c_string(gpu_backend))

  use_gpu = device == "cpu" ? 0 : 1
  values = [OPEN_PARAM_VERSION, threads, use_gpu, 0, 1, -1] + Array.new(6, 0)
  unless values.length == OPEN_PARAM_INTEGER_COUNT
    raise TranscriptionRuntimeError, "Native open-parameter ABI is internally inconsistent"
  end

  packed = values.pack("i!*")
  pointer = call(
    :session_open_with_params,
    c_string(model_path.to_s),
    c_string("cohere"),
    Fiddle::Pointer[packed]
  )
  return pointer unless null_pointer?(pointer)

  native_kind = Integer(call(:last_error_kind))
  native_name = NATIVE_ERROR_NAMES.fetch(native_kind, "unknown")
  native_message = string(call(:last_error_message)).strip
  diagnostic = "native #{native_name} error (#{native_kind})"
  diagnostic = "#{diagnostic}: #{native_message}" unless native_message.empty?
  message = "Unable to load Dense Cohere model #{model_path.inspect} " \
            "on device #{device.inspect}: #{diagnostic}"
  raise TranscriptionRuntimeError, message
end

#resolve_device(requested) ⇒ Object 



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/cohere/transcribe/asr/native.rb', line 220

def resolve_device(requested)
  value = requested.to_s
  pointer = call(:runtime_resolve_device, c_string(value))
  resolved = string(pointer)
  return resolved.freeze unless resolved.empty?

  case value
  when "cuda"
    raise TranscriptionRuntimeError,
          "--device cuda was requested, but CUDA is not available to the native runtime"
  when "mps"
    raise TranscriptionRuntimeError,
          "--device mps was requested, but Metal is not available to the native runtime"
  else
    raise TranscriptionRuntimeError, "Unsupported native inference device: #{value.inspect}"
  end
end

#string(pointer) ⇒ Object 



242
243
244
245
246
247
 
# File 'lib/cohere/transcribe/asr/native.rb', line 242

def string(pointer)
  return "" if null_pointer?(pointer)

  value = pointer.is_a?(Fiddle::Pointer) ? pointer.to_s : Fiddle::Pointer.new(pointer).to_s
  value.force_encoding(Encoding::UTF_8).scrub
end

#supports_bf16?(device) ⇒ Boolean

Returns:

  • (Boolean) 


238
239
240
 
# File 'lib/cohere/transcribe/asr/native.rb', line 238

def supports_bf16?(device)
  call(:runtime_supports_bf16, c_string(device.to_s)) == 1
end