solid_agent 0.1.1 → 0.2.0

data/lib/solid_agent/has_reasons.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # HasReasons provides reasoning/thinking trace collection for agents.
+  #
+  # This concern enables agents to capture and track extended thinking
+  # from LLMs that support it (Claude's extended thinking, OpenAI o1, etc.).
+  #
+  # Reasoning traces are captured separately from the main response content,
+  # allowing for:
+  # - Transparent AI decision-making
+  # - Debugging and analysis of AI behavior
+  # - Audit trails for compliance
+  # - Cost tracking (reasoning tokens)
+  #
+  # @example Basic usage
+  #   class ResearchAgent < ApplicationAgent
+  #     include SolidAgent::HasReasons
+  #
+  #     def analyze
+  #       result = prompt(
+  #         messages: research_messages,
+  #         extended_thinking: true  # Enable extended thinking
+  #       )
+  #
+  #       # Reasoning is automatically captured
+  #       last_reasoning.content  #=> "Let me analyze this systematically..."
+  #       total_reasoning_tokens  #=> 450
+  #     end
+  #   end
+  #
+  # @example Configuring reasoning capture
+  #   class AnalysisAgent < ApplicationAgent
+  #     include SolidAgent::HasReasons
+  #
+  #     has_reasons(
+  #       auto_capture: true,        # Auto-capture from all generations
+  #       persist: true,             # Persist to database
+  #       budget_tokens: 10000       # Default reasoning token budget
+  #     )
+  #   end
+  #
+  # @example Accessing reasoning history
+  #   agent.reasons                  # All captured reasons
+  #   agent.reasoning_chain          # Formatted reasoning chain
+  #   agent.total_reasoning_tokens   # Sum of all reasoning tokens
+  #
+  module HasReasons
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_reasons_config, default: {
+        auto_capture: true,
+        persist: false,
+        budget_tokens: nil,
+        redact_on_persist: false
+      }
+
+      # Storage for captured reasons
+      attr_accessor :_captured_reasons
+    end
+
+    class_methods do
+      # Configure reasoning behavior for this agent
+      #
+      # @param auto_capture [Boolean] Automatically capture reasoning from responses
+      # @param persist [Boolean] Persist reasoning to context (requires HasContext)
+      # @param budget_tokens [Integer, nil] Default reasoning token budget
+      # @param redact_on_persist [Boolean] Redact reasoning content when persisting
+      def has_reasons(auto_capture: true, persist: false, budget_tokens: nil, redact_on_persist: false)
+        self._reasons_config = {
+          auto_capture: auto_capture,
+          persist: persist,
+          budget_tokens: budget_tokens,
+          redact_on_persist: redact_on_persist
+        }
+      end
+    end
+
+    # Get all captured reasons for this agent instance
+    #
+    # @return [Array<Reasonable::Reason>]
+    def reasons
+      @_captured_reasons ||= []
+    end
+
+    # Get the last captured reason
+    #
+    # @return [Reasonable::Reason, nil]
+    def last_reasoning
+      reasons.last
+    end
+
+    # Get the total reasoning tokens used
+    #
+    # @return [Integer]
+    def total_reasoning_tokens
+      reasons.sum(&:tokens)
+    end
+
+    # Check if any reasoning has been captured
+    #
+    # @return [Boolean]
+    def has_reasoning?
+      reasons.any?(&:extended_thinking?)
+    end
+
+    # Get a formatted reasoning chain (all reasoning in sequence)
+    #
+    # @param separator [String] Separator between reasons
+    # @return [String]
+    def reasoning_chain(separator: "\n\n---\n\n")
+      reasons
+        .select(&:extended_thinking?)
+        .reject(&:redacted?)
+        .map(&:content)
+        .join(separator)
+    end
+
+    # Get reasoning statistics
+    #
+    # @return [Hash]
+    def reasoning_stats
+      {
+        count: reasons.count,
+        total_tokens: total_reasoning_tokens,
+        total_thinking_time_ms: reasons.sum { |r| r.thinking_time_ms || 0 },
+        redacted_count: reasons.count(&:redacted?),
+        models: reasons.map(&:model).compact.uniq
+      }
+    end
+
+    # Capture reasoning from an LLM response
+    #
+    # @param response [Object] LLM response object
+    # @return [Reasonable::Reason, nil] The captured reason
+    def capture_reasoning(response)
+      reason = Reasonable::Reason.from_response(response)
+      return nil unless reason&.extended_thinking?
+
+      @_captured_reasons ||= []
+      @_captured_reasons << reason
+
+      # Persist if configured and HasContext is available
+      persist_reasoning(reason) if _reasons_config[:persist]
+
+      reason
+    end
+
+    # Manually add a reason
+    #
+    # @param content [String] Reasoning content
+    # @param tokens [Integer] Token count
+    # @param metadata [Hash] Additional metadata
+    # @return [Reasonable::Reason]
+    def add_reason(content:, tokens: 0, **metadata)
+      reason = Reasonable::Reason.new(
+        content: content,
+        tokens: tokens,
+        model: current_model,
+        **metadata
+      )
+
+      @_captured_reasons ||= []
+      @_captured_reasons << reason
+
+      persist_reasoning(reason) if _reasons_config[:persist]
+
+      reason
+    end
+
+    # Clear all captured reasons
+    def clear_reasons!
+      @_captured_reasons = []
+    end
+
+    # Get default prompt options with reasoning configuration
+    #
+    # @return [Hash]
+    def reasoning_prompt_options
+      options = {}
+
+      if _reasons_config[:budget_tokens]
+        options[:reasoning_budget_tokens] = _reasons_config[:budget_tokens]
+      end
+
+      options[:extended_thinking] = true if _reasons_config[:auto_capture]
+
+      options
+    end
+
+    private
+
+    def persist_reasoning(reason)
+      return unless respond_to?(:context) && context.respond_to?(:generations)
+
+      # Find the most recent generation and store reasoning
+      generation = context.generations.order(created_at: :desc).first
+      return unless generation
+
+      if generation.respond_to?(:store_reason!)
+        # If generation includes Reasonable
+        persisted_reason = if _reasons_config[:redact_on_persist]
+          Reasonable::Reason.new(
+            content: "[Redacted]",
+            tokens: reason.tokens,
+            model: reason.model,
+            thinking_time_ms: reason.thinking_time_ms,
+            redacted: true,
+            metadata: reason.metadata
+          )
+        else
+          reason
+        end
+
+        generation.store_reason!(persisted_reason)
+      end
+    rescue StandardError => e
+      # Log but don't fail if persistence fails
+      Rails.logger.warn "[SolidAgent::HasReasons] Failed to persist reasoning: #{e.message}" if defined?(Rails)
+    end
+
+    def current_model
+      return @model if defined?(@model)
+      return prompt_options[:model] if respond_to?(:prompt_options) && prompt_options[:model]
+
+      nil
+    end
+  end
+end

