langsmith-sdk 0.1.1

data/lib/langsmith/railtie.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Langsmith
+  # Rails integration for automatic configuration and lifecycle management.
+  #
+  # When Rails is detected, this Railtie will:
+  # - Automatically configure Langsmith from Rails credentials or environment
+  # - Register shutdown hooks to flush traces before the application exits
+  # - Provide a generator for creating an initializer
+  #
+  # @example Using Rails credentials (config/credentials.yml.enc)
+  #   langsmith:
+  #     api_key: ls_...
+  #     project: my-rails-app
+  #
+  # @example Using environment variables
+  #   LANGSMITH_API_KEY=ls_...
+  #   LANGSMITH_PROJECT=my-rails-app
+  #   LANGSMITH_TRACING=true
+  #
+  class Railtie < ::Rails::Railtie
+    config.langsmith = ActiveSupport::OrderedOptions.new
+
+    # Default configuration values
+    config.langsmith.auto_configure = true
+    config.langsmith.tracing_enabled = nil # nil means defer to env var
+
+    initializer "langsmith.configure" do |app|
+      next unless app.config.langsmith.auto_configure
+
+      configure_from_rails(app)
+    end
+
+    config.after_initialize do
+      # Log configuration status in development
+      if Rails.env.development? && Langsmith.tracing_enabled?
+        Rails.logger.info "[Langsmith] Tracing enabled for project: #{Langsmith.configuration.project}"
+      end
+    end
+
+    # Ensure traces are flushed before the application exits
+    config.before_configuration do
+      at_exit do
+        Langsmith.shutdown if Langsmith.tracing_enabled?
+      rescue StandardError => e
+        Rails.logger.error "[Langsmith] Error during shutdown: #{e.message}" if defined?(Rails.logger)
+      end
+    end
+
+    private
+
+    def configure_from_rails(app) # rubocop:disable Metrics/AbcSize
+      Langsmith.configure do |config|
+        # Try Rails credentials first, fall back to environment variables
+        credentials = app.credentials.langsmith || {}
+
+        config.api_key = credentials[:api_key] || ENV.fetch("LANGSMITH_API_KEY", nil)
+        config.endpoint = credentials[:endpoint] || ENV.fetch("LANGSMITH_ENDPOINT", "https://api.smith.langchain.com")
+        config.project = credentials[:project] || ENV.fetch("LANGSMITH_PROJECT",
+                                                            Rails.application.class.module_parent_name.underscore)
+        config.tenant_id = credentials[:tenant_id] || ENV.fetch("LANGSMITH_TENANT_ID", nil)
+
+        # Tracing can be set via Rails config, credentials, or environment
+        config.tracing_enabled = resolve_tracing_enabled(app, credentials)
+
+        # Optional settings from credentials
+        config.batch_size = credentials[:batch_size] if credentials[:batch_size]
+        config.flush_interval = credentials[:flush_interval] if credentials[:flush_interval]
+        config.timeout = credentials[:timeout] if credentials[:timeout]
+      end
+    rescue Langsmith::ConfigurationError => e
+      Rails.logger.warn "[Langsmith] Configuration error: #{e.message}" if defined?(Rails.logger)
+    end
+
+    def resolve_tracing_enabled(app, credentials)
+      # Priority: Rails config > credentials > environment variable
+      return app.config.langsmith.tracing_enabled unless app.config.langsmith.tracing_enabled.nil?
+      return credentials[:tracing_enabled] unless credentials[:tracing_enabled].nil?
+
+      env_value = ENV.fetch("LANGSMITH_TRACING", nil)
+      return false if env_value.nil?
+
+      %w[true 1 yes on].include?(env_value.downcase)
+    end
+  end
+end

