solid_agent 0.0.0 → 0.2.0

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

data/lib/solid_agent/reasonable.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative "reasonable/reason"
+
+module SolidAgent
+  # Reasonable provides AI reasoning/thinking trace support for models.
+  #
+  # This concern enables models to track and store reasoning traces from
+  # LLMs that support extended thinking (like Claude's extended thinking
+  # or OpenAI's o1 reasoning models).
+  #
+  # Reasoning traces help with:
+  # - Transparency: Understanding why an AI made certain decisions
+  # - Debugging: Identifying issues in AI logic
+  # - Auditing: Maintaining records of AI decision-making processes
+  # - Learning: Improving prompts based on reasoning patterns
+  #
+  # @example Basic usage in a model
+  #   class AgentGeneration < ApplicationRecord
+  #     include SolidAgent::Reasonable
+  #   end
+  #
+  #   generation.store_reasoning!(response)
+  #   generation.reasoning_content     #=> "Let me think step by step..."
+  #   generation.reasoning_tokens      #=> 150
+  #   generation.has_reasoning?        #=> true
+  #
+  # @example Configuring reasoning storage
+  #   class MyGeneration < ApplicationRecord
+  #     include SolidAgent::Reasonable
+  #
+  #     reasonable_config(
+  #       column: :thinking_trace,    # Custom column name
+  #       tokens_column: :think_tokens,
+  #       auto_extract: true          # Auto-extract from responses
+  #     )
+  #   end
+  #
+  module Reasonable
+    extend ActiveSupport::Concern
+
+    included do
+      # Default configuration
+      class_attribute :_reasonable_config, default: {
+        column: :reasoning_content,
+        tokens_column: :reasoning_tokens,
+        metadata_column: :reasoning_metadata,
+        auto_extract: false
+      }
+    end
+
+    class_methods do
+      # Configure reasoning storage options
+      #
+      # @param column [Symbol] Column to store reasoning content
+      # @param tokens_column [Symbol] Column to store token count
+      # @param metadata_column [Symbol] Column to store metadata (JSON)
+      # @param auto_extract [Boolean] Auto-extract reasoning from responses
+      def reasonable_config(column: nil, tokens_column: nil, metadata_column: nil, auto_extract: nil)
+        config = _reasonable_config.dup
+        config[:column] = column if column
+        config[:tokens_column] = tokens_column if tokens_column
+        config[:metadata_column] = metadata_column if metadata_column
+        config[:auto_extract] = auto_extract unless auto_extract.nil?
+        self._reasonable_config = config
+      end
+    end
+
+    # Store reasoning from an LLM response
+    #
+    # @param response [Object] LLM response with reasoning data
+    # @return [Reason, nil] The extracted reason or nil
+    def store_reasoning!(response)
+      reason = Reason.from_response(response)
+      return nil unless reason&.extended_thinking?
+
+      update_reasoning_columns(reason)
+      reason
+    end
+
+    # Store reasoning from a Reason object
+    #
+    # @param reason [Reason] The reason to store
+    # @return [Reason] The stored reason
+    def store_reason!(reason)
+      return nil unless reason.is_a?(Reason)
+
+      update_reasoning_columns(reason)
+      reason
+    end
+
+    # Get the stored reasoning content
+    #
+    # @return [String, nil]
+    def reasoning_content
+      column = _reasonable_config[:column]
+      respond_to?(column) ? send(column) : nil
+    end
+
+    # Get the stored reasoning token count
+    #
+    # @return [Integer]
+    def reasoning_tokens
+      column = _reasonable_config[:tokens_column]
+      (respond_to?(column) ? send(column) : 0).to_i
+    end
+
+    # Get the stored reasoning metadata
+    #
+    # @return [Hash]
+    def reasoning_metadata
+      column = _reasonable_config[:metadata_column]
+      (respond_to?(column) ? send(column) : {}) || {}
+    end
+
+    # Check if this record has reasoning stored
+    #
+    # @return [Boolean]
+    def has_reasoning?
+      reasoning_content.present? || reasoning_tokens.positive?
+    end
+
+    # Check if reasoning was redacted
+    #
+    # @return [Boolean]
+    def reasoning_redacted?
+      reasoning_metadata["redacted"] == true
+    end
+
+    # Get a Reason object from stored data
+    #
+    # @return [Reason, nil]
+    def to_reason
+      return nil unless has_reasoning?
+
+      Reason.new(
+        content: reasoning_content,
+        tokens: reasoning_tokens,
+        model: respond_to?(:model) ? model : nil,
+        thinking_time_ms: reasoning_metadata["thinking_time_ms"],
+        redacted: reasoning_redacted?,
+        metadata: reasoning_metadata,
+        created_at: respond_to?(:created_at) ? created_at : nil
+      )
+    end
+
+    # Get a summary of the reasoning
+    #
+    # @param length [Integer] Maximum length
+    # @return [String]
+    def reasoning_summary(length: 200)
+      return "[Redacted]" if reasoning_redacted?
+      return "" if reasoning_content.blank?
+
+      reasoning_content.truncate(length)
+    end
+
+    private
+
+    def update_reasoning_columns(reason)
+      updates = {}
+
+      content_col = _reasonable_config[:column]
+      tokens_col = _reasonable_config[:tokens_column]
+      metadata_col = _reasonable_config[:metadata_column]
+
+      updates[content_col] = reason.content if respond_to?("#{content_col}=")
+      updates[tokens_col] = reason.tokens if respond_to?("#{tokens_col}=")
+
+      if respond_to?("#{metadata_col}=")
+        updates[metadata_col] = {
+          thinking_time_ms: reason.thinking_time_ms,
+          redacted: reason.redacted,
+          model: reason.model
+        }.merge(reason.metadata).compact
+      end
+
+      update!(updates) if updates.any? && respond_to?(:update!)
+    end
+  end
+end