ruby_llm-contract 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc8b1278c5464978cfc50d87ac90cbde94c2a5920b00996365a2e366bb27f1e6
-  data.tar.gz: daf51e9b66472464137d371439f503317b84706f167fa74c2118635ae82823b1
+  metadata.gz: 2803caa3f400a1c3ca1f2a3c062bf1e79080d25f4dd3d9a652300007eb363d21
+  data.tar.gz: 27cfd8b34f7ddeb2e2af72142c2d38994a84cd50a2ecd494c173d9fdaf220329
 SHA512:
-  metadata.gz: 7899b4c2df5e7824a5104c24698b728b017e996cced82022c26d81167e8876085fcec93396d13ce67aed7034cfbd0cfbde2e0ebd76376a8dd198d6a561d273d7
-  data.tar.gz: 7ca10ee16ea71eda609439546b9f02b20e184e9c6a8861d88a172c0e75ca611cf3c2bddf8827b820b31aa9cc5baf88bdaf9b708732b78f3e6321438030186ef8
+  metadata.gz: f587bc603e2270a6e96979a62421bb0ac45cf68ae1d0ca53518bca6e394a72fd6ab2b8cb3622e0f98104fa0212aa3fe45fb5814a2aea6560b0ae2ae57a2f3041
+  data.tar.gz: b6dd0147f09e8936ac2198f95a26188913095cbb26d3a073a233c7822cb5441b04567ae88a1c68dacd79a792fe84e6479fd771282c1a51bfedb3fa0609ff0ebb

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.2.1 (2026-03-23)
+
+Production DX improvements from first real-world integration (persona_tool).
+
+### Features
+
+- **`temperature` DSL** — `temperature 0.3` in step definition, overridable via `context: { temperature: 0.7 }`. RubyLLM handles per-model normalization natively.
+- **`around_call` hook** — callback for logging, metrics, observability. Replaces need for custom middleware.
+- **`build_messages` public** — inspect rendered prompt without running the step.
+- **`stub_step` RSpec helper** — `stub_step(MyStep, response: { ... })` reduces test boilerplate. Auto-included via `require "ruby_llm/contract/rspec"`.
+- **`estimate_cost` / `estimate_eval_cost`** — predict spend before API calls.
+
+### Fixes
+
+- **Reload lifecycle** — `load_evals!` clears definitions before re-loading. Railtie hooks `config.to_prepare` for development reload. `define_eval` warns on duplicate name (suppressed during reload).
+- **Pipeline eval cost** — uses `Pipeline::Trace#total_cost` (all steps), not just last step.
+- **Adapter isolation** — `compare_models` and `run_all_own_evals` deep-dup context per run.
+- **Offline mode** — cases without adapter return `:skipped` instead of crashing. Skipped cases excluded from score.
+- **`expected_traits`** reachable from `define_eval` DSL via `add_case`.
+- **`verify`** raises when both positional and `expect:` keyword provided.
+- **`best_for`** excludes zero-score models from recommendation.
+- **`print_summary`** replaces `pretty_print` (avoids `Kernel#pretty_print` shadow).
+- **`CaseResult#to_h`** round-trips correctly (`name:` key).
+
+### Docs
+
+- All 5 guides updated for v0.2 API
+- Symbol keys documented
+- Retry model priority documented
+- Test adapter format documented
+
+### Stats
+
+- 1077 tests, 0 failures
+- 3 architecture review rounds, 32 findings fixed
+
 ## 0.2.0 (2026-03-23)
 
 Contracts for LLM quality. Know which model to use, what it costs, and when accuracy drops.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_llm-contract (0.2.0)
+    ruby_llm-contract (0.2.1)
       dry-types (~> 1.7)
       ruby_llm (~> 1.0)
       ruby_llm-schema (~> 0.3)
@@ -165,7 +165,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.2.0)
+  ruby_llm-contract (0.2.1)
   ruby_llm-schema (0.3.0) sha256=a591edc5ca1b7f0304f0e2261de61ba4b3bea17be09f5cf7558153adfda3dec6
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f

data/lib/ruby_llm/contract/rspec/helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Contract
+    module RSpec
+      module Helpers
+        # Stub a step to return a canned response without API calls.
+        #
+        #   stub_step(ClassifyTicket, response: { priority: "high" })
+        #   result = ClassifyTicket.run("test")
+        #   result.parsed_output  # => {priority: "high"}
+        #
+        # For multiple sequential responses:
+        #   stub_step(ClassifyTicket, responses: [{ a: 1 }, { a: 2 }])
+        #
+        def stub_step(step_class, response: nil, responses: nil)
+          adapter = if responses
+                      Adapters::Test.new(responses: responses.map { |r| r.is_a?(String) ? r : r.to_json })
+                    else
+                      content = response.is_a?(String) ? response : response.to_json
+                      Adapters::Test.new(response: content)
+                    end
+          RubyLLM::Contract.configure { |c| c.default_adapter = adapter }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/contract/rspec.rb

@@ -4,3 +4,8 @@ require "ruby_llm/contract"
 
 require_relative "rspec/satisfy_contract"
 require_relative "rspec/pass_eval"