data/lib/langsmith/run.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "json"
+
+module Langsmith
+  # Represents a single trace run/span in LangSmith.
+  # All run types (chain, llm, tool, etc.) use this same class with different run_type values.
+  #
+  # @example Creating a run
+  #   run = Langsmith::Run.new(name: "my_operation", run_type: "chain")
+  #   run.add_metadata(user_id: "123")
+  #   run.finish(outputs: { result: "success" })
+  class Run
+    # Valid run types supported by LangSmith
+    VALID_RUN_TYPES = %w[chain llm tool retriever prompt parser].freeze
+
+    # @return [String] unique identifier for this run
+    attr_reader :id
+
+    # @return [String] name of the operation
+    attr_reader :name
+
+    # @return [String] type of run (chain, llm, tool, etc.)
+    attr_reader :run_type
+
+    # @return [String, nil] parent run ID for nested traces
+    attr_reader :parent_run_id
+
+    # @return [String] project/session name
+    attr_reader :session_name
+
+    # @return [Time] when the run started
+    attr_reader :start_time
+
+    # @return [String, nil] tenant ID for multi-tenant scenarios
+    attr_reader :tenant_id
+
+    # @return [String] trace ID (root run's ID)
+    attr_reader :trace_id
+
+    # @return [String] dotted order for trace tree ordering
+    attr_reader :dotted_order
+
+    # @return [Hash] input data
+    attr_accessor :inputs
+
+    # @return [Hash, nil] output data
+    attr_accessor :outputs
+
+    # @return [String, nil] error message if run failed
+    attr_accessor :error
+
+    # @return [Time, nil] when the run ended
+    attr_accessor :end_time
+
+    # @return [Hash] additional metadata
+    attr_accessor :metadata
+
+    # @return [Hash] extra data (e.g., token usage)
+    attr_accessor :extra
+
+    # @return [Array<Hash>] events that occurred during the run
+    attr_accessor :events
+
+    # @return [Array<String>] tags for filtering
+    attr_accessor :tags
+
+    # Creates a new Run instance.
+    #
+    # @param name [String] name of the operation
+    # @param run_type [String] type of run ("chain", "llm", "tool", etc.)
+    # @param inputs [Hash, nil] input data
+    # @param parent_run_id [String, nil] parent run ID for nested traces
+    # @param session_name [String, nil] project/session name
+    # @param metadata [Hash, nil] additional metadata
+    # @param tags [Array<String>, nil] tags for filtering
+    # @param extra [Hash, nil] extra data
+    # @param id [String, nil] custom ID (auto-generated if not provided)
+    # @param tenant_id [String, nil] tenant ID for multi-tenant scenarios
+    # @param trace_id [String, nil] trace ID (defaults to own ID for root runs)
+    # @param parent_dotted_order [String, nil] parent's dotted order for tree ordering
+    #
+    # @raise [ArgumentError] if run_type is invalid
+    def initialize(
+      name:,
+      run_type: "chain",
+      inputs: nil,
+      parent_run_id: nil,
+      session_name: nil,
+      metadata: nil,
+      tags: nil,
+      extra: nil,
+      id: nil,
+      tenant_id: nil,
+      trace_id: nil,
+      parent_dotted_order: nil
+    )
+      @id = id || SecureRandom.uuid
+      @name = name
+      @run_type = validate_run_type(run_type)
+      @inputs = inputs || {}
+      @outputs = nil
+      @error = nil
+      @parent_run_id = parent_run_id
+      @session_name = session_name || Langsmith.configuration.project
+      @tenant_id = tenant_id || Langsmith.configuration.tenant_id
+      # trace_id is the root run's ID; for root runs it equals the run's own ID
+      @trace_id = trace_id || @id
+      @start_time = Time.now.utc
+      @end_time = nil
+      @metadata = metadata || {}
+      @tags = tags || []
+      @extra = extra || {}
+      @events = []
+      # dotted_order is used for ordering runs in the trace tree
+      @dotted_order = build_dotted_order(parent_dotted_order)
+    end
+
+    # Marks the run as finished.
+    #
+    # @param outputs [Hash, nil] output data
+    # @param error [Exception, String, nil] error if the run failed
+    # @return [self]
+    def finish(outputs: nil, error: nil)
+      @end_time = Time.now.utc
+      @outputs = outputs if outputs
+      @error = format_error(error) if error
+      self
+    end
+
+    # Adds metadata to the run.
+    #
+    # @param new_metadata [Hash] metadata to merge
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def add_metadata(new_metadata)
+      @metadata.merge!(new_metadata)
+      nil
+    end
+
+    # Adds tags to the run.
+    #
+    # @param new_tags [Array<String>] tags to add
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def add_tags(*new_tags)
+      @tags.concat(new_tags.flatten)
+      nil
+    end
+
+    # Adds an event to the run.
+    #
+    # @param name [String] event name
+    # @param time [Time, nil] event time (defaults to now)
+    # @param kwargs [Hash] additional event data
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def add_event(name:, time: nil, **kwargs)
+      @events << {
+        name: name,
+        time: (time || Time.now.utc).iso8601(3),
+        **kwargs
+      }
+      nil
+    end
+
+    # Sets token usage for LLM runs.
+    # Follows the Python SDK pattern: tokens are stored in extra.metadata.usage_metadata
+    # with keys: input_tokens, output_tokens, total_tokens
+    #
+    # @param input_tokens [Integer, nil] number of input/prompt tokens
+    # @param output_tokens [Integer, nil] number of output/completion tokens
+    # @param total_tokens [Integer, nil] total tokens (calculated if not provided)
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def set_token_usage(input_tokens: nil, output_tokens: nil, total_tokens: nil)
+      calculated_total = total_tokens || ((input_tokens || 0) + (output_tokens || 0))
+
+      @extra[:metadata] ||= {}
+      @extra[:metadata][:usage_metadata] = {
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        total_tokens: calculated_total
+      }.compact
+
+      nil # Return nil to prevent circular reference if used as last line of trace block
+    end
+
+    # Sets LLM model metadata.
+    # The model name should be stored in extra.metadata for LangSmith to display it.
+    #
+    # @param model [String] the model name/identifier
+    # @param provider [String, nil] the model provider (e.g., "openai", "anthropic")
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def set_model(model:, provider: nil)
+      @extra[:metadata] ||= {}
+      @extra[:metadata][:ls_model_name] = model
+      @extra[:metadata][:ls_provider] = provider if provider
+      nil
+    end
+
+    # Sets streaming metrics for LLM runs.
+    # Useful for tracking performance of streaming responses.
+    #
+    # @param time_to_first_token [Float, nil] time in seconds until first token received
+    # @param chunk_count [Integer, nil] total number of chunks received
+    # @param tokens_per_second [Float, nil] throughput in tokens per second
+    # @return [nil] returns nil to prevent circular reference when used as last line
+    def set_streaming_metrics(time_to_first_token: nil, chunk_count: nil, tokens_per_second: nil)
+      @extra[:metadata] ||= {}
+      @extra[:metadata][:streaming_metrics] = {
+        time_to_first_token_s: time_to_first_token,
+        chunk_count: chunk_count,
+        tokens_per_second: tokens_per_second
+      }.compact
+
+      nil
+    end
+
+    # Returns whether the run has finished.
+    # @return [Boolean]
+    def finished?
+      !end_time.nil?
+    end
+
+    # Returns the duration in milliseconds.
+    # @return [Float, nil] duration in ms, or nil if not finished
+    def duration_ms
+      return nil unless end_time
+
+      ((end_time - start_time) * 1000).round(2)
+    end
+
+    # Convert to hash for JSON serialization to LangSmith API (full run for POST).
+    # Token usage is stored in extra.metadata.usage_metadata following Python SDK pattern.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        id:,
+        name:,
+        run_type:,
+        inputs:,
+        outputs:,
+        error:,
+        parent_run_id:,
+        trace_id:,
+        dotted_order:,
+        session_name:,
+        start_time: start_time.iso8601(3),
+        end_time: end_time&.iso8601(3),
+        extra: extra.empty? ? nil : extra,
+        events: events.empty? ? nil : events,
+        tags: tags.empty? ? nil : tags,
+        serialized: { name: },
+        **(metadata.empty? ? {} : { metadata: })
+      }.compact
+    end
+
+    # Convert to hash for PATCH requests (only fields that change on completion).
+    # Note: parent_run_id is required for LangSmith to validate dotted_order correctly.
+    # Token usage is included in extra.metadata.usage_metadata.
+    # Metadata and tags are included as they may be added during execution.
+    #
+    # @return [Hash]
+    def to_update_h
+      {
+        id:,
+        trace_id:,
+        parent_run_id:,
+        dotted_order:,
+        end_time: end_time&.iso8601(3),
+        outputs:,
+        error:,
+        events: events.empty? ? nil : events,
+        extra: extra.empty? ? nil : extra,
+        tags: tags.empty? ? nil : tags,
+        **(metadata.empty? ? {} : { metadata: })
+      }.compact
+    end
+
+    # Convert to JSON string.
+    #
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    def validate_run_type(run_type)
+      return run_type if VALID_RUN_TYPES.include?(run_type)
+
+      raise ArgumentError, "Invalid run_type '#{run_type}'. Must be one of: #{VALID_RUN_TYPES.join(", ")}"
+    end
+
+    def format_error(error)
+      case error
+      when Exception
+        "#{error.class}: #{error.message}\n#{error.backtrace&.first(10)&.join("\n")}"
+      when String
+        error
+      else
+        error.to_s
+      end
+    end
+
+    # Build the dotted_order string for trace ordering
+    # Format: {timestamp}{id} for root, {parent_dotted_order}.{timestamp}{id} for children
+    def build_dotted_order(parent_dotted_order)
+      # Format timestamp as YYYYMMDDTHHMMSSffffffZ (compact ISO8601 with microseconds)
+      timestamp = @start_time.strftime("%Y%m%dT%H%M%S%6NZ")
+      order_part = "#{timestamp}#{@id}"
+
+      if parent_dotted_order
+        "#{parent_dotted_order}.#{order_part}"
+      else
+        order_part
+      end
+    end
+  end
+end

