tracebook 0.1.1 → 1.0.1

data/lib/generators/tracebook/install/install_generator.rb

@@ -7,11 +7,7 @@ module Tracebook
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      desc "Install TraceBook: copy migrations and create initializer"
-
-      def copy_migrations
-        rake "tracebook:install:migrations"
-      end
+      desc "Install Tracebook: create initializer"
 
       def create_initializer
         template "initializer.rb.tt", "config/initializers/tracebook.rb"
@@ -19,16 +15,17 @@ module Tracebook
 
       def show_next_steps
         say ""
-        say "TraceBook installed!", :green
+        say "Tracebook installed!", :green
         say ""
         say "Next steps:"
         say "  1. Run migrations:  bin/rails db:migrate"
         say "  2. Mount the engine in config/routes.rb:"
         say ""
-        say "     mount TraceBook::Engine => \"/tracebook\""
+        say "     mount Tracebook::Engine => \"/tracebook\""
         say ""
-        say "  3. Configure authorization in config/initializers/tracebook.rb"
-        say "  4. Set up ActiveRecord encryption (see README)"
+        say "  3. Seed default pricing:  bin/rails tracebook:seed_pricing"
+        say "  4. Call Tracebook.calculate_cost! after LLM responses"
+        say "     (see README for integration examples)"
         say ""
       end
     end

data/lib/generators/tracebook/install/templates/initializer.rb.tt

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
-TraceBook.configure do |config|
-  # config.project_name = "My App"
+Tracebook.configure do |config|
+  # Class names for your RubyLLM models (must use acts_as_chat / acts_as_message)
+  # config.chat_class = "Chat"
+  # config.message_class = "Message"
 
-  config.persist_async = Rails.env.production?
+  # Currency for cost calculations
+  # config.default_currency = "USD"
 
-  # config.auto_subscribe_ruby_llm = true
-  # config.auto_subscribe_active_agent = true
+  # How to display the actor (user) in the dashboard
+  # config.actor_display = ->(actor) { actor.try(:name) || actor.try(:email) }
+
+  # Items per page in the dashboard
+  # config.per_page = 25
 end

data/lib/tasks/tracebook_tasks.rake

@@ -1,4 +1,14 @@
-# desc "Explaining what the task does"
-# task :tracebook do
-#   # Task goes here
-# end
+# frozen_string_literal: true
+
+namespace :tracebook do
+  desc "Seed default pricing rules for common LLM providers (Gemini, OpenAI, Anthropic, Ollama)"
+  task seed_pricing: :environment do
+    result = Tracebook::Seeds::PricingRules.seed!
+
+    puts "TraceBook pricing rules seeded!"
+    puts "  Created: #{result[:created]}"
+    puts "  Skipped (already exist): #{result[:skipped]}"
+
+    puts "\nRun again after gem updates to add new model pricing." if result[:created] > 0
+  end
+end

data/lib/tracebook/adapters/ruby_llm.rb

@@ -1,97 +1,35 @@
 # frozen_string_literal: true
 
-require "active_support/notifications"
-require "active_support/core_ext/hash/indifferent_access"
-
 module Tracebook
   module Adapters
-    # Adapter for capturing LLM interactions via ActiveSupport::Notifications.
-    #
-    # This adapter subscribes to instrumentation events (default: "ruby_llm.request")
-    # and automatically records interactions in TraceBook.
-    #
-    # @example Basic setup
-    #   # config/initializers/tracebook_adapters.rb
-    #   TraceBook::Adapters::RubyLLM.enable!
-    #
-    # @example Custom event name
-    #   TraceBook::Adapters::RubyLLM.enable!(instrumentation: "my_llm.complete")
-    #
-    # @example Emitting events from your LLM client
-    #   ActiveSupport::Notifications.instrument("ruby_llm.request", {
-    #     provider: "openai",
-    #     request: { model: "gpt-4o", messages: messages },
-    #     response: response,
-    #     meta: {
-    #       project: "support",
-    #       user: current_user,
-    #       session_id: session.id,
-    #       latency_ms: 150,
-    #       status: :success,
-    #       tags: ["production", "triage"]
-    #     }
-    #   })
-    #
-    # @see Mappers
     module RubyLLM
