tracebook 0.1.0

data/lib/tracebook/result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tracebook
+  # Result object returned by {TraceBook.record!}.
+  #
+  # Contains either the persisted interaction (when sync) or success/error information.
+  #
+  # @example Successful async recording
+  #   result = TraceBook.record!(provider: "openai", model: "gpt-4o", ...)
+  #   result.success? # => true
+  #   result.interaction # => nil (async - not available yet)
+  #
+  # @example Successful sync recording
+  #   TraceBook.configure { |c| c.persist_async = false }
+  #   result = TraceBook.record!(provider: "openai", model: "gpt-4o", ...)
+  #   result.success? # => true
+  #   result.interaction # => #<TraceBook::Interaction id: 123>
+  #
+  # @example Failed recording
+  #   result = TraceBook.record!(provider: nil, model: nil) # Invalid
+  #   result.success? # => false
+  #   result.error # => #<KeyError: key not found: :provider>
+  class Result
+    # @return [TraceBook::Interaction, nil] The persisted interaction (sync mode only)
+    attr_reader :interaction
+
+    # @return [Exception, nil] The error that occurred during recording
+    attr_reader :error
+
+    # @return [String, nil] Idempotency key for deduplication
+    attr_reader :idempotency_key
+
+    # Creates a new Result.
+    #
+    # @param interaction [TraceBook::Interaction, nil] Persisted interaction
+    # @param error [Exception, nil] Error that occurred
+    # @param idempotency_key [String, nil] Deduplication key
+    def initialize(interaction: nil, error: nil, idempotency_key: nil)
+      @interaction = interaction
+      @error = error
+      @idempotency_key = idempotency_key
+    end
+
+    # Returns true if recording succeeded (no error).
+    #
+    # @return [Boolean] true when no error occurred
+    def success?
+      error.nil?
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

data/lib/tracebook/version.rb

@@ -0,0 +1,3 @@
+module Tracebook
+  VERSION = "0.1.0"
+end

data/lib/tracebook.rb