data/lib/solid_agent/model_naming.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # The one place that knows how a context class name maps to its message and
+  # generation class names.
+  #
+  # Two callers derive these names — HasContext#infer_class_names at runtime and
+  # the context generator when writing files — and they used to implement the
+  # rule independently, which is how they drifted.
+  module ModelNaming
+    # Suffixes a context class may end with. Only the first match is stripped:
+    # chaining +delete_suffix+ reduces "SessionContext" to "" and produces a
+    # bare "Message"/"Generation" pair that collides across every context.
+    CONTEXT_SUFFIXES = %w[Context Session].freeze
+
+    class << self
+      # The stem a context class name contributes to its siblings.
+      #
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      #
+      # @example
+      #   base_for("ChatSession")     #=> "Chat"
+      #   base_for("SessionContext")  #=> "Session"
+      #   base_for("Conversation")    #=> "Conversation"
+      def base_for(class_name)
+        name = class_name.to_s
+        suffix = CONTEXT_SUFFIXES.find { |candidate| name.end_with?(candidate) && name != candidate }
+
+        suffix ? name.delete_suffix(suffix) : name
+      end
+
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      def message_class_for(class_name) = "#{base_for(class_name)}Message"
+
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      def generation_class_for(class_name) = "#{base_for(class_name)}Generation"
+    end
+  end
+end

