ruby_llm-contract 0.8.0 → 0.10.1

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

@@ -6,6 +6,37 @@ module RubyLLM
       # Extracted from Base to reduce class length.
       # DSL accessor methods for step definition (input_type, output_type, prompt, etc.).
       module Dsl # rubocop:disable Metrics/ModuleLength
+        # Sentinel signalling "explicitly reset" (`some_attr(:default)`).
+        # Distinguishes reset (lookup stops at this class, returns nil) from
+        # "never set" (lookup falls through to superclass).
+        UNSET = Object.new
+        def UNSET.inspect = "Step::Dsl::UNSET"
+        UNSET.freeze
+
+        # Walks the inheritance chain for a class-level DSL attribute.
+        # Returns the first explicitly-set value found, or nil.
+        def inherited_value(name)
+          ivar = :"@#{name}"
+          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+          superclass.public_send(name) if superclass.respond_to?(name)
+        end
+
+        # Like `inherited_value`, but honours the `UNSET` sentinel — when this
+        # class has been reset via `some_attr(:default)`, returns nil without
+        # falling through to the superclass.
+        def inherited_value_with_reset(name)
+          ivar = :"@#{name}"
+          if instance_variable_defined?(ivar)
+            value = instance_variable_get(ivar)
+            return value unless value.equal?(UNSET)
+
+            return nil
+          end
+
+          superclass.public_send(name) if superclass.respond_to?(name)
+        end
+
         def input_type(type = nil)
           return @input_type = type if type
 
@@ -70,6 +101,11 @@ module RubyLLM
         end
 
         def validate(description, &block)
+          # `nil.to_s.empty?` is already true - the explicit nil branch was
+          # redundant. `caller` pushes the backtrace to user code instead
+          # of DSL internals (per Codex review of 0.10.0).
+          raise ArgumentError, "validate description must be a non-empty string", caller if description.to_s.empty?
+
           (@class_validates ||= []) << Invariant.new(description, block)
         end
 
@@ -91,131 +127,114 @@ module RubyLLM
 
         def max_output(tokens = nil)
           if tokens
-            unless tokens.is_a?(Numeric) && tokens.positive?
-              raise ArgumentError, "max_output must be positive, got #{tokens}"
-            end
-
+            validate_positive!("max_output", tokens)
             return @max_output = tokens
           end
 
-          if defined?(@max_output)
-            @max_output
-          elsif superclass.respond_to?(:max_output)
-            superclass.max_output
-          end
+          inherited_value(:max_output)
         end
 
         def max_input(tokens = nil)
           if tokens
-            unless tokens.is_a?(Numeric) && tokens.positive?
-              raise ArgumentError, "max_input must be positive, got #{tokens}"
-            end
-
+            validate_positive!("max_input", tokens)
             return @max_input = tokens
           end
 
-          if defined?(@max_input)
-            @max_input
-          elsif superclass.respond_to?(:max_input)
-            superclass.max_input
-          end
+          inherited_value(:max_input)
         end
 
         def max_cost(amount = nil, on_unknown_pricing: nil)
           if amount == :default
-            @max_cost = nil
-            @max_cost_explicitly_unset = true
+            @max_cost = UNSET
             @on_unknown_pricing = nil
             return nil
           end
 
           if amount
-            unless amount.is_a?(Numeric) && amount.positive?
-              raise ArgumentError, "max_cost must be positive, got #{amount}"
-            end
+            validate_positive!("max_cost", amount)
 
             if on_unknown_pricing && !%i[refuse warn].include?(on_unknown_pricing)
               raise ArgumentError, "on_unknown_pricing must be :refuse or :warn, got #{on_unknown_pricing.inspect}"
             end
 
-            @max_cost_explicitly_unset = false
             @max_cost = amount
             @on_unknown_pricing = on_unknown_pricing || :refuse
             return @max_cost
           end
 
-          return @max_cost if defined?(@max_cost) && !@max_cost_explicitly_unset
-          return nil if @max_cost_explicitly_unset
-
-          superclass.max_cost if superclass.respond_to?(:max_cost)
+          inherited_value_with_reset(:max_cost)
         end
 
         def on_unknown_pricing
