langsmith-sdk 0.1.1

data/langsmith.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/langsmith/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "langsmith-sdk"
+  spec.version = Langsmith::VERSION
+  spec.authors = ["Felipe Cabezudo"]
+  spec.email = ["felipecabedilo@gmail.com"]
+
+  spec.summary = "Ruby SDK for LangSmith tracing and observability"
+  spec.description = "A Ruby client for LangSmith, providing tracing and observability for LLM applications"
+  spec.homepage = "https://github.com/felipekb/langsmith-ruby-sdk"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "concurrent-ruby", ">= 1.1", "< 3.0"
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-net_http_persistent", "~> 2.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+end

data/lib/langsmith/batch_processor.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Langsmith
+  # Background processor that batches trace runs and sends them to LangSmith.
+  # Uses concurrent-ruby for thread-safe operations.
+  #
+  # Thread Safety:
+  # - Uses AtomicBoolean for atomic start/shutdown
+  # - Uses a Mutex to protect flush_pending from concurrent access
+  # - Uses Concurrent::Array for thread-safe pending queues
+  class BatchProcessor
+    # Entry types for the queue
+    CREATE = :create
+    UPDATE = :update
+    SHUTDOWN = :shutdown
+
+    def initialize(client: nil, batch_size: nil, flush_interval: nil)
+      config = Langsmith.configuration
+      @client = client || Client.new
+      @batch_size = batch_size || config.batch_size
+      @flush_interval = flush_interval || config.flush_interval
+
+      @queue = Queue.new
+      @running = Concurrent::AtomicBoolean.new(false)
+      @worker_thread = Concurrent::AtomicReference.new(nil)
+      @pending_creates = Concurrent::Array.new
+      @pending_updates = Concurrent::Array.new
+      @flush_task = nil
+      @flush_mutex = Mutex.new
+      @shutdown_hook_registered = false
+    end
+
+    def start
+      return unless @running.make_true
+
+      @worker_thread.set(create_worker_thread)
+      @flush_task = create_flush_task
+      @flush_task.execute
+
+      register_shutdown_hook
+    end
+
+    def shutdown
+      return unless @running.make_false
+
+      @flush_task&.shutdown
+      @queue << { type: SHUTDOWN }
+
+      worker = @worker_thread.get
+      if worker&.alive? && !worker.join(5)
+        # Give the worker time to drain the queue gracefully
+        log_error("Worker thread did not terminate within timeout", force: true)
+      end
+
+      flush_pending
+    end
+
+    def enqueue_create(run)
+      enqueue(CREATE, run)
+    end
+
+    def enqueue_update(run)
+      enqueue(UPDATE, run)
+    end
+
+    def flush
+      flush_pending
+    end
+
+    def running?
+      @running.true?
+    end
+
+    private
+
+    def enqueue(type, run)
+      unless run.is_a?(Run)
+        log_error("enqueue expects a Run instance, got #{run.class}")
+        return
+      end
+
+      ensure_started
+      # Use to_h for creates (full data), to_update_h for updates (minimal PATCH payload)
+      run_data = type == CREATE ? run.to_h : run.to_update_h
+      @queue << { type: type, run_data: run_data, tenant_id: run.tenant_id }
+    end
+
+    def create_worker_thread
+      Thread.new { worker_loop }.tap do |t|
+        t.abort_on_exception = false
+        t.report_on_exception = false
+      end
+    end
+
+    def create_flush_task
+      Concurrent::TimerTask.new(
+        execution_interval: @flush_interval,
+        run_now: false
+      ) { safe_flush }
+    end
+
+    def register_shutdown_hook
+      return if @shutdown_hook_registered
+
+      @shutdown_hook_registered = true
+      processor = self
+      at_exit do
+        processor.shutdown if processor.running?
+      rescue StandardError => e
+        warn "[Langsmith] Error during shutdown: #{e.message}" if ENV["LANGSMITH_DEBUG"]
+      end
+    end
+
+    def ensure_started
+      start unless running?
+    end
+
+    def worker_loop
+      loop do
+        entry = @queue.pop
+        break if process_entry(entry) == :shutdown
+
+        flush_if_batch_full
+      rescue StandardError => e
+        log_error("Batch processor error: #{e.message}")
+      end
+    end
+
+    def process_entry(entry)
+      case entry[:type]
+      when CREATE
+        @pending_creates << build_pending_entry(entry)
+      when UPDATE
+        @pending_updates << build_pending_entry(entry)
+      when SHUTDOWN
+        drain_queue
+        flush_pending
+        :shutdown
+      end
+    end
+
+    def build_pending_entry(entry)
+      { data: entry[:run_data], tenant_id: entry[:tenant_id] }
+    end
+
+    def drain_queue
+      loop do
+        entry = @queue.pop(true)
+        process_entry(entry) unless entry[:type] == SHUTDOWN
+      rescue ThreadError
+        break
+      end
+    end
+
+    def safe_flush
+      flush_pending if has_pending?
+    rescue StandardError => e
+      log_error("Flush task error: #{e.message}")
+    end
+
+    def flush_if_batch_full
+      flush_pending if batch_full?
+    end
+
+    def batch_full?
+      pending_count >= @batch_size
+    end
+
+    def has_pending?
+      pending_count.positive?
+    end
+
+    def pending_count
+      @pending_creates.size + @pending_updates.size
+    end
+
+    def flush_pending
+      @flush_mutex.synchronize do
+        creates = extract_all(@pending_creates)
+        updates = extract_all(@pending_updates)
+
+        return if creates.empty? && updates.empty?
+
+        send_batches(creates, updates)
+      end
+    end
+
+    def extract_all(array)
+      result = []
+      result << array.shift until array.empty?
+      result
+    rescue ThreadError
+      result
+    end
+
+    def send_batches(creates, updates)
+      by_tenant = group_by_tenant(creates, updates)
+
+      # Send POSTs first, then PATCHes (LangSmith needs runs created before updating)
+      send_batch_type(by_tenant, :creates, :post_runs)
+      send_batch_type(by_tenant, :updates, :patch_runs)
+    end
+
+    def group_by_tenant(creates, updates)
+      {
+        creates: creates.group_by { |e| e[:tenant_id] },
+        updates: updates.group_by { |e| e[:tenant_id] }
+      }
+    end
+
+    def send_batch_type(by_tenant, type_key, param_key)
+      by_tenant[type_key].each do |tenant_id, entries|
+        runs = entries.map { |e| e[:data] }
+        next if runs.empty?
+
+        send_to_api(tenant_id, param_key, runs)
+      end
+    end
+
+    def send_to_api(tenant_id, param_key, runs)
+      params = { post_runs: [], patch_runs: [], tenant_id: tenant_id }
+      params[param_key] = runs
+
+      @client.batch_ingest_raw(**params)
+    rescue Client::APIError => e
+      log_error("Failed to send #{param_key} for tenant #{tenant_id}: #{e.message}", force: true)
+    rescue StandardError => e
+      log_error("Unexpected error sending #{param_key}: #{e.message}")
+    end
+
+    def log_error(message, force: false)
+      warn "[Langsmith] #{message}" if force || ENV["LANGSMITH_DEBUG"]
+    end
+  end
+end