@@ -0,0 +1,201 @@
+require "tracebook/version"
+require "tracebook/engine"
+require "tracebook/errors"
+require "tracebook/redactors"
+require "tracebook/mappers"
+require "tracebook/config"
+require "tracebook/result"
+require "tracebook/normalized_interaction"
+require "tracebook/redaction_pipeline"
+require "tracebook/pricing"
+require "tracebook/adapters"
+
+# TraceBook is a Rails engine for capturing, storing, and reviewing LLM interactions.
+#
+# It provides:
+# - Automatic redaction of PII from request/response payloads
+# - Encrypted storage of sensitive data using ActiveRecord::Encryption
+# - Cost tracking based on token usage and configurable pricing rules
+# - Review workflow (approve/flag/reject) with audit trail
+# - Hotwire-powered dashboard UI with filtering and export
+# - Built-in adapters for OpenAI, Anthropic, Ollama
+# - Support for hierarchical agent sessions (parent-child relationships)
+#
+# @example Basic configuration
+#   TraceBook.configure do |config|
+#     config.authorize = ->(user, action, resource) { user&.admin? }
+#     config.project_name = "My App"
+#     config.persist_async = Rails.env.production?
+#   end
+#
+# @example Recording an interaction
+#   TraceBook.record!(
+#     provider: "openai",
+#     model: "gpt-4o",
+#     request_payload: { messages: messages },
+#     response_payload: response,
+#     input_tokens: 100,
+#     output_tokens: 50,
+#     user: current_user,
+#     tags: ["production", "support"]
+#   )
+#
+# @see https://github.com/dpaluy/tracebook README for full documentation
+module Tracebook
+  class << self
+    # Returns the current configuration instance.
+    #
+    # @return [Tracebook::Config] the configuration object
+    def config
+      @config ||= Config.new
+    end
+
+    # Configures TraceBook with a block.
+    #
+    # Configuration is frozen after the block executes. Call {#reset_configuration!}
+    # in tests to reset.
+    #
+    # @yield [config] Yields the config object for modification
+    # @yieldparam config [Tracebook::Config] the configuration object
+    # @return [Tracebook::Config] the finalized configuration
+    # @raise [ConfigurationError] if configuration is already finalized
+    #
+    # @example
+    #   TraceBook.configure do |config|
+    #     config.authorize = ->(user, action, resource) { user&.admin? }
+    #     config.persist_async = true
+    #     config.project_name = "Support App"
+    #   end
+    def configure
+      ensure_configurable!
+
+      yield(config)
+      finalize_configuration!
+      config
+    end
+
+    # Resets configuration to a clean state.
+    #
+    # Used in tests to start with fresh configuration between test cases.
+    #
+    # @return [void]
+    #
+    # @example In test setup
+    #   setup do
+    #     TraceBook.reset_configuration!
+    #     TraceBook.configure do |config|
+    #       config.authorize = ->(*) { true }
+    #     end
+    #   end
+    def reset_configuration!
+      @config = Config.new
+      @configuration_finalized = false
+    end
+
+    # Records an LLM interaction.
+    #
+    # When `config.persist_async` is true, the interaction is enqueued via
+    # {PersistInteractionJob}. Otherwise, it's persisted inline.
+    #
+    # @param attributes [Hash] Interaction attributes
+    # @option attributes [String] :provider Provider name (e.g., "openai", "anthropic") **required**
+    # @option attributes [String] :model Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet") **required**
+    # @option attributes [String, nil] :project Project name for filtering
+    # @option attributes [Hash, nil] :request_payload Full request sent to provider (will be encrypted)
+    # @option attributes [Hash, nil] :response_payload Full response from provider (will be encrypted)
+    # @option attributes [String, nil] :request_text Human-readable request summary
+    # @option attributes [String, nil] :response_text Human-readable response summary
+    # @option attributes [Integer, nil] :input_tokens Prompt token count
+    # @option attributes [Integer, nil] :output_tokens Completion token count
+    # @option attributes [Integer, nil] :latency_ms Request duration in milliseconds
+    # @option attributes [Symbol, String] :status :success, :error, or :canceled (default: :success)
+    # @option attributes [String, nil] :error_class Exception class name on failure
+    # @option attributes [String, nil] :error_message Exception message on failure
+    # @option attributes [Array<String>] :tags Labels for filtering (e.g., ["prod", "urgent"])
+    # @option attributes [Hash] :metadata Custom metadata (e.g., { ticket_id: 123 })
+    # @option attributes [ActiveRecord::Base, nil] :user Associated user (polymorphic)
+    # @option attributes [String, nil] :session_id Session identifier for grouping related calls
+    # @option attributes [Integer, nil] :parent_id Parent interaction ID for hierarchical chains
+    # @option attributes [String, nil] :idempotency_key Key for deduplication
+    #
+    # @return [Tracebook::Result] Result object with success/error information
+    #
+    # @example Recording a successful completion
+    #   result = TraceBook.record!(
+    #     provider: "openai",
+    #     model: "gpt-4o-mini",
+    #     request_payload: { messages: [{ role: "user", content: "Hello" }] },
+    #     response_payload: { choices: [{ message: { content: "Hi!" } }] },
+    #     input_tokens: 10,
+    #     output_tokens: 5,
+    #     latency_ms: 150,
+    #     status: :success,
+    #     user: current_user,
+    #     tags: ["greeting"]
+    #   )
+    #
+    # @example Recording a failed request
+    #   TraceBook.record!(
+    #     provider: "anthropic",
+    #     model: "claude-3-5-sonnet",
+    #     request_payload: request,
+    #     response_payload: nil,
+    #     status: :error,
+    #     error_class: "Faraday::TimeoutError",
+    #     error_message: "Request timed out after 30s",
+    #     latency_ms: 30000
+    #   )
+    def record!(**attributes)
+      payload = build_normalized_interaction(attributes)
+      result = Result.new(idempotency_key: attributes[:idempotency_key])
+
+      if config.persist_async
+        PersistInteractionJob.perform_later(payload.to_h)
+        result
+      else
+        interaction = PersistInteractionJob.perform_now(payload.to_h)
+        Result.new(interaction: interaction, idempotency_key: attributes[:idempotency_key])
+      end
+    rescue StandardError => error
+      Result.new(error: error, idempotency_key: attributes[:idempotency_key])
+    end
+
+    private
+
+    def finalize_configuration!
+      config.finalize!
+      @configuration_finalized = true
+    end
+
+    def ensure_configurable!
+      return unless @configuration_finalized || config.finalized?
+
+      raise ConfigurationError, "TraceBook configuration is already finalized"
+    end
+
+    def build_normalized_interaction(attributes)
+      NormalizedInteraction.new(
+        provider: attributes.fetch(:provider),
+        model: attributes.fetch(:model),
+        project: attributes[:project],
+        request_payload: attributes[:request],
+        response_payload: attributes[:response],
+        request_text: attributes[:request_text],
+        response_text: attributes[:response_text],
+        input_tokens: attributes[:input_tokens],
+        output_tokens: attributes[:output_tokens],
+        latency_ms: attributes[:latency_ms],
+        status: attributes.fetch(:status, "success"),
+        error_class: attributes[:error_class],
+        error_message: attributes[:error_message],
+        tags: Array(attributes[:tags]).compact,
+        metadata: attributes[:metadata] || {},
+        user: attributes[:user],
+        parent_id: attributes[:parent_id],
+        session_id: attributes[:session_id]
+      )
+    end
+  end
+end
+
+TraceBook = Tracebook unless defined?(TraceBook)

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: tracebook
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dpaluy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: TraceBook provides a Rails engine for capturing, storing, and reviewing
+  LLM API interactions with built-in support for OpenAI, Anthropic, and Ollama. Features
+  include PII redaction, cost tracking, review workflows, and export capabilities.
+email:
+- dpaluy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- MIT-LICENSE
+- README.md
+files:
+- ".yardopts"
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/images/tracebook/.keep
+- app/assets/javascripts/tracebook/application.js
+- app/assets/stylesheets/tracebook/application.css
+- app/controllers/concerns/.keep
+- app/controllers/tracebook/application_controller.rb
+- app/controllers/tracebook/exports_controller.rb
+- app/controllers/tracebook/interactions_controller.rb
+- app/helpers/tracebook/application_helper.rb
+- app/helpers/tracebook/interactions_helper.rb
+- app/jobs/tracebook/application_job.rb
+- app/jobs/tracebook/daily_rollups_job.rb
+- app/jobs/tracebook/export_job.rb
+- app/jobs/tracebook/persist_interaction_job.rb
+- app/mailers/tracebook/application_mailer.rb
+- app/models/concerns/.keep
+- app/models/tracebook/application_record.rb
+- app/models/tracebook/interaction.rb
+- app/models/tracebook/pricing_rule.rb
+- app/models/tracebook/redaction_rule.rb
+- app/models/tracebook/rollup_daily.rb
+- app/views/layouts/tracebook/application.html.erb
+- app/views/tracebook/interactions/index.html.erb
+- app/views/tracebook/interactions/show.html.erb
+- config/routes.rb
+- db/migrate/20241112000100_create_tracebook_interactions.rb
+- db/migrate/20241112000200_create_tracebook_rollups_dailies.rb
+- db/migrate/20241112000300_create_tracebook_pricing_rules.rb
+- db/migrate/20241112000400_create_tracebook_redaction_rules.rb
+- lib/tasks/tracebook_tasks.rake
+- lib/tasks/yard.rake
+- lib/tracebook.rb
+- lib/tracebook/adapters.rb
+- lib/tracebook/adapters/active_agent.rb
+- lib/tracebook/adapters/ruby_llm.rb
+- lib/tracebook/config.rb
+- lib/tracebook/engine.rb
+- lib/tracebook/errors.rb
+- lib/tracebook/mappers.rb
+- lib/tracebook/mappers/anthropic.rb
+- lib/tracebook/mappers/base.rb
+- lib/tracebook/mappers/ollama.rb
+- lib/tracebook/mappers/openai.rb
+- lib/tracebook/normalized_interaction.rb
+- lib/tracebook/pricing.rb
+- lib/tracebook/pricing/calculator.rb
+- lib/tracebook/redaction_pipeline.rb
+- lib/tracebook/redactors.rb
+- lib/tracebook/redactors/base.rb
+- lib/tracebook/redactors/card_pan.rb
+- lib/tracebook/redactors/email.rb
+- lib/tracebook/redactors/phone.rb
+- lib/tracebook/result.rb
+- lib/tracebook/version.rb
+homepage: https://github.com/dpaluy/tracebook
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dpaluy/tracebook
+  documentation_uri: https://rubydoc.info/gems/tracebook
+  source_code_uri: https://github.com/dpaluy/tracebook
+  changelog_uri: https://github.com/dpaluy/tracebook/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/tracebook/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.0
+specification_version: 4
+summary: Rails engine for LLM interaction telemetry and review.
+test_files: []