data/lib/langsmith/run_tree.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "run"
+require_relative "context"
+
+module Langsmith
+  # RunTree manages the creation and lifecycle of trace runs.
+  # It handles parent-child relationships and coordinates with the batch processor.
+  class RunTree
+    attr_reader :run
+
+    def initialize(
+      name:,
+      run_type: "chain",
+      inputs: nil,
+      metadata: nil,
+      tags: nil,
+      extra: nil,
+      parent_run_id: nil,
+      tenant_id: nil,
+      project: nil
+    )
+      # If no explicit parent, check context for current parent
+      effective_parent_id = parent_run_id || Context.current_parent_run_id
+
+      # Inherit tenant_id from parent run if not explicitly set
+      effective_tenant_id = tenant_id || Context.current_run&.tenant_id
+
+      # Child traces must use the same project as their parent to keep the trace tree together.
+      # Only root traces can set the project; children always inherit from parent.
+      effective_project = Context.current_run&.session_name || project
+
+      # Inherit trace_id from root run (parent's trace_id)
+      # For root runs, trace_id will default to the run's own ID
+      effective_trace_id = Context.current_run&.trace_id
+
+      # Inherit dotted_order from parent for proper trace ordering
+      parent_dotted_order = Context.current_run&.dotted_order
+
+      @run = Run.new(
+        name: name,
+        run_type: run_type,
+        inputs: inputs,
+        parent_run_id: effective_parent_id,
+        metadata: metadata,
+        tags: tags,
+        extra: extra,
+        tenant_id: effective_tenant_id,
+        session_name: effective_project,
+        trace_id: effective_trace_id,
+        parent_dotted_order: parent_dotted_order
+      )
+
+      @posted_start = false
+      @posted_end = false
+    end
+
+    # Post the run start to LangSmith
+    def post_start
+      return if @posted_start || !Langsmith.tracing_enabled?
+
+      Langsmith.batch_processor.enqueue_create(@run)
+      @posted_start = true
+    end
+
+    # Post the run end to LangSmith
+    def post_end
+      return if @posted_end || !Langsmith.tracing_enabled?
+
+      Langsmith.batch_processor.enqueue_update(@run)
+      @posted_end = true
+    end
+
+    # Execute a block within this run's context
+    def execute
+      return yield(@run) unless Langsmith.tracing_enabled?
+
+      post_start
+
+      Context.with_run(@run) do
+        result = yield(@run)
+        @run.finish(outputs: sanitize_outputs(result))
+        result
+      end
+    rescue StandardError => e
+      @run.finish(error: e)
+      raise
+    ensure
+      post_end if Langsmith.tracing_enabled?
+    end
+
+    # Convenience methods that delegate to the run
+    def add_metadata(...)
+      @run.add_metadata(...)
+    end
+
+    def add_tags(...)
+      @run.add_tags(...)
+    end
+
+    def set_inputs(inputs)
+      @run.inputs = inputs
+    end
+
+    def set_outputs(outputs)
+      @run.outputs = outputs
+    end
+
+    def set_token_usage(...)
+      @run.set_token_usage(...)
+    end
+
+    def set_model(...)
+      @run.set_model(...)
+    end
+
+    def set_streaming_metrics(...)
+      @run.set_streaming_metrics(...)
+    end
+
+    def id
+      @run.id
+    end
+
+    def parent_run_id
+      @run.parent_run_id
+    end
+
+    # Create a child run tree
+    def create_child(name:, run_type: "chain", **kwargs)
+      RunTree.new(
+        name: name,
+        run_type: run_type,
+        parent_run_id: @run.id,
+        **kwargs
+      )
+    end
+
+    private
+
+    # Sanitize block results to prevent circular references.
+    # When users call methods like `run.add_metadata(...)` as the last line,
+    # the Run object itself becomes the result, creating a circular reference.
+    def sanitize_outputs(result)
+      case result
+      when Run, RunTree, nil
+        # Run/RunTree objects would create circular reference, nil means no output
+        nil
+      else
+        { result: result }
+      end
+    end
+  end
+end