data/lib/langsmith/client.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http_persistent"
+require "faraday/retry"
+require "json"
+
+module Langsmith
+  # HTTP client for communicating with the LangSmith API.
+  # Handles authentication, retries, and batch operations.
+  class Client
+    # Raised when API requests fail.
+    class APIError < Langsmith::Error
+      # @return [Integer, nil] HTTP status code
+      attr_reader :status_code
+
+      # @return [Hash, String, nil] response body
+      attr_reader :response_body
+
+      # @param message [String] error message
+      # @param status_code [Integer, nil] HTTP status code
+      # @param response_body [Hash, String, nil] response body
+      def initialize(message, status_code: nil, response_body: nil)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+      end
+    end
+
+    RETRYABLE_EXCEPTIONS = [
+      Faraday::ConnectionFailed,
+      Faraday::TimeoutError
+    ].freeze
+
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    # Creates a new Client instance.
+    #
+    # @param api_key [String, nil] API key (defaults to configuration)
+    # @param endpoint [String, nil] API endpoint (defaults to configuration)
+    # @param timeout [Integer, nil] request timeout in seconds (defaults to configuration)
+    # @param max_retries [Integer, nil] max retry attempts (defaults to configuration)
+    def initialize(api_key: nil, endpoint: nil, timeout: nil, max_retries: nil)
+      config = Langsmith.configuration
+      @api_key = api_key || config.api_key
+      @endpoint = endpoint || config.endpoint
+      @timeout = timeout || config.timeout
+      @max_retries = max_retries || config.max_retries
+    end
+
+    # Create a new run.
+    #
+    # @param run [Run] the run to create
+    # @return [Hash] API response
+    # @raise [APIError] if the request fails
+    def create_run(run)
+      post("/runs", run.to_h, tenant_id: run.tenant_id)
+    end
+
+    # Update an existing run (typically when it ends).
+    #
+    # @param run [Run] the run to update
+    # @return [Hash] API response
+    # @raise [APIError] if the request fails
+    def update_run(run)
+      patch("/runs/#{run.id}", run.to_h, tenant_id: run.tenant_id)
+    end
+
+    # Batch create/update runs.
+    # All runs in a batch should have the same tenant_id for optimal performance.
+    #
+    # @param post_runs [Array<Run>] runs to create
+    # @param patch_runs [Array<Run>] runs to update
+    # @param tenant_id [String, nil] tenant ID (inferred from runs if not provided)
+    # @return [Hash, nil] API response
+    # @raise [APIError] if the request fails
+    def batch_ingest(post_runs: [], patch_runs: [], tenant_id: nil)
+      return if post_runs.empty? && patch_runs.empty?
+
+      payload = {}
+      payload[:post] = post_runs.map(&:to_h) unless post_runs.empty?
+      payload[:patch] = patch_runs.map(&:to_h) unless patch_runs.empty?
+
+      # Use tenant_id from first run if not explicitly provided
+      effective_tenant_id = tenant_id ||
+                            post_runs.first&.tenant_id ||
+                            patch_runs.first&.tenant_id
+
+      post("/runs/batch", payload, tenant_id: effective_tenant_id)
+    end
+
+    # Batch create/update runs using pre-serialized hashes.
+    # Used by BatchProcessor which snapshots run data at enqueue time.
+    #
+    # @param post_runs [Array<Hash>] run hashes to create
+    # @param patch_runs [Array<Hash>] run hashes to update
+    # @param tenant_id [String, nil] tenant ID for the request
+    # @return [Hash, nil] API response
+    # @raise [APIError] if the request fails
+    def batch_ingest_raw(post_runs: [], patch_runs: [], tenant_id: nil)
+      return if post_runs.empty? && patch_runs.empty?
+
+      payload = {}
+      payload[:post] = post_runs unless post_runs.empty?
+      payload[:patch] = patch_runs unless patch_runs.empty?
+
+      post("/runs/batch", payload, tenant_id: tenant_id)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: @endpoint) do |f|
+        f.request :json
+        f.response :json, parser_options: { symbolize_names: true }
+        f.request :retry,
+                  max: @max_retries,
+                  interval: 0.5,
+                  interval_randomness: 0.5,
+                  backoff_factor: 2,
+                  exceptions: RETRYABLE_EXCEPTIONS,
+                  retry_statuses: RETRY_STATUSES
+
+        f.headers["X-API-Key"] = @api_key
+        f.headers["User-Agent"] = "langsmith-sdk-ruby/#{Langsmith::VERSION}"
+
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout
+
+        f.adapter :net_http_persistent
+      end
+    end
+
+    def post(path, body, tenant_id: nil)
+      response = connection.post(path, body) do |req|
+        req.headers["X-Tenant-Id"] = tenant_id if tenant_id
+      end
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise APIError, "Network error: #{e.message}"
+    rescue Faraday::Error => e
+      # Raised by retry middleware when retries are exhausted
+      raise APIError, "Request failed: #{e.message}" unless e.respond_to?(:response) && e.response
+
+      handle_response(e.response)
+    end
+
+    def patch(path, body, tenant_id: nil)
+      response = connection.patch(path, body) do |req|
+        req.headers["X-Tenant-Id"] = tenant_id if tenant_id
+      end
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise APIError, "Network error: #{e.message}"
+    rescue Faraday::Error => e
+      # Raised by retry middleware when retries are exhausted
+      raise APIError, "Request failed: #{e.message}" unless e.respond_to?(:response) && e.response
+
+      handle_response(e.response)
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401
+        raise APIError.new("Unauthorized: Invalid API key", status_code: 401, response_body: response.body)
+      when 404
+        raise APIError.new("Not found", status_code: 404, response_body: response.body)
+      when 422
+        raise APIError.new("Unprocessable entity: #{response.body}", status_code: 422, response_body: response.body)
+      when 429
+        raise APIError.new("Rate limited", status_code: 429, response_body: response.body)
+      when 500..599
+        raise APIError.new("Server error", status_code: response.status, response_body: response.body)
+      else
+        raise APIError.new("Request failed", status_code: response.status, response_body: response.body)
+      end
+    end
+  end
+end