-          if defined?(@on_unknown_pricing)
-            @on_unknown_pricing
-          elsif superclass.respond_to?(:on_unknown_pricing)
-            superclass.on_unknown_pricing
-          else
-            :refuse
+          inherited_value(:on_unknown_pricing) || :refuse
+        end
+
+        def attachment_token_estimate(n = nil)
+          if n == :default
+            @attachment_token_estimate = UNSET
+            return nil
+          end
+
+          if n
+            validate_positive!("attachment_token_estimate", n)
+            return @attachment_token_estimate = n
+          end
+
+          inherited_value_with_reset(:attachment_token_estimate)
+        end
+
+        def on_unknown_attachment_size(mode = nil)
+          if mode
+            unless %i[refuse warn].include?(mode)
+              raise ArgumentError,
+                    "on_unknown_attachment_size must be :refuse or :warn, got #{mode.inspect}"
+            end
+
+            return @on_unknown_attachment_size = mode
           end
+
+          inherited_value(:on_unknown_attachment_size) || :refuse
         end
 
         def model(name = nil)
           if name == :default
-            @model = nil
-            @model_explicitly_unset = true
+            @model = UNSET
             return nil
           end
 
-          if name
-            @model_explicitly_unset = false
-            return @model = name
-          end
-
-          return @model if defined?(@model) && !@model_explicitly_unset
-          return nil if @model_explicitly_unset
+          return @model = name if name
 
-          superclass.model if superclass.respond_to?(:model)
+          inherited_value_with_reset(:model)
         end
 
         def temperature(value = nil)
           if value == :default
-            @temperature = nil
-            @temperature_explicitly_unset = true
+            @temperature = UNSET
             return nil
           end
 
-          if value
+          # NOTE: `value` may be 0 (a legitimate setting); use `nil?` rather
+          # than truthiness to distinguish "no arg passed" from "explicit 0".
+          unless value.nil?
             unless value.is_a?(Numeric) && value >= 0 && value <= 2
               raise ArgumentError, "temperature must be 0.0-2.0, got #{value}"
             end
 
-            @temperature_explicitly_unset = false
             return @temperature = value
           end
 
-          return @temperature if defined?(@temperature) && !@temperature_explicitly_unset
-          return nil if @temperature_explicitly_unset
-
-          superclass.temperature if superclass.respond_to?(:temperature)
+          inherited_value_with_reset(:temperature)
         end
 
         def thinking(effort: nil, budget: nil)
           if effort == :default
-            @thinking = nil
-            @thinking_explicitly_unset = true
+            @thinking = UNSET
             return nil
           end
 
-          if effort || budget
-            @thinking_explicitly_unset = false
-            return @thinking = { effort: effort, budget: budget }.compact
-          end
-
-          return @thinking if defined?(@thinking) && !@thinking_explicitly_unset
-          return nil if @thinking_explicitly_unset
+          return @thinking = { effort: effort, budget: budget }.compact if effort || budget
 
-          superclass.thinking if superclass.respond_to?(:thinking)
+          inherited_value_with_reset(:thinking)
         end
 
         def reasoning_effort(value = nil)
@@ -228,7 +247,6 @@ module RubyLLM
           if value == :default
             current_budget = thinking && thinking[:budget]
             if current_budget
-              @thinking_explicitly_unset = false
               @thinking = { budget: current_budget }
               return nil
             end
@@ -261,6 +279,16 @@ module RubyLLM
             superclass.retry_policy
           end
         end
+
+        private
+
+        # Shared positivity guard for `max_input`, `max_output`, `max_cost`,
+        # `attachment_token_estimate`. Mirrors `CostCalculator.validate_price!`.
+        def validate_positive!(name, value)
+          return if value.is_a?(Numeric) && value.positive?
+
+          raise ArgumentError, "#{name} must be positive, got #{value}"
+        end
       end
     end
   end

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

@@ -11,7 +11,13 @@ module RubyLLM
         def check_limits(messages)
           return nil unless max_input || max_cost
 
-          estimated = TokenEstimator.estimate(messages)
+          text_tokens = TokenEstimator.estimate(messages)
+          attachment_tokens, attachment_error = resolve_attachment_tokens
+          if attachment_error
+            return build_limit_result(messages, text_tokens, [attachment_error])
+          end
+
+          estimated = text_tokens + attachment_tokens
           errors = collect_limit_errors(estimated)
 
           return nil if errors.empty?
@@ -19,6 +25,33 @@ module RubyLLM
           build_limit_result(messages, estimated, errors)
         end
 
