red-candle 1.8.0.pre3-aarch64-linux

data/lib/candle/tokenizer.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Candle
+  # Tokenizer class for text tokenization
+  #
+  # This class provides methods to encode text into tokens and decode tokens back to text.
+  # It supports both single text and batch processing, with options for special tokens,
+  # padding, and truncation.
+  #
+  # @example Create a tokenizer from a pretrained model
+  #   tokenizer = Candle::Tokenizer.from_pretrained("bert-base-uncased")
+  #
+  # @example Encode and decode text
+  #   tokens = tokenizer.encode("Hello, world!")
+  #   text = tokenizer.decode(tokens)
+  #
+  # @example Batch encoding
+  #   texts = ["Hello", "World", "Test"]
+  #   batch_tokens = tokenizer.encode_batch(texts)
+  #
+  # @example Configure padding and truncation
+  #   padded_tokenizer = tokenizer.with_padding(length: 128)
+  #   truncated_tokenizer = tokenizer.with_truncation(512)
+  class Tokenizer
+    # These methods are implemented in Rust
+    # - from_file(path) - Load tokenizer from a JSON file
+    # - from_pretrained(model_id) - Load tokenizer from HuggingFace
+    # - encode(text, add_special_tokens = true) - Encode text to token IDs
+    # - encode_to_tokens(text, add_special_tokens = true) - Encode text to token strings
+    # - encode_with_tokens(text, add_special_tokens = true) - Get both IDs and tokens
+    # - encode_batch(texts, add_special_tokens = true) - Encode multiple texts to IDs
+    # - encode_batch_to_tokens(texts, add_special_tokens = true) - Encode multiple texts to tokens
+    # - decode(token_ids, skip_special_tokens = true) - Decode token IDs to text
+    # - id_to_token(token_id) - Get token string for a token ID
+    # - get_vocab(with_added_tokens = true) - Get vocabulary as hash
+    # - vocab_size(with_added_tokens = true) - Get vocabulary size
+    # - with_padding(options) - Create tokenizer with padding enabled
+    # - with_truncation(max_length) - Create tokenizer with truncation enabled
+    # - get_special_tokens - Get special tokens info
+    # - inspect - String representation
+    # - to_s - String representation
+
+    # The native methods accept positional arguments, but we provide keyword argument interfaces
+    # for better Ruby ergonomics. We need to call the native methods with positional args.
+    
+    alias_method :_native_encode, :encode
+    alias_method :_native_encode_to_tokens, :encode_to_tokens
+    alias_method :_native_encode_with_tokens, :encode_with_tokens
+    alias_method :_native_encode_batch, :encode_batch
+    alias_method :_native_encode_batch_to_tokens, :encode_batch_to_tokens
+    alias_method :_native_decode, :decode
+    alias_method :_native_get_vocab, :get_vocab
+    alias_method :_native_vocab_size, :vocab_size
+    alias_method :_native_with_padding, :with_padding
+
+    # Encode text with convenient keyword arguments
+    #
+    # @param text [String] The text to encode
+    # @param add_special_tokens [Boolean] Whether to add special tokens (default: true)
+    # @return [Array<Integer>] Token IDs
+    def encode(text, add_special_tokens: true)
+      _native_encode(text, add_special_tokens)
+    end
+
+    # Encode text into token strings (words/subwords)
+    #
+    # @param text [String] The text to encode
+    # @param add_special_tokens [Boolean] Whether to add special tokens (default: true)
+    # @return [Array<String>] Token strings
+    def encode_to_tokens(text, add_special_tokens: true)
+      _native_encode_to_tokens(text, add_special_tokens)
+    end
+
+    # Encode text and return both IDs and token strings
+    #
+    # @param text [String] The text to encode
+    # @param add_special_tokens [Boolean] Whether to add special tokens (default: true)
+    # @return [Hash] Hash with :ids and :tokens arrays
+    def encode_with_tokens(text, add_special_tokens: true)
+      _native_encode_with_tokens(text, add_special_tokens)
+    end
+
+    # Encode multiple texts with convenient keyword arguments
+    #
+    # @param texts [Array<String>] The texts to encode
+    # @param add_special_tokens [Boolean] Whether to add special tokens (default: true)
+    # @return [Array<Array<Integer>>] Arrays of token IDs
+    def encode_batch(texts, add_special_tokens: true)
+      _native_encode_batch(texts, add_special_tokens)
+    end
+
+    # Encode multiple texts into token strings
+    #
+    # @param texts [Array<String>] The texts to encode
+    # @param add_special_tokens [Boolean] Whether to add special tokens (default: true)
+    # @return [Array<Array<String>>] Arrays of token strings
+    def encode_batch_to_tokens(texts, add_special_tokens: true)
+      _native_encode_batch_to_tokens(texts, add_special_tokens)
+    end
+
+    # Decode token IDs with convenient keyword arguments
+    #
+    # @param token_ids [Array<Integer>] The token IDs to decode
+    # @param skip_special_tokens [Boolean] Whether to skip special tokens (default: true)
+    # @return [String] Decoded text
+    def decode(token_ids, skip_special_tokens: true)
+      _native_decode(token_ids, skip_special_tokens)
+    end
+
+    # Get vocabulary with convenient keyword arguments
+    #
+    # @param with_added_tokens [Boolean] Include added tokens (default: true)
+    # @return [Hash<String, Integer>] Token to ID mapping
+    def get_vocab(with_added_tokens: true)
+      _native_get_vocab(with_added_tokens)
+    end
+
+    # Get vocabulary size with convenient keyword arguments
+    #
+    # @param with_added_tokens [Boolean] Include added tokens (default: true)
+    # @return [Integer] Vocabulary size
+    def vocab_size(with_added_tokens: true)
+      _native_vocab_size(with_added_tokens)
+    end
+
+    # Create a new tokenizer with padding configuration
+    #
+    # @param options [Hash] Padding options
+    # @option options [Integer] :length Fixed length padding
+    # @option options [Boolean] :max_length Use batch longest padding
+    # @option options [String] :direction Padding direction ("left" or "right")
+    # @option options [Integer] :pad_id Padding token ID
+    # @option options [String] :pad_token Padding token string
+    # @return [Tokenizer] New tokenizer instance with padding enabled
+    def with_padding(**options)
+      _native_with_padding(options)
+    end
+  end
+end

