tracebook 0.1.0

data/config/routes.rb

@@ -0,0 +1,8 @@
+Tracebook::Engine.routes.draw do
+  resources :interactions, only: [ :index, :show ] do
+    post :review, on: :member
+    post :bulk_review, on: :collection
+  end
+
+  resources :exports, only: [ :create, :show ]
+end

data/db/migrate/20241112000100_create_tracebook_interactions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class CreateTracebookInteractions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :tracebook_interactions do |t|
+      t.string :project
+      t.string :provider, null: false
+      t.string :model, null: false
+      t.string :session_id
+
+      t.text :request_payload
+      t.text :response_payload
+      t.text :request_text
+      t.text :response_text
+
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :total_tokens
+      t.integer :latency_ms
+
+      t.integer :status, null: false, default: 0
+      t.integer :review_state, null: false, default: 0
+      t.string :error_class
+      t.text :error_message
+
+      t.string :user_type
+      t.bigint :user_id
+      t.bigint :parent_id
+
+      t.text :tags
+      t.text :metadata
+
+      t.string :request_payload_store, null: false, default: "inline"
+      t.string :response_payload_store, null: false, default: "inline"
+      t.bigint :request_payload_blob_id
+      t.bigint :response_payload_blob_id
+
+      t.integer :cost_input_cents, default: 0, null: false
+      t.integer :cost_output_cents, default: 0, null: false
+      t.integer :cost_total_cents, default: 0, null: false
+      t.string :currency, null: false, default: "USD"
+
+      t.timestamps
+    end
+
+    add_index :tracebook_interactions, :created_at
+    add_index :tracebook_interactions, [ :provider, :model, :created_at ]
+    add_index :tracebook_interactions, [ :project, :created_at ]
+    add_index :tracebook_interactions, :session_id
+    add_index :tracebook_interactions, :status
+    add_index :tracebook_interactions, :review_state
+    add_index :tracebook_interactions, :parent_id
+    add_index :tracebook_interactions, [ :user_type, :user_id ]
+  end
+end

data/db/migrate/20241112000200_create_tracebook_rollups_dailies.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateTracebookRollupsDailies < ActiveRecord::Migration[8.0]
+  def change
+    create_table :tracebook_rollups_dailies do |t|
+      t.date :date, null: false
+      t.string :project
+      t.string :provider
+      t.string :model
+
+      t.integer :interactions_count, null: false, default: 0
+      t.integer :success_count, null: false, default: 0
+      t.integer :error_count, null: false, default: 0
+      t.integer :input_tokens_sum, null: false, default: 0
+      t.integer :output_tokens_sum, null: false, default: 0
+      t.integer :cost_cents_sum, null: false, default: 0
+      t.string :currency, null: false, default: "USD"
+
+      t.timestamps
+    end
+
+    add_index :tracebook_rollups_dailies, [ :date, :project, :provider, :model ], unique: true, name: "index_tracebook_rollups_on_dimensions"
+  end
+end

data/db/migrate/20241112000300_create_tracebook_pricing_rules.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateTracebookPricingRules < ActiveRecord::Migration[8.0]
+  def change
+    create_table :tracebook_pricing_rules do |t|
+      t.string :provider, null: false
+      t.string :model_glob, null: false
+      t.string :unit, null: false, default: "per_1k_tokens"
+      t.integer :input_cents_per_unit, null: false, default: 0
+      t.integer :output_cents_per_unit, null: false, default: 0
+      t.date :effective_from, null: false
+      t.date :effective_to
+      t.string :currency, null: false, default: "USD"
+
+      t.timestamps
+    end
+
+    add_index :tracebook_pricing_rules, :provider
+    add_index :tracebook_pricing_rules, [ :provider, :effective_from ], name: "index_tracebook_pricing_on_provider_effective_from"
+  end
+end

data/db/migrate/20241112000400_create_tracebook_redaction_rules.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateTracebookRedactionRules < ActiveRecord::Migration[8.0]
+  def change
+    create_table :tracebook_redaction_rules do |t|
+      t.string :name, null: false
+      t.text :pattern, null: false
+      t.string :replacement, null: false, default: "[REDACTED]"
+      t.integer :applies_to, null: false, default: 2
+      t.boolean :enabled, null: false, default: true
+      t.integer :priority, null: false, default: 100
+
+      t.timestamps
+    end
+
+    add_index :tracebook_redaction_rules, :enabled
+    add_index :tracebook_redaction_rules, :priority
+  end
+end