+        # Fail-closed: when an attachment is passed via context but no
+        # attachment_token_estimate is declared, the gem cannot bound vision/
+        # PDF cost. Refuses with a clear error unless on_unknown_attachment_size
+        # is :warn (per-step opt-out, mirroring on_unknown_pricing).
+        def resolve_attachment_tokens
+          return [0, nil] unless attachment_present?
+
+          estimate = attachment_token_estimate
+          if estimate.nil?
+            if on_unknown_attachment_size == :warn
+              warn "[ruby_llm-contract] attachment present but " \
+                   "attachment_token_estimate not declared — cost limit not enforced " \
+                   "for the attachment portion"
+              return [0, nil]
+            end
+
+            return [0,
+                    "attachment present but attachment_token_estimate not declared; " \
+                    "cost cannot be bounded. Declare " \
+                    "`attachment_token_estimate(n)` on the step class, or set " \
+                    "`on_unknown_attachment_size :warn` to proceed without attachment " \
+                    "cost checks."]
+          end
+
+          [estimate, nil]
+        end
+
         def collect_limit_errors(estimated)
           errors = []
           if max_input && estimated > max_input

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

@@ -6,6 +6,8 @@ module RubyLLM
       # Extracted from Base to reduce class length.
       # Handles retry logic: run_with_retry, build_retry_result, aggregate usage, build attempt entries.
       module RetryExecutor
+        include Concerns::UsageAggregator
+
         private
 
         def run_with_retry(input, adapter:, default_model:, policy:, context_temperature: nil, extra_options: {})
@@ -29,7 +31,7 @@ module RubyLLM
         def build_retry_result(all_attempts)
           last = all_attempts.last[:result]
           attempt_log = all_attempts.map { |attempt| build_attempt_entry(attempt) }
-          aggregated_usage = aggregate_retry_usage(all_attempts)
+          aggregated_usage = aggregate_usage(all_attempts.map { |a| a[:result].trace })
           total_cost = sum_attempt_costs(all_attempts)
           total_latency = sum_attempt_latency(all_attempts)
 
@@ -80,18 +82,9 @@ module RubyLLM
           end
         end
 
-        def aggregate_retry_usage(all_attempts)
-          totals = { input_tokens: 0, output_tokens: 0 }
-          all_attempts.each do |attempt|
-            usage = attempt[:result].trace
-            usage = usage.respond_to?(:usage) ? usage.usage : nil
-            next unless usage.is_a?(Hash)
-
-            totals[:input_tokens] += usage[:input_tokens] || 0
-            totals[:output_tokens] += usage[:output_tokens] || 0
-          end
-          totals
-        end
+        # `aggregate_usage(traces)` provided by Concerns::UsageAggregator —
+        # replaces the prior `aggregate_retry_usage` private helper which
+        # duplicated the same per-trace input/output token sum.
       end
     end
   end

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

@@ -6,26 +6,15 @@ module RubyLLM
       class Runner
         include LimitChecker
 
-        def initialize(input_type:, output_type:, prompt_block:, contract_definition:,
-                       adapter:, model:, output_schema: nil, max_output: nil,
-                       max_input: nil, max_cost: nil, on_unknown_pricing: :refuse,
-                       temperature: nil, extra_options: {}, observers: [])
-          @config = RunnerConfig.new(
-            input_type: input_type,
-            output_type: output_type,
-            prompt_block: prompt_block,
-            contract_definition: contract_definition,
-            adapter: adapter,
-            model: model,
-            output_schema: output_schema,
-            max_output: max_output,
-            max_input: max_input,
-            max_cost: max_cost,
-            on_unknown_pricing: on_unknown_pricing,
-            temperature: temperature,
-            extra_options: extra_options,
-            observers: observers
-          )
+        # Two construction forms:
+        #   Runner.new(config: a_runner_config)          # preferred — value-object
+        #   Runner.new(input_type:, output_type:, ...)   # legacy kwarg form (still supported)
+        #
+        # The legacy form delegates to `RunnerConfig.build(**kwargs)`, so the
+        # defaults live in one place (`RunnerConfig.build`) and the kwarg
+        # surface is no longer duplicated here.
+        def initialize(config: nil, **kwargs)
+          @config = config || RunnerConfig.build(**kwargs)
         end
 
         def call(input)
@@ -90,6 +79,19 @@ module RubyLLM
           @config.on_unknown_pricing
         end
 
+        def attachment_token_estimate
+          @config.attachment_token_estimate
+        end
+
+        def on_unknown_attachment_size
+          @config.on_unknown_attachment_size
+        end
+
+        def attachment_present?
+          opts = @config.extra_options
+          !opts.nil? && !opts[:attachment].nil?
+        end
+
         def effective_max_output
           @config.effective_max_output
         end

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

@@ -15,10 +15,36 @@ module RubyLLM
         :max_input,
         :max_cost,
         :on_unknown_pricing,
