ruby_llm-contract 1.1.1 → 1.2.0

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

@@ -7,19 +7,40 @@ module RubyLLM
         include Concerns::TraceEquality
         include Concerns::DeepFreeze
 
-        attr_reader :messages, :model, :latency_ms, :usage, :attempts, :cost
-
-        def initialize(messages: nil, model: nil, latency_ms: nil, usage: nil, attempts: nil, cost: nil)
+        attr_reader :messages, :model, :latency_ms, :usage, :attempts, :cost,
+                    :usage_complete, :cost_complete, :finish_reason, :error_class, :error_type
+
+        # Marks `cost:` as not given, as distinct from an explicit nil. Only an
+        # omitted cost is priced from the registry; nil from an adapter that
+        # reports its own cost means "unknown" and must stay unknown.
+        COST_UNSET = Object.new.freeze
+
+        # usage_complete / cost_complete are nil for traces that carry no
+        # accounting state (Test adapter, older adapters, hand-built traces);
+        # those keep the token-count rule in `unpriced?`.
+        # error_class names the exception behind an :adapter_error and is part
+        # of to_h; error_type is the class itself, kept in memory only so
+        # `retry_on SomeError` can match subclasses. A trace rebuilt from a
+        # hash has the name but not the class.
+        def initialize(messages: nil, model: nil, latency_ms: nil, usage: nil, attempts: nil, cost: COST_UNSET,
+                       usage_complete: nil, cost_complete: nil, finish_reason: nil, error_class: nil, error_type: nil)
           @messages = deep_dup_freeze(messages)
           @model = model.frozen? ? model : model&.dup&.freeze
           @latency_ms = latency_ms
           @usage = deep_dup_freeze(usage)
           @attempts = deep_dup_freeze(attempts)
-          @cost = cost || CostCalculator.calculate(model_name: model, usage: usage)
+          @usage_complete = usage_complete
+          @cost_complete = cost_complete
+          @finish_reason = finish_reason
+          @error_class = error_class
+          @error_type = error_type
+          @cost = resolve_cost(cost)
+          @keep_nil_cost = keep_nil_cost?(cost)
           freeze
         end
 
-        KNOWN_KEYS = %i[messages model latency_ms usage attempts cost].freeze
+        KNOWN_KEYS = %i[messages model latency_ms usage attempts cost
+                        usage_complete cost_complete finish_reason error_class].freeze
 
         def [](key)
           return nil unless KNOWN_KEYS.include?(key.to_sym)
@@ -39,27 +60,28 @@ module RubyLLM
         end
         alias has_key? key?
 
+        # Never re-prices: a retry merges a subtotal and an aggregate usage that
+        # no single model's pricing describes.
         def merge(**overrides)
-          self.class.new(
-            messages: overrides.fetch(:messages, @messages),
-            model: overrides.fetch(:model, @model),
-            latency_ms: overrides.fetch(:latency_ms, @latency_ms),
-            usage: overrides.fetch(:usage, @usage),
-            attempts: overrides.fetch(:attempts, @attempts),
-            cost: overrides.fetch(:cost, @cost)
-          )
+          self.class.new(**KNOWN_KEYS.to_h { |key| [key, overrides.fetch(key) { public_send(key) }] },
+                         error_type: overrides.fetch(:error_type, @error_type))
         end
 
-        # True when a call ran on a named model, used tokens, and still got no
-        # cost, so any total built from this trace undercounts. A zero-token call
+        # True when a total built from this trace undercounts: the adapter said
+        # its cost does not cover the call, or (no accounting state) a call ran
+        # on a named model, used tokens, and still got no cost. A zero-token call
         # (Test adapter, sample_response) costs 0 whatever the pricing. A retried
         # step is judged per attempt: a priced subtotal must not hide an unpriced
-        # attempt, and the merged trace may have re-priced on the last model.
+        # attempt.
         def cost_unknown?
+          return true if @cost_complete == false
+
           if @attempts.is_a?(Array) && !@attempts.empty?
-            @attempts.any? { |attempt| self.class.unpriced?(attempt[:model], attempt[:usage], attempt[:cost]) }
+            @attempts.any? do |attempt|
+              attempt[:cost_unknown] || self.class.unpriced?(attempt[:model], attempt[:usage], attempt[:cost])
+            end
           else
-            self.class.unpriced?(@model, @usage, @cost)
+            @cost_complete.nil? && self.class.unpriced?(@model, @usage, @cost)
           end
         end
 
@@ -70,8 +92,11 @@ module RubyLLM
         end
 
         def to_h
-          { messages: @messages, model: @model, latency_ms: @latency_ms,
-            usage: @usage, attempts: @attempts, cost: @cost }.compact
+          hash = { messages: @messages, model: @model, latency_ms: @latency_ms,
+                   usage: @usage, attempts: @attempts, cost: @cost, usage_complete: @usage_complete,
+                   cost_complete: @cost_complete, finish_reason: @finish_reason, error_class: @error_class }.compact
+          hash[:cost] = nil if @keep_nil_cost
+          hash
         end
 
         def to_s
