ruby_llm-contract 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc8b1278c5464978cfc50d87ac90cbde94c2a5920b00996365a2e366bb27f1e6
-  data.tar.gz: daf51e9b66472464137d371439f503317b84706f167fa74c2118635ae82823b1
+  metadata.gz: c8111e9c77abab44b943129932bf6f225f619c930568bfe848c96b916cb72224
+  data.tar.gz: 4d54273d0b0dfd2fc4a44a34ff681aaa767956bbe89230659e975a91bf2a3821
 SHA512:
-  metadata.gz: 7899b4c2df5e7824a5104c24698b728b017e996cced82022c26d81167e8876085fcec93396d13ce67aed7034cfbd0cfbde2e0ebd76376a8dd198d6a561d273d7
-  data.tar.gz: 7ca10ee16ea71eda609439546b9f02b20e184e9c6a8861d88a172c0e75ca611cf3c2bddf8827b820b31aa9cc5baf88bdaf9b708732b78f3e6321438030186ef8
+  metadata.gz: d5226bdd266a5676bbf4bef0b71580387825f15eb77e9739426e6845b62d6410d22583d2f3f3ad47d2eacca8980fb0763a8a23bf1c1f04c723cae5d4f021ed68
+  data.tar.gz: 2ee39172b68a94fd8dae1b633d17cc1e0bfac4f82413a0d4233d50f1851b860527248887ca35ebf88ef6b1fc69de78f6fc2775712c75e272891f36d44ba30f57

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.2.2 (2026-03-23)
+
+Fixes from first real-world integration (persona_tool).
+
+- **`around_call` fires per-run** — not per-attempt. With retry_policy, callback fires once with final result. Signature: `around_call { |step, input, result| ... }`
+- **`Result#trace` always `Trace` object** — never bare Hash. `result.trace.model` works on success AND failure.
+- **`around_call` exception safe** — warns and returns result instead of crashing.
+- **`model` DSL** — `model "gpt-4o-mini"` per-step. Priority: context > step DSL > global config.
+- **Test adapter `raw_output` always String** — Hash/Array normalized to `.to_json`.
+- **`Trace#dig`** — `trace.dig(:usage, :input_tokens)` works.
+
+## 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.2)
       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.2)
   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/adapters/test.rb

@@ -20,7 +20,7 @@ module RubyLLM
 
         def normalize_response(response)
           case response
-          when Hash, Array then response
+          when Hash, Array then response.to_json
           when nil then ""
           else response.to_s
           end

data/lib/ruby_llm/contract/pipeline/trace.rb

@@ -25,6 +25,13 @@ module RubyLLM
           public_send(key)
         end
 
+        def dig(key, *rest)
+          value = self[key]
+          return value if rest.empty? || value.nil?
+
+          value.dig(*rest)
+        end
+
         def to_h
           { trace_id: @trace_id, total_latency_ms: @total_latency_ms,
             total_usage: @total_usage, step_traces: @step_traces,

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

@@ -63,14 +63,24 @@ module RubyLLM
           def run(input, context: {})
             warn_unknown_context_keys(context)
             adapter = resolve_adapter(context)
-            default_model = context[:model] || RubyLLM::Contract.configuration.default_model
+            default_model = context[:model] || model || RubyLLM::Contract.configuration.default_model
             policy = retry_policy
 
-            if policy
-              run_with_retry(input, adapter: adapter, default_model: default_model, policy: policy)
-            else
-              run_once(input, adapter: adapter, model: default_model)
-            end
+            result = if policy
+                       run_with_retry(input, adapter: adapter, default_model: default_model, policy: policy)
+                     else
+                       run_once(input, adapter: adapter, model: default_model, context_temperature: context[:temperature])
+                     end
+
+            invoke_around_call(input, result)
+          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
@@ -91,18 +101,30 @@ module RubyLLM
                                             "{ |c| c.default_adapter = ... } or pass context: { adapter: ... }"
           end
 
-          def run_once(input, adapter:, model:)
+          def run_once(input, adapter:, model:, context_temperature: nil)
+            effective_temp = context_temperature || temperature
             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
+              max_output: max_output, max_input: max_input, max_cost: max_cost,
+              temperature: effective_temp
             ).call(input)
           rescue ArgumentError => e
             Result.new(status: :input_error, raw_output: nil, parsed_output: nil,
                        validation_errors: [e.message])
           end
 
+          def invoke_around_call(input, result)
+            return result unless around_call
+
+            around_call.call(self, input, result)
+            result
+          rescue StandardError => e
+            warn "[ruby_llm-contract] around_call raised #{e.class}: #{e.message}"
+            result
+          end
+
           def effective_contract
             base = contract
             extra = class_validates
@@ -118,14 +140,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,46 @@ module RubyLLM
           end
         end
 
+        def model(name = nil)
+          if name
+            return @model = name
+          end
+
+          if defined?(@model)
+            @model
+          elsif superclass.respond_to?(:model)
+            superclass.model
+          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/result.rb

@@ -6,12 +6,12 @@ module RubyLLM
       class Result
         attr_reader :status, :raw_output, :parsed_output, :validation_errors, :trace
 
-        def initialize(status:, raw_output:, parsed_output:, validation_errors: [], trace: {})
+        def initialize(status:, raw_output:, parsed_output:, validation_errors: [], trace: nil)
           @status = status
           @raw_output = raw_output
           @parsed_output = parsed_output
           @validation_errors = validation_errors.freeze
-          @trace = trace.freeze
+          @trace = normalize_trace(trace)
           freeze
         end
 
@@ -23,6 +23,19 @@ module RubyLLM
           @status != :ok
         end
 
+        private
+
+        def normalize_trace(trace)
+          case trace
+          when Trace then trace
+          when Hash then Trace.new(**trace)
+          when nil then Trace.new
+          else trace
+          end.freeze
+        end
+
+        public
+
         def to_s
           if ok?
             "#{@status} (#{@trace})"

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/step/trace.rb

@@ -26,6 +26,13 @@ module RubyLLM
           public_send(key)
         end
 
+        def dig(key, *rest)
+          value = self[key]
+          return value if rest.empty? || value.nil?
+
+          value.dig(*rest)
+        end
+
         def key?(key)
           KNOWN_KEYS.include?(key.to_sym) && !public_send(key).nil?
         end

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "0.2.0"
+    VERSION = "0.2.2"
   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.2
 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