latticerb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5250f7a9782b3db18aa0002eda4b3194f1092d0a832e4b764ce1c49cbb8f202
-  data.tar.gz: 7f2a83e342e5498728f3fac15d20e6706859a10a7b2697b666ccb0e67e72bccf
+  metadata.gz: e1cd02dabe1821baf68283ad31fb90aa688bd1642943fa2f5d914cad759389fe
+  data.tar.gz: 4c1f1118737aa6fe2a2917db077fd6badf3f03fc169c110bf5c5255a1b8376aa
 SHA512:
-  metadata.gz: 51b3c0f8c486a628f9e4274d2a6f66b2f79a7eb75c519e892c760cd3c65cdebedb005cd845189505f29bcac63ac716c6f3d0d249f38fb4c3a5a8a96d4543a381
-  data.tar.gz: 781caca48f95fc5ef3d8562c717ebe4dd2b987630a6ca2d5a886f51a8db0c06abdfeb4f19713531133c3e27a9149861821ff093385ad8b2f649d9ef5b118aa74
+  metadata.gz: '087a54e0c2896d3a71ffb4eb8737dbf3ad2a0e04ed36682d8fa232cee7b7a131f706cdf5456277c2c6b3eef59446c263dd8ff4277879345160b386c64b06f8d0'
+  data.tar.gz: 0fceafc2667a8042a38c7dc292b42d185b7305cf57cbf2a7d21bab7d1915723d0fd5fb33c27a444a349b9bff148357a7313f55542af393a69cf69402551426f3

data/README.md

@@ -54,7 +54,7 @@ run = Lattice.generate(
 
 run.scenarios        # array of { name => value } hashes
 run.coverage_curve   # cumulative coverage per scenario
-run.to_table         # human-readable table (also: to_json_output, to_csv, to_summary)
+run.to_table         # human-readable table (also: to_json_output, to_yaml_output, to_csv, to_summary)
 
 Lattice.scenarios(file: "...")  # shortcut straight to the hashes
 Lattice.validate!(schema)       # raises Lattice::ValidationError / Lattice::ConstraintError
@@ -70,6 +70,7 @@ The gem installs a `lattice` executable mirroring the Python CLI:
 cat schema.yaml | lattice validate
 cat schema.yaml | lattice generate                 # JSON by default
 lattice generate schema.yaml --format table
+lattice generate schema.yaml --format yaml         # same content as JSON, for hand-edited files
 lattice generate schema.yaml --strength 3 --seed 7
 lattice agent instructions                          # coding-agent integration guidance
 ```
@@ -98,11 +99,22 @@ constraints:
 
 Constraint types: `invalid_pair`, `higher_order`, `forward_dep`, `bidirectional`, `conditional`, `forced`. Run `lattice agent instructions` for the full reference.
 
+### Values keep their text
+
+Every value in a schema (the model name, parameter names and values, and constraint references) is used exactly as written. In YAML, unquoted `1.10`, `0x1F`, `.inf` or `2026-10-26T10:00:00Z` stay as typed rather than being turned into numbers or dates. The exceptions:
+
+- Unquoted `yes`, `no`, `on`, `off`, `true` and `false` (lowercase, Capitalized or UPPERCASE) become `true` / `false`, and an empty value, `~` or `null` becomes `null`. Quote them (`"yes"`) to keep the word.
+- JSON integers are written in plain decimal form (`-0` becomes `0`).
+
+`strength` must be a whole number, and `weights` decimal numbers such as `0.7` or `1e-3`. Anchors, aliases and `<<` merge keys work; a key written twice, more than one YAML document, or a tag other than YAML's standard ones is an error.
+
+Changed in 0.3.0: earlier versions converted unquoted numbers and dates, so `0x1F` became `31`, `1.10` became `1.1`, and some values (`.inf`, timestamps) came out differently in the Ruby and Python implementations.
+
 ## Parity with the Python implementation
 
 The generator seeds an MT19937 RNG that reproduces CPython's `random.Random` bit-for-bit, so both implementations walk the same candidate pools and pick the same rows. `test/python_parity_test.rb` shells out to the Python implementation (checkout via `LATTICE_PYTHON_SRC`, or an installed `lattice-cli`) and asserts byte-equal output across formats, seeds, strengths, and stopping rules; it skips when no Python implementation is available.
 
-YAML is parsed with Psych here and PyYAML in Python — both YAML 1.1 (libyaml lineage), so common scalars including unquoted `yes`/`no`/`on`/`off` booleans resolve identically. Exotic YAML 1.1 corners (e.g. sexagesimal numbers) may differ between the two parsers; quote ambiguous scalars or use JSON if in doubt.
+Schemas are read with Psych here and PyYAML in Python, but both implementations build values from the parsed text with the same rules (see "Values keep their text"), so a schema means the same thing in either. `test/fixtures/scalar_text.*` pins those rules for both.
 
 ## Development
 

data/lib/lattice/cli.rb

@@ -65,7 +65,7 @@ module Lattice
       }
       parser = OptionParser.new do |opts|
         opts.on("--strength STRENGTH", Integer)
-        opts.on("--format FORMAT", %w[table json csv summary])
+        opts.on("--format FORMAT", %w[table json csv summary yaml])
         opts.on("--seed SEED", Integer)
         opts.on("--pool-size SIZE", Integer) { |value| options[:pool_size] = value }
         opts.on("--max-rows ROWS", Integer) { |value| options[:max_rows] = value }

data/lib/lattice/formatters.rb

@@ -7,8 +7,9 @@ require_relative "ipog"
 require_relative "model"
 
 module Lattice
-  # Output rendering. Table, JSON, CSV, and summary formats are byte-identical
-  # to the Python implementation's output for the same model and result.
+  # Output rendering. Table, JSON, CSV, summary, and YAML formats are
+  # byte-identical to the Python implementation's output for the same model
+  # and result.
   module Formatters
     extend self
 
@@ -18,6 +19,7 @@ module Lattice
       when "json" then format_json(model, result, seed:)
       when "csv" then format_csv(model, result)
       when "summary" then format_summary(model, result)
+      when "yaml" then format_yaml(model, result, seed:)
       else
         raise ArgumentError, "Unknown format `#{output_format}`."
       end
@@ -77,16 +79,81 @@ module Lattice
           }
         end
       }
