ruby-laya 0.1.0

data/lib/laya/tokenizer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require "tokenizers"
+
+module Laya
+  # Thin wrapper over the Hugging Face `tokenizers` gem exposing what sequence construction
+  # needs: the special tokens and ids of a checkpoint, `encode_ids` (no special tokens) and a
+  # padded batch encoder for the embedding helper.
+  class Tokenizer
+    SPECIAL = %w[mask cls sep pad].freeze
+    CANDIDATES = {
+      "mask" => ["[MASK]", "<mask>"],
+      "cls" => ["[CLS]", "<s>", "<cls>", "<bos>"],
+      "sep" => ["[SEP]", "</s>", "<sep>", "<eos>"],
+      "pad" => ["[PAD]", "<pad>"]
+    }.freeze
+
+    attr_reader :inner, :mask_token, :cls_token, :sep_token, :pad_token,
+                :mask_token_id, :cls_token_id, :sep_token_id, :pad_token_id
+
+    # Load `tokenizer.json` plus the special-token names from `tokenizer_config.json` /
+    # `special_tokens_map.json` in `dir`.
+    def self.from_dir(dir)
+      json = File.join(dir, "tokenizer.json")
+      raise ModelNotFoundError, "tokenizer.json not found in #{dir}" unless File.exist?(json)
+
+      specials = {}
+      ["special_tokens_map.json", "tokenizer_config.json"].each do |name|
+        path = File.join(dir, name)
+        next unless File.exist?(path)
+
+        cfg = JSON.parse(File.read(path))
+        SPECIAL.each do |kind|
+          value = cfg["#{kind}_token"]
+          value = value["content"] if value.is_a?(Hash)
+          specials[kind] = value if value.is_a?(String) && !value.empty?
+        end
+      end
+      new(Tokenizers.from_file(json), **specials.transform_keys { |k| :"#{k}_token" })
+    end
+
+    def initialize(inner, mask_token: nil, cls_token: nil, sep_token: nil, pad_token: nil)
+      @inner = inner
+      @lock = Mutex.new
+      @mask_token = resolve("mask", mask_token)
+      @cls_token = resolve("cls", cls_token)
+      @sep_token = resolve("sep", sep_token)
+      @pad_token = resolve("pad", pad_token)
+      @mask_token_id = @inner.token_to_id(@mask_token)
+      @cls_token_id = @inner.token_to_id(@cls_token)
+      @sep_token_id = @inner.token_to_id(@sep_token)
+      @pad_token_id = @inner.token_to_id(@pad_token)
+    end
+
+    # Token ids for `text`, without special tokens (what `tok(text, add_special_tokens=False)` gives).
+    def encode_ids(text)
+      @inner.encode(text, add_special_tokens: false).ids
+    end
+
+    # Tokens for `text`, without special tokens.
+    def tokenize(text)
+      @inner.encode(text, add_special_tokens: false).tokens
+    end
+
+    def decode(ids, skip_special_tokens: true)
+      @inner.decode(ids, skip_special_tokens: skip_special_tokens)
+    end
+
+    def vocab_size
+      @inner.vocab_size
+    end
+
+    # Encode several texts with special tokens, truncated to `max_length` and padded to the
+    # longest. Returns {"input_ids" => [[...]], "attention_mask" => [[...]]}.
+    def encode_batch(texts, max_length: 512)
+      @lock.synchronize do
+        @inner.enable_truncation(max_length)
+        @inner.enable_padding(pad_id: @pad_token_id, pad_token: @pad_token)
+        begin
+          encodings = @inner.encode_batch(texts, add_special_tokens: true)
+        ensure
+          @inner.no_truncation
+          @inner.no_padding
+        end
+        { "input_ids" => encodings.map(&:ids), "attention_mask" => encodings.map(&:attention_mask) }
+      end
+    end
+
+    private
+
+    def resolve(kind, explicit)
+      candidates = explicit ? [explicit] + CANDIDATES[kind] : CANDIDATES[kind]
+      found = candidates.find { |c| !@inner.token_to_id(c).nil? }
+      return found if found
+
+      raise IncompatibleModelError,
+            "tokenizer has no #{kind} token (tried #{candidates.inspect}); check tokenizer_config.json"
+    end
+  end
+end