data/lib/langsmith/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Langsmith
+  # Configuration settings for the Langsmith SDK.
+  #
+  # @example Configure via block
+  #   Langsmith.configure do |config|
+  #     config.api_key = "ls_..."
+  #     config.tracing_enabled = true
+  #     config.project = "my-project"
+  #   end
+  #
+  # @example Configure via environment variables
+  #   # LANGSMITH_API_KEY=ls_...
+  #   # LANGSMITH_TRACING=true
+  #   # LANGSMITH_PROJECT=my-project
+  class Configuration
+    # @return [String, nil] LangSmith API key (required for tracing)
+    attr_accessor :api_key
+
+    # @return [String] LangSmith API endpoint
+    attr_accessor :endpoint
+
+    # @return [String] Project name for organizing traces
+    attr_accessor :project
+
+    # @return [Boolean] Enable/disable tracing
+    attr_accessor :tracing_enabled
+
+    # @return [Integer] Batch size for sending traces
+    attr_accessor :batch_size
+
+    # @return [Float] Flush interval in seconds
+    attr_accessor :flush_interval
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Maximum retry attempts for failed requests
+    attr_accessor :max_retries
+
+    # @return [String, nil] Tenant ID for multi-tenant scenarios
+    attr_accessor :tenant_id
+
+    def initialize
+      @api_key = ENV.fetch("LANGSMITH_API_KEY", nil)
+      @endpoint = ENV.fetch("LANGSMITH_ENDPOINT", "https://api.smith.langchain.com")
+      @project = ENV.fetch("LANGSMITH_PROJECT", "default")
+      @tracing_enabled = env_boolean("LANGSMITH_TRACING", false)
+      @batch_size = ENV.fetch("LANGSMITH_BATCH_SIZE", 100).to_i
+      @flush_interval = ENV.fetch("LANGSMITH_FLUSH_INTERVAL", 1.0).to_f
+      @timeout = ENV.fetch("LANGSMITH_TIMEOUT", 10).to_i
+      @max_retries = ENV.fetch("LANGSMITH_MAX_RETRIES", 3).to_i
+      @tenant_id = ENV.fetch("LANGSMITH_TENANT_ID", nil)
+    end
+
+    # Returns whether tracing is enabled in configuration.
+    # Note: This only checks the configuration flag, not whether tracing can actually occur.
+    # @return [Boolean]
+    # @see #tracing_possible?
+    def tracing_enabled?
+      @tracing_enabled
+    end
+
+    # Returns whether tracing can actually occur (enabled AND has API key).
+    # Use this to check if traces will be sent.
+    # @return [Boolean]
+    def tracing_possible?
+      @tracing_enabled && api_key_present?
+    end
+
+    # Returns whether an API key is configured.
+    # @return [Boolean]
+    def api_key_present?
+      !@api_key.nil? && !@api_key.empty?
+    end
+
+    # Validates the configuration, raising an error if invalid.
+    # @raise [ConfigurationError] if tracing is enabled but API key is missing
+    # @return [void]
+    def validate!
+      return unless @tracing_enabled
+
+      raise ConfigurationError, "LANGSMITH_API_KEY is required when tracing is enabled" unless api_key_present?
+    end
+
+    private
+
+    def env_boolean(key, default)
+      value = ENV.fetch(key, nil)
+      return default if value.nil?
+
+      %w[true 1 yes on].include?(value.downcase)
+    end
+  end
+end