-      JSON.pretty_generate(payload, ascii_only: true)
+      # Python's json.dumps also escapes DEL, which Ruby's ascii_only leaves raw.
+      JSON.pretty_generate(payload, ascii_only: true).gsub("\u007f", "\\u007f")
     end
 
-    def format_csv(model, result)
-      CSV.generate(row_sep: "\r\n") do |csv|
-        csv << model.parameter_names
-        named_rows(model, result).each do |row|
-          csv << model.parameter_names.map { |name| row[name] }
+    # Same content as format_json, written by hand in one fixed style so Ruby
+    # and Python emit identical bytes (Psych and PyYAML each quote and wrap
+    # differently). Every string is double-quoted, so no value can be read
+    # back as a boolean, null, number or date.
+    def format_yaml(model, result, seed:)
+      last_point = result.coverage_curve.last
+      lines = [
+        "meta:",
+        "  model_name: #{yaml_string(model.model_name)}",
+        "  strength: #{model.strength}",
+        "  test_count: #{result.rows.length}",
+        "  exhaustive_count: #{model.exhaustive_count}",
+        "  reduction: #{yaml_string(reduction_label(model.exhaustive_count, result.rows.length))}",
+        "  coverage: #{yaml_string(last_point ? format('%.1f%%', last_point.cumulative_pct) : '0.0%')}",
+        "  seed: #{seed.nil? ? 'null' : seed}"
+      ]
+
+      if result.coverage_curve.empty?
+        lines << "coverage_curve: []"
+      else
+        lines << "coverage_curve:"
+        result.coverage_curve.each do |point|
+          lines << "  - scenario: #{point.scenario}"
+          lines << "    cumulative_pct: #{JSON.generate(point.cumulative_pct)}"
+        end
+      end
+
+      rows = named_rows(model, result)
+      if rows.empty?
+        lines << "scenarios: []"
+      else
+        lines << "scenarios:"
+        rows.each_with_index do |row, index|
+          lines << "  - id: #{index + 1}"
+          lines << "    values:"
+          model.parameter_names.each do |name|
+            lines << "      #{yaml_string(name)}: #{yaml_string(row[name])}"
+          end
         end
