interscript 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '047058523934ce18616d22f657269aa926232df2739ddfa87577c0753d6921dd'
-  data.tar.gz: 7ae9aad06aac1f0c87a8581c58aedc229674a5e0113516a4532b665a7b3f69e4
+  metadata.gz: d563d6c5e8b2552d43b377d7c0637bc178a03bfa48ab8296c13de68269264266
+  data.tar.gz: f235d6abf2393cd6b7af75eb78960466f915f81a4d873c4db920ffe97a226bbd
 SHA512:
-  metadata.gz: 35b234e18f152088a43e072f428c563564ff6b594bf7bea471f07f761f936d206b9efaa4ba885180c0bf92010a3521fe5f0e6e5673825e35d225ff1611814805
-  data.tar.gz: 776266ef1babe566d4d95a16b637d26923ea1b1458738edcb3b5840d63aeed86b25af14203bb8d05c04733812b1e297f4c10c0f9fbbce1c2c08569ba0818f21a
+  metadata.gz: 494749273ef3a9d265c0ab4d5c622024f7cac93125a0a13c3f5773b24648d1a195c550371d2379e8ec2a96dbf63d9217dad24b24497df72f1afa6dfb4467c29f
+  data.tar.gz: 630e78cfd16a814c80b3a53441cfb48b7d82094c32be909e683727cfa4607a885455018be87bf3a8fa48c9efea7a4cd228612b8450c9f6d22bdb93e5fa9a7f8a

data/README.md

@@ -1,18 +1,91 @@
 image:https://github.com/interscript/interscript-ruby/actions/workflows/rake.yml/badge.svg["CI status", link="https://github.com/interscript/interscript-ruby/actions/workflows/rake.yml"]
-# Interscript
 
-Documentation is available directory higher in file README.adoc.
+# Interscript (Ruby)
 
-## Phonological layer (optional)
+The Ruby runtime for https://www.interscript.org[Interscript] —
+interoperable script conversion systems. Interscript turns the world's
+transliteration standards from paper tables into executable, verifiable
+software: authority schemes (BGN/PCGN, ISO, UN/UNGEGN, ALA-LC, ICAO,
+ODNI, ...) are encoded once in the ISC language, every runtime produces
+provably identical output, and neural models ship under the same proof
+regime — pinned artifacts, sha256 verification, frozen conformance
+vectors.
+
+== Install
+
+[source,sh]
+----
+gem install interscript
+----
+
+== Transliterate
+
+[source,sh]
+----
+interscript -s odni-ara-Arab-Latn-2015 ara-Arab.txt -o out.txt
+----
+
+[source,ruby]
+----
+require "interscript"
+
+Interscript.transliterate("odni-rus-Cyrl-Latn-2015", "привет")
+# => "privet"
+----
+
+== Neural models (Interscript::ML)
+
+The gem embeds the IMF v1 model runtime — resolve a model id through
+the interscript-models index, verify its sha256, and run ONNX
+inference locally:
+
+[source,ruby]
+----
+require "interscript/ml"
+
+Interscript::ML::Translator.new(model_file: "urd-diac-base-1.0")
+  .translate("...")
+----
+
+Runtime dependencies (onnxruntime, rubyzip, numo-narray) are optional
+and load lazily; a missing gem raises a `LoadError` naming it. The
+artifact contract and frozen conformance vectors live in
+https://github.com/interscript/interscript-models[interscript-models]
+(see its `conformance/CONFORMANCE.md`).
+
+== The phonological layer
 
 Some transliteration systems need their input vocalized before the map
 can apply (undiacritized Arabic, nikud-less Hebrew, unsegmented Thai).
 The stdlib ships adapters for this: the `secryst` function dispatches