-      extend self
-
-      # Default ActiveSupport::Notifications event name
-      DEFAULT_EVENT = "ruby_llm.request".freeze
-
-      # Enables the adapter to start capturing events.
-      #
-      # Subscribes to the specified instrumentation event and routes payloads
-      # through {Mappers} to {TraceBook.record!}.
-      #
-      # @param instrumentation [String] Event name to subscribe to
-      # @return [void]
-      #
-      # @example
-      #   TraceBook::Adapters::RubyLLM.enable!
-      #   TraceBook::Adapters::RubyLLM.enable!(instrumentation: "custom.llm")
-      def enable!(instrumentation: DEFAULT_EVENT)
-        return if subscribers.key?(instrumentation)
-
-        subscribers[instrumentation] = ActiveSupport::Notifications.subscribe(instrumentation) do |*args|
-          event = ActiveSupport::Notifications::Event.new(*args)
-          handle_payload(event.payload.with_indifferent_access)
+      def self.enable!
+        unless defined?(::RubyLLM)
+          raise LoadError, "RubyLLM is not loaded. Add `gem 'ruby_llm'` to your Gemfile."
         end
-      end
 
-      # Disables the adapter and unsubscribes from events.
-      #
-      # @param instrumentation [String] Event name to unsubscribe from
-      # @return [void]
-      #
-      # @example
-      #   TraceBook::Adapters::RubyLLM.disable!
-      def disable!(instrumentation: DEFAULT_EVENT)
-        token = subscribers.delete(instrumentation)
-        ActiveSupport::Notifications.unsubscribe(token) if token
+        message_class = Tracebook.config.message_class.constantize
+        message_class.include(CostTracking)
       end
 
-      private
+      module CostTracking
+        extend ActiveSupport::Concern
 
-      def handle_payload(payload)
-        provider = payload[:provider].to_s.presence || "ruby_llm"
-        normalized = Mappers.normalize(
-          provider,
-          raw_request: payload[:request],
-          raw_response: payload[:response],
-          meta: payload[:meta] || {}
-        )
+        included do
+          after_create_commit :tracebook_calculate_cost, if: :assistant?
+        end
 
-        TraceBook.record!(**normalized.to_h)
-      rescue KeyError => error
-        Rails.logger.error("TraceBook RubyLLM adapter error: #{error.message}") if defined?(Rails)
-      end
+        private
+
+        def tracebook_calculate_cost
+          model_id = chat.model_id
+          provider = ::RubyLLM::Models.find(model_id).provider
 
-      def subscribers
-        @subscribers ||= {}
+          Tracebook.calculate_cost!(self, provider: provider, model: model_id)
+        rescue StandardError => e
+          Rails.logger.error("[Tracebook] Cost calculation failed for message #{id}: #{e.class} - #{e.message}")
+        end
       end
     end
   end
 end
-
-TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/adapters.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "adapters/ruby_llm"
-require_relative "adapters/active_agent"
-
-TraceBook = Tracebook unless defined?(TraceBook)
+module Tracebook
+  module Adapters
+    autoload :RubyLLM, "tracebook/adapters/ruby_llm"
+  end
+end

data/lib/tracebook/config.rb

@@ -1,135 +1,114 @@
 # frozen_string_literal: true
 
 module Tracebook
-  # Configuration object for TraceBook.
-  #
-  # Contains all configurable options for the TraceBook engine. Configuration
-  # is frozen after the {Tracebook.configure} block executes to prevent
-  # runtime modifications.
-  #
-  # @example Basic configuration
-  #   TraceBook.configure do |config|
-  #     config.project_name = "Support Console"
-  #     config.persist_async = Rails.env.production?
-  #     config.default_currency = "USD"
-  #   end
-  #
-  # @example With custom redactors
-  #   TraceBook.configure do |config|
-  #     config.custom_redactors += [
-  #       ->(payload) { payload.gsub(/api_key=\w+/, "api_key=[REDACTED]") }
-  #     ]
-  #   end
-  #
-  # @see Tracebook.configure
   class Config
