laya 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69d7ddd3d48590f822730d724339adf76897e8eefe51e3fb1bb6aff35fa9d5de
+  data.tar.gz: 62fa0d3a2491c0e65d13da93712498e96249561e01859488eb8a50f5e5721fe7
+SHA512:
+  metadata.gz: a83ae9a6a5f0040399b4e5ec638cc3c87e4101cf3b058ed6fb00d064cd0fc68d8f6262c58ad85f36420b1879f2be214f66205e59560246ca97f9c6759b968726
+  data.tar.gz: a03f5b5c4563c2be24f13907acfdfdc131d2d74b7bee886b7919475593f20c6e32e7b76642fa0eab3141c20aada95a3de1b0fea57f14d6edaf3fec446fa17ea6

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- `Laya.configure`, `Laya.new` and `Laya::Client#system_one` for `choice`, `score` and `noul` questions
+- Lazy, thread-safe model loading, with `load!` for preloading before fork
+- Hugging Face download into a cache: `Laya.download`, the `laya download|path|help` command, `laya:download` / `laya:path` Rake tasks and a Railtie

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Hernandez
+
+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,207 @@
+# laya
+
+Run [Laya](https://laya.convaiinnovations.com/), Convai Innovations' open-source "System-1" decision model, from Ruby. It runs locally on the CPU through ONNX Runtime.
+
+You give Laya a **state** (a ticket, an email, any JSON) and some **typed questions**. It returns every answer with calibrated probabilities in a single forward pass, in a few hundred milliseconds on a laptop CPU.
+
+```ruby
+laya = Laya.new
+
+result = laya.system_one(
+  {
+    subject: "Refund not received",
+    body: "I cancelled my subscription two weeks ago and I still have not received my refund. " \
+      "This is the third time I am writing. If this is not resolved I will dispute the charge with my bank."
+  },
+  {
+    department: {type: :choice, instructions: "Which team should handle this ticket?",
+                 criteria: {billing: "payments, refunds, invoices", support: "product help and bugs", sales: "new purchases"}},
+    churn_risk: {type: :noul, instructions: "Is the customer likely to cancel or dispute?"}
+  }
+)
+
+result[:department].choice  # => "billing"
+result[:churn_risk].noul    # => 0.0988
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "laya"
+```
+
+This requires Ruby 3.3+. The runtime dependencies are [`onnxruntime`](https://github.com/ankane/onnxruntime-ruby) and [`tokenizers`](https://github.com/ankane/tokenizers-ruby), which ship prebuilt binaries.
+
+The model itself is about 1.7 GB, published at [receptron/laya-onnx](https://huggingface.co/receptron/laya-onnx). It downloads on first use into `~/.cache/receptron-laya`, so a machine running both downloads it only once. You can also fetch it ahead of time; see [Downloading the model](#downloading-the-model). Budget about 2 GB of RAM once it's loaded.
+
+## Asking questions
+
+`system_one(state, questions)` answers every question about one state in a single forward pass.
+
+- **`state`** is a String, or anything JSON-serializable (Hash, Array, numbers). Long states are truncated to the model's 512-token window.
+- **`questions`** is a Hash of `name => question`. Names and `type` can be Symbols or Strings, and the answers come back under the same keys.
+
+### The three question types
+
+The `choice` and `score` examples below use the ticket state from the top of this README.
+
+| Type | Use it for | `criteria` | Answer |
+| --- | --- | --- | --- |
+| `choice` | Picking one option | `{label => description}`, or `[label, ...]` | `choice`, `probabilities`, `confidence` |
+| `score` | A level on an ordered scale | `[lowest, ..., highest]` | `score`, `probabilities`, `legend`, `confidence` |
+| `noul` | A yes/no probability | optional `{true => "...", false => "..."}` | `noul` |
+
+**choice** picks the most likely label and gives the probability of each one:
+
+```ruby
+department: {
+  type: :choice,
+  instructions: "Which team should handle this ticket?",
+  criteria: {billing: "payments, refunds, invoices", support: "product help and bugs", sales: "new purchases"}
+}
+# result[:department].choice        # => "billing"
+# result[:department].probabilities # => {"billing" => 0.9415, "support" => 0.031, "sales" => 0.0275}
+# result[:department].confidence    # => 0.7603 (1 = certain, 0 = evenly spread)
+```
+
+**score** returns the expected level, from 0 up to the number of levels minus 1, plus the distribution:
+
+```ruby
+urgency: {
+  type: :score,
+  instructions: "How urgent is this ticket?",
+  criteria: ["not urgent", "somewhat urgent", "urgent", "critical"]
+}
+# result[:urgency].score         # => 1.3886 (between "somewhat urgent" and "urgent")
+# result[:urgency].probabilities # => {"0" => 0.1752, "1" => 0.2947, "2" => 0.4962, "3" => 0.0338}
+# result[:urgency].legend        # => {"0" => "not urgent", "1" => "somewhat urgent", ...}
+```
+
+**noul** returns P(true). The criteria are optional and let you say what true and false mean:
+
+```ruby
+laya.system_one(
+  "Hi, my order #4521 arrived damaged, can I get a replacement?",
+  {
+    spam: {
+      type: :noul,
+      instructions: "Is this message spam?",
+      criteria: {true => "unsolicited advertising", false => "a genuine request"}
+    }
+  }
+)[:spam].noul # => 0.1134
+```
+
+Every answer also has `type` and `act_probability`. `result.usage.input_tokens` reports how many tokens were read, and `result.to_h` returns a plain Hash.
+
+### Tips from Laya's docs
+
+- Keep `choice` under about 20 options. With many labels, each one gets only a few tokens and accuracy drops.
+- `score` is the weakest of the three types, so it works best with coarse scales (3 to 5 levels).
+- The probabilities are calibrated, so thresholds mean something. A common pattern is to act automatically above 0.85 confidence and escalate to a human below it.
+
+See: https://huggingface.co/convaiinnovations/laya#where-jev-leads
+
+## Configuration
+
+```ruby
+# config/initializers/laya.rb
+Laya.configure do |config|
+  config.cache_dir = "/var/cache/laya"
+  config.session_options = {intra_op_num_threads: 4}
+end
+```
+
+| Setting | Default | |
+| --- | --- | --- |
+| `cache_dir` | `$LAYA_CACHE`, `$XDG_CACHE_HOME/receptron-laya` or `~/.cache/receptron-laya` | Where downloads go |
+| `model_dir` | `nil` | Use local model files; nothing is downloaded |
+| `token` | `$HF_TOKEN` | For private or gated Hugging Face repos |
+| `repo` | `"receptron/laya-onnx"` | Hugging Face repo |
+| `revision` | `"main"` | Branch, tag or commit to download |
+| `subfolder` | `nil` | Subfolder inside the repo |
+| `providers` | `["CPUExecutionProvider"]` | ONNX Runtime execution providers |
+| `session_options` | `{}` | Passed to `OnnxRuntime::InferenceSession` |
+| `on_progress` | `nil` | `->(file:, received:, total:) { ... }`, called during downloads |
+| `logger` | `nil` | Logs each downloaded file |
+
+`Laya.new(**overrides)` builds a client from the global configuration plus any overrides, for example `Laya.new(model_dir: "./onnx")`.
+
+### Loading and threads
+
+`Laya.new` is cheap: the model loads on the first `system_one` call. To load it up front, call `load!`:
+
+```ruby
+LAYA = Laya.new.load!
+```
+
+With Puma or Unicorn and `preload_app!`, load before forking so all workers share the model's memory. Clients are thread-safe, and one client per process is enough. `laya.loaded?` tells you whether the model is in memory, and `laya.close` releases it.
+
+## Downloading the model
+
+To avoid downloading 1.7 GB on the first request, fetch the model at build time.
+
+**Rails:** the tasks are registered automatically and run after your initializers:
+
+```bash
+bin/rails laya:download   # fetch the model into the cache
+bin/rails laya:path       # print the model directory; fails if files are missing
+```
+
+**Other Rake projects:** add `require "laya/tasks"` to your `Rakefile`, then run `rake laya:download`.
+
+**Command line:**
+
+```console
+$ bundle exec laya download
+Downloading receptron/laya-onnx@main into /Users/you/.cache/receptron-laya/receptron--laya-onnx/main
+  laya.onnx.data                    42%  708.1 MB / 1607.2 MB
+```
+
+Run `bundle exec laya help` to see every command and environment variable, with its current value. The command prints the model directory on stdout, so `MODEL_DIR=$(laya path)` works in scripts.
+
+**From Ruby:** `Laya.download` returns the directory.
+
+**Docker:**
+
+```dockerfile
+ENV LAYA_CACHE=/models
+RUN SECRET_KEY_BASE_DUMMY=1 bin/rails laya:download
+```
+
+The model then gets its own image layer, which stays cached until you change the revision.
+
+These environment variables override the configuration in all of the above: `LAYA_CACHE`, `HF_TOKEN`, `LAYA_REPO`, `LAYA_REVISION`, `LAYA_SUBFOLDER`.
+
+A download only fetches files that are missing or have changed size. Each file is written to a temporary file first, so an interrupted download never leaves a broken model behind. If the network is unavailable, a complete cache is used as-is.
+
+## Errors
+
+Every error inherits from `Laya::Error`:
+
+| Error | When |
+| --- | --- |
+| `Laya::InvalidQuestionError` | A question is malformed; the message names the question |
+| `Laya::InputTooLongError` | A question's options don't fit in the model's window |
+| `Laya::DownloadError` | Network or Hugging Face errors (401/403 hint at `HF_TOKEN`) |
+| `Laya::ModelError` | The model files are corrupt or incompatible |
+| `Laya::ConfigurationError` | An invalid setting, or `model_dir` is missing files |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake    # specs + StandardRB; no model needed
+```
+
+The specs that need the real model are tagged `:model` and only run when `LAYA_MODEL_DIR` is set:
+
+```bash
+bundle exec exe/laya download
+LAYA_MODEL_DIR=$(bundle exec exe/laya path) bundle exec rspec
+```
+
+## License
+
+The gem is MIT-licensed. The model weights are Apache 2.0, by [Convai Innovations](https://huggingface.co/convaiinnovations/laya). The ONNX export is by [receptron/laya](https://github.com/receptron/laya) (MIT).

data/exe/laya

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "laya"
+
+exit Laya::CLI.new.run(ARGV)

data/lib/laya/cli.rb

@@ -0,0 +1,113 @@
+module Laya
+  # `laya download` / `laya path`, shared by exe/laya and the Rake tasks.
+  class CLI
+    EX_USAGE = 64
+    ENV_OVERRIDES = {
+      cache_dir: "LAYA_CACHE",
+      token: "HF_TOKEN",
+      repo: "LAYA_REPO",
+      revision: "LAYA_REVISION",
+      subfolder: "LAYA_SUBFOLDER"
+    }.freeze
+
+    def initialize(out: $stdout, err: $stderr, env: ENV)
+      @out = out
+      @err = err
+      @env = env
+    end
+
+    def run(argv)
+      case argv.first
+      when "download" then download
+      when "path" then path
+      when "help", "-h", "--help"
+        @out.puts help
+        0
+      when nil
+        @err.puts help
+        EX_USAGE
+      else
+        @err.puts "laya: unknown command #{argv.first.inspect}", "", help
+        EX_USAGE
+      end
+    end
+
+    def help
+      settings = config
+      <<~HELP
+        laya #{VERSION}: manage the Laya model files
+
+        Usage:
+          laya download   Download the model into the cache (~1.7 GB the first time)
+          laya path       Print the model directory; exits 1 if files are missing
+          laya help       Show this message
+
+        Environment (overrides Laya.configure):
+          LAYA_CACHE      Cache directory         #{settings.cache_dir}
+          HF_TOKEN        Hugging Face token      #{settings.token ? "set" : "not set"}
+          LAYA_REPO       Hugging Face repo       #{settings.repo}
+          LAYA_REVISION   Branch, tag or commit   #{settings.revision}
+          LAYA_SUBFOLDER  Subfolder in the repo   #{settings.subfolder || "none"}
+
+        Examples:
+          laya download
+          LAYA_CACHE=/models laya download
+          ls "$(laya path)"
+      HELP
+    end
+
+    private
+
+    def config
+      overrides = ENV_OVERRIDES.to_h { |setting, variable| [setting, @env[variable]] }.compact
+      Laya.config.merge(**overrides)
+    end
+
+    def download
+      settings = config
+      downloader = Downloader.new(settings.merge(on_progress: progress).validate!)
+      @err.puts "Downloading #{settings.repo}@#{settings.revision} into #{downloader.dir}" unless settings.model_dir
+      dir = downloader.call
+      @err.puts "Model ready in #{dir}"
+      @out.puts dir
+      0
+    rescue Laya::Error => e
+      @err.puts "", "laya: #{e.message}"
+      1
+    end
+
+    def path
+      downloader = Downloader.new(config)
+      missing_files = downloader.missing_files
+      if missing_files.empty?
+        @out.puts downloader.dir
+        0
+      else
+        @err.puts "laya: #{downloader.dir} is missing:"
+        missing_files.each { |file| @err.puts "  #{file}" }
+        @err.puts "Run `laya download` to fetch them."
+        1
+      end
+    end
+
+    def progress
+      last_percent = {}
+      lambda do |file:, received:, total:|
+        percent = total&.positive? ? received * 100 / total : nil
+        next if percent && last_percent[file] == percent
+
+        last_percent[file] = percent
+        @err.print "\r  #{file.ljust(32)} #{progress_detail(percent, received, total)}"
+        @err.puts if percent == 100
+      end
+    end
+
+    def progress_detail(percent, received, total)
+      return megabytes(received) unless percent
+
+      "#{percent.to_s.rjust(3)}%  #{megabytes(received)} / #{megabytes(total)}"
+    end
+
+    def megabytes(bytes) = format("%.1f MB", bytes / 1_048_576.0)
+  end
+end

data/lib/laya/client.rb

@@ -0,0 +1,87 @@
+module Laya
+  # Answers typed questions about a state. Loading is lazy (first call, or load!) and thread-safe.
+  class Client
+    attr_reader :config
+
+    def initialize(config, session: nil)
+      @config = config.validate!.freeze
+      @session = session
+      @mutex = Mutex.new
+    end
+
+    def load!
+      session
+      self
+    end
+
+    def loaded? = !@session.nil?
+
+    def close
+      @mutex.synchronize { @session = nil }
+      nil
+    end
+
+    def system_one(state, questions)
+      normalized_questions = Questions.normalize_all(questions)
+      model = session
+      encoded = {}
+      encode = ->(text) { encoded[text] ||= model.encode(text) }
+
+      rows = normalized_questions.map do |key, question|
+        built = Sequence.build(encode, model.special_ids, state, question, max_len: model.max_len, head_max_len: model.head_max_len)
+        if built.markers.size != question.options.size
+          raise InputTooLongError, "question #{key.inspect}: options do not fit in head_max_len=#{model.head_max_len} tokens"
+        end
+
+        [built, question.type_id]
+      end
+
+      logits, act_probs = model.run(Sequence.collate(rows, pad: model.special_ids.pad))
+
+      answers = normalized_questions.each_with_index.to_h do |(key, question), row|
+        option_count = rows[row].first.markers.size
+        [key, decode(question, logits[row].first(option_count), act_probs[row][0], model.model_config)]
+      end
+
+      Result.new(
+        model: "laya",
+        answers: answers.freeze,
+        usage: Usage.new(input_tokens: rows.sum { |built, _| built.ids.size }, output_tokens: 0)
+      )
+    end
+
+    private
+
+    def session
+      @session || @mutex.synchronize do
+        @session ||= Session.new(Downloader.new(config).call, providers: config.providers, session_options: config.session_options)
+      end
+    end
+
+    def decode(question, logits, act_probability, model_config)
+      temperature = Sequence.temperature(model_config, question.type, logits.size)
+      probabilities = Sequence.softmax(logits.map { |logit| logit / temperature })
+
+      case question.type
+      when "choice"
+        labels = question.criteria.keys
+        ChoiceAnswer.new(
+          choice: labels[probabilities.index(probabilities.max)],
+          probabilities: labels.zip(probabilities.map { |probability| probability.round(4) }).to_h.freeze,
+          confidence: Sequence.confidence(probabilities).round(4),
+          act_probability: act_probability
+        )
+      when "score"
+        ScoreAnswer.new(
+          score: probabilities.each_with_index.sum { |probability, level| probability * level }.round(4),
+          probabilities: probabilities.each_with_index.to_h { |probability, level| [level.to_s, probability.round(4)] }.freeze,
+          legend: question.criteria.each_with_index.to_h { |description, level| [level.to_s, description] }.freeze,
+          confidence: Sequence.confidence(probabilities).round(4),
+          act_probability: act_probability
+        )
+      else
+        NoulAnswer.new(noul: probabilities[1].round(4), act_probability: act_probability)
+      end
+    end
+  end
+end

data/lib/laya/configuration.rb

@@ -0,0 +1,56 @@
+module Laya
+  class Configuration
+    BUNDLE_FILES = %w[laya.onnx laya.onnx.data laya_config.json
+      tokenizer/tokenizer.json tokenizer/tokenizer_config.json].freeze
+    SETTINGS = %i[repo revision subfolder model_dir cache_dir token providers
+      session_options on_progress logger].freeze
+
+    attr_accessor(*SETTINGS)
+
+    def self.default_cache_dir(env)
+      env["LAYA_CACHE"] ||
+        File.join(env["XDG_CACHE_HOME"] ||
+                  File.join(Dir.home, ".cache"), "receptron-laya")
+    end
+
+    def initialize(env: ENV)
+      @repo = "receptron/laya-onnx"
+      @revision = "main"
+      @subfolder = nil
+      @model_dir = nil
+      @cache_dir = self.class.default_cache_dir(env)
+      @token = env["HF_TOKEN"]
+      @providers = ["CPUExecutionProvider"]
+      @session_options = {}
+      @on_progress = nil
+      @logger = nil
+    end
+
+    def initialize_copy(source)
+      super
+      @providers = source.providers.dup
+      @session_options = source.session_options.dup
+    end
+
+    def merge(**overrides)
+      unknown = overrides.keys - SETTINGS
+      raise ConfigurationError, "unknown setting(s): #{unknown.join(", ")}" if unknown.any?
+
+      dup.tap { |copy| overrides.each { |name, value| copy.public_send(:"#{name}=", value) } }
+    end
+
+    def validate!
+      raise ConfigurationError, "repo must look like \"owner/name\" (got #{repo.inspect})" unless repo.to_s.match?(%r{\A[^/\s]+/[^/\s]+\z})
+      raise ConfigurationError, "revision can't be blank" if revision.to_s.empty?
+      raise ConfigurationError, "providers must be an Array" unless providers.is_a?(Array)
+      raise ConfigurationError, "session_options must be a Hash" unless session_options.is_a?(Hash)
+      raise ConfigurationError, "on_progress must respond to #call" if on_progress && !on_progress.respond_to?(:call)
+
+      if model_dir
+        missing = BUNDLE_FILES.reject { |file| File.file?(File.join(model_dir, file)) }
+        raise ConfigurationError, "model_dir #{model_dir} is missing: #{missing.join(", ")}" if missing.any?
+      end
+      self
+    end
+  end
+end

data/lib/laya/downloader.rb

@@ -0,0 +1,130 @@
+require "fileutils"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Laya
+  # Resolves the directory that holds the model files: model_dir as-is, or the Hugging Face cache.
+  # Files are fetched when missing or when their size differs from the remote one; each streams to a
+  # .part file that is renamed when complete, so an interrupted download never leaves a broken file.
+  class Downloader
+    ORIGIN = URI("https://huggingface.co")
+    MAX_REDIRECTS = 5
+    NETWORK_ERRORS = [SocketError, SystemCallError, IOError, Timeout::Error,
+      OpenSSL::SSL::SSLError, Net::HTTPBadResponse].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    def call
+      return dir if @config.model_dir
+
+      Configuration::BUNDLE_FILES.each { |file| fetch(file) }
+      dir
+    end
+
+    def dir
+      return File.expand_path(@config.model_dir) if @config.model_dir
+
+      File.join(File.expand_path(@config.cache_dir), @config.repo.sub("/", "--"), @config.revision, *subfolder)
+    end
+
+    def missing_files
+      Configuration::BUNDLE_FILES.reject { |file| File.file?(File.join(dir, file)) }
+    end
+
+    private
+
+    def subfolder
+      name = @config.subfolder.to_s.gsub(%r{\A/+|/+\z}, "")
+      name.empty? ? [] : [name]
+    end
+
+    def url_for(file)
+      path = [@config.repo, "resolve", URI.encode_www_form_component(@config.revision), *subfolder, file].join("/")
+      "#{ORIGIN}/#{path}"
+    end
+
+    def fetch(file)
+      destination = File.join(dir, file)
+      url = url_for(file)
+      if File.file?(destination)
+        remote_size = remote_size(url)
+        return if remote_size.nil? || remote_size == File.size(destination)
+      end
+      download(url, destination, file)
+    end
+
+    # A failed HEAD (offline, DNS, 5xx) means "unknown", so a populated cache keeps working offline.
+    def remote_size(url)
+      request(Net::HTTP::Head, url) do |response, linked_size|
+        next Integer(linked_size, exception: false) if linked_size
+        next nil unless response.is_a?(Net::HTTPSuccess)
+
+        Integer(response["content-length"], exception: false)
+      end
+    rescue DownloadError, *NETWORK_ERRORS
+      nil
+    end
+
+    def download(url, destination, file)
+      FileUtils.mkdir_p(File.dirname(destination))
+      partial = "#{destination}.part-#{Process.pid}"
+      request(Net::HTTP::Get, url) do |response, _linked_size|
+        raise DownloadError, failure_message(url, response) unless response.is_a?(Net::HTTPSuccess)
+
+        write_body(response, partial, file, url)
+      end
+      File.rename(partial, destination)
+      @config.logger&.info("laya: downloaded #{file}")
+    rescue *NETWORK_ERRORS => e
+      raise DownloadError, "failed to download #{url}: #{e.message}"
+    ensure
+      FileUtils.rm_f(partial) if partial
+    end
+
+    def write_body(response, partial, file, url)
+      total = Integer(response["content-length"], exception: false)
+      received = 0
+      File.open(partial, "wb") do |output|
+        response.read_body do |chunk|
+          output.write(chunk)
+          received += chunk.bytesize
+          @config.on_progress&.call(file: file, received: received, total: total)
+        end
+      end
+      raise DownloadError, "incomplete download of #{url}: got #{received} of #{total} bytes" if total && received != total
+    end
+
+    def failure_message(url, response)
+      hint = [401, 403].include?(response.code.to_i) ? " (set HF_TOKEN or config.token for private or gated repos)" : ""
+      "failed to download #{url}: #{response.code} #{response.message}#{hint}"
+    end
+
+    # Follows redirects and yields the final response (with its connection still open, for streaming)
+    # plus the first x-linked-size seen, which Hugging Face only sends on the LFS redirect.
+    def request(verb, url, hops: MAX_REDIRECTS, linked_size: nil, &block)
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 15, read_timeout: 60) do |http|
+        http.request(build_request(verb, uri)) do |response|
+          linked_size ||= response["x-linked-size"]
+          # A HEAD stops at the LFS redirect: x-linked-size already answers it, and CDNs often refuse HEAD
+          final = !response.is_a?(Net::HTTPRedirection) || (verb == Net::HTTP::Head && linked_size)
+          return yield(response, linked_size) if final
+          raise DownloadError, "too many redirects fetching #{url}" if hops.zero?
+
+          return request(verb, URI.join(uri, response["location"]).to_s, hops: hops - 1, linked_size: linked_size, &block)
+        end
+      end
+    end
+
+    def build_request(verb, uri)
+      verb.new(uri).tap do |request|
+        request["User-Agent"] = "laya-ruby/#{VERSION}"
+        request["Accept-Encoding"] = "identity" # sizes must match the bytes on disk
+        request["Authorization"] = "Bearer #{@config.token}" if @config.token && uri.host == ORIGIN.host
+      end
+    end
+  end
+end

data/lib/laya/errors.rb

@@ -0,0 +1,13 @@
+module Laya
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class InvalidQuestionError < Error; end
+
+  class InputTooLongError < Error; end
+
+  class DownloadError < Error; end
+
+  class ModelError < Error; end
+end

data/lib/laya/questions.rb

@@ -0,0 +1,99 @@
+require "json"
+
+module Laya
+  # Validates Jev-style question hashes and normalizes them (rl_agent_api.RLAgent._to_internal).
+  module Questions
+    TYPES = {"choice" => 0, "score" => 1, "noul" => 2}.freeze
+    NOUL_DEFAULTS = {
+      "false" => "no, the statement does not hold",
+      "true" => "yes, the statement holds"
+    }.freeze
+
+    Question = Data.define(:type, :instructions, :criteria) do
+      def type_id = TYPES.fetch(type)
+
+      def options
+        case type
+        when "choice"
+          criteria.map { |label, desc| desc.to_s.empty? ? label : "#{label}: #{desc}" }
+        when "score"
+          criteria.each_with_index.map { |level, i| "level #{i}: #{level}" }
+        else
+          %w[false true].map do |k|
+            "#{k}: #{criteria[k].to_s.empty? ? NOUL_DEFAULTS[k] : criteria[k]}"
+          end
+        end
+      end
+    end
+
+    module_function
+
+    def normalize_all(questions)
+      raise InvalidQuestionError, "questions must be a Hash of name => question" unless questions.is_a?(Hash)
+      raise InvalidQuestionError, "at least one question is required" if questions.empty?
+
+      questions.to_h { |key, question_definition| [key, normalize(key, question_definition)] }
+    end
+
+    def normalize(key, question_definition)
+      invalid!(key, "must be a Hash") unless question_definition.is_a?(Hash)
+      attributes = question_definition.transform_keys(&:to_s)
+      type = attributes["type"].to_s
+      invalid!(key, "type must be one of choice, score, noul (got #{attributes["type"].inspect})") unless TYPES.key?(type)
+
+      Question.new(
+        type: type,
+        instructions: instructions(key, attributes["instructions"]),
+        criteria: criteria(key, type, attributes["criteria"])
+      )
+    end
+
+    def instructions(key, value)
+      case value
+      when String
+        invalid!(key, "instructions can't be blank") if value.strip.empty?
+        value
+      when Hash then JSON.generate(value)
+      else invalid!(key, "instructions must be a String or Hash")
+      end
+    end
+
+    def criteria(key, type, value)
+      case type
+      when "choice" then choice_criteria(key, value)
+      when "score" then score_criteria(key, value)
+      else noul_criteria(key, value)
+      end
+    end
+
+    def choice_criteria(key, value)
+      pairs =
+        case value
+        when Hash then value.map { |label, desc| [label.to_s, desc&.to_s] }
+        when Array then value.map { |label| [label.to_s, nil] }
+        else invalid!(key, "choice criteria must be a Hash of label => description or an Array of labels")
+        end
+      invalid!(key, "choice needs at least 2 options") if pairs.size < 2
+      invalid!(key, "choice labels must be unique") if pairs.map(&:first).uniq.size != pairs.size
+      pairs.to_h
+    end
+
+    def score_criteria(key, value)
+      invalid!(key, "score criteria must be an Array of levels, lowest first") unless value.is_a?(Array)
+      invalid!(key, "score needs at least 2 levels") if value.size < 2
+      value.map(&:to_s)
+    end
+
+    def noul_criteria(key, value)
+      return {} if value.nil?
+
+      crit = value.is_a?(Hash) ? value.to_h { |k, v| [k.to_s, v&.to_s] } : nil
+      invalid!(key, "noul criteria must be a Hash with only true and false keys") unless crit && (crit.keys - %w[true false]).empty?
+      crit
+    end
+
+    def invalid!(key, message)
+      raise InvalidQuestionError, "question #{key.inspect}: #{message}"
+    end
+  end
+end

data/lib/laya/railtie.rb

@@ -0,0 +1,9 @@
+module Laya
+  # Registers the Rake tasks in Rails apps, after the app boots so config/initializers/laya.rb applies.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks.rb", __dir__)
+      %w[laya:download laya:path].each { |name| Rake::Task[name].enhance([:environment]) }
+    end
+  end
+end

data/lib/laya/result.rb

@@ -0,0 +1,56 @@
+module Laya
+  Usage = Data.define(:input_tokens, :output_tokens)
+
+  ChoiceAnswer = Data.define(:choice, :probabilities, :confidence, :act_probability) do
+    def type = "choice"
+
+    def to_h
+      {
+        type: type,
+        choice: choice,
+        probabilities: probabilities,
+        confidence: confidence,
+        rl_agent: {act_probability: act_probability}
+      }
+    end
+  end
+
+  ScoreAnswer = Data.define(:score, :probabilities, :legend, :confidence, :act_probability) do
+    def type = "score"
+
+    def to_h
+      {
+        type: type,
+        score: score,
+        legend: legend,
+        probabilities: probabilities,
+        confidence: confidence,
+        rl_agent: {act_probability: act_probability}
+      }
+    end
+  end
+
+  NoulAnswer = Data.define(:noul, :act_probability) do
+    def type = "noul"
+
+    def to_h
+      {
+        type: type,
+        noul: noul,
+        rl_agent: {act_probability: act_probability}
+      }
+    end
+  end
+
+  Result = Data.define(:model, :answers, :usage) do
+    def [](key) = answers[key]
+
+    def to_h
+      {
+        model: model,
+        answers: answers.transform_values(&:to_h),
+        usage: usage.to_h
+      }
+    end
+  end
+end

data/lib/laya/sequence.rb

@@ -0,0 +1,97 @@
+require "json"
+
+module Laya
+  module Sequence
+    SpecialIds = Data.define(:cls, :sep, :mask, :pad, :mask_token)
+    Built = Data.define(:ids, :markers)
+
+    OPTION_TOKEN_CAP = 48
+    MIN_OPTION_BUDGET = 16
+    MIN_TOKENS_PER_OPTION = 4
+    MIN_HEAD_TOKENS = 8
+
+    module_function
+
+    def serialize_state(state) = state.is_a?(String) ? state : model_json(state)
+
+    # JSON with json.dumps separators (", " and ": "), the format the model was trained on.
+    def model_json(value)
+      case value
+      when Hash then "{" + value.map { |key, item| "#{JSON.generate(key.to_s)}: #{model_json(item)}" }.join(", ") + "}"
+      when Array then "[" + value.map { |item| model_json(item) }.join(", ") + "]"
+      else JSON.generate(value)
+      end
+    end
+
+    def build(encode, special_ids, state, question, max_len:, head_max_len:)
+      scrub = ->(text) { text.gsub(special_ids.mask_token, " ") }
+
+      head_ids = encode.call("#{question.type} question: #{scrub.call(question.instructions)}")
+      option_ids = question.options.map do |option|
+        [special_ids.mask] + encode.call(" " + scrub.call(option)).first(OPTION_TOKEN_CAP)
+      end
+
+      budget = head_max_len - option_ids.sum(&:size)
+      if budget < MIN_OPTION_BUDGET # too many / too long options: shrink every option text evenly
+        per_option = [MIN_TOKENS_PER_OPTION, (head_max_len - MIN_OPTION_BUDGET) / [1, option_ids.size].max].max
+        option_ids = option_ids.map { |ids| ids.first(per_option) }
+        budget = head_max_len - option_ids.sum(&:size)
+      end
+
+      ids = [special_ids.cls, *head_ids.first([MIN_HEAD_TOKENS, budget].max), special_ids.sep]
+      markers = option_ids.map { |option| ids.size.tap { ids.concat(option) } }
+      ids << special_ids.sep
+
+      room = [0, max_len - ids.size - 1].max
+      ids.concat(encode.call(scrub.call(serialize_state(state))).first(room))
+      ids << special_ids.sep
+
+      Built.new(ids: ids.first(max_len), markers: markers.select { |marker| marker < max_len })
+    end
+
+    def collate(rows, pad:)
+      length = rows.map { |built, _| built.ids.size }.max
+      width = rows.map { |built, _| built.markers.size }.max
+
+      {
+        input_ids: rows.map { |built, _| built.ids + [pad] * (length - built.ids.size) },
+        attention_mask: rows.map { |built, _| [1] * built.ids.size + [0] * (length - built.ids.size) },
+        marker_pos: rows.map { |built, _| built.markers + [0] * (width - built.markers.size) },
+        marker_mask: rows.map { |built, _| [true] * built.markers.size + [false] * (width - built.markers.size) },
+        qtype: rows.map { |_, type_id| type_id }
+      }
+    end
+
+    def temp_bucket(type, option_count)
+      size =
+        if option_count <= 2 then "2"
+        elsif option_count <= 5 then "3-5"
+        elsif option_count <= 10 then "6-10"
+        else "11+"
+        end
+
+      "#{type}:#{size}"
+    end
+
+    def temperature(model_config, type, option_count)
+      model_config.fetch("temperature_by_options", {})[temp_bucket(type, option_count)] ||
+        model_config.fetch("temperature", [])[Questions::TYPES.fetch(type)] ||
+        1.0
+    end
+
+    def softmax(logits)
+      max = logits.max
+      exponentials = logits.map { |logit| Math.exp(logit - max) }
+      sum = exponentials.sum
+
+      exponentials.map { |exponential| exponential / sum }
+    end
+
+    def confidence(probabilities)
+      return 1.0 if probabilities.size < 2
+
+      entropy = -probabilities.sum { |probability| probability * Math.log([probability, 1e-12].max) }
+      1 - entropy / Math.log(probabilities.size)
+    end
+  end
+end

data/lib/laya/session.rb

@@ -0,0 +1,38 @@
+require "json"
+require "onnxruntime"
+
+module Laya
+  # The loaded model: laya_config.json, the tokenizer and the ONNX Runtime session.
+  class Session
+    OUTPUTS = %w[logits act_probs].freeze
+
+    attr_reader :model_config, :tokenizer
+
+    def initialize(dir, providers:, session_options: {})
+      @model_config = JSON.parse(File.read(File.join(dir, "laya_config.json")))
+      @tokenizer = Tokenizer.new(dir)
+      options = {graph_optimization_level: :all}.merge(session_options.transform_keys(&:to_sym))
+      @onnx = OnnxRuntime::InferenceSession.new(File.join(dir, "laya.onnx"), providers: providers, **options)
+    rescue OnnxRuntime::Error, JSON::ParserError, SystemCallError => e
+      raise ModelError, "could not load the model from #{dir}: #{e.message}"
+    end
+
+    def special_ids = tokenizer.special_ids
+
+    def encode(text) = tokenizer.encode(text)
+
+    def max_len = model_config.fetch("max_len")
+
+    def head_max_len = model_config.fetch("head_max_len")
+
+    # inputs: the Hash from Sequence.collate. Returns [logits [B,K], act_probs [B,2]] as nested Arrays.
+    def run(inputs)
+      logits, act_probs = @onnx.run(OUTPUTS, inputs)
+      raise ModelError, "unexpected model outputs (expected logits and act_probs)" unless logits.is_a?(Array) && act_probs.is_a?(Array)
+
+      [logits, act_probs]
+    rescue OnnxRuntime::Error => e
+      raise ModelError, "inference failed: #{e.message}"
+    end
+  end
+end

data/lib/laya/tasks.rb

@@ -0,0 +1,16 @@
+require "rake"
+require "laya"
+
+namespace :laya do
+  desc "Download the Laya model files into the cache"
+  task :download do
+    status = Laya::CLI.new.run(["download"])
+    exit(status) unless status.zero?
+  end
+
+  desc "Print the directory holding the Laya model files"
+  task :path do
+    status = Laya::CLI.new.run(["path"])
+    exit(status) unless status.zero?
+  end
+end

data/lib/laya/tokenizer.rb

@@ -0,0 +1,25 @@
+require "tokenizers"
+
+module Laya
+  # The checkpoint's ModernBERT tokenizer and the special ids the sequence layout needs.
+  class Tokenizer
+    attr_reader :special_ids
+
+    def initialize(dir)
+      @tokenizer = Tokenizers.from_file(File.join(dir, "tokenizer", "tokenizer.json"))
+      @special_ids = Sequence::SpecialIds.new(
+        cls: token_id("[CLS]"),
+        sep: token_id("[SEP]"),
+        mask: token_id("[MASK]"),
+        pad: token_id("[PAD]"),
+        mask_token: "[MASK]"
+      )
+    end
+
+    def encode(text) = @tokenizer.encode(text, add_special_tokens: false).ids
+
+    private
+
+    def token_id(token) = @tokenizer.token_to_id(token) || raise(ModelError, "special token #{token} missing from tokenizer")
+  end
+end

data/lib/laya/version.rb

@@ -0,0 +1,3 @@
+module Laya
+  VERSION = "0.1.0"
+end

data/lib/laya.rb

@@ -0,0 +1,40 @@
+require_relative "laya/version"
+require_relative "laya/errors"
+require_relative "laya/configuration"
+require_relative "laya/questions"
+require_relative "laya/sequence"
+require_relative "laya/result"
+require_relative "laya/tokenizer"
+require_relative "laya/session"
+require_relative "laya/downloader"
+require_relative "laya/client"
+require_relative "laya/cli"
+
+module Laya
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # A client with the global config plus overrides. Cheap: the model loads on first use or load!.
+    def new(**overrides)
+      Client.new(config.merge(**overrides))
+    end
+
+    # Fetch the model files without loading them (Docker builds, CI caches). Returns the directory.
+    def download(**overrides)
+      Downloader.new(config.merge(**overrides).validate!).call
+    end
+  end
+end
+
+require_relative "laya/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: laya
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eduardo Hernandez
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: onnxruntime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: tokenizers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: Typed decisions (choice, score, noul) with calibrated probabilities in
+  one forward pass. A Ruby port of @receptron/laya on top of the onnxruntime and tokenizers
+  gems.
+email:
+- eduardoghdez.io@gmail.com
+executables:
+- laya
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/laya
+- lib/laya.rb
+- lib/laya/cli.rb
+- lib/laya/client.rb
+- lib/laya/configuration.rb
+- lib/laya/downloader.rb
+- lib/laya/errors.rb
+- lib/laya/questions.rb
+- lib/laya/railtie.rb
+- lib/laya/result.rb
+- lib/laya/sequence.rb
+- lib/laya/session.rb
+- lib/laya/tasks.rb
+- lib/laya/tokenizer.rb
+- lib/laya/version.rb
+homepage: https://github.com/EduardoGHdez/laya
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/EduardoGHdez/laya
+  changelog_uri: https://github.com/EduardoGHdez/laya/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/EduardoGHdez/laya/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Run the Laya System-1 decision model from Ruby via ONNX Runtime
+test_files: []