smith-agents 0.7.0 → 0.10.0

data/lib/smith/agent/provider_completion.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "provider_failure_handling"
+require_relative "invocation_preparation"
+require_relative "provider_attempt"
+require_relative "provider_call_timing"
+require_relative "provider_candidate_sequence"
+
+module Smith
+  class Agent
+    module ProviderCompletion
+      include ProviderFailureHandling
+      include InvocationPreparation
+      include ProviderCallTiming
+
+      private
+
+      def complete_with_provider(agent_class, prepared_input, output_schema:)
+        candidates = ProviderCandidateSequence.new(build_model_chain(agent_class))
+        candidates.each do |model_reference, index|
+          check_deadline! if index.positive?
+          attempt = attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index: index)
+          return attempt if attempt.success?
+
+          candidates.suppress(account_failed_provider(attempt, model_reference))
+          handle_provider_failure!(
+            attempt.error, attempt.model_reference, agent_class,
+            fallback_available: candidates.fallback_available?,
+            attempt_id: attempt.attempt_id
+          )
+        end
+
+        # Fail closed: an empty candidate chain (agent without a model)
+        # or any exhausted sequence must surface a typed diagnostic, not
+        # the sequence itself destructured into nils.
+        raise Smith::AgentError,
+              "no executable model candidate for #{agent_class}; declare a model or fallback_models"
+      end
+
+      # Suppression keys on the provider that actually rejected the
+      # account; when the chat is unobservable the attempted reference's
+      # declared provider is the best available attribution, so a dead
+      # account is not billed a second same-provider attempt.
+      def account_failed_provider(attempt, attempted_reference)
+        return unless provider_account_failure?(attempt.error)
+
+        attempt.model_reference.provider || attempted_reference.provider
+      end
+
+      def build_model_chain(agent_class)
+        references = [primary_model_reference(agent_class), *fallback_model_references(agent_class)].compact
+        references.each_with_object([]) do |reference, chain|
+          chain << reference unless chain.any? { |kept| kept.same_candidate?(reference) }
+        end
+      end
+
+      def primary_model_reference(agent_class)
+        return resolve_dynamic_model(agent_class) if agent_class.model_block
+
+        model_id = agent_class.chat_kwargs[:model]
+        return unless model_id
+
+        # Static declarations stay literal: RubyLLM owns the meaning of
+        # the declared id, so a slashed id ("openai/gpt-5") is not split
+        # into provider/model here the way ModelReference.coerce parses
+        # host-supplied strings.
+        ModelReference.new(model_id: model_id, provider: agent_class.chat_kwargs[:provider])
+      end
+
+      def fallback_model_references(agent_class)
+        Array(agent_class.fallback_models).map { |model| ModelReference.coerce(model) }
+      end
+
+      def resolve_dynamic_model(agent_class)
+        result = agent_class.model_block.call(@context || {})
+        reference = ModelReference.coerce(result)
+        return reference if reference.provider
+
+        raise Smith::AgentError,
+              "model block for #{agent_class} must return a provider-qualified model reference; got #{result.inspect}"
+      rescue ArgumentError, Dry::Struct::Error => e
+        raise Smith::AgentError, "invalid model block result for #{agent_class}: #{e.message}"
+      end
+
+      # rubocop:disable Metrics/AbcSize -- one provider attempt is a single
+      # cohesive lifecycle (identity, prepared chat, observed model, timed
+      # completion, prefix accounting on failure); splitting it would scatter
+      # the rescue-path accounting away from what it accounts for.
+      def attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index:)
+        attempt_id = SecureRandom.uuid
+        chat = prepared_attempt_chat(agent_class, prepared_input, model_reference, output_schema:)
+        message_count = chat_message_count(chat)
+        observed_reference = observed_model_reference(chat, fallback: model_reference)
+        timer = ProviderCallTiming::Timer.start
+        response = chat.complete
+        timer.stop
+        completion = Completion.from_messages(response: response, messages: new_chat_messages(chat, message_count))
+
+        attempt = ProviderAttempt.success(
+          completion:, model_reference: observed_reference, attempt_id:, duration_ms: timer.elapsed_ms
+        )
+        record_provider_call_trace(attempt, attempt_index)
+        attempt
+      rescue StandardError => e
+        timer&.stop
+        observed_reference ||= observed_model_reference(chat, fallback: model_reference)
+        account_completed_prefix(agent_class, observed_reference, new_chat_messages(chat, message_count), attempt_id:)
+        attempt = failed_provider_attempt(e, observed_reference, attempt_id, timer, attempt_index)
+        raise unless provider_failure?(e)
+
+        attempt
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def observed_model_reference(chat, fallback:)
+        model = observable_model(chat)
+        return fallback unless model.respond_to?(:id) && !model.id.to_s.empty?
+
+        ModelReference.coerce(model.id, provider: observed_provider(model, fallback))
+      rescue StandardError
+        fallback
+      end
+
+      def observable_model(chat)
+        resolved_chat = chat.respond_to?(:to_llm) ? chat.to_llm : chat
+        resolved_chat.model if resolved_chat.respond_to?(:model)
+      end
+
+      def observed_provider(model, fallback)
+        model.respond_to?(:provider) && !model.provider.to_s.empty? ? model.provider : fallback.provider
+      end
+
+      def prepared_attempt_chat(agent_class, prepared_input, model_reference, output_schema:)
+        chat = agent_class.chat(**model_reference.chat_options, **bridge_workflow_inputs(agent_class))
+        add_prepared_input(chat, prepared_input)
+        output_schema ? chat.with_schema(output_schema) : chat
+      end
+
+      def chat_message_count(chat)
+        chat.respond_to?(:messages) ? chat.messages.length : nil
+      end
+
+      def new_chat_messages(chat, message_count)
+        message_count ? chat.messages.drop(message_count) : []
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_failure_handling.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module ProviderFailureHandling
+      TRANSIENT_ERRORS = [
+        RubyLLM::ServerError,
+        RubyLLM::ServiceUnavailableError,
+        RubyLLM::OverloadedError,
+        RubyLLM::RateLimitError
+      ].freeze
+      MODEL_UNAVAILABLE_STATUSES = [404, 410].freeze
+      PROVIDER_ACCOUNT_ERRORS = [
+        RubyLLM::UnauthorizedError,
+        RubyLLM::PaymentRequiredError
+      ].freeze
+      MODEL_PERMISSION_ERRORS = [RubyLLM::ForbiddenError].freeze
+
+      private_constant :TRANSIENT_ERRORS, :MODEL_UNAVAILABLE_STATUSES,
+                       :PROVIDER_ACCOUNT_ERRORS, :MODEL_PERMISSION_ERRORS
+
+      private
+
+      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:, attempt_id: nil)
+        account_failed_attempt(error, model_reference, agent_class, attempt_id:)
+        if completed_tool_calls?
+          raise Smith::ToolOutcomeUncertain.new(
+            "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"
+          ), cause: error
+        end
+        return if fallback_eligible?(error) && fallback_available
+
+        raise terminal_provider_error(error, model_reference), cause: error
+      end
+
+      def provider_failure?(error)
+        error.is_a?(RubyLLM::Error) ||
+          (defined?(RubyLLM::ModelNotFoundError) && error.is_a?(RubyLLM::ModelNotFoundError)) ||
+          error.is_a?(Faraday::TimeoutError) ||
+          error.is_a?(Faraday::ConnectionFailed)
+      end
+
+      def provider_account_failure?(error)
+        PROVIDER_ACCOUNT_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def completed_tool_calls?
+        Tool.current_tool_execution_tracker&.started?
+      end
+
+      def fallback_eligible?(error)
+        transient_failure?(error) ||
+          transport_failure?(error) ||
+          provider_account_failure?(error) ||
+          model_permission_failure?(error) ||
+          model_unavailable?(error)
+      end
+
+      def transient_failure?(error)
+        TRANSIENT_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def transport_failure?(error)
+        error.is_a?(Faraday::TimeoutError) || error.is_a?(Faraday::ConnectionFailed)
+      end
+
+      def model_permission_failure?(error)
+        MODEL_PERMISSION_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def model_unavailable?(error)
+        return true if defined?(RubyLLM::ModelNotFoundError) && error.is_a?(RubyLLM::ModelNotFoundError)
+        return false unless error.respond_to?(:response)
+
+        response = error.response
+        response.respond_to?(:status) && MODEL_UNAVAILABLE_STATUSES.include?(response.status.to_i)
+      rescue StandardError
+        false
+      end
+
+      def terminal_provider_error(error, model_reference)
+        return Smith::AgentError.new(error.message) if transient_failure?(error) || transport_failure?(error)
+
+        Smith::ProviderPermanentFailure.new(
+          error.message,
+          provider: model_reference.provider,
+          model_id: model_reference.model_id,
+          source_error_class: error.class.name
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_usage.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+
+module Smith
+  class Agent
+    class ProviderUsage < Dry::Struct
+      attribute :input_tokens, Types::Integer
+      attribute :output_tokens, Types::Integer
+
+      def self.from_message(message)
+        return unless message.respond_to?(:input_tokens) && message.respond_to?(:output_tokens)
+
+        input_tokens = message.input_tokens
+        output_tokens = message.output_tokens
+        return unless input_tokens.is_a?(Integer) && output_tokens.is_a?(Integer)
+
+        new(input_tokens:, output_tokens:)
+      end
+
+      def total_tokens
+        input_tokens + output_tokens
+      end
+    end
+  end
+end

data/lib/smith/agent/reserved_input_bridge.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module ReservedInputBridge
+      private
+
+      def partition_inputs(kwargs)
+        input_values, chat_options = super
+        provider = input_values[:provider]
+        chat_options[:provider] = provider if provider && provider.to_sym != :unknown
+        [input_values, chat_options]
+      end
+
+      def apply_configuration(chat_object, input_values:, persist_instructions:)
+        super(
+          chat_object,
+          input_values: reserved_inputs_for(chat_object, input_values),
+          persist_instructions:
+        )
+      end
+
+      def reserved_inputs_for(chat_object, input_values)
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        model = llm_chat.model if llm_chat.respond_to?(:model)
+        profile = resolve_profile(
+          model&.id || input_values[:model_id],
+          provider: actual_provider(llm_chat) || input_values[:provider]
+        )
+        return input_values unless profile
+
+        input_values.merge(
+          model_id: profile.model_id,
+          provider: profile.provider,
+          endpoint_mode: profile.endpoint_mode
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_entry_recording.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module UsageEntryRecording
+      private
+
+      def record_usage(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
+        return unless agent_result.usage_known?
+
+        model_reference = coerce_model_reference(model_reference)
+        entry = build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id:)
+        accumulate_usage(agent_result, entry)
+      end
+
+      # Attribution (transition, branch key, optimizer round) is read from the
+      # ambient context of the recording thread, which is the thread that ran
+      # the provider call: a fan-out branch records under its own overlay.
+      # transition and branch_key are recorded as Symbols even when a host
+      # seeded Strings through Attribution.with, because from_h symbolizes
+      # them on restore: recording the same way keeps a restored entry equal
+      # to the recorded one.
+      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
+        Workflow::UsageEntry.new(
+          usage_id: SecureRandom.uuid,
+          agent_name: agent_class.register_as,
+          model: model_reference.model_id,
+          provider: model_reference.provider,
+          input_tokens: agent_result.input_tokens,
+          output_tokens: agent_result.output_tokens,
+          cost: agent_result.cost,
+          attempt_kind: attempt_kind,
+          recorded_at: Time.now.utc.iso8601(6),
+          attempt_id: attempt_id,
+          **ambient_attribution_fields
+        )
+      end
+
+      def ambient_attribution_fields
+        attribution = Smith::Attribution.ambient
+        {
+          transition: symbolized_attribution(attribution.transition),
+          branch_key: symbolized_attribution(attribution.branch_key),
+          round: attribution.round,
+          workflow: attribution.workflow
+        }
+      end
+
+      def symbolized_attribution(value)
+        value.is_a?(String) ? value.to_sym : value
+      end
+
+      def accumulate_usage(agent_result, entry)
+        @usage_mutex.synchronize do
+          @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens
+          @total_cost = (@total_cost || 0.0) + (agent_result.cost || 0.0)
+          @usage_entries << entry
+        end
+      end
+
+      def coerce_model_reference(value)
+        ModelReference.coerce(value)
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_traces.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # Trace emission for a completed agent invocation's usage facts, kept
+    # apart from the accounting itself (UsageTracking) so recording rows and
+    # emitting observability stay separate concerns.
+    module UsageTraces
+      private
+
+      def emit_token_usage(agent_result)
+        return unless agent_result.usage_known?
+
+        Smith::Trace.record(
+          type: :token_usage,
+          data: {
+            input_tokens: agent_result.input_tokens,
+            output_tokens: agent_result.output_tokens,
+            model: agent_result.model_used,
+            provider: agent_result.provider_used
+          }.compact
+        )
+      end
+
+      # One :cost trace per completed agent invocation. The cost is the sum
+      # of the invocation's per-response entry costs (what tiered catalogs
+      # actually bill), never the aggregate token totals priced as one call.
+      # Token counts remain the invocation aggregates. Billed failed and
+      # partial attempts appear only in usage entries, so summing :cost
+      # traces is not a spend total. Unpriced usage emits nothing, and the
+      # caller gates out partially metered or partially priced invocations
+      # so an incomplete figure is never presented as the invocation cost.
+      def emit_cost_trace(agent_result, invocation_cost)
+        return if invocation_cost.nil?
+
+        Smith::Trace.record(
+          type: :cost,
+          data: {
+            cost: invocation_cost,
+            model: agent_result.model_used,
+            provider: agent_result.provider_used,
+            input_tokens: agent_result.input_tokens,
+            output_tokens: agent_result.output_tokens
+          }.compact
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_tracking.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "completion_usage_recording"
+require_relative "usage_entry_recording"
+require_relative "usage_traces"
+
+module Smith
+  class Agent
+    module UsageTracking
+      include CompletionUsageRecording
+      include UsageEntryRecording
+      include UsageTraces
+
+      private
+
+      def account_failed_attempt(error, model_reference, agent_class, attempt_id: nil)
+        return unless error.respond_to?(:input_tokens) && error.respond_to?(:output_tokens)
+
+        input = error.input_tokens
+        output = error.output_tokens
+        return unless input.is_a?(Integer) && output.is_a?(Integer)
+
+        record_failed_usage(agent_class, model_reference, input, output, attempt_id:)
+      end
+
+      def account_completed_prefix(agent_class, model_reference, messages, attempt_id: nil)
+        completion = Completion.from_messages(response: nil, messages: messages)
+        record_completion_usage(agent_class, completion, :partial_attempt, model_reference, attempt_id:)
+      end
+
+      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_id: nil)
+        model_reference = coerce_model_reference(model_reference)
+        cost = Smith::Pricing.compute_cost(
+          model: model_reference.model_id,
+          provider: model_reference.provider,
+          input_tokens:,
+          output_tokens:
+        )
+        agent_result = Workflow::AgentResult.new(
+          content: nil,
+          input_tokens:,
+          output_tokens:,
+          cost: cost,
+          model_used: model_reference.model_id,
+          provider_used: model_reference.provider
+        )
+        Thread.current[:smith_failed_agent_results] ||= []
+        Thread.current[:smith_failed_agent_results] << agent_result
+        record_usage(agent_class, agent_result, :failed_attempt, model_reference, attempt_id:)
+      end
+
+      def snapshot_and_finalize(agent_class, completion, model_reference, attempt_id: nil)
+        model_reference = coerce_model_reference(model_reference)
+        agent_result = Workflow::AgentResult.new(
+          content: completion.content,
+          input_tokens: completion.input_tokens,
+          output_tokens: completion.output_tokens,
+          cost: nil,
+          model_used: model_reference.model_id,
+          provider_used: model_reference.provider
+        )
+        Thread.current[:smith_last_agent_result] = agent_result
+        emit_token_usage(agent_result)
+        account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
+
+        agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
+        raise_blank_output!(agent_class, agent_result)
+        agent_result
+      end
+
+      def raise_blank_output!(agent_class, agent_result)
+        return unless blank_agent_output?(agent_result.content)
+
+        raise Smith::BlankAgentOutputError.new(
+          agent_name: agent_class.register_as,
+          model_used: agent_result.model_used
+        )
+      end
+
+      def blank_agent_output?(content)
+        return true if content.nil?
+        return content.strip.empty? if content.is_a?(String)
+
+        false
+      end
+
+      # Records one usage entry per provider response and settles the
+      # invocation's cost from the recorded per-response sum: that sum is
+      # what tiered catalogs bill, so it becomes agent_result.cost (which
+      # budget settlement and result surfaces read) and the recorded entries,
+      # the budget ledger, and the :cost trace all agree. The trace emits
+      # only for fully metered, fully priced invocations, so a partial
+      # figure is never presented as the invocation cost; the partial sum
+      # still settles the budget because it is what was verifiably billed.
+      def account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
+        invocation_cost, fully_priced = record_completion_usage(
+          agent_class, completion, :completed_attempt, model_reference, attempt_id:
+        )
+        agent_result.cost = invocation_cost
+        emit_cost_trace(agent_result, invocation_cost) if fully_priced
+      end
+
+      def compute_agent_cost(agent_result)
+        return unless agent_result.usage_known?
+
+        model = agent_result.model_used
+        agent_result.cost = Smith::Pricing.compute_cost(
+          model: model,
+          provider: agent_result.provider_used,
+          input_tokens: agent_result.input_tokens,
+          output_tokens: agent_result.output_tokens
+        )
+      end
+    end
+  end
+end