-      end.strip
+      end
+      lines.join("\n")
+    end
+
+    YAML_ESCAPES = {
+      "\"" => "\\\"", "\\" => "\\\\", "\b" => "\\b", "\t" => "\\t", "\n" => "\\n", "\f" => "\\f", "\r" => "\\r"
+    }.freeze
+
+    # Characters escaped inside a double-quoted YAML string: the quote and
+    # backslash, C0 controls, DEL, C1 controls (U+0085 would otherwise fold to
+    # a space), the Unicode line and paragraph separators, the byte-order mark,
+    # and the two noncharacters YAML cannot hold. Everything else is written as
+    # UTF-8, so accented letters and emoji stay readable.
+    YAML_ESCAPED_CHARS = /["\\\u0000-\u001f\u007f-\u009f\u2028\u2029\ufeff\ufffe\uffff]/
+
+    def yaml_string(value)
+      escaped = value.gsub(YAML_ESCAPED_CHARS) do |char|
+        YAML_ESCAPES.fetch(char) { format("\\u%04x", char.ord) }
+      end
+      "\"#{escaped}\""
+    end
+
+    # Matches Python's csv.writer: empty fields are written bare, except a row
+    # made of a single empty field, which is written as "" so it isn't a blank
+    # line.
+    def format_csv(model, result)
+      records = [model.parameter_names] + named_rows(model, result).map do |row|
+        model.parameter_names.map { |name| row[name] }
+      end
+      records.map do |record|
+        record == [""] ? "\"\"\r\n" : CSV.generate_line(record, row_sep: "\r\n", quote_empty: false)
+      end.join.strip
     end
 
     def headline(model, result)

data/lib/lattice/parser.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
-require "yaml"
-
 require_relative "model"
+require_relative "schema_text"
 
 module Lattice
   class ModelIOError < StandardError; end
@@ -78,7 +76,7 @@ module Lattice
 
       errors = []
       loaders.each do |loader|
-        return loader == :json ? JSON.parse(text) : safe_load_yaml(text)
+        return loader == :json ? SchemaText.load_json(text) : SchemaText.load_yaml(text)
       rescue StandardError => e
         errors << e.message
       end
@@ -86,10 +84,6 @@ module Lattice
       raise ModelIOError, "Unable to parse model from `#{source_name}`: #{errors.join('; ')}"
     end
 
-    def safe_load_yaml(text)
-      YAML.safe_load(text, permitted_classes: [Date, Time], aliases: true)
-    end
-
     def parse_parameters(raw_parameters, errors)
       parameters = {}
       if raw_parameters.nil?
@@ -351,8 +345,9 @@ module Lattice
       end
 
       parsed = []
-      raw_weights.each do |weight|
-        unless weight.is_a?(Numeric)
+      raw_weights.each do |raw_weight|
+        weight = parse_number(raw_weight)
+        if weight.nil?
           errors << "`weights` for parameter `#{parameter_name}` must be numeric."
           return nil
         end
@@ -360,24 +355,37 @@ module Lattice
           errors << "`weights` for parameter `#{parameter_name}` must be greater than zero."
           return nil
         end
-        parsed << weight.to_f
+        parsed << weight
       end
       parsed
     end
 
+    DECIMAL_TEXT = /\A[-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?\z/
+    INTEGER_TEXT = /\A[-+]?[0-9]+\z/
+
+    # A finite number, from a Ruby number or decimal text such as "0.7" or
+    # "1e-3" (schema files keep numbers as text). Booleans are not numbers.
+    def parse_number(raw)
+      number =
+        case raw
+        when Integer, Float then raw.to_f
+        when String then DECIMAL_TEXT.match?(raw) ? Float(raw) : nil
+        end
+      number&.finite? ? number : nil
+    end
+
     def parse_strength(raw_strength, parameter_count, errors)
       strength =
         case raw_strength
         when nil then 2
-        when Numeric then raw_strength.to_i
-        else
-          begin
-            Integer(raw_strength)
-          rescue TypeError, ArgumentError
-            errors << "`strength` must be an integer."
-            return 2
-          end
+        when Integer then raw_strength
+        when Float then raw_strength.finite? ? raw_strength.to_i : nil
+        when String then INTEGER_TEXT.match?(raw_strength) ? Integer(raw_strength, 10) : nil
         end
+      if strength.nil?
+        errors << "`strength` must be an integer."
+        return 2
+      end
 
       errors << "`strength` must be at least 1." if strength < 1
       errors << "`strength` cannot exceed the number of parameters." if parameter_count.positive? && strength > parameter_count

data/lib/lattice/schema_text.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+require "psych"
+
+module Lattice
+  # Reads schema text (JSON or YAML) into plain Hashes, Arrays and Strings,
+  # keeping every value as the text the user wrote. `1.10` stays "1.10",
+  # `0x1F` stays "0x1F" and `2026-10-26T10:00:00Z` stays as typed, instead of
+  # being converted to a number or time and printed back differently by Ruby
+  # and Python. The only conversions:
+  #
+  # - unquoted yes/no/on/off/true/false (in the case forms below) become
+  #   true/false, and an empty value, ~ or null becomes nil;
+  # - JSON integers are written in plain decimal form.
+  #
+  # The Python implementation (lattice.schema_text) follows the same rules, and
+  # test/fixtures/scalar_text.* pins the result for both.
+  module SchemaText
+    extend self
+
+    class SyntaxError < StandardError; end
+
+    TRUE_WORDS = %w[yes Yes YES true True TRUE on On ON].freeze
+    FALSE_WORDS = %w[no No NO false False FALSE off Off OFF].freeze
+    NULL_WORDS = ["", "~", "null", "Null", "NULL"].freeze
+
+    YAML_TAG_PREFIX = "tag:yaml.org,2002:"
+    STR_TAGS = ["!", "#{YAML_TAG_PREFIX}str"].freeze
+    SCALAR_TAGS = %w[str int float bool null timestamp binary merge value].map { |name| "#{YAML_TAG_PREFIX}#{name}" }.freeze
+    SEQUENCE_TAGS = [nil, "!", "#{YAML_TAG_PREFIX}seq"].freeze
+    MAPPING_TAGS = [nil, "!", "#{YAML_TAG_PREFIX}map"].freeze
+
+    # Hands JSON floats back as their source text.
+    class RawNumber
+      def self.new(text) = text
+    end
+
+    # Rejects a key written twice. json 2.x calls []= on a custom object_class;
+    # json 3.x checks duplicates itself when allow_duplicate_key is false.
+    class UniqueHash < Hash
+      def []=(key, value)
+        raise JSON::ParserError, "duplicate key `#{key}`" if key?(key)
+
+        super
+      end
+    end
+
+    def load_json(text)
+      json_strings(
+        JSON.parse(text, decimal_class: RawNumber, object_class: UniqueHash, allow_duplicate_key: false)
+      )
+    end
+
+    def load_yaml(text)
+      documents = Psych.parse_stream(text).children
+      raise SyntaxError, "expected a single YAML document, found #{documents.length}" if documents.length > 1
+      return nil if documents.empty?
+
+      yaml_value(documents.first.root, {})
+    end
+
+    private
+
+    def json_strings(value)
+      case value
+      when Hash then value.to_h { |key, child| [key, json_strings(child)] }
+      when Array then value.map { |child| json_strings(child) }
+      when Integer then value.to_s
+      else value
+      end
+    end
+
+    # `anchors` maps each anchor to its value once built; an anchor still
+    # being built (nil value) means an alias points back into itself.
+    def yaml_value(node, anchors)
+      return yaml_alias(node, anchors) if node.is_a?(Psych::Nodes::Alias)
+
+      anchors[node.anchor] = nil if node.anchor
+      value =
+        case node
+        when Psych::Nodes::Scalar then yaml_scalar(node)
+        when Psych::Nodes::Sequence
+          check_tag(node.tag, SEQUENCE_TAGS)
+          node.children.map { |child| yaml_value(child, anchors) }
+        when Psych::Nodes::Mapping then yaml_mapping(node, anchors)
+        end
+      anchors[node.anchor] = [value] if node.anchor
+      value
+    end
+
+    def yaml_alias(node, anchors)
+      built = anchors.fetch(node.anchor) { raise SyntaxError, "unknown alias `*#{node.anchor}`" }
+      raise SyntaxError, "recursive alias" if built.nil?
+
+      built.first
+    end
+
+    def yaml_scalar(node)
+      check_tag(node.tag, [nil, "!"] + SCALAR_TAGS)
+      return node.value unless node.style == Psych::Nodes::Scalar::PLAIN && !STR_TAGS.include?(node.tag)
+      return true if TRUE_WORDS.include?(node.value)
+      return false if FALSE_WORDS.include?(node.value)
+      return nil if NULL_WORDS.include?(node.value)
+
+      node.value
+    end
+
+    # Keys from `<<` merges come first, earlier sources winning; the
+    # mapping's own keys then override them. A key written twice is an error.
+    def yaml_mapping(node, anchors)
+      check_tag(node.tag, MAPPING_TAGS)
+      merged = {}
+      own = {}
+      seen_merge = false
+      node.children.each_slice(2) do |key_node, value_node|
+        key = yaml_value(key_node, anchors)
+        raise SyntaxError, "mapping keys must be scalars" if key.is_a?(Enumerable)
+
+        if merge_key?(key_node)
+          raise SyntaxError, "duplicate key `<<`" if seen_merge
+
+          seen_merge = true
+          merge_sources(yaml_value(value_node, anchors)).each do |source|
+            source.each { |merged_key, merged_value| merged[merged_key] = merged_value unless merged.key?(merged_key) }
+          end
+          next
+        end
+
+        raise SyntaxError, "duplicate key `#{Lattice.normalize_scalar(key)}`" if own.key?(key)
+
+        own[key] = yaml_value(value_node, anchors)
+      end
+      merged.merge(own)
+    end
+
+    def merge_key?(key_node)
+      key_node.is_a?(Psych::Nodes::Scalar) && key_node.style == Psych::Nodes::Scalar::PLAIN && key_node.value == "<<" &&
+        [nil, "#{YAML_TAG_PREFIX}merge"].include?(key_node.tag)
+    end
+
+    def merge_sources(value)
+      sources = [value].flatten(1)
+      raise SyntaxError, "merge key `<<` needs a mapping or a list of mappings" unless sources.all?(Hash)
+
+      sources
+    end
+
+    def check_tag(tag, allowed)
+      raise SyntaxError, "unsupported YAML tag `#{tag}`" unless allowed.include?(tag)
+    end
+  end
+end

data/lib/lattice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lattice
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/lattice.rb

@@ -32,6 +32,7 @@ module Lattice
     def to_json_output = Formatters.render_output(model, result, output_format: "json", seed:)
     def to_csv = Formatters.render_output(model, result, output_format: "csv", seed:)
     def to_summary = Formatters.render_output(model, result, output_format: "summary", seed:)
+    def to_yaml_output = Formatters.render_output(model, result, output_format: "yaml", seed:)
   end
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: latticerb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tyler Klose
@@ -56,6 +56,7 @@ files:
 - lib/lattice/resources/generic/lattice-workflow/SKILL.md
 - lib/lattice/resources/generic/lattice-workflow/references/modeling-rules.md
 - lib/lattice/resources/generic/lattice-workflow/references/worked-examples.md
+- lib/lattice/schema_text.rb
 - lib/lattice/version.rb
 - lib/latticerb.rb
 homepage: https://github.com/tylerklose/lattice-ruby