gliner 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: edbbf72af6499d1823db172793f3dc183f90e445d4ae45587dc1a0cd4005c15e
+  data.tar.gz: 04d0881c074e9e84617591768c1b53767d2f509bbb7497c6bc0920bf3bac96b3
+SHA512:
+  metadata.gz: 0ea1480d83e383534c50d14320f5cbfcc7c7a890101f9e0492cbd486dc36e05fbebaedaeea31ccf4f8b5efb3f553349cee1b25ad890457734443054d7e1dfb91
+  data.tar.gz: da1f798fd89bcaad28a41e67ec2f07e779e8a7d2681ac3d4790f2e27b2adfcfcc02f5c42e7b02c8eb7bc519fea4178f16bad6050576543dde241e8becd18dbec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elcuervo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# Gliner
+
+![](https://images.unsplash.com/photo-1625768376503-68d2495d78c5?q=80&w=2225&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D)
+
+Minimal Ruby inference wrapper for the **GLiNER2** ONNX model using:
+
+## Install
+
+```ruby
+gem "gliner"
+```
+
+## Usage
+### entities
+
+```ruby
+require "gliner"
+
+Gliner.load("path/to/gliner2-multi-v1")
+
+text = "Apple CEO Tim Cook announced iPhone 15 in Cupertino yesterday."
+labels = ["company", "person", "product", "location"]
+
+model = Gliner[labels]
+pp model[text]
+```
+
+Expected shape:
+
+```ruby
+{"entities"=>{"company"=>["Apple"], "person"=>["Tim Cook"], "product"=>["iPhone 15"], "location"=>["Cupertino"]}}
+```
+
+You can also pass per-entity configs:
+
+```ruby
+labels = {
+  "email" => { "description" => "Email addresses", "dtype" => "list", "threshold" => 0.9 },
+  "person" => { "description" => "Person names", "dtype" => "str" }
+}
+
+model = Gliner[labels]
+pp model["Email John Doe at john@example.com.", threshold: 0.5]
+```
+
+### classification
+
+```ruby
+model = Gliner.classify[
+  { "sentiment" => %w[positive negative neutral] }
+]
+
+result = model["This laptop has amazing performance but terrible battery life!"]
+
+pp result
+```
+
+Expected shape:
+
+```ruby
+{"sentiment"=>"negative"}
+```
+
+### structured extraction
+
+```ruby
+text = "iPhone 15 Pro Max with 256GB storage, A17 Pro chip, priced at $1199."
+
+structure = {
+  "product" => [
+    "name::str::Full product name and model",
+    "storage::str::Storage capacity",
+    "processor::str::Chip or processor information",
+    "price::str::Product price with currency"
+  ]
+}
+
+result = Gliner[structure][text]
+
+pp result
+```
+
+Expected shape:
+
+```ruby
+{"product"=>[{"name"=>"iPhone 15 Pro Max", "storage"=>"256GB", "processor"=>"A17 Pro chip", "price"=>"$1199"}]}
+```
+
+Choices can be included in field specs:
+
+```ruby
+result = Gliner[{ "order" => ["status::[pending|processing|shipped]::str"] }]["Status: shipped"]
+```
+
+## Model files
+
+This implementation expects a directory containing:
+
+- `tokenizer.json`
+- `model.onnx` or `model_int8.onnx`
+- (optional) `config.json` with `max_width` and `max_seq_len`
+
+One publicly available ONNX export is `cuerbot/gliner2-multi-v1` on Hugging Face.
+
+## Integration test
+
+Downloads a public ONNX export and runs a real inference:
+
+```bash
+rake test:integration
+```
+
+To download the model separately (for console testing, etc):
+
+```bash
+rake model:pull
+```
+
+To reuse an existing local download:
+
+```bash
+GLINER_MODEL_DIR=/path/to/model_dir rake test:integration
+```
+
+## Console
+
+Start an IRB session with the gem loaded:
+
+```bash
+rake console MODEL_DIR=/path/to/model_dir
+```
+
+If you omit `MODEL_DIR`, the console auto-downloads a public test model (configurable):
+
+```bash
+rake console
+# or:
+GLINER_REPO_ID=cuerbot/gliner2-multi-v1 GLINER_MODEL_FILE=model_int8.onnx rake console
+```
+
+Or:
+
+```bash
+ruby -Ilib bin/console /path/to/model_dir
+```

data/bin/console

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+end
+
+require "gliner"
+require "fileutils"
+require "httpx"
+require "irb"
+
+DEFAULT_REPO_ID = "cuerbot/gliner2-multi-v1"
+DEFAULT_MODEL_FILE = "model_int8.onnx"
+
+def ensure_model_dir!(repo_id:, model_file:)
+  dir = File.expand_path("../tmp/models/#{repo_id.tr('/', '__')}", __dir__)
+  FileUtils.mkdir_p(dir)
+
+  base = "https://huggingface.co/#{repo_id}/resolve/main"
+  files = ["tokenizer.json", "config.json", model_file]
+
+  files.each do |file|
+    dest = File.join(dir, file)
+    next if File.exist?(dest) && File.size?(dest)
+    download("#{base}/#{file}", dest)
+  end
+
+  dir
+end
+
+def download(url, dest)
+  response = HTTPX.get(url)
+  raise "Download failed: #{url} (status: #{response.status})" unless response.status.between?(200, 299)
+
+  File.binwrite(dest, response.body.to_s)
+end
+
+model_dir = ARGV[0] || ENV["GLINER_MODEL_DIR"]
+repo_id = ENV["GLINER_REPO_ID"] || DEFAULT_REPO_ID
+model_file = ENV["GLINER_MODEL_FILE"] || DEFAULT_MODEL_FILE
+
+if model_dir && !model_dir.empty?
+  $gliner_model = Gliner.load(model_dir, file: model_file)
+else
+  begin
+    require "fileutils"
+    model_dir = ensure_model_dir!(repo_id: repo_id, model_file: model_file)
+    $gliner_model = Gliner.load(model_dir, file: model_file)
+  rescue => e
+    warn "No model loaded (auto-download failed: #{e.class}: #{e.message})"
+    warn "Set GLINER_MODEL_DIR to a local model dir, or set GLINER_REPO_ID/GLINER_MODEL_FILE for auto-download."
+  end
+end
+
+def gliner_extract(text, labels, **opts)
+  raise "No model loaded (set GLINER_MODEL_DIR or pass a directory arg)" unless $gliner_model
+  Gliner[labels][text, **opts]
+end
+
+def gliner_classify(text, tasks, **opts)
+  raise "No model loaded (set GLINER_MODEL_DIR or pass a directory arg)" unless $gliner_model
+  Gliner.classify[tasks][text, **opts]
+end
+
+def gliner_extract_json(text, structures, **opts)
+  raise "No model loaded (set GLINER_MODEL_DIR or pass a directory arg)" unless $gliner_model
+  Gliner[structures][text, **opts]
+end
+
+puts "Gliner console"
+puts "- model: #{$gliner_model ? "loaded" : "not loaded"}"
+puts "- helper: gliner_extract(text, labels, threshold: 0.5)"
+puts "- helper: gliner_classify(text, tasks)"
+puts "- helper: gliner_extract_json(text, structures)"
+puts "- model variable: $gliner_model"
+puts "- model dir: #{model_dir.inspect}"
+puts "- auto-download env: GLINER_REPO_ID=#{repo_id.inspect} GLINER_MODEL_FILE=#{model_file.inspect}" unless $gliner_model
+
+IRB.start(__FILE__)

data/gliner.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'lib/gliner/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'gliner'
+  spec.version = Gliner::VERSION
+  spec.authors = ['elcuervo']
+
+  spec.summary = 'Schema-based information extraction (GLiNER2) via ONNX Runtime'
+  spec.description = 'Basic Ruby inference wrapper for the GLiNER2 ONNX model.'
+  spec.homepage = 'https://github.com/elcuervo/gliner'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.files = Dir.glob('lib/**/*') + Dir.glob('bin/*') + %w[README.md LICENSE gliner.gemspec]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'onnxruntime', '~> 0.10'
+  spec.add_dependency 'tokenizers', '~> 0.6'
+
+  spec.add_development_dependency 'httpx', '~> 1.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+end

data/lib/gliner/classifier.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'gliner/position_iteration'
+
+module Gliner
+  class Classifier
+    include PositionIteration
+
+    def initialize(inference, max_width:)
+      @inference = inference
+      @max_width = max_width
+    end
+
+    def classification_scores(logits, labels, label_positions, prepared)
+      labels.each_index.map do |label_index|
+        max_label_score(logits, label_index, label_positions, prepared)
+      end
+    end
+
+    def format_classification(scores, labels:, multi_label:, include_confidence:, cls_threshold:)
+      label_scores = sorted_label_scores(scores, labels)
+
+      return format_multi_label(label_scores, cls_threshold, include_confidence) if multi_label
+
+      format_single_label(label_scores.first, include_confidence)
+    end
+
+    private
+
+    def max_label_score(logits, label_index, label_positions, prepared)
+      seq_len = logits[0].length
+
+      scores = each_position_width(seq_len, prepared, @max_width).map do |pos, _start_word, width|
+        logit = @inference.label_logit(logits, pos, width, label_index, label_positions)
+        @inference.sigmoid(logit)
+      end
+
+      scores.max || -Float::INFINITY
+    end
+
+    def sorted_label_scores(scores, labels)
+      scores
+        .each_with_index.map { |score, i| [labels.fetch(i), score] }
+        .sort_by { |(_label, score)| -score }
+    end
+
+    def format_multi_label(label_scores, cls_threshold, include_confidence)
+      chosen = labels_above_threshold(label_scores, cls_threshold)
+
+      chosen.map { |label, score| format_label(label, score, include_confidence) }
+    end
+
+    def labels_above_threshold(label_scores, threshold)
+      above = label_scores.select { |_label, score| score >= threshold }
+      above.empty? && label_scores.first ? [label_scores.first] : above
+    end
+
+    def format_single_label(label_score, include_confidence)
+      label, score = label_score
+
+      format_label(label, score, include_confidence)
+    end
+
+    def format_label(label, score, include_confidence)
+      include_confidence ? { 'label' => label, 'confidence' => score } : label
+    end
+  end
+end

data/lib/gliner/config/classification_task.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Gliner
+  module Config
+    class ClassificationTask
+      DEFAULT_THRESHOLD = 0.5
+
+      class << self
+        def parse(task_name, config)
+          case config
+          when Array
+            from_labels(config)
+          when Hash
+            from_hash(task_name, config)
+          else
+            raise Error, "classification task #{task_name.inspect} must be an Array or Hash"
+          end
+        end
+
+        private
+
+        def from_labels(labels)
+          {
+            labels: labels.map(&:to_s),
+            multi_label: false,
+            cls_threshold: DEFAULT_THRESHOLD,
+            label_descs: {}
+          }
+        end
+
+        def from_hash(task_name, config)
+          config_hash = config.transform_keys(&:to_s)
+
+          return from_described_labels(task_name, config_hash) if config_hash.key?('labels')
+
+          {
+            labels: config.keys.map(&:to_s),
+            multi_label: false,
+            cls_threshold: DEFAULT_THRESHOLD,
+            label_descs: config.transform_keys(&:to_s).transform_values(&:to_s)
+          }
+        end
+
+        def from_described_labels(task_name, config_hash)
+          labels, label_descs = parse_labels(task_name, config_hash['labels'])
+
+          {
+            labels: labels,
+            multi_label: config_hash['multi_label'] ? true : false,
+            cls_threshold: threshold(config_hash['cls_threshold']),
+            label_descs: label_descs
+          }
+        end
+
+        def parse_labels(task_name, raw_labels)
+          case raw_labels
+          when Array
+            [raw_labels.map(&:to_s), {}]
+          when Hash
+            [raw_labels.keys.map(&:to_s), raw_labels.transform_keys(&:to_s).transform_values(&:to_s)]
+          else
+            raise Error, "classification task #{task_name.inspect} must include labels"
+          end
+        end
+
+        def threshold(value)
+          return DEFAULT_THRESHOLD if value.nil? || value == false
+
+          Float(value)
+        end
+      end
+    end
+  end
+end

data/lib/gliner/config/entity_types.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Gliner
+  module Config
+    class EntityTypes
+      class << self
+        def parse(entity_types)
+          case entity_types
+          when Array
+            list_config(entity_types)
+          when String, Symbol
+            list_config([entity_types])
+          when Hash
+            hash_config(entity_types)
+          else
+            raise Error, 'labels must be a String, Array, or Hash'
+          end
+        end
+
+        private
+
+        def list_config(entity_types)
+          {
+            labels: entity_types.map(&:to_s),
+            descriptions: {},
+            dtypes: {},
+            thresholds: {}
+          }
+        end
+
+        def hash_config(entity_types)
+          state = { labels: [], descriptions: {}, dtypes: {}, thresholds: {} }
+          entity_types.each { |label, config| apply_config(state, label, config) }
+          state
+        end
+
+        def apply_config(state, label, config)
+          name = label.to_s
+          state[:labels] << name
+
+          return if config.nil?
+
+          case config
+          when String
+            apply_description(state, name, config)
+          when Hash
+            apply_hash_config(state, name, config)
+          else
+            apply_description(state, name, config.to_s)
+          end
+        end
+
+        def apply_hash_config(state, name, config)
+          config_hash = config.transform_keys(&:to_s)
+          apply_description(state, name, config_hash['description']) if config_hash['description']
+          apply_dtype(state, name, config_hash['dtype']) if config_hash['dtype']
+          apply_threshold(state, name, config_hash['threshold']) if config_hash.key?('threshold')
+        end
+
+        def apply_description(state, name, description)
+          state[:descriptions][name] = description
+        end
+
+        def apply_dtype(state, name, dtype)
+          state[:dtypes][name] = dtype.to_s == 'str' ? :str : :list
+        end
+
+        def apply_threshold(state, name, threshold)
+          state[:thresholds][name] = Float(threshold)
+        end
+      end
+    end
+  end
+end

data/lib/gliner/config/field_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Gliner
+  module Config
+    class FieldSpec
+      class << self
+        def parse(spec)
+          name, *parts = spec.split('::')
+          field = build_field(name)
+
+          parts.each { |part| apply_part(field, part.to_s) }
+          field.delete(:dtype_explicit)
+          field
+        end
+
+        def build_descriptions(parsed_fields)
+          parsed_fields.each_with_object({}) do |field, acc|
+            description = description_for(field)
+            acc[field[:name]] = description if description
+          end
+        end
+
+        private
+
+        def build_field(name)
+          {
+            name: name.to_s,
+            dtype: :list,
+            description: nil,
+            choices: nil,
+            dtype_explicit: false
+          }
+        end
+
+        def apply_part(field, part)
+          return apply_dtype_part(field, part) if dtype_part?(part)
+          return apply_choice_part(field, part) if bracketed_list?(part)
+
+          append_description(field, part)
+        end
+
+        def dtype_part?(part)
+          %w[str list].include?(part)
+        end
+
+        def apply_dtype_part(field, part)
+          set_dtype(field, part == 'str' ? :str : :list)
+        end
+
+        def apply_choice_part(field, part)
+          field[:choices] = parse_choices(part)
+          field[:dtype] = :str unless field[:dtype_explicit]
+        end
+
+        def set_dtype(field, dtype)
+          field[:dtype] = dtype
+          field[:dtype_explicit] = true
+        end
+
+        def append_description(field, part)
+          field[:description] = [field[:description], part].compact.join('::')
+        end
+
+        def bracketed_list?(part)
+          part.start_with?('[') && part.end_with?(']')
+        end
+
+        def parse_choices(part)
+          part[1..-2].split('|').map(&:strip).reject(&:empty?)
+        end
+
+        def description_for(field)
+          description = field[:description].to_s
+          choices = field[:choices]
+          return nil if description.empty? && !choices&.any?
+
+          if choices&.any?
+            choices_str = choices.join('|')
+            description = description.empty? ? "Choices: #{choices_str}" : "#{description} (choices: #{choices_str})"
+          end
+
+          description.empty? ? nil : description
+        end
+      end
+    end
+  end
+end

data/lib/gliner/config_parser.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'gliner/config/entity_types'
+require 'gliner/config/classification_task'
+require 'gliner/config/field_spec'
+
+module Gliner
+  class ConfigParser
+    def parse_entity_types(entity_types)
+      Config::EntityTypes.parse(entity_types)
+    end
+
+    def parse_classification_task(task_name, config)
+      Config::ClassificationTask.parse(task_name, config)
+    end
+
+    def parse_field_spec(spec)
+      Config::FieldSpec.parse(spec)
+    end
+
+    def build_field_descriptions(parsed_fields)
+      Config::FieldSpec.build_descriptions(parsed_fields)
+    end
+
+    def build_prompt(base, label_descriptions)
+      prompt = base.to_s
+
+      label_descriptions.to_h.each do |label, description|
+        next if description.to_s.empty?
+
+        prompt += " [DESCRIPTION] #{label}: #{description}"
+      end
+
+      prompt
+    end
+  end
+end

data/lib/gliner/inference/session_validator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Gliner
+  class Inference
+    class SessionValidator
+      EXPECTED_INPUTS_LOGITS = %w[
+        input_ids
+        attention_mask
+        words_mask
+        text_lengths
+        task_type
+        label_positions
+        label_mask
+      ].freeze
+
+      EXPECTED_INPUTS_SPAN_LOGITS = %w[
+        input_ids
+        attention_mask
+      ].freeze
+
+      class << self
+        def [](session) = call(session)
+
+        def call(session)
+          input_names = session.inputs.map { |input| input[:name] }
+          output_names = session.outputs.map { |output| output[:name] }
+          has_cls_logits = output_names.include?('cls_logits')
+
+          validation = validation_for_outputs(output_names, input_names)
+
+          IOValidation.new(
+            input_names: input_names,
+            output_name: validation.fetch(:output_name),
+            label_index_mode: validation.fetch(:label_index_mode),
+            has_cls_logits: has_cls_logits
+          )
+        end
+
+        private
+
+        def validation_for_outputs(output_names, input_names)
+          return validation_for_logits(input_names) if output_names.include?('logits')
+          return validation_for_span_logits(input_names) if output_names.include?('span_logits')
+
+          raise Error, 'Model missing output: logits or span_logits'
+        end
+
+        def validation_for_logits(input_names)
+          ensure_expected_inputs!(EXPECTED_INPUTS_LOGITS, input_names)
+
+          { output_name: 'logits', label_index_mode: :label_index }
+        end
+
+        def validation_for_span_logits(input_names)
+          ensure_expected_inputs!(EXPECTED_INPUTS_SPAN_LOGITS, input_names)
+
+          { output_name: 'span_logits', label_index_mode: :label_position }
+        end
+
+        def ensure_expected_inputs!(expected_inputs, input_names)
+          missing = expected_inputs - input_names
+          raise Error, "Model missing inputs: #{missing.join(', ')}" unless missing.empty?
+        end
+      end
+    end
+  end
+end