data/lib/laya/training.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Laya
+  # The reward and target arithmetic behind Laya's training, ported so a Ruby process can score
+  # or audit a checkpoint's calibration. Training itself lives upstream; these are the pure
+  # functions, over plain Arrays.
+  module Training
+    module_function
+
+    # The strictly proper scoring rule Laya is trained against: log score plus spherical score,
+    # minus a ranked probability score for ordinal questions.
+    #
+    # `reported` and `targets` are Arrays of distributions, `qtypes` the question type per row
+    # (a name or its index), and `mask` marks the valid options of each row.
+    def proper_reward(reported, targets, qtypes, mask = nil, spherical_weight: 0.5,
+                      rps_weight: 1.0, log_floor: -9.21)
+      reported.each_with_index.map do |row, i|
+        valid = if mask
+                  mask[i].map { |flag| flag ? 1.0 : 0.0 }
+                else
+                  Array.new(row.length, 1.0)
+                end
+        masked = row.each_with_index.map { |value, j| value * valid[j] }
+        target = targets[i]
+        reward = log_score(masked, target, log_floor) +
+                 (spherical_weight * spherical_score(masked, target))
+        next reward unless score_question?(qtypes[i])
+
+        reward - (rps_weight * ranked_probability_score(masked, target, valid))
+      end
+    end
+
+    def log_score(reported, target, log_floor)
+      reported.each_with_index.sum do |value, i|
+        target[i] * [Math.log([value, 1e-12].max), log_floor].max
+      end
+    end
+
+    def spherical_score(reported, target)
+      norm = Math.sqrt(reported.sum { |value| value * value })
+      reported.each_with_index.sum { |value, i| target[i] * value } / [norm, 1e-9].max
+    end
+
+    def ranked_probability_score(reported, target, valid)
+      options = [valid.sum, 2.0].max
+      reported_cdf = cumulative(reported)
+      target_cdf = cumulative(target)
+      squared = reported_cdf.each_with_index.sum do |value, i|
+        ((value - target_cdf[i])**2) * valid[i]
+      end
+      squared / (options - 1)
+    end
+
+    def cumulative(values)
+      total = 0.0
+      values.map { |value| total += value }
+    end
+
+    def score_question?(qtype)
+      index = qtype.is_a?(Integer) ? qtype : QTYPES[qtype.to_s]
+      index == QTYPES["score"]
+    end
+
+    # TD(lambda) targets for multi-turn conversation trajectories.
+    #
+    # `batch` holds "target" (a `[false, true]` pair per row) and, for trajectories, "ep_group"
+    # and "ep_step". Without groups the targets are returned unchanged.
+    def td_lambda_targets(p_true, batch, lam: 1.0)
+      targets = Util.get(batch, "target").map(&:dup)
+      groups = Util.get(batch, "ep_group")
+      return targets if groups.nil?
+
+      steps = Util.get(batch, "ep_step")
+      groups.uniq.select { |group| group >= 0 }.sort.each do |group|
+        rows = groups.each_index.select { |i| groups[i] == group }.sort_by { |i| steps[i] }
+        discounted = targets[rows.last][1]
+        rows.each_index.reverse_each do |position|
+          row = rows[position]
+          unless position == rows.length - 1
+            discounted = ((1 - lam) * p_true[rows[position + 1]]) + (lam * discounted)
+          end
+          targets[row] = [1 - discounted, discounted]
+        end
+      end
+      targets
+    end
+  end
+end

data/lib/laya/util.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Laya
+  # Small helpers shared across modules. Question and state hashes may use string or symbol
+  # keys (Ruby callers naturally write `type: :choice`, JSON payloads arrive as strings), so
+  # every lookup goes through {get} which accepts both.
+  module Util
+    module_function
+
+    # Fetch `key` (a String) from `hash`, also trying its Symbol form.
+    def get(hash, key)
+      return nil unless hash.is_a?(Hash)
+      return hash[key] if hash.key?(key)
+
+      sym = key.to_sym
+      hash.key?(sym) ? hash[sym] : nil
+    end
+
+    # True when `hash` holds `key` as a String or a Symbol.
+    def key?(hash, key)
+      hash.is_a?(Hash) && (hash.key?(key) || hash.key?(key.to_sym))
+    end
+
+    # Assign `value` under `key`, keeping whichever key form (String/Symbol) the hash already uses.
+    def put(hash, key, value)
+      if hash.key?(key.to_sym) && !hash.key?(key)
+        hash[key.to_sym] = value
+      else
+        hash[key] = value
+      end
+      hash
+    end
+
+    # Deep-convert Symbol keys to Strings (values are left alone, apart from nested containers).
+    def stringify_keys(obj)
+      case obj
+      when Hash then obj.to_h { |k, v| [k.is_a?(Symbol) ? k.to_s : k, stringify_keys(v)] }
+      when Array then obj.map { |v| stringify_keys(v) }
+      else obj
+      end
+    end
+
+    # A callable: a Proc/Method or anything responding to #call.
+    def callable?(obj)
+      obj.respond_to?(:call)
+    end
+
+    # Convert a strictly positive integer argument, rejecting booleans, floats and strings.
+    def positive_int!(value, name)
+      unless value.is_a?(Integer) && value >= 1
+        raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}"
+      end
+
+      value
+    end
+  end
+end

