ruby_llm-contract 0.10.2 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac8c19463285a3e2c0f9050e835125454b21d2b1500dcb5bad2dd4a114666bd0
-  data.tar.gz: 339c0609e3dccbf55da649c3470ed234c5abafa55c8649aee5d8dd41f9bd82ec
+  metadata.gz: 7413f62a11d7d8b350d7ea24f5ef5df479c3f258d1c32e952553214a6182023e
+  data.tar.gz: 7061cdf57b6633130e20e1653ef5223c1948825afb95f878e50d0ac65b6995dc
 SHA512:
-  metadata.gz: c04fea66393868fbdb369f5a75eaeb66a28172c8f9ddabd0a8c053fd55e5daa06174aeeb00c4bb7e9aabaf613bd1ef4ea354ff7d0f4b817f2ec41af1a4c61667
-  data.tar.gz: 71f502ebe497ede22df508d3b56396660fbd1eba109066885d5e905724bd82d30a0d46fddfe4f1c1e7efe47f95ea41b4f61341a4698c12d3f3a397cab2510068
+  metadata.gz: 58af240032c98ff1d25bad9114c2ef83cbea54ab13e024e7b3665bf38b5c2478813dafec1a6666811539eaecc828d97c926010eb21d61f0daeb15de89c3d1ff2
+  data.tar.gz: 5b473df00607e1dbe9cb2d1e113fb72b9ab3fea534040eadb912aaee1d9d2d9ca1a2c99b2406fb0757124beae6fafecd03536aaf2c4e4df8d8072d8c38cfcbbb

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.10.4 (2026-06-10)
+
+Patch release: the `ruby_llm_contract:optimize` rake task now auto-loads in Rails apps. No behaviour change to the task itself.
+
+### Fixed
+
+- **`ruby_llm_contract:optimize` no longer requires manual `require "ruby_llm/contract/rake_task"` in Rails apps.** Pre-0.10.4 the docs claimed the task was "included" with `RubyLLM::Contract::RakeTask`, but the railtie did not load the file — adopters running `bin/rails ruby_llm_contract:optimize` got `Unrecognized command` until they added the require to `Rakefile` or `lib/tasks/*.rake`. The railtie now uses the standard `rake_tasks { require "..." }` idiom, lazy-loading the file only when `rake` is invoked (no boot cost).
+- **Docs corrected** in `docs/guide/optimizing_retry_policy.md` — the "rake task is included" line now explicitly states it auto-loads on 0.10.4+ in Rails, and that non-Rails / older-Rails setups still need the explicit `require`.
+
+## 0.10.3 (2026-06-10)
+
+Hot-fix release: the schema validator now correctly accepts `nil` on **required-but-nullable** fields. This unblocks OpenAI structured-output strict mode, where every property has to be in `required` and "nullable" is expressed as a `null` branch in `anyOf`/`oneOf` or as an array `type` — exactly the combination the prior validator wrongly rejected.
+
+### Fixed
+
+- **`SchemaValidator` no longer rejects legal `nil` on required-nullable fields.** Pre-0.10.3 (every published version 0.2.x–0.10.2) conflated "required" (must be present) with "non-nullable" (cannot be null) — JSON Schema treats those as orthogonal. The validator now honours all three idioms for nullability:
+  - `type: ["string", "null"]` (array form)
+  - `type: "null"` (degenerate scalar form)
+  - `anyOf: [{type: "string"}, {type: "null"}]` and `oneOf` equivalents
+
+  **Adopter impact:** if you bypassed the bug by setting `required: false` + disabling OpenAI `strict: true` on every nullable field, you can now restore `strict: true` and keep the field required (= OpenAI's standard nullable idiom). Non-nullable required fields still reject `nil` exactly as before; this is a strictly additive fix.
+
+  Discovered via dogfooding in a production adopter using OpenAI strict structured output with 17 nullable fields (`"set the rest to null"` prompt). Smoking-gun mutation: remove `nullable_schema?` short-circuit from `validate_nil_field` — the three new spec cases in `spec/ruby_llm/contract/contract/schema_validator_spec.rb` fail.
+
 ## 0.10.2 (2026-06-10)
 
 Patch release: ship the `docs/guide/` directory inside the gem so adopters and LLM integration agents can read the manuals locally (via `bundle show ruby_llm-contract` or `gem unpack`) without an internet round-trip to GitHub. No code behavior change.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_llm-contract (0.10.2)
+    ruby_llm-contract (0.10.4)
       dry-types (~> 1.7)
       ruby_llm (~> 1.12)
       ruby_llm-schema (~> 0.3)
@@ -258,7 +258,7 @@ CHECKSUMS
   rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   ruby_llm (1.14.0) sha256=57c6f7034fc4a44504ea137d70f853b07824f1c1cdbe774ab3ab3522e7098deb
-  ruby_llm-contract (0.10.2)
+  ruby_llm-contract (0.10.4)
   ruby_llm-schema (0.3.0) sha256=a591edc5ca1b7f0304f0e2261de61ba4b3bea17be09f5cf7558153adfda3dec6
   ruby_parser (3.22.0) sha256=1eb4937cd9eb220aa2d194e352a24dba90aef00751e24c8dfffdb14000f15d23
   rubycritic (4.12.0) sha256=024fed90fe656fa939f6ea80aab17569699ac3863d0b52fd72cb99892247abc8

data/README.md

@@ -157,7 +157,7 @@ Different layers, complementary. [`ruby_llm-tribunal`](https://github.com/Alqemi
 
 ## Status & versioning
 
-Pre-1.0 (currently **0.10.2**). Semver tracked; breaking changes flagged in [CHANGELOG](CHANGELOG.md). Pin `~> 0.10.2` until 1.0 ships.
+Pre-1.0 (currently **0.10.4**). Semver tracked; breaking changes flagged in [CHANGELOG](CHANGELOG.md). Pin `~> 0.10.4` until 1.0 ships.
 
 ## FAQ
 

data/docs/guide/optimizing_retry_policy.md

@@ -8,7 +8,7 @@ You defined `SummarizeArticle` in the [README](../../README.md) with `retry_poli
 
 - **`SummarizeArticle` already has `retry_policy`.** If your step has none, add one first ([getting started](getting_started.md)).
 - **2–3 evals per step.** One eval optimizes for one scenario; with only `smoke`, you get a recommendation that passes smoke but may miss production edge cases. See [eval-first](eval_first.md).
-- **Rake tasks.** The standard `RubyLLM::Contract::RakeTask` includes `ruby_llm_contract:optimize`. Non-Rails projects: set `EVAL_DIRS=...`.
+- **Rake task `ruby_llm_contract:optimize` is registered when `lib/ruby_llm/contract/rake_task.rb` is loaded.** In Rails apps on **0.10.4+** the railtie auto-loads it lazily during `rake` invocation — no manual setup needed. On older Rails versions or in non-Rails projects, add `require "ruby_llm/contract/rake_task"` to your `Rakefile` (or any file under `lib/tasks/`) and set `EVAL_DIRS=...` on the command line.
 
 > **Two orthogonal dimensions to a retry chain.** A chain element is `{ model:, reasoning_effort: }` — model identity AND thinking budget. `optimize_retry_policy` explores both. You can also fix the thinking config at class level via `thinking effort: :low` (or alias `reasoning_effort :low`) on the Step — it becomes the default for every chain element unless an override is passed. See the `thinking` DSL note at the bottom of this guide.
 

data/lib/ruby_llm/contract/contract/schema_validator/object_rules.rb

@@ -45,11 +45,35 @@ module RubyLLM
 
         def validate_nil_field(path, field_schema, required)
           return unless required
+          return if nullable_schema?(field_schema)
 
           expected_type = field_schema[:type] || "non-null"
           @errors << "#{path}: expected #{expected_type}, got nil"
         end
 
+        # JSON Schema permits nil when the field schema explicitly accepts
+        # null. Three idiomatic forms are recognised:
+        #   - `type: ["string", "null"]`     (array form)
+        #   - `type: "null"`                 (degenerate scalar form)
+        #   - `anyOf` / `oneOf` containing a branch with `type: "null"`
+        # Without this gate the validator wrongly rejected legal nulls on
+        # required-but-nullable fields, forcing adopters into `required: false`
+        # + `strict: false` workarounds. Fixed in 0.10.3.
+        def nullable_schema?(field_schema)
+          return false unless field_schema.is_a?(Hash)
+
+          type = field_schema[:type] || field_schema["type"]
+          return true if type.is_a?(Array) && type.any? { |t| t.to_s == "null" }
+          return true if type.to_s == "null"
+
+          %i[anyOf oneOf].any? do |key|
+            branches = field_schema[key] || field_schema[key.to_s]
+            branches.is_a?(Array) && branches.any? do |branch|
+              branch.is_a?(Hash) && (branch[:type] || branch["type"]).to_s == "null"
+            end
+          end
+        end
+
         def validate_additional_properties(node)
           return unless node.schema[:additionalProperties] == false
 

data/lib/ruby_llm/contract/railtie.rb

@@ -21,6 +21,14 @@ module RubyLLM
       config.to_prepare do
         RubyLLM::Contract.load_evals!
       end
+
+      # Auto-load rake tasks in Rails apps so `bin/rails ruby_llm_contract:optimize`
+      # works without an explicit `require "ruby_llm/contract/rake_task"` in the
+      # adopter's Rakefile / lib/tasks. Standard Rails railtie idiom: the
+      # `rake_tasks` block fires lazily during `rake` invocation, no boot cost.
+      rake_tasks do
+        require "ruby_llm/contract/rake_task"
+      end
     end
   end
 end

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "0.10.2"
+    VERSION = "0.10.4"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-contract
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.4
 platform: ruby
 authors:
 - Justyna