data/lib/tasks/tracebook_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :tracebook do
+#   # Task goes here
+# end

data/lib/tasks/yard.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.files = [ "lib/**/*.rb", "app/**/*.rb" ]
+    t.options = [
+      "--markup", "markdown",
+      "--markup-provider", "kramdown",
+      "--readme", "README.md",
+      "--output-dir", "doc",
+      "--protected",
+      "--private"
+    ]
+  end
+
+  desc "Generate YARD documentation and open in browser"
+  task "yard:open" => :yard do
+    system "open doc/index.html"
+  end
+
+  desc "Generate YARD stats"
+  task "yard:stats" do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  # YARD not available
+end

data/lib/tracebook/adapters/active_agent.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+
+module Tracebook
+  module Adapters
+    module ActiveAgent
+      extend self
+
+      def enable!(bus: nil)
+        bus ||= discover_bus
+        return unless bus.respond_to?(:subscribe)
+
+        subscribers << bus.subscribe { |event| handle_event(event) }
+      end
+
+      def disable!
+        subscribers.clear
+      end
+
+      private
+
+      def handle_event(event)
+        payload = event.with_indifferent_access
+        provider = payload[:provider]&.to_s.presence || "active_agent"
+        mapper = mapper_for(provider)
+        meta_hash = payload[:meta] || {}
+        meta = meta_hash.merge(
+          session_id: payload[:session_id],
+          parent_id: payload[:parent_id]
+        )
+
+        normalized = if mapper
+                        mapper.normalize(raw_request: payload[:request], raw_response: payload[:response], meta: meta)
+        else
+                        fallback(provider, payload, meta)
+        end
+
+        TraceBook.record!(**normalized.to_h)
+      end
+
+      def mapper_for(provider)
+        case provider
+        when "openai"
+          Tracebook::Mappers::OpenAI.new
+        when "anthropic"
+          Tracebook::Mappers::Anthropic.new
+        when "ollama"
+          Tracebook::Mappers::Ollama.new
+        else
+          nil
+        end
+      end
+
+      def fallback(provider, payload, meta)
+        NormalizedInteraction.new(
+          provider: provider,
+          model: payload.dig(:request, :model),
+          project: meta[:project],
+          request_payload: payload[:request],
+          response_payload: payload[:response],
+          status: meta[:status] || :success,
+          tags: Array(meta[:tags]),
+          session_id: meta[:session_id],
+          parent_id: meta[:parent_id]
+        )
+      end
+
+      def subscribers
+        @subscribers ||= []
+      end
+
+      def discover_bus
+        ActiveAgent::Bus if defined?(ActiveAgent::Bus)
+      rescue NameError
+        nil
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/adapters/ruby_llm.rb

@@ -0,0 +1,97 @@
+# 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)
+        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
+      end
+
+      private
+
+      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] || {}
+        )
+
+        TraceBook.record!(**normalized.to_h)
+      rescue KeyError => error
+        Rails.logger.error("TraceBook RubyLLM adapter error: #{error.message}") if defined?(Rails)
+      end
+
+      def subscribers
+        @subscribers ||= {}
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/adapters.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "adapters/ruby_llm"
+require_relative "adapters/active_agent"
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/config.rb

@@ -0,0 +1,130 @@
+# 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
+    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
+
+    # Creates a new configuration with default values.
+    #
+    # @return [Config]
+    def initialize
+      @project_name = nil
+      @persist_async = true
+      @inline_payload_bytes = 64 * 1024
+      @default_currency = "USD"
+      @export_formats = [ :csv, :ndjson ]
+      @redactors = default_redactors
+      @custom_redactors = []
+      @auto_subscribe_ruby_llm = false
+      @auto_subscribe_active_agent = false
+    end
+
+    # Returns true if configuration has been finalized.
+    #
+    # @return [Boolean]
+    def finalized?
+      @finalized == true
+    end
+
+    # Freezes the configuration to prevent further changes.
+    #
+    # Called automatically by {Tracebook.configure} after the block executes.
+    #
+    # @return [void]
+    def finalize!
+      return if finalized?
+
+      @finalized = true
+      freeze_collections!
+      freeze
+    end
+
+    private
+
+    def default_redactors
+      [
+        Tracebook::Redactors::Email.new,
+        Tracebook::Redactors::Phone.new,
+        Tracebook::Redactors::CardPAN.new
+      ]
+    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
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/engine.rb

