tracebook 0.1.0

data/lib/tracebook/mappers/openai.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Tracebook
+  module Mappers
+    class OpenAI < Base
+      def normalize(raw_request:, raw_response:, meta: {})
+        request = symbolize(raw_request || {})
+        response = symbolize(raw_response || {})
+        metadata = build_metadata(response)
+        meta_info = indifferent_meta(meta)
+
+        build_interaction(
+          provider: "openai",
+          model: request[:model] || response[:model],
+          project: meta_info[:project],
+          request_payload: raw_request,
+          response_payload: raw_response,
+          request_text: join_messages(request[:messages]),
+          response_text: first_choice_text(response),
+          input_tokens: usage_tokens(response, :prompt_tokens),
+          output_tokens: usage_tokens(response, :completion_tokens),
+          latency_ms: meta_info[:latency_ms],
+          status: meta_info[:status]&.to_sym || default_status(response),
+          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 join_messages(messages)
+        Array(messages).map { |message| message.with_indifferent_access[:content].to_s }.reject(&:empty?).join("\n\n")
+      end
+
+      def first_choice(response)
+        Array(response[:choices]).first || {}
+      end
+
+      def first_choice_text(response)
+        choice = first_choice(response)
+        message = choice[:message] || {}
+        message.with_indifferent_access[:content].to_s
+      end
+
+      def usage_tokens(response, key)
+        usage = response[:usage] || {}
+        usage.with_indifferent_access[key]&.to_i
+      end
+
+      def build_metadata(response)
+        choice = first_choice(response)
+        metadata = {}
+        metadata["finish_reason"] = choice[:finish_reason] if choice[:finish_reason]
+        metadata
+      end
+
+      def default_status(response)
+        finish_reason = first_choice(response)[:finish_reason]
+        return :canceled if finish_reason == "length"
+        return :error if finish_reason == "error"
+
+        :success
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/mappers.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/deep_dup"
+require_relative "mappers/base"
+require_relative "mappers/openai"
+require_relative "mappers/anthropic"
+require_relative "mappers/ollama"
+
+module Tracebook
+  # Mappers normalize provider-specific request/response formats into TraceBook's
+  # standard {NormalizedInteraction} structure.
+  #
+  # Built-in mappers exist for OpenAI, Anthropic, and Ollama. For other providers,
+  # a fallback mapper is used which preserves the raw payloads.
+  #
+  # @example Using the mapper in an adapter
+  #   normalized = Tracebook::Mappers.normalize(
+  #     "openai",
+  #     raw_request: { model: "gpt-4o", messages: messages },
+  #     raw_response: openai_response,
+  #     meta: { project: "chatbot", user: current_user, latency_ms: 200 }
+  #   )
+  #   TraceBook.record!(**normalized.to_h)
+  #
+  # @example Creating a custom mapper
+  #   # See {Mappers::Base} for the base class
+  #   class Mappers::Cohere < Mappers::Base
+  #     def self.normalize(raw_request:, raw_response:, meta: {})
+  #       # Your normalization logic
+  #       build_interaction(provider: "cohere", model: ..., ...)
+  #     end
+  #   end
+  #
+  # @see Mappers::Base
+  # @see NormalizedInteraction
+  module Mappers
+    extend self
+
+    # Normalizes a provider's request/response into standard format.
+    #
+    # Routes to provider-specific mappers for OpenAI, Anthropic, and Ollama.
+    # Falls back to a generic mapper for unknown providers.
+    #
+    # @param provider [String] Provider name ("openai", "anthropic", "ollama", etc.)
+    # @param raw_request [Hash] The original request sent to the provider
+    # @param raw_response [Hash] The original response from the provider
+    # @param meta [Hash] Additional metadata (project, user, session_id, tags, etc.)
+    #
+    # @option meta [String] :project Project name for filtering
+    # @option meta [ActiveRecord::Base] :user Associated user
+    # @option meta [String] :session_id Session identifier
+    # @option meta [Integer] :parent_id Parent interaction ID
+    # @option meta [Array<String>] :tags Labels for filtering
+    # @option meta [Integer] :latency_ms Request duration in milliseconds
+    # @option meta [Symbol] :status :success, :error, or :canceled
+    # @option meta [String] :error_class Exception class name (for errors)
+    # @option meta [String] :error_message Exception message (for errors)
+    #
+    # @return [NormalizedInteraction] Normalized interaction ready for {TraceBook.record!}
+    #
+    # @example Normalizing an OpenAI response
+    #   normalized = Tracebook::Mappers.normalize(
+    #     "openai",
+    #     raw_request: {
+    #       model: "gpt-4o",
+    #       messages: [{ role: "user", content: "Hello" }]
+    #     },
+    #     raw_response: {
+    #       choices: [{ message: { content: "Hi!" } }],
+    #       usage: { prompt_tokens: 10, completion_tokens: 5 }
+    #     },
+    #     meta: { latency_ms: 150, user: current_user }
+    #   )
+    def normalize(provider, raw_request:, raw_response:, meta: {})
+      case provider.to_s
+      when "openai"
+        normalize_openai(raw_request, raw_response, meta)
+      when "anthropic"
+        normalize_anthropic(raw_request, raw_response, meta)
+      when "ollama"
+        normalize_ollama(raw_request, raw_response, meta)
+      else
+        fallback_normalized(provider, raw_request, raw_response, meta)
+      end
+    end
+
+    private
+
+    def normalize_openai(raw_request, raw_response, meta)
+      request = symbolize(raw_request || {})
+      response = symbolize(raw_response || {})
+      metadata = openai_metadata(response)
+      meta_info = indifferent_meta(meta)
+
+      Tracebook::NormalizedInteraction.new(
+        provider: "openai",
+        model: request[:model] || response[:model],
+        project: meta_info[:project],
+        request_payload: raw_request,
+        response_payload: raw_response,
+        request_text: join_messages(request[:messages]),
+        response_text: openai_response_text(response),
+        input_tokens: openai_usage_tokens(response, :prompt_tokens),
+        output_tokens: openai_usage_tokens(response, :completion_tokens),
+        latency_ms: meta_info[:latency_ms],
+        status: meta_info[:status]&.to_sym || openai_status(response),
+        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
+
+    def normalize_anthropic(raw_request, raw_response, meta)
+      request = symbolize(raw_request || {})
+      response = symbolize(raw_response || {})
+      meta_info = indifferent_meta(meta)
+
+      Tracebook::NormalizedInteraction.new(
+        provider: "anthropic",
+        model: request[:model] || response[:model],
+        project: meta_info[:project],
+        request_payload: raw_request,
+        response_payload: raw_response,
+        request_text: extract_anthropic_messages(request[:messages]),
+        response_text: extract_blocks(response[:content]).join("\n\n"),
+        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
+
+    def normalize_ollama(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)
+
+      Tracebook::NormalizedInteraction.new(
+        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
+
+    def fallback_normalized(provider, raw_request, raw_response, meta)
+      request = symbolize(raw_request || {})
+      response = symbolize(raw_response || {})
+      meta_info = indifferent_meta(meta)
+
+      Tracebook::NormalizedInteraction.new(
+        provider: provider.to_s,
+        model: request[:model] || response[:model],
+        project: meta_info[:project],
+        request_payload: raw_request,
+        response_payload: raw_response,
+        request_text: meta_info[:request_text],
+        response_text: meta_info[:response_text],
+        input_tokens: meta_info[:input_tokens],
+        output_tokens: meta_info[:output_tokens],
+        latency_ms: meta_info[:latency_ms],
+        status: meta_info[:status]&.to_sym || :success,
+        error_class: meta_info[:error_class],
+        error_message: meta_info[:error_message],
+        tags: Array(meta_info[:tags]).compact,
+        metadata: meta_info[:metadata] || {},
+        user: meta_info[:user],
+        parent_id: meta_info[:parent_id],
+        session_id: meta_info[:session_id]
+      )
+    end
+
+    # OpenAI helpers
+    def join_messages(messages)
+      Array(messages).map { |message| message.with_indifferent_access[:content].to_s }.reject(&:empty?).join("\n\n")
+    end
+
+    def openai_first_choice(response)
+      choices = Array(response[:choices])
+      choices.first&.with_indifferent_access || {}
+    end
+
+    def openai_response_text(response)
+      choice = openai_first_choice(response)
+      message = choice[:message] || {}
+      message.with_indifferent_access[:content].to_s
+    end
+
+    def openai_usage_tokens(response, key)
+      usage = response[:usage] || {}
+      usage.with_indifferent_access[key]&.to_i
+    end
+
+    def openai_metadata(response)
+      choice = openai_first_choice(response)
+      metadata = {}
+      metadata["finish_reason"] = choice[:finish_reason] if choice[:finish_reason]
+      metadata
+    end
+
+    def openai_status(response)
+      finish_reason = openai_first_choice(response)[:finish_reason]
+      return :canceled if finish_reason == "length"
+      return :error if finish_reason == "error"
+
+      :success
+    end
+
+    # Anthropic helpers
+    def extract_anthropic_messages(messages)
+      Array(messages).flat_map do |message|
+        message = message.respond_to?(:with_indifferent_access) ? message.with_indifferent_access : message
+        extract_blocks(message[:content])
+      end.join("\n\n")
+    end
+
+    def extract_blocks(blocks)
+      Array(blocks).flat_map do |block|
+        block = block.respond_to?(:with_indifferent_access) ? block.with_indifferent_access : block
+        case block[:type]
+        when "text"
+          block[:text]
+        when "input_text"
+          block[:text]
+        else
+          nil
+        end
+      end.compact
+    end
+
+    def anthropic_usage(response, key)
+      usage = response[:usage] || {}
+      usage.with_indifferent_access[key]&.to_i
+    end
+
+    # Ollama helpers
+    def to_milliseconds(value)
+      return unless value
+
+      (value.to_f * 1000).to_i
+    end
+
+    # Common helpers
+    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
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/normalized_interaction.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Tracebook
+  # Normalized representation of an LLM interaction.
+  #
+  # This immutable data structure provides a standard format for LLM interactions
+  # across different providers. Mappers convert provider-specific formats into this
+  # structure before persistence.
+  #
+  # @attr provider [String] Provider name (e.g., "openai", "anthropic")
+  # @attr model [String] Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet")
+  # @attr project [String, nil] Project name for filtering
+  # @attr request_payload [Hash] Full request sent to provider (will be encrypted)
+  # @attr response_payload [Hash] Full response from provider (will be encrypted)
+  # @attr request_text [String, nil] Human-readable request summary
+  # @attr response_text [String, nil] Human-readable response summary
+  # @attr input_tokens [Integer, nil] Prompt token count
+  # @attr output_tokens [Integer, nil] Completion token count
+  # @attr latency_ms [Integer, nil] Request duration in milliseconds
+  # @attr status [Symbol, String] :success, :error, or :canceled
+  # @attr error_class [String, nil] Exception class name on failure
+  # @attr error_message [String, nil] Exception message on failure
+  # @attr tags [Array<String>] Labels for filtering
+  # @attr metadata [Hash] Custom metadata
+  # @attr user [ActiveRecord::Base, nil] Associated user (polymorphic)
+  # @attr parent_id [Integer, nil] Parent interaction ID for hierarchical chains
+  # @attr session_id [String, nil] Session identifier for grouping related calls
+  #
+  # @example Creating a normalized interaction
+  #   interaction = NormalizedInteraction.new(
+  #     provider: "openai",
+  #     model: "gpt-4o",
+  #     request_payload: { messages: messages },
+  #     response_payload: response,
+  #     input_tokens: 100,
+  #     output_tokens: 50,
+  #     status: :success
+  #   )
+  #
+  # @see Mappers
+  NormalizedInteraction = Data.define(
+    :provider,
+    :model,
+    :project,
+    :request_payload,
+    :response_payload,
+    :request_text,
+    :response_text,
+    :input_tokens,
+    :output_tokens,
+    :latency_ms,
+    :status,
+    :error_class,
+    :error_message,
+    :tags,
+    :metadata,
+    :user,
+    :parent_id,
+    :session_id
+  ) do
+    def initialize(
+      provider:,
+      model:,
+      project: nil,
+      request_payload: {},
+      response_payload: {},
+      request_text: nil,
+      response_text: nil,
+      input_tokens: nil,
+      output_tokens: nil,
+      latency_ms: nil,
+      status: "success",
+      error_class: nil,
+      error_message: nil,
+      tags: [],
+      metadata: {},
+      user: nil,
+      parent_id: nil,
+      session_id: nil
+    )
+      super
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/pricing/calculator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Pricing
+    CostBreakdown = Data.define(:input_cents, :output_cents, :total_cents, :currency)
+
+    module Calculator
+      extend self
+
+      def call(provider:, model:, input_tokens:, output_tokens:, occurred_at: Time.current)
+        rule = matching_rule(provider, model, occurred_at)
+        return CostBreakdown.new(input_cents: 0, output_cents: 0, total_cents: 0, currency: Tracebook.config.default_currency) unless rule
+
+        input_cents = cost_for(rule.input_cents_per_unit, input_tokens)
+        output_cents = cost_for(rule.output_cents_per_unit, output_tokens)
+        CostBreakdown.new(
+          input_cents: input_cents,
+          output_cents: output_cents,
+          total_cents: input_cents + output_cents,
+          currency: rule.currency
+        )
+      end
+
+      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
+
+      def cost_for(cents_per_unit, tokens)
+        return 0 if cents_per_unit.to_i <= 0 || tokens.to_i <= 0
+
+        (tokens.to_i / 1000.0 * cents_per_unit.to_i).round
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/pricing.rb

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

data/lib/tracebook/redaction_pipeline.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+
+module Tracebook
+  class RedactionPipeline
+    attr_reader :config
+
+    def initialize(config: Tracebook.config)
+      @config = config
+    end
+
+    def call(normalized)
+      data = normalized.to_h.deep_dup
+
+      apply_callable_redactors!(data)
+      apply_database_rules!(data)
+
+      NormalizedInteraction.new(**data)
+    end
+
+    private
+
+    def apply_callable_redactors!(data)
+      redactors = Array(config.redactors) + Array(config.custom_redactors)
+      redactors.each do |redactor|
+        apply_to_request!(data, redactor)
+        apply_to_response!(data, redactor)
+        apply_to_metadata!(data, redactor)
+      end
+    end
+
+    def apply_database_rules!(data)
+      Tracebook::RedactionRule.where(enabled: true).order(:priority).find_each do |rule|
+        callable = ->(value) { redact_string(value, rule.compiled_pattern, rule.replacement) }
+
+        case rule.applies_to.to_sym
+        when :request
+          apply_to_request!(data, callable)
+        when :response
+          apply_to_response!(data, callable)
+        when :both
+          apply_to_request!(data, callable)
+          apply_to_response!(data, callable)
+        when :metadata
+          apply_to_metadata!(data, callable)
+        end
+      end
+    end
+
+    def apply_to_request!(data, redactor)
+      data[:request_payload] = deep_transform(data[:request_payload], redactor)
+      data[:request_text] = redactor.call(data[:request_text]) if data[:request_text].is_a?(String)
+    end
+
+    def apply_to_response!(data, redactor)
+      data[:response_payload] = deep_transform(data[:response_payload], redactor)
+      data[:response_text] = redactor.call(data[:response_text]) if data[:response_text].is_a?(String)
+    end
+
+    def apply_to_metadata!(data, redactor)
+      data[:metadata] = deep_transform(data[:metadata], redactor)
+    end
+
+    def deep_transform(value, redactor)
+      case value
+      when String
+        redactor.call(value)
+      when Hash
+        value.each_with_object({}) do |(key, nested), memo|
+          memo[key] = deep_transform(nested, redactor)
+        end
+      when Array
+        value.map { |nested| deep_transform(nested, redactor) }
+      else
+        value
+      end
+    end
+
+    def redact_string(value, pattern, replacement)
+      return value unless value.is_a?(String)
+
+      value.gsub(pattern, replacement)
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redactors/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redactors
+    class Base
+      def call(value)
+        return value unless value.is_a?(String)
+
+        value.gsub(pattern, replacement)
+      end
+
+      def applies_to
+        :both
+      end
+
+      private
+
+      def pattern
+        raise NotImplementedError, "implement in subclasses"
+      end
+
+      def replacement
+        "[REDACTED]"
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redactors/card_pan.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redactors
+    class CardPAN < Base
+      private
+
+      def pattern
+        /\b(?:\d[ -]*?){13,16}\b/
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redactors/email.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redactors
+    class Email < Base
+      private
+
+      def pattern
+        /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redactors/phone.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tracebook
+  module Redactors
+    class Phone < Base
+      private
+
+      def pattern
+        /(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}/
+      end
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/redactors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "redactors/base"
+require_relative "redactors/email"
+require_relative "redactors/phone"
+require_relative "redactors/card_pan"
+
+TraceBook = Tracebook unless defined?(TraceBook)