data/lib/laya/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Laya
+  VERSION = "0.1.0"
+
+  # The upstream Python release this port tracks, feature for feature.
+  UPSTREAM_VERSION = "0.3.7"
+end

data/lib/laya.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "laya/version"
+require_relative "laya/errors"
+require_relative "laya/util"
+require_relative "laya/py_json"
+require_relative "laya/common"
+require_relative "laya/checkpoints"
+require_relative "laya/lang"
+require_relative "laya/email"
+require_relative "laya/presets"
+require_relative "laya/shortlist"
+require_relative "laya/training"
+require_relative "laya/hub"
+require_relative "laya/router"
+require_relative "laya/configuration"
+require_relative "laya/questions"
+
+# Laya: a fast, non-autoregressive System 1 decision engine with calibrated probabilities.
+#
+#   agent = Laya.load("convaiinnovations/laya")
+#   result = agent.predict({ "message" => "I was charged twice" }, Laya.triage_questions)
+#   result[:intent].choice          # => "refund"
+#   result[:churn_risk].probability # => 0.89
+#
+# Routing, language detection, email cleaning, the presets and the shortlist are pure Ruby and
+# load with the gem. The runtime, which needs ONNX Runtime, is loaded on first use, so a process
+# that only routes never opens a model.
+module Laya
+  # Absolute paths, so the runtime still autoloads when the gem was reached by require_relative
+  # rather than through the load path.
+  { Agent: "agent", RLAgent: "agent", Answer: "result", Ask: "ask", Decision: "decision",
+    Question: "question", Result: "result", Runtime: "runtime", Tokenizer: "tokenizer" }.each do |constant, file|
+    autoload constant, File.expand_path("laya/#{file}", __dir__)
+  end
+
+  # The shipped question sets, as decision classes:
+  #
+  #   Laya::Guard.decide(prompt).jailbreak?
+  #   Laya::Triage.decide(message).churn_risk.probability
+  #
+  # Each is a {Decision}, so it subclasses like any other and its questions are readable with
+  # `.questions`. The plain hashes are still there as `Laya.triage_questions` and friends.
+  def self.preset(questions)
+    Decision.define(questions)
+  end
+
+  class << self
+    # Load a checkpoint, by upstream model id or from a directory holding an ONNX export.
+    #
+    #   Laya.load("convaiinnovations/laya")                            # English
+    #   Laya.load("convaiinnovations/laya", subfolder: "multilingual") # 100+ languages
+    #   Laya.load("./my-export", device: "coreml")
+    #
+    # Given a block, the agent is closed when the block returns.
+    def load(model_id_or_path = Checkpoints::BUNDLE_REPO, **, &)
+      Agent.load(model_id_or_path, **, &)
+    end
+
+    # Ask questions about `state` without declaring a class for them.
+    #
+    #   Laya.ask(email)
+    #       .choice(:department, "Which team?", billing: "invoices", technical: "outages")
+    #       .noul(:refund, "Do they want money back?")
+    #       .decide
+    #
+    # Runs on the shared client unless given `client:`; see {Laya.configure}.
+    def ask(state, client: nil, **)
+      Ask.new(state, client: client, **)
+    end
+
+    # A {Router} that picks a checkpoint per request. Given a block, it is closed afterwards.
+    def router(**, &)
+      Router.open(**, &)
+    end
+
+    # --- language and script detection
+    def detect_language(state) = Lang.analyse(state)
+    def detect_script(text) = Lang.detect_script(text)
+    def english?(state) = Lang.english?(state)
+    def is_english(state) = Lang.english?(state)
+
+    # --- email
+    def clean_email_body(body, max_chars: 3000) = Email.clean_email_body(body, max_chars: max_chars)
+
+    def email_state(subject, body, sender: nil, clean: true, **extra)
+      Email.email_state(subject, body, sender: sender, clean: clean, **extra)
+    end
+
+    # --- question presets
+    def email_questions(categories = nil) = Presets.email_questions(categories)
+    def guard_questions = Presets.guard_questions
+    def moderation_questions = Presets.moderation_questions
+    def router_questions = Presets.router_questions
+    def triage_questions = Presets.triage_questions
+
+    # --- shortlist
+    def shortlist_choice(state, criteria, embed_fn, k: Shortlist::DEFAULT_SHORTLIST_K, instructions: nil)
+      Shortlist.shortlist_choice(state, criteria, embed_fn, k: k, instructions: instructions)
+    end
+
+    def predict_shortlist(agent, state, questions, embed_fn, k: Shortlist::DEFAULT_SHORTLIST_K, **)
+      Shortlist.predict_shortlist(agent, state, questions, embed_fn, k: k, **)
+    end
+
+    def embed_fn_from_agent(agent, max_length: nil, batch_size: 32)
+      Shortlist.embed_fn_from_agent(agent, max_length: max_length, batch_size: batch_size)
+    end
+
+    # --- rendering and calibration
+    def render_options(question) = Common.render_options(question)
+    def confidence_from_probs(probabilities, k) = Common.confidence_from_probs(probabilities, k)
+    def ece_score(confidences, correct, bins: 15) = Common.ece_score(confidences, correct, bins: bins)
+
+    # --- training arithmetic
+    def proper_reward(...) = Training.proper_reward(...)
+    def td_lambda_targets(...) = Training.td_lambda_targets(...)
+  end
+
+  # The shipped question sets, ready to ask. Declared last so {Decision} and {Presets} are both
+  # in place; each is a plain subclass, so `Laya::Guard.questions` and subclassing both work.
+  Triage = preset(Presets.triage_questions)
+  EmailTriage = preset(Presets.email_questions)
+  Guard = preset(Presets.guard_questions)
+  Moderation = preset(Presets.moderation_questions)
+  RequestRouting = preset(Presets.router_questions)
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: ruby-laya
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Valentino Stoll
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: onnxruntime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tokenizers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: |
+  Ruby port of Laya: typed decisions (choice, score, noul) over any state in a single
+  forward pass, with calibrated probabilities and a router that picks the right checkpoint
+  per request (English, multilingual, typed-decisions). Inference runs on ONNX Runtime
+  against exports of the published checkpoints, so installing needs no Python, no LibTorch
+  and no compiler. Language and script detection, email cleaning, workflow presets and the
+  embedding shortlist are pure Ruby.
+email:
+- v@codenamev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- NOTICE
+- README.md
+- lib/laya.rb
+- lib/laya/agent.rb
+- lib/laya/ask.rb
+- lib/laya/checkpoints.rb
+- lib/laya/common.rb
+- lib/laya/configuration.rb
+- lib/laya/decision.rb
+- lib/laya/email.rb
+- lib/laya/errors.rb
+- lib/laya/hub.rb
+- lib/laya/lang.rb
+- lib/laya/presets.rb
+- lib/laya/py_json.rb
+- lib/laya/question.rb
+- lib/laya/questions.rb
+- lib/laya/result.rb
+- lib/laya/router.rb
+- lib/laya/runtime.rb
+- lib/laya/shortlist.rb
+- lib/laya/tokenizer.rb
+- lib/laya/training.rb
+- lib/laya/util.rb
+- lib/laya/version.rb
+homepage: https://github.com/codenamev/ruby-laya
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://codenamev.github.io/ruby-laya
+  source_code_uri: https://github.com/codenamev/ruby-laya
+  changelog_uri: https://github.com/codenamev/ruby-laya/blob/main/CHANGELOG.md
+  documentation_uri: https://codenamev.github.io/ruby-laya
+  bug_tracker_uri: https://github.com/codenamev/ruby-laya/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: Fast, non-autoregressive System 1 decision engine with calibrated probabilities
+test_files: []