-to a [secryst crystal](https://www.secryst.org) —
-`gem 'secryst'` (Ruby), `pip install secryst`, or `npm i secryst` —
+to a crystal runtime — `pip install secryst`, or `npm i secryst` —
 which resolves a model id through the
-[interscript-ml `models.yaml` index](https://github.com/interscript/interscript-ml)
-and runs sha256-verified ONNX inference locally. The gem has no
-interscript dependency: a crystal can be used standalone for any G2P
-need, and an engine without a crystal simply cannot execute maps that
-declare a vocalization step.
+https://github.com/interscript/interscript-models[models.yaml index]
+and runs sha256-verified ONNX inference locally. An engine without a
+crystal simply cannot execute maps that declare a vocalization step.
+
+== Development
+
+[source,sh]
+----
+bundle install
+bundle exec rake   # spec suite
+----
+
+`SKIP_JS=1 SKIP_PYTHON=1` exclude the cross-compiler *execution* specs
+(they need the monorepo's sibling js assets); that coverage is owned by
+the CI matrix that runs on every push.
+
+== Release
+
+Push a `v*` tag: the release workflow runs the spec suite, builds the
+gem, and publishes via RubyGems.org trusted publishing (OIDC). The
+`interscript-maps` dependency is pinned to the published lineage
+(`~> 2.5`), not derived from the gem version.
+
+== Project
+
+Purpose, architecture, and direction: see the
+https://github.com/interscript/interscript-models#direction-audit-2026-10[project
+direction] and https://github.com/interscript/interscript[the project
+monorepo].

data/lib/interscript/equivalence.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Interscript
+  # A3 (WO59): mechanical equivalence checking between two systems.
+  #
+  # Probes a sample set through both systems and reports the agreement
+  # ratio plus the minimal distinguishing samples. The sample set is
+  # caller-supplied or derived from the systems' own embedded tests.
+  class Equivalence
+    def self.check(first, second, samples:)
+      new(first, second).check(samples)
+    end
+
+    # Embedded test inputs of the given systems (the natural probe set
+    # for near-equivalent authorities).
+    def self.samples_from_tests(*codes)
+      codes.flat_map do |code|
+        Array(Interscript.parse(code).tests&.data).map(&:first).compact
+      end.uniq
+    end
+
+    def initialize(first, second)
+      @first = first
+      @second = second
+    end
+
+    def check(samples)
+      distinguishing = []
+      tested = 0
+      matched = 0
+      samples.each do |sample|
+        tested += 1
+        a = Interscript.transliterate(@first, sample)
+        b = Interscript.transliterate(@second, sample)
+        if a == b
+          matched += 1
+        else
+          distinguishing << {sample: sample, first: a, second: b}
+        end
+      end
+      ratio = tested.zero? ? 1.0 : matched.fdiv(tested)
+      {tested: tested, matched: matched, ratio: ratio,
+       distinguishing: distinguishing}
+    end
+  end
+end

data/lib/interscript/ml/byt5_onnx.rb

@@ -18,7 +18,7 @@ module Interscript::ML
       @pasts = @kv ? zero_pasts : {}
     end
 
-    def translate(text, max_seq_length: 256)
+    def translate(text, max_seq_length: 512)
       ids = IMF.encode(text)
       return "" if ids.length == 1 # only the trailing EOS: empty input
 
@@ -38,7 +38,9 @@ module Interscript::ML
     def build_session(graphs, name)
       path = File.join(@tmpdir, name)
       File.binwrite(path, graphs.fetch(name))
-      OnnxRuntime::Model.new(path)
+      # single-thread decode: the conformance contract is byte-exact
+      # across environments (WO79); multi-thread fp16 ties flip rows
+      OnnxRuntime::Model.new(path, intra_op_num_threads: 1)
     end
 
     def zero_pasts

data/lib/interscript/ml/imf.rb

@@ -42,7 +42,10 @@ module Interscript::ML
           next if token == PAD_ID || token == UNK_ID
           out << ((token - BYTE_OFFSET) % 256).chr
         end
-        out.force_encoding(Encoding::UTF_8)
+        # the python reference decodes with errors="replace": invalid
+        # bytes (mid-character sequence caps) become U+FFFD -- scrub to
+        # match byte-for-byte (the C1 matrix catch)
+        out.force_encoding(Encoding::UTF_8).scrub
       end
 
       def manifest(zip_path)

data/lib/interscript/ml/translator.rb

@@ -10,7 +10,7 @@ module Interscript::ML
       @model = Model.from_file(model_file)
     end
 
-    def translate(phrase, max_seq_length: 100)
+    def translate(phrase, max_seq_length: 512)
       return @model.translate(phrase, max_seq_length: max_seq_length) if @model.is_a?(Byt5Onnx)
 
       Interscript::ML.require_optional!("numo-narray", feature: "numo/narray")

data/lib/interscript/stdlib/functions/secryst_adapter.rb

@@ -23,6 +23,17 @@ class Interscript::Stdlib
           end
         end
 
+        # The 126e8e1 split lost this body but kept the call — an ML
+        # funcall without a provisioned model crashed with an accidental
+        # NoMethodError instead of a named provisioning error (A4).
+        def require_secryst!
+          require "interscript/ml/translator"
+        rescue LoadError => e
+          raise LoadError,
+            "the secryst funcall requires Interscript::ML — " \
+            "loading failed: #{e.message}"
+        end
+
         def build_translator(model_key)
           Interscript.secryst_index_locations.each do |remote|
             Interscript::ML::Provisioning.add_remote(remote)

data/lib/interscript/version.rb

@@ -1,3 +1,3 @@
 module Interscript
-  VERSION = "3.2.0"
+  VERSION = "3.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interscript
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.2.1
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -124,6 +124,7 @@ files:
 - lib/interscript/dsl/stage.rb
 - lib/interscript/dsl/symbol_mm.rb
 - lib/interscript/dsl/tests.rb
+- lib/interscript/equivalence.rb
 - lib/interscript/interpreter.rb
 - lib/interscript/isc.rb
 - lib/interscript/isc/codemod.rb