data/lib/candle/tool.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Candle
+  class Tool
+    attr_reader :name, :description, :parameters
+
+    def initialize(name:, description:, parameters: {}, &block)
+      @name = name
+      @description = description
+      @parameters = parameters
+      @callable = block
+    end
+
+    def call(arguments)
+      @callable.call(arguments)
+    end
+
+    def to_tool_definition
+      {
+        "type" => "function",
+        "function" => {
+          "name" => @name,
+          "description" => @description,
+          "parameters" => @parameters
+        }
+      }
+    end
+  end
+
+  ToolCall = Struct.new(:name, :arguments, keyword_init: true)
+
+  ToolCallResult = Struct.new(
+    :tool_calls,
+    :tool_results,
+    :text_response,
+    :raw_response,
+    keyword_init: true
+  ) do
+    def has_tool_calls?
+      tool_calls && !tool_calls.empty?
+    end
+
+    def success?
+      tool_results.all? { |r| r[:error].nil? }
+    end
+  end
+end

data/lib/candle/tool_call_parser.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Candle
+  class ToolCallParser
+    DEFAULT_PATTERN = /<tool_call>\s*(.*?)\s*<\/tool_call>/m
+
+    attr_reader :pattern
+
+    def initialize(pattern: DEFAULT_PATTERN)
+      @pattern = pattern
+    end
+
+    ParseResult = Struct.new(:text_response, :tool_calls, keyword_init: true) do
+      def has_tool_calls?
+        tool_calls && !tool_calls.empty?
+      end
+    end
+
+    def parse(text, available_tools: [])
+      tool_calls = []
+
+      text.scan(@pattern) do |match|
+        json_str = match[0].strip
+        begin
+          parsed = JSON.parse(json_str)
+          name = parsed["name"]
+          arguments = parsed["arguments"] || parsed["parameters"] || {}
+
+          next unless name
+          if available_tools.empty? || available_tools.any? { |t| t.name == name }
+            tool_calls << ToolCall.new(name: name, arguments: arguments)
+          end
+        rescue JSON::ParserError
+          # Skip malformed tool calls
+        end
+      end
+
+      # Deduplicate identical tool calls (models sometimes repeat the same call)
+      tool_calls.uniq! { |tc| [tc.name, tc.arguments] }
+
+      remaining_text = text.gsub(@pattern, "").strip
+      remaining_text = nil if remaining_text.empty?
+
+      ParseResult.new(
+        text_response: remaining_text,
+        tool_calls: tool_calls
+      )
+    end
+
+    # Convenience class method using the default pattern
+    def self.parse(text, available_tools: [])
+      new.parse(text, available_tools: available_tools)
+    end
+  end
+end

data/lib/candle/version.rb

@@ -0,0 +1,5 @@
+# :nocov:
+module Candle
+  VERSION = "1.8.0.pre3"
+end
+# :nocov:

data/lib/candle/vlm.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Candle
+  class VLM
+    class << self
+      def from_pretrained(model_id, device: nil, **options)
+        device_obj = case device
+                     when "cpu" then Candle::Device.cpu
+                     when "metal" then Candle::Device.metal
+                     when "cuda" then Candle::Device.cuda
+                     when Candle::Device then device
+                     when nil then nil
+                     else Candle::Device.best
+                     end
+        _create(model_id, device_obj)
+      end
+    end
+
+    def describe(image_path, max_length: 256)
+      _describe(image_path, max_length)
+    end
+
+    def ask(image_path, question, max_length: 256)
+      _ask(image_path, question, max_length)
+    end
+
+    def inspect
+      "#<Candle::VLM model_id=#{model_id.inspect} device=#{device}>"
+    end
+  end
+end

data/lib/candle.rb