-    # @!attribute [rw] project_name
-    #   @return [String, nil] Project identifier for this application (optional)
-    #   Used to filter interactions by project in the dashboard
-    attr_accessor :project_name
-
-    # @!attribute [rw] persist_async
-    #   @return [Boolean] Whether to persist interactions asynchronously (default: true)
-    #   When true, {Tracebook.record!} enqueues {PersistInteractionJob}.
-    #   When false, interactions are persisted inline.
-    attr_accessor :persist_async
-
-    # @!attribute [rw] inline_payload_bytes
-    #   @return [Integer] Maximum payload size before spilling to ActiveStorage (default: 64KB)
-    #   Payloads larger than this threshold are stored as ActiveStorage blobs
-    #   instead of inline JSONB columns.
-    attr_accessor :inline_payload_bytes
-
-    # @!attribute [rw] default_currency
-    #   @return [String] Currency code for cost calculations (default: "USD")
-    #   Used in {PricingRule} cost tracking
+    # @return [String] class name of the host app's Chat model (default: "Chat")
+    attr_accessor :chat_class
+
+    # @return [String] class name of the host app's Message model (default: "Message")
+    attr_accessor :message_class
+
+    # @return [String] currency code for cost calculations (default: "USD")
     attr_accessor :default_currency
 
-    # @!attribute [rw] export_formats
-    #   @return [Array<Symbol>] Available export formats (default: [:csv, :ndjson])
-    #   Supported formats for {ExportJob}
-    attr_accessor :export_formats
-
-    # @!attribute [rw] redactors
-    #   @return [Array<Redactor>] Built-in PII redactors
-    #   Default redactors for email, phone, credit card numbers.
-    #   See {Redactors::Email}, {Redactors::Phone}, {Redactors::CardPAN}
-    attr_accessor :redactors
-
-    # @!attribute [rw] custom_redactors
-    #   @return [Array<Proc>] Custom redaction lambdas
-    #   Additional user-defined redactors that receive the payload string
-    #   and return a redacted version.
-    #   @example
-    #     config.custom_redactors += [
-    #       ->(payload) { payload.gsub(/secret=\w+/, "secret=[REDACTED]") }
-    #     ]
-    attr_accessor :custom_redactors
-
-    # @!attribute [rw] auto_subscribe_ruby_llm
-    #   @return [Boolean] Auto-enable RubyLLM adapter on boot (default: false)
-    attr_accessor :auto_subscribe_ruby_llm
-
-    # @!attribute [rw] auto_subscribe_active_agent
-    #   @return [Boolean] Auto-enable ActiveAgent adapter on boot (default: false)
-    attr_accessor :auto_subscribe_active_agent
-
-    # @!attribute [rw] per_page
-    #   @return [Integer] Number of interactions per page in dashboard (default: 100)
+    # @return [Integer] items per page in dashboard (default: 25)
     attr_accessor :per_page
 
-    # Creates a new configuration with default values.
-    #
-    # @return [Config]
+    # @return [Proc, nil] lambda to format actor display name
+    attr_accessor :actor_display
+
+    # @return [Array<Proc>] custom redaction callables
+    attr_reader :custom_redactors
+
     def initialize
-      @project_name = nil
-      @persist_async = true
-      @inline_payload_bytes = 64 * 1024
+      @chat_class = "Chat"
+      @message_class = "Message"
       @default_currency = "USD"
-      @export_formats = [ :csv, :ndjson ]
-      @redactors = default_redactors
+      @per_page = 25
+      @actor_display = nil
+      @redaction_patterns = []
       @custom_redactors = []
-      @auto_subscribe_ruby_llm = false
-      @auto_subscribe_active_agent = false
-      @per_page = 100
     end
 
-    # Returns true if configuration has been finalized.
+    # Enable named redaction patterns.
     #
-    # @return [Boolean]
-    def finalized?
-      @finalized == true
+    # @example
+    #   config.redact :email, :phone, :ssn, :credit_card
+    def redact(*names)
+      names.each do |name|
+        if Redaction::GROUPS.key?(name)
+          redact_group(name)
+        elsif Redaction::PATTERNS.key?(name)
+          @redaction_patterns << name unless @redaction_patterns.include?(name)
+        else
+          raise ArgumentError, "Unknown redaction pattern: #{name}. Available: #{(Redaction::PATTERNS.keys + Redaction::GROUPS.keys).join(", ")}"
+        end
+      end
+    end
+
+    # Enable a named group of patterns.
+    #
+    # @example
+    #   config.redact_group :api_keys
+    def redact_group(group_name)
+      patterns = Redaction::GROUPS.fetch(group_name) do
+        raise ArgumentError, "Unknown redaction group: #{group_name}. Available: #{Redaction::GROUPS.keys.join(", ")}"
+      end
+      patterns.each { |name| redact(name) }
     end
 
-    # Freezes the configuration to prevent further changes.
+    # Add a custom regex pattern for redaction.
     #