data/lib/solid_agent/model_pricing.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # Estimates LLM spend from token counts (USD). Generation records store
+  # tokens only; pricing is layered on top for cost reporting, so figures
+  # are always estimates.
+  #
+  # Rates come from RubyLLM's model registry (USD per million tokens,
+  # maintained upstream per model) when that gem is available and knows
+  # the model; the static pattern table below is the fallback for aliases
+  # and self-hosted models, and a conservative blended rate covers
+  # everything else so totals stay meaningful.
+  #
+  # @example Estimate a generation's cost
+  #   SolidAgent::ModelPricing.estimate(
+  #     model: "claude-sonnet-5", input_tokens: 12_000, output_tokens: 800
+  #   ) # => 0.048
+  #
+  # @example Look up a model's rates ($/1M input, $/1M output)
+  #   SolidAgent::ModelPricing.rate_for("gpt-4o-mini") # => [0.15, 0.60]
+  class ModelPricing
+    PRICES = [
+      # [pattern, input $/1M, output $/1M] — first match wins, so mock
+      # models ("mock-gpt-4o-mini") price free before real-model patterns.
+      [ /mock/i, 0.0, 0.0 ],
+      [ /gpt-4o-mini/i, 0.15, 0.60 ],
+      [ /gpt-4o/i, 2.50, 10.00 ],
+      [ /gpt-4\.1-nano/i, 0.10, 0.40 ],
+      [ /gpt-4\.1-mini/i, 0.40, 1.60 ],
+      [ /gpt-4\.1/i, 2.00, 8.00 ],
+      [ /o3-mini|o4-mini/i, 1.10, 4.40 ],
+      [ /claude.*(fable|mythos)/i, 10.00, 50.00 ],
+      [ /claude.*haiku-?4/i, 1.00, 5.00 ],
+      [ /claude.*(haiku)/i, 0.80, 4.00 ],
+      [ /claude.*(sonnet)/i, 3.00, 15.00 ],
+      [ /claude.*opus-(5|4-[5-9])/i, 5.00, 25.00 ],
+      [ /claude.*(opus)/i, 15.00, 75.00 ],
+      [ /gemini.*flash/i, 0.10, 0.40 ],
+      [ /gemini.*pro/i, 1.25, 10.00 ],
+      [ /llama|mistral|mixtral|qwen|deepseek/i, 0.20, 0.60 ]
+    ].freeze
+
+    # Fallback blended rate for unknown models ($/1M input, $/1M output)
+    DEFAULT_RATE = [ 1.00, 4.00 ].freeze
+
+    class << self
+      # @return [Float, nil] estimated USD cost, nil when there is nothing
+      #   to price
+      def estimate(model:, input_tokens:, output_tokens:)
+        input = input_tokens.to_i
+        output = output_tokens.to_i
+        return nil if input.zero? && output.zero?
+
+        input_rate, output_rate = rate_for(model)
+        ((input * input_rate) + (output * output_rate)) / 1_000_000.0
+      end
+
+      # @return [Array(Float, Float)] $/1M input and output token rates
+      def rate_for(model)
+        return DEFAULT_RATE if model.blank?
+
+        registry_rate(model) || static_rate(model)
+      end
+
+      # Exact per-model rates from RubyLLM's registry when that gem is
+      # loaded. Lookups are memoized — the registry scan is not free and
+      # cost reporting calls this per row.
+      def registry_rate(model)
+        return nil unless defined?(::RubyLLM)
+
+        @registry_rates ||= {}
+        return @registry_rates[model] if @registry_rates.key?(model)
+
+        @registry_rates[model] = begin
+          info = ::RubyLLM.models.find(model.to_s)
+          tokens = info&.pricing&.text_tokens
+          if tokens&.input && tokens&.output
+            [ tokens.input, tokens.output ]
+          end
+        rescue ::StandardError
+          nil
+        end
+      end
+
+      def static_rate(model)
+        PRICES.each do |pattern, input_rate, output_rate|
+          return [ input_rate, output_rate ] if model.to_s.match?(pattern)
+        end
+        DEFAULT_RATE
+      end
+    end
+  end
+end