+require_relative "rspec/helpers"
+
+RSpec.configure do |config|
+  config.include RubyLLM::Contract::RSpec::Helpers
+end if defined?(::RSpec)

data/lib/ruby_llm/contract/step/base.rb

@@ -69,10 +69,18 @@ module RubyLLM
             if policy
               run_with_retry(input, adapter: adapter, default_model: default_model, policy: policy)
             else
-              run_once(input, adapter: adapter, model: default_model)
+              run_once(input, adapter: adapter, model: default_model, context_temperature: context[:temperature])
             end
           end
 
+          def build_messages(input)
+            dynamic = prompt.arity >= 1
+            ast = Prompt::Builder.build(input: dynamic ? input : nil, &prompt)
+            variables = dynamic ? {} : { input: input }
+            variables.merge!(input.transform_keys(&:to_sym)) if !dynamic && input.is_a?(Hash)
+            Prompt::Renderer.render(ast, variables: variables)
+          end
+
           private
 
           def warn_unknown_context_keys(context)
@@ -91,13 +99,21 @@ module RubyLLM
                                             "{ |c| c.default_adapter = ... } or pass context: { adapter: ... }"
           end
 
-          def run_once(input, adapter:, model:)
-            Runner.new(
+          def run_once(input, adapter:, model:, context_temperature: nil)
+            effective_temp = context_temperature || temperature
+            runner = Runner.new(
               input_type: input_type, output_type: output_type,
               prompt_block: prompt, contract_definition: effective_contract,
               adapter: adapter, model: model, output_schema: output_schema,
-              max_output: max_output, max_input: max_input, max_cost: max_cost
-            ).call(input)
+              max_output: max_output, max_input: max_input, max_cost: max_cost,
+              temperature: effective_temp
+            )
+
+            if around_call
+              around_call.call(self, input) { runner.call(input) }
+            else
+              runner.call(input)
+            end
           rescue ArgumentError => e
             Result.new(status: :input_error, raw_output: nil, parsed_output: nil,
                        validation_errors: [e.message])
@@ -118,14 +134,6 @@ module RubyLLM
             )
           end
 
-          def build_messages(input)
-            dynamic = prompt.arity >= 1
-            ast = Prompt::Builder.build(input: dynamic ? input : nil, &prompt)
-            variables = dynamic ? {} : { input: input }
-            variables.merge!(input.transform_keys(&:to_sym)) if !dynamic && input.is_a?(Hash)
-            Prompt::Renderer.render(ast, variables: variables)
-          end
-
           def json_compatible_type?(type)
             type == RubyLLM::Contract::Types::Hash || type == Hash ||
               type == RubyLLM::Contract::Types::Array || type == Array ||

data/lib/ruby_llm/contract/step/dsl.rb

@@ -127,6 +127,34 @@ module RubyLLM
           end
         end
 
+        def temperature(value = nil)
+          if value
+            unless value.is_a?(Numeric) && value >= 0 && value <= 2
+              raise ArgumentError, "temperature must be 0.0-2.0, got #{value}"
+            end
+
+            return @temperature = value
+          end
+
+          if defined?(@temperature)
+            @temperature
+          elsif superclass.respond_to?(:temperature)
+            superclass.temperature
+          end
+        end
+
+        def around_call(&block)
+          if block
+            return @around_call = block
+          end
+
+          if defined?(@around_call) && @around_call
+            @around_call
+          elsif superclass.respond_to?(:around_call)
+            superclass.around_call
+          end
+        end
+
         def retry_policy(models: nil, attempts: nil, retry_on: nil, &block)
           if block || models || attempts
             return @retry_policy = RetryPolicy.new(models: models, attempts: attempts, retry_on: retry_on, &block)

data/lib/ruby_llm/contract/step/runner.rb

@@ -8,7 +8,7 @@ module RubyLLM
 
         def initialize(input_type:, output_type:, prompt_block:, contract_definition:,
                        adapter:, model:, output_schema: nil, max_output: nil,
-                       max_input: nil, max_cost: nil)
+                       max_input: nil, max_cost: nil, temperature: nil)
           @input_type = input_type
           @output_type = output_type
           @prompt_block = prompt_block
@@ -19,6 +19,7 @@ module RubyLLM
           @max_output = max_output
           @max_input = max_input
           @max_cost = max_cost
+          @temperature = temperature
         end
 
         def call(input)
@@ -84,6 +85,7 @@ module RubyLLM
           { model: @model }.tap do |opts|
             opts[:schema] = @output_schema if @output_schema
             opts[:max_tokens] = @max_output if @max_output
+            opts[:temperature] = @temperature if @temperature
           end
         end
 

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-contract
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Justyna
@@ -129,6 +129,7 @@ files:
 - lib/ruby_llm/contract/railtie.rb
 - lib/ruby_llm/contract/rake_task.rb
 - lib/ruby_llm/contract/rspec.rb
+- lib/ruby_llm/contract/rspec/helpers.rb
 - lib/ruby_llm/contract/rspec/pass_eval.rb
 - lib/ruby_llm/contract/rspec/satisfy_contract.rb
 - lib/ruby_llm/contract/step.rb