+        :attachment_token_estimate,
+        :on_unknown_attachment_size,
         :temperature,
         :extra_options,
         :observers
       ) do
+        # Factory with sensible defaults for optional fields. Lets callers
+        # (Step::Base#run_once and tests) construct a RunnerConfig without
+        # repeating the 11-default boilerplate, and gives `Runner.new(config:)`
+        # a clean entry point for the value-object form.
+        def self.build(input_type:, output_type:, prompt_block:, contract_definition:,
+                       adapter:, model:,
+                       output_schema: nil, max_output: nil,
+                       max_input: nil, max_cost: nil, on_unknown_pricing: :refuse,
+                       attachment_token_estimate: nil, on_unknown_attachment_size: :refuse,
+                       temperature: nil, extra_options: {}, observers: [])
+          new(
+            input_type: input_type, output_type: output_type,
+            prompt_block: prompt_block, contract_definition: contract_definition,
+            adapter: adapter, model: model,
+            output_schema: output_schema, max_output: max_output,
+            max_input: max_input, max_cost: max_cost,
+            on_unknown_pricing: on_unknown_pricing,
+            attachment_token_estimate: attachment_token_estimate,
+            on_unknown_attachment_size: on_unknown_attachment_size,
+            temperature: temperature, extra_options: extra_options,
+            observers: observers
+          )
+        end
+
         def effective_max_output
           extra_options[:max_tokens] || max_output
         end

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "0.8.0"
+    VERSION = "0.10.1"
   end
 end

data/lib/ruby_llm/contract.rb

@@ -158,6 +158,7 @@ require_relative "contract/concerns/production_mode_context"
 require_relative "contract/concerns/eval_host"
 require_relative "contract/concerns/trace_equality"
 require_relative "contract/concerns/usage_aggregator"
+require_relative "contract/concerns/stub_helpers"
 require_relative "contract/configuration"
 require_relative "contract/prompt/node"
 require_relative "contract/prompt/nodes"

data/ruby_llm-contract.gemspec

@@ -23,9 +23,13 @@ Gem::Specification.new do |spec|
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
+    # Internal trackers + dev configs excluded so the published gem
+    # contains only what adopters actually need at runtime.
+    excluded_files = %w[TODO.md .rspec .rubycritic.yml .simplecov]
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?("spec/", "docs/", "doc/", ".ai/", ".claude/", ".git")
+        f.start_with?("spec/", "docs/", "doc/", ".ai/", ".claude/", ".git", ".revive/") ||
+        excluded_files.include?(f)
     end
   end
   spec.require_paths = ["lib"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-contract
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Justyna
@@ -59,10 +59,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
 - ".rubocop.yml"
-- ".rubycritic.yml"
-- ".simplecov"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -88,6 +85,7 @@ files:
 - lib/ruby_llm/contract/concerns/deep_symbolize.rb
 - lib/ruby_llm/contract/concerns/eval_host.rb
 - lib/ruby_llm/contract/concerns/production_mode_context.rb
+- lib/ruby_llm/contract/concerns/stub_helpers.rb
 - lib/ruby_llm/contract/concerns/trace_equality.rb
 - lib/ruby_llm/contract/concerns/usage_aggregator.rb
 - lib/ruby_llm/contract/configuration.rb
@@ -159,6 +157,7 @@ files:
 - lib/ruby_llm/contract/prompt/renderer.rb
 - lib/ruby_llm/contract/railtie.rb
 - lib/ruby_llm/contract/rake_task.rb
+- lib/ruby_llm/contract/rake_task/suite_gate.rb
 - lib/ruby_llm/contract/rspec.rb
 - lib/ruby_llm/contract/rspec/helpers.rb
 - lib/ruby_llm/contract/rspec/pass_eval.rb

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubycritic.yml

@@ -1,8 +0,0 @@
-paths:
-  - lib
-
-formats:
-  - console
-
-minimum_score: 80
-no_browser: true

data/.simplecov

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require "simplecov"
-
-SimpleCov.start do
-  enable_coverage :branch
-  primary_coverage :branch
-
-  add_filter "/spec/"
-  add_filter "/examples/"
-  add_filter "/internal/"
-  add_filter "/tmp/"
-
-  track_files "lib/**/*.rb"
-
-  if ENV["CI"] == "true" || ENV["SIMPLECOV_STRICT"] == "1"
-    minimum_coverage line: 89
-    minimum_coverage branch: 75
-  end
-
-  command_name "RSpec"
-end