data/lib/solid_agent/reasonable/reason.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  module Reasonable
+    # Reason represents a single reasoning trace from an LLM's extended thinking.
+    #
+    # LLMs like Claude (with extended thinking) and OpenAI's o1 models produce
+    # reasoning traces that explain their thought process before generating output.
+    # This class captures and structures that reasoning for persistence and analysis.
+    #
+    # @example Creating a reason from an LLM response
+    #   reason = Reason.new(
+    #     content: "Let me think about this step by step...",
+    #     tokens: 150,
+    #     model: "claude-sonnet-4-20250514",
+    #     thinking_time_ms: 2500
+    #   )
+    #
+    # @example Checking if reasoning was used
+    #   reason.extended_thinking? #=> true
+    #   reason.summary(100) #=> "Let me think about this..."
+    #
+    class Reason
+      attr_reader :content, :tokens, :model, :thinking_time_ms,
+                  :created_at, :metadata, :redacted
+
+      # Initialize a new Reason
+      #
+      # @param content [String] The reasoning content/trace
+      # @param tokens [Integer] Number of reasoning tokens used
+      # @param model [String] The model that generated the reasoning
+      # @param thinking_time_ms [Integer, nil] Time spent on reasoning
+      # @param redacted [Boolean] Whether content was redacted by provider
+      # @param metadata [Hash] Additional provider-specific metadata
+      def initialize(content:, tokens: 0, model: nil, thinking_time_ms: nil,
+                     redacted: false, metadata: {}, created_at: nil)
+        @content = content
+        @tokens = tokens.to_i
+        @model = model
+        @thinking_time_ms = thinking_time_ms
+        @redacted = redacted
+        @metadata = metadata || {}
+        @created_at = created_at || Time.current
+      end
+
+      # Check if this represents extended thinking (vs. standard generation)
+      #
+      # @return [Boolean]
+      def extended_thinking?
+        tokens.positive? || content.present?
+      end
+
+      # Check if the reasoning content was redacted by the provider
+      #
+      # @return [Boolean]
+      def redacted?
+        @redacted == true
+      end
+
+      # Get a summary of the reasoning content
+      #
+      # @param length [Integer] Maximum length of summary
+      # @return [String]
+      def summary(length: 200)
+        return "[Redacted]" if redacted?
+        return "" if content.blank?
+
+        str = content.to_s
+        return str if str.length <= length
+
+        "#{str[0, length - 3]}..."
+      end
+
+      # Convert to a hash for serialization
+      #
+      # @return [Hash]
+      def to_h
+        {
+          content: content,
+          tokens: tokens,
+          model: model,
+          thinking_time_ms: thinking_time_ms,
+          redacted: redacted,
+          metadata: metadata,
+          created_at: created_at&.iso8601
+        }.compact
+      end
+
+      # Create from a hash (deserialization)
+      #
+      # @param hash [Hash] Hash representation
+      # @return [Reason]
+      def self.from_h(hash)
+        return nil unless hash.is_a?(Hash)
+
+        new(
+          content: hash[:content] || hash["content"],
+          tokens: hash[:tokens] || hash["tokens"] || 0,
+          model: hash[:model] || hash["model"],
+          thinking_time_ms: hash[:thinking_time_ms] || hash["thinking_time_ms"],
+          redacted: hash[:redacted] || hash["redacted"] || false,
+          metadata: hash[:metadata] || hash["metadata"] || {},
+          created_at: parse_time(hash[:created_at] || hash["created_at"])
+        )
+      end
+
+      # Create from an ActiveAgent/LLM provider response
+      #
+      # @param response [Object] Provider response object
+      # @return [Reason, nil]
+      def self.from_response(response)
+        return nil unless response
+
+        # Handle different response formats
+        reasoning_content = extract_reasoning_content(response)
+        reasoning_tokens = extract_reasoning_tokens(response)
+
+        return nil if reasoning_content.blank? && reasoning_tokens.zero?
+
+        new(
+          content: reasoning_content,
+          tokens: reasoning_tokens,
+          model: response.respond_to?(:model) ? response.model : nil,
+          thinking_time_ms: extract_thinking_time(response),
+          redacted: reasoning_redacted?(response),
+          metadata: extract_reasoning_metadata(response)
+        )
+      end
+
+      class << self
+        private
+
+        def parse_time(value)
+          return nil unless value
+          return value if value.is_a?(Time)
+
+          Time.parse(value.to_s)
+        rescue ArgumentError
+          nil
+        end
+
+        def extract_reasoning_content(response)
+          # Claude format
+          return response.reasoning_content if response.respond_to?(:reasoning_content)
+
+          # OpenAI o1 format (reasoning is often in a separate field)
+          if response.respond_to?(:choices) && response.choices&.first
+            choice = response.choices.first
+            return choice.reasoning if choice.respond_to?(:reasoning)
+          end
+
+          # Check usage for reasoning summary
+          if response.respond_to?(:usage) && response.usage
+            usage = response.usage
+            return usage.reasoning_content if usage.respond_to?(:reasoning_content)
+          end
+
+          nil
+        end
+
+        def extract_reasoning_tokens(response)
+          return 0 unless response.respond_to?(:usage) && response.usage
+
+          usage = response.usage
+          if usage.respond_to?(:reasoning_tokens)
+            usage.reasoning_tokens || 0
+          else
+            0
+          end
+        end
+
+        def extract_thinking_time(response)
+          return nil unless response.respond_to?(:usage) && response.usage
+
+          usage = response.usage
+          # Some providers track thinking time separately
+          if usage.respond_to?(:thinking_time_ms)
+            usage.thinking_time_ms
+          elsif usage.respond_to?(:reasoning_time_ms)
+            usage.reasoning_time_ms
+          end
+        end
+
+        def reasoning_redacted?(response)
+          return false unless response.respond_to?(:usage) && response.usage
+
+          usage = response.usage
+          usage.respond_to?(:reasoning_redacted) && usage.reasoning_redacted == true
+        end
+
+        def extract_reasoning_metadata(response)
+          metadata = {}
+
+          if response.respond_to?(:usage) && response.usage
+            usage = response.usage
+            metadata[:budget_tokens] = usage.reasoning_budget_tokens if usage.respond_to?(:reasoning_budget_tokens)
+            metadata[:effort] = usage.reasoning_effort if usage.respond_to?(:reasoning_effort)
+          end
+
+          metadata.compact
+        end
+      end
+    end
+  end
+end