@@ -0,0 +1,29 @@
+require_relative "candle/logger"
+
+# Load the compiled Rust extension. Precompiled (platform) gems install it into a
+# Ruby-ABI-versioned subdir (lib/candle/<major.minor>/candle.{so,bundle}) so a single
+# fat gem can carry a binary per Ruby version; source/dev builds place it flat at
+# lib/candle/candle.{so,bundle}. Try the versioned path first, fall back to the flat
+# one. Resolution goes through $LOAD_PATH (`require`, never `require_relative`) because
+# RubyGems installs native extensions outside the gem's lib/ dir — see
+# spec/require_spec.rb and Issue #75.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "candle/#{Regexp.last_match(1)}/candle"
+rescue LoadError
+  require "candle/candle"
+end
+
+require_relative "candle/tensor"
+require_relative "candle/device_utils"
+require_relative "candle/embedding_model_type"
+require_relative "candle/embedding_model"
+require_relative "candle/reranker"
+require_relative "candle/tool"
+require_relative "candle/tool_call_parser"
+require_relative "candle/llm"
+require_relative "candle/agent"
+require_relative "candle/tokenizer"
+require_relative "candle/ner"
+require_relative "candle/vlm"
+require_relative "candle/build_info"

data/lib/red-candle.rb

@@ -0,0 +1 @@
+require 'candle'

metadata

@@ -0,0 +1,309 @@
+--- !ruby/object:Gem::Specification
+name: red-candle
+version: !ruby/object:Gem::Version
+  version: 1.8.0.pre3
+platform: aarch64-linux
+authors:
+- Christopher Petersen
+- kojix2
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-rustdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: informers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby gem for running state-of-the-art language models locally. Access
+  LLMs, embeddings, rerankers, and NER models directly from Ruby using Rust-powered
+  Candle with Metal/CUDA acceleration.
+email:
+- chris@petersen.io
+- 2xijok@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- ext/candle/Cargo.toml
+- ext/candle/build.rs
+- ext/candle/extconf.rb
+- ext/candle/rustfmt.toml
+- ext/candle/src/gvl.rs
+- ext/candle/src/lib.rs
+- ext/candle/src/llm/constrained_generation_test.rs
+- ext/candle/src/llm/gemma.rs
+- ext/candle/src/llm/generation_config.rs
+- ext/candle/src/llm/glm4.rs
+- ext/candle/src/llm/granite.rs
+- ext/candle/src/llm/granitemoehybrid.rs
+- ext/candle/src/llm/llama.rs
+- ext/candle/src/llm/mistral.rs
+- ext/candle/src/llm/mod.rs
+- ext/candle/src/llm/phi.rs
+- ext/candle/src/llm/quantized_gguf.rs
+- ext/candle/src/llm/qwen.rs
+- ext/candle/src/llm/qwen3.rs
+- ext/candle/src/llm/text_generation.rs
+- ext/candle/src/ruby/device.rs
+- ext/candle/src/ruby/dtype.rs
+- ext/candle/src/ruby/embedding_model.rs
+- ext/candle/src/ruby/errors.rs
+- ext/candle/src/ruby/llm.rs
+- ext/candle/src/ruby/mod.rs
+- ext/candle/src/ruby/ner.rs
+- ext/candle/src/ruby/reranker.rs
+- ext/candle/src/ruby/result.rs
+- ext/candle/src/ruby/structured.rs
+- ext/candle/src/ruby/tensor.rs
+- ext/candle/src/ruby/tokenizer.rs
+- ext/candle/src/ruby/utils.rs
+- ext/candle/src/ruby/vlm.rs
+- ext/candle/src/structured/integration_test.rs
+- ext/candle/src/structured/mod.rs
+- ext/candle/src/structured/schema_processor.rs
+- ext/candle/src/structured/vocabulary_adapter.rs
+- ext/candle/src/structured/vocabulary_adapter_real_test.rs
+- ext/candle/src/structured/vocabulary_adapter_simple_test.rs
+- ext/candle/src/tokenizer/loader.rs
+- ext/candle/src/tokenizer/mod.rs
+- ext/candle/tests/device_tests.rs
+- ext/candle/tests/tensor_tests.rs
+- lib/candle.rb
+- lib/candle/3.1/candle.so
+- lib/candle/3.2/candle.so
+- lib/candle/3.3/candle.so
+- lib/candle/3.4/candle.so
+- lib/candle/4.0/candle.so
+- lib/candle/agent.rb
+- lib/candle/build_info.rb
+- lib/candle/device_utils.rb
+- lib/candle/embedding_model.rb
+- lib/candle/embedding_model_type.rb
+- lib/candle/llm.rb
+- lib/candle/logger.rb
+- lib/candle/ner.rb
+- lib/candle/reranker.rb
+- lib/candle/tensor.rb
+- lib/candle/tokenizer.rb
+- lib/candle/tool.rb
+- lib/candle/tool_call_parser.rb
+- lib/candle/version.rb
+- lib/candle/vlm.rb
+- lib/red-candle.rb
+homepage: https://github.com/scientist-labs/red-candle
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+requirements:
+- Rust >= 1.85
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby gem for running state-of-the-art language models locally. Access LLMs,
+  embeddings, rerankers, and NER models directly from Ruby using Rust-powered Candle
+  with Metal/CUDA acceleration.
+test_files: []