@@ -0,0 +1,5 @@
+module Tracebook
+  class Engine < ::Rails::Engine
+    isolate_namespace Tracebook
+  end
+end

data/lib/tracebook/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tracebook
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/mappers/anthropic.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Tracebook
+  module Mappers
+    class Anthropic < Base
+      def normalize(raw_request:, raw_response:, meta: {})
+        request = symbolize(raw_request || {})
+        response = symbolize(raw_response || {})
+        meta_info = indifferent_meta(meta)
+
+        build_interaction(
+          provider: "anthropic",
+          model: request[:model] || response[:model],
+          project: meta_info[:project],
+          request_payload: raw_request,
+          response_payload: raw_response,
+          request_text: extract_blocks(request[:messages]),
+          response_text: extract_blocks(response[:content]),
+          input_tokens: anthropic_usage(response, :input_tokens),
+          output_tokens: anthropic_usage(response, :output_tokens),
+          latency_ms: meta_info[:latency_ms],
+          status: meta_info[:status]&.to_sym || :success,
+          error_class: nil,
+          error_message: nil,
+          tags: Array(meta_info[:tags]).compact,
+          metadata: {},
+          user: meta_info[:user],
+          parent_id: meta_info[:parent_id],
+          session_id: meta_info[:session_id]
+        )
+      end
+
+      private
+
+      def extract_blocks(blocks)
+        Array(blocks).flat_map do |block|
+          block = block.with_indifferent_access
+          case block[:type]
+          when "text"
+            block[:text]
+          when "input_text"
+            block[:text]
+          else
+            nil
+          end
+        end.compact.join("\n\n")
+      end
+
+      def anthropic_usage(response, key)
+        usage = response[:usage] || {}
+        usage.with_indifferent_access[key]&.to_i
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/mappers/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/deep_dup"
+
+module Tracebook
+  module Mappers
+    class Base
+      def normalize(raw_request:, raw_response:, meta: {})
+        raise NotImplementedError
+      end
+
+      private
+
+      def build_interaction(**attributes)
+        NormalizedInteraction.new(**attributes)
+      end
+
+      def indifferent_meta(meta)
+        (meta || {}).with_indifferent_access
+      end
+
+      def symbolize(hash)
+        hash.deep_dup.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+      end
+
+      def compact_hash(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          next if value.nil?
+
+          memo[key] = value
+        end
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/mappers/ollama.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Tracebook
+  module Mappers
+    class Ollama < Base
+      def normalize(raw_request:, raw_response:, meta: {})
+        request = symbolize(raw_request || {})
+        response = symbolize(raw_response || {})
+        meta_info = indifferent_meta(meta)
+
+        metadata = {}
+        metadata["eval_count"] = response[:eval_count] if response.key?(:eval_count)
+
+        build_interaction(
+          provider: "ollama",
+          model: request[:model] || response[:model],
+          project: meta_info[:project],
+          request_payload: raw_request,
+          response_payload: raw_response,
+          request_text: request[:prompt] || request[:input],
+          response_text: response[:response],
+          input_tokens: response[:prompt_eval_count],
+          output_tokens: response[:eval_count],
+          latency_ms: meta_info[:latency_ms] || to_milliseconds(response[:total_duration]),
+          status: meta_info[:status]&.to_sym || :success,
+          error_class: nil,
+          error_message: nil,
+          tags: Array(meta_info[:tags]).compact,
+          metadata: metadata,
+          user: meta_info[:user],
+          parent_id: meta_info[:parent_id],
+          session_id: meta_info[:session_id]
+        )
+      end
+
+      private
+
+      def to_milliseconds(value)
+        return unless value
+
+        (value.to_f * 1000).to_i
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)