data/lib/langsmith/context.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Langsmith
+  # Thread-local context manager for maintaining the current trace stack.
+  # This allows nested traces to automatically link to their parent runs.
+  #
+  # Each thread maintains its own trace stack, ensuring proper isolation
+  # in concurrent environments.
+  #
+  # Note: We use Thread.current instead of Fiber.storage for compatibility
+  # across Ruby versions. Fiber.storage behavior differs between Ruby versions
+  # and caused test failures on Ruby 3.2.
+  module Context
+    CONTEXT_KEY = :langsmith_run_stack
+    private_constant :CONTEXT_KEY
+
+    class << self
+      # Returns the current run stack for this thread.
+      def run_stack
+        Thread.current[CONTEXT_KEY] ||= []
+      end
+
+      # Returns the current (topmost) run, or nil if no active trace
+      def current_run
+        run_stack.last
+      end
+
+      # Returns the current parent run ID for creating child runs
+      def current_parent_run_id
+        current_run&.id
+      end
+
+      # Push a run onto the context stack
+      def push(run)
+        run_stack.push(run)
+        run
+      end
+
+      # Pop a run from the context stack
+      def pop
+        run_stack.pop
+      end
+
+      # Execute a block with a run pushed onto the stack
+      def with_run(run)
+        push(run)
+        yield run
+      ensure
+        pop
+      end
+
+      # Clear the entire run stack (useful for testing)
+      def clear!
+        Thread.current[CONTEXT_KEY] = []
+      end
+
+      # Check if there's an active trace context
+      def active?
+        !run_stack.empty?
+      end
+
+      # Get the depth of the current trace (0 = root level)
+      def depth
+        run_stack.size
+      end
+
+      # Get the root run of the current trace tree
+      def root_run
+        run_stack.first
+      end
+    end
+  end
+end

data/lib/langsmith/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Langsmith
+  # Base error class for all Langsmith errors.
+  # All custom errors inherit from this class.
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or incomplete.
+  class ConfigurationError < Error; end
+
+  # Raised when tracing operations fail.
+  class TracingError < Error; end
+end