data/lib/langsmith/traceable.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Langsmith
+  # Module that provides method decoration for automatic tracing.
+  # Include this module in your class and use the `traceable` class method
+  # to mark methods for tracing.
+  #
+  # @example
+  #   class MyService
+  #     include Langsmith::Traceable
+  #
+  #     traceable run_type: "llm"
+  #     def call_llm(prompt)
+  #       # automatically traced
+  #     end
+  #
+  #     traceable run_type: "tool", name: "search"
+  #     def search(query)
+  #       # traced with custom name
+  #     end
+  #
+  #     traceable run_type: "chain", tenant_id: "tenant-123"
+  #     def process_for_tenant(data)
+  #       # traced to specific tenant
+  #     end
+  #   end
+  module Traceable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Marks the next defined method as traceable
+      def traceable(run_type: "chain", name: nil, metadata: nil, tags: nil, tenant_id: nil)
+        @pending_traceable_options = {
+          run_type: run_type,
+          name: name,
+          metadata: metadata,
+          tags: tags,
+          tenant_id: tenant_id
+        }
+      end
+
+      def method_added(method_name)
+        super
+
+        return unless @pending_traceable_options
+
+        options = @pending_traceable_options
+        @pending_traceable_options = nil
+
+        # Don't wrap private/protected methods that start with underscore
+        return if method_name.to_s.start_with?("_langsmith_")
+
+        wrap_method(method_name, options)
+      end
+
+      private
+
+      def wrap_method(method_name, options)
+        original_method = instance_method(method_name)
+        trace_name = options[:name] || "#{name}##{method_name}"
+
+        # Remove original method to avoid "method redefined" warning
+        remove_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          Langsmith.trace(
+            trace_name,
+            run_type: options[:run_type],
+            inputs: build_trace_inputs(args, kwargs, original_method),
+            metadata: options[:metadata],
+            tags: options[:tags],
+            tenant_id: options[:tenant_id]
+          ) do |_run|
+            if kwargs.empty?
+              original_method.bind(self).call(*args, &block)
+            else
+              original_method.bind(self).call(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def build_trace_inputs(args, kwargs, method)
+      params = method.parameters
+      inputs = {}
+
+      # Map positional arguments
+      args.each_with_index do |arg, index|
+        param = params[index]
+        param_name = param ? param[1] : "arg#{index}"
+        inputs[param_name] = serialize_input(arg)
+      end
+
+      # Map keyword arguments
+      kwargs.each do |key, value|
+        inputs[key] = serialize_input(value)
+      end
+
+      inputs
+    end
+
+    def serialize_input(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        value
+      when Array
+        value.map { |v| serialize_input(v) }
+      when Hash
+        value.transform_values { |v| serialize_input(v) }
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/langsmith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Langsmith
+  VERSION = "0.1.1"
+end