-    # Called automatically by {Tracebook.configure} after the block executes.
+    # @example
+    #   config.redact_pattern(/policy[:\s]*\d{10}/i, "[POLICY_NUMBER]", name: "policy_number")
+    def redact_pattern(regex, replacement, name: nil)
+      pattern = Redaction::Pattern.new(
+        name: name || "custom_#{@redaction_patterns.size}",
+        regex: regex,
+        replacement: replacement
+      )
+      @redaction_patterns << pattern
+    end
+
+    # Build the redaction pipeline from configured patterns and custom redactors.
+    # Memoized after first call (safe because config is frozen after finalize!).
     #
-    # @return [void]
+    # @return [Redaction::Pipeline]
+    def redaction_pipeline
+      @redaction_pipeline || build_redaction_pipeline
+    end
+
+    def finalized?
+      @finalized == true
+    end
+
     def finalize!
       return if finalized?
 
+      @redaction_patterns.freeze
+      @custom_redactors.freeze
+      @redaction_pipeline = redaction_pipeline
       @finalized = true
-      freeze_collections!
       freeze
     end
 
-    private
+    # @return [Class] the resolved chat model class
+    def chat_model
+      @chat_class.constantize
+    end
 
-    def default_redactors
-      [
-        Tracebook::Redactors::Email.new,
-        Tracebook::Redactors::Phone.new,
-        Tracebook::Redactors::CardPAN.new
-      ]
+    # @return [Class] the resolved message model class
+    def message_model
+      @message_class.constantize
     end
 
-    def freeze_collections!
-      @redactors = @redactors.map { |redactor| redactor }.freeze
-      @custom_redactors = @custom_redactors.map { |callable| callable }.freeze
-      @export_formats = @export_formats.map(&:to_sym).freeze
+    private
+
+    def build_redaction_pipeline
+      patterns = @redaction_patterns.map do |p|
+        p.is_a?(Symbol) ? Redaction::PATTERNS.fetch(p) : p
+      end
+      Redaction::Pipeline.new(patterns: patterns, custom_redactors: @custom_redactors)
     end
   end
 end
-
-TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/engine.rb

@@ -1,5 +1,13 @@
 module Tracebook
   class Engine < ::Rails::Engine
     isolate_namespace Tracebook
+
+    initializer :append_migrations do |app|
+      unless app.root.to_s.match?(root.to_s)
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path unless app.config.paths["db/migrate"].include?(expanded_path)
+        end
+      end
+    end
   end
 end

data/lib/tracebook/errors.rb

@@ -5,5 +5,3 @@ module Tracebook
 
   class ConfigurationError < Error; end
 end
-
-TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/pricing/calculator.rb

@@ -24,16 +24,21 @@ module Tracebook
       def matching_rule(provider, model, occurred_at)
         Tracebook::PricingRule.where(provider: provider).select do |rule|
           rule.matches_model?(model) && rule.active_on?(occurred_at.to_date)
-        end.min_by(&:effective_from)
+        end.max_by { |rule| [ glob_specificity(rule.model_glob), rule.effective_from ] }
       end
 
-      def cost_for(cents_per_unit, tokens)
-        return 0 if cents_per_unit.to_i <= 0 || tokens.to_i <= 0
+      def glob_specificity(glob)
+        glob.delete("*?").length
+      end
+
+      # Calculates cost in cents.
+      # cents_per_unit is cents per 1M tokens (matching the pricing rule storage).
+      # Example: $2.50/1M = 250 cents/1M. 1000 tokens => 1000 * 250 / 1_000_000 = 0.25 cents.
+      def cost_for(cents_per_million, tokens)
+        return 0 if cents_per_million.to_d <= 0 || tokens.to_i <= 0
 
-        (tokens.to_i / 1000.0 * cents_per_unit.to_i).round
+        (tokens.to_i * cents_per_million.to_d / 1_000_000).round(4)
       end
     end
   end
 end
-
-TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/pricing.rb