@@ -80,6 +105,22 @@ module RubyLLM
 
         private
 
+        # A given nil cost that the registry would price must stay `cost: nil` in
+        # to_h, or `Trace.new(**to_h)` would come back priced. Otherwise it is
+        # left out, so a merged trace compares equal to the one it came from.
+        def keep_nil_cost?(cost)
+          return false unless cost.nil? && @cost_complete.nil?
+
+          !CostCalculator.calculate(model_name: @model, usage: @usage).nil?
+        end
+
+        def resolve_cost(cost)
+          return cost unless cost.equal?(COST_UNSET)
+          return nil unless @cost_complete.nil?
+
+          CostCalculator.calculate(model_name: @model, usage: @usage)
+        end
+
         def build_summary_parts
           parts = [@model || "no-model"]
           parts << "#{@latency_ms}ms" if @latency_ms

data/lib/ruby_llm/contract/token_estimator.rb

@@ -11,9 +11,11 @@ module RubyLLM
     #   - Worse for non-English text, code, structured data, and unusual scripts
     #   - Useless for models with very different tokenizers (e.g. some open-source models)
     #
-    # RubyLLM 1.14 ships no pre-flight tokenizer either; once the API call
-    # returns, `RubyLLM::Tokens` provides accurate counts from provider usage
-    # data. This estimator is for the *pre-flight refusal* path only — its job
+    # RubyLLM 2.x can count tokens exactly before a call (`chat.count_tokens`),
+    # but only on some providers and at the price of an extra request, so this
+    # local estimate stays the default; once the API call returns,
+    # `RubyLLM::Tokens` provides accurate counts from provider usage data.
+    # This estimator is for the *pre-flight refusal* path only - its job
     # is to answer "is this call almost certainly within budget?" with enough
     # accuracy that runaway prompts get caught, while accepting that the
     # boundary cases will be wrong.

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "1.1.1"
+    VERSION = "1.2.0"
   end
 end

data/lib/ruby_llm/contract/workflow_scope.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Contract
+    # Groups a step's or pipeline's RubyLLM calls under `RubyLLM.workflow`, so
+    # OpenTelemetry spans and instrumentation events carry the step's name.
+    # Off unless `RubyLLM::Contract.configure { |c| c.workflow_instrumentation = true }`.
+    #
+    # A pipeline opens one workflow and runs each step as `workflow.step(alias)`;
+    # a step run inside it does not open another. A step run on its own opens a
+    # workflow named after its class. A workflow the application opened itself
+    # becomes the parent, as RubyLLM links nested workflows.
+    module WorkflowScope
+      CURRENT_KEY = :ruby_llm_contract_workflow
+
+      def self.workflow(name, &block)
+        return yield unless enabled? && current.nil?
+
+        ::RubyLLM.workflow(name.to_s) { |workflow| within(workflow, &block) }
+      end
+
+      def self.step(name, &)
+        workflow = current
+        return yield unless enabled? && workflow
+
+        workflow.step(name.to_s, &)
+      end
+
+      def self.enabled?
+        Contract.configuration.workflow_instrumentation
+      end
+
+      # Fiber-local, so concurrent eval threads each get their own.
+      def self.current
+        Thread.current[CURRENT_KEY]
+      end
+
+      def self.within(workflow)
+        previous = Thread.current[CURRENT_KEY]
+        Thread.current[CURRENT_KEY] = workflow
+        yield
+      ensure
+        Thread.current[CURRENT_KEY] = previous
+      end
+      private_class_method :within
+    end
+  end
+end

data/lib/ruby_llm/contract.rb

@@ -3,6 +3,8 @@
 require_relative "contract/version"
 require_relative "contract/errors"
 require_relative "contract/unknown_policy"
+require_relative "contract/provider_options"
+require_relative "contract/workflow_scope"
 require_relative "contract/types"
 
 module RubyLLM

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-contract
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Justyna
@@ -170,6 +170,7 @@ files:
 - lib/ruby_llm/contract/prompt/nodes/system_node.rb
 - lib/ruby_llm/contract/prompt/nodes/user_node.rb
 - lib/ruby_llm/contract/prompt/renderer.rb
+- lib/ruby_llm/contract/provider_options.rb
 - lib/ruby_llm/contract/railtie.rb
 - lib/ruby_llm/contract/rake_task.rb
 - lib/ruby_llm/contract/rake_task/suite_gate.rb
@@ -195,6 +196,7 @@ files:
 - lib/ruby_llm/contract/types.rb
 - lib/ruby_llm/contract/unknown_policy.rb
 - lib/ruby_llm/contract/version.rb
+- lib/ruby_llm/contract/workflow_scope.rb
 - ruby_llm-contract.gemspec
 homepage: https://github.com/justi/ruby_llm-contract
 licenses: