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.



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

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.



155
156
157
 
# File 'lib/cohere/transcribe/asr/native.rb', line 155

def path
  @path
end

Class Method Details

.available? ⇒ Boolean

Returns:

  • (Boolean) 


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

def available?
  load
  true
rescue TranscriptionRuntimeError
  false
end

.candidate_paths ⇒ Object 



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

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 



93
94
95
96
 
# File 'lib/cohere/transcribe/asr/native.rb', line 93

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

Instance Method Details

#call(name) ⇒ Object 



181
182
183
 
# File 'lib/cohere/transcribe/asr/native.rb', line 181

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

#function?(name) ⇒ Boolean

Returns:

  • (Boolean) 


185
186
187
 
# File 'lib/cohere/transcribe/asr/native.rb', line 185

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

#null_pointer?(pointer) ⇒ Boolean

Returns:

  • (Boolean) 


251
252
253
 
# File 'lib/cohere/transcribe/asr/native.rb', line 251

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

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

Raises:



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
219
220
 
# File 'lib/cohere/transcribe/asr/native.rb', line 189

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 



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

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 



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

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) 


240
241
242
 
# File 'lib/cohere/transcribe/asr/native.rb', line 240

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