@@ -1,5 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "pricing/calculator"
-
-TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redaction/pattern.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redaction
+    # A single redaction pattern with regex, replacement, and optional validator.
+    Pattern = Data.define(:name, :regex, :replacement, :validator) do
+      def initialize(name:, regex:, replacement:, validator: nil)
+        super
+      end
+
+      def redact(text)
+        return text unless text.is_a?(String)
+
+        text.gsub(regex) do |match|
+          if validator && !validator.call(match)
+            match
+          else
+            replacement
+          end
+        end
+      end
+    end
+
+    # Luhn algorithm for credit card validation
+    LUHN = ->(number) {
+      digits = number.gsub(/\D/, "")
+      return false if digits.length < 13 || digits.length > 19
+
+      sum = 0
+      digits.reverse.each_char.with_index do |d, i|
+        n = d.to_i
+        n *= 2 if i.odd?
+        n -= 9 if n > 9
+        sum += n
+      end
+      (sum % 10).zero?
+    }
+
+    PATTERNS = {
+      email: Pattern.new(
+        name: :email,
+        regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+        replacement: "[EMAIL]"
+      ),
+      phone: Pattern.new(
+        name: :phone,
+        regex: /(?<!\d)\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}\b/,
+        replacement: "[PHONE]"
+      ),
+      ssn: Pattern.new(
+        name: :ssn,
+        regex: /\b\d{3}-\d{2}-\d{4}\b/,
+        replacement: "[SSN]",
+        validator: ->(match) {
+          area = match[0..2].to_i
+          area > 0 && area != 666 && area < 900
+        }
+      ),
+      credit_card: Pattern.new(
+        name: :credit_card,
+        regex: /\b(?:\d[ -]*?){13,19}\b/,
+        replacement: "[CREDIT_CARD]",
+        validator: LUHN
+      ),
+      openai_key: Pattern.new(
+        name: :openai_key,
+        regex: /\bsk-[A-Za-z0-9_-]{20,}\b/,
+        replacement: "[KEY]"
+      ),
+      anthropic_key: Pattern.new(
+        name: :anthropic_key,
+        regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/,
+        replacement: "[KEY]"
+      ),
+      aws_key: Pattern.new(
+        name: :aws_key,
+        regex: /\bAKIA[0-9A-Z]{16}\b/,
+        replacement: "[KEY]"
+      ),
+      stripe_key: Pattern.new(
+        name: :stripe_key,
+        regex: /\b[sr]k_(test|live)_[A-Za-z0-9]{20,}\b/,
+        replacement: "[KEY]"
+      ),
+      github_token: Pattern.new(
+        name: :github_token,
+        regex: /\bgh[pousr]_[A-Za-z0-9_]{36,}\b/,
+        replacement: "[KEY]"
+      ),
+      bearer_token: Pattern.new(
+        name: :bearer_token,
+        regex: /Bearer\s+[A-Za-z0-9\-._~+\/]+=*/i,
+        replacement: "Bearer [REDACTED]"
+      ),
+      jwt: Pattern.new(
+        name: :jwt,
+        regex: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/,
+        replacement: "[JWT]"
+      ),
+      ipv4: Pattern.new(
+        name: :ipv4,
+        regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/,
+        replacement: "[IP_ADDRESS]",
+        validator: ->(match) {
+          match.split(".").all? { |octet| octet.to_i.between?(0, 255) }
+        }
+      ),
+      private_key: Pattern.new(
+        name: :private_key,
+        regex: /-----BEGIN [A-Z ]+ PRIVATE KEY-----.*?-----END [A-Z ]+ PRIVATE KEY-----/m,
+        replacement: "[PRIVATE_KEY]"
+      )
+    }.freeze
+
+    GROUPS = {
+      pii: %i[email phone ssn],
+      financial: %i[credit_card],
+      api_keys: %i[openai_key anthropic_key aws_key stripe_key github_token],
+      auth: %i[bearer_token jwt],
+      network: %i[ipv4],
+      crypto: %i[private_key]
+    }.freeze
+  end
+end

data/lib/tracebook/redaction/pipeline.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redaction
+    class Pipeline
+      attr_reader :patterns, :custom_redactors
+
+      def initialize(patterns: [], custom_redactors: [])
+        @patterns = patterns
+        @custom_redactors = custom_redactors
+      end
+
+      # Redact a string through all patterns and custom redactors.
+      #
+      # @param text [String] the text to redact
+      # @return [String] redacted text
+      def call(text)
+        return text unless text.is_a?(String)
+        return text if patterns.empty? && custom_redactors.empty?
+
+        result = text
+        patterns.each { |pattern| result = pattern.redact(result) }
+        custom_redactors.each { |redactor| result = redactor.call(result) }
+        result
+      end
+
+      def active?
+        patterns.any? || custom_redactors.any?
+      end
+    end
+  end
+end