lf-cli 1.0.0

data/lib/langfuse/cli/client.rb

@@ -0,0 +1,233 @@
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module Langfuse
+  module CLI
+    class Client
+      class APIError < StandardError; end
+      class AuthenticationError < APIError; end
+      class NotFoundError < APIError; end
+      class RateLimitError < APIError; end
+      class TimeoutError < APIError; end
+
+      attr_reader :host, :public_key
+
+      def initialize(config)
+        @host = config.host
+        @public_key = config.public_key
+        @secret_key = config.secret_key
+        @connection = build_connection
+      end
+
+      # Traces API
+      def list_traces(filters = {})
+        params = build_trace_params(filters)
+        paginate('/api/public/traces', params)
+      end
+
+      def get_trace(trace_id)
+        request(:get, "/api/public/traces/#{trace_id}")
+      end
+
+      # Sessions API
+      def list_sessions(filters = {})
+        params = build_session_params(filters)
+        paginate('/api/public/sessions', params)
+      end
+
+      def get_session(session_id)
+        request(:get, "/api/public/sessions/#{session_id}")
+      end
+
+      # Observations API
+      def list_observations(filters = {})
+        params = build_observation_params(filters)
+        paginate('/api/public/observations', params)
+      end
+
+      def get_observation(observation_id)
+        request(:get, "/api/public/observations/#{observation_id}")
+      end
+
+      # Metrics API
+      def query_metrics(query_params)
+        request(:post, '/api/public/metrics', query_params)
+      end
+
+      # Scores API
+      def list_scores(filters = {})
+        params = build_score_params(filters)
+        paginate('/api/public/scores', params)
+      end
+
+      def get_score(score_id)
+        request(:get, "/api/public/scores/#{score_id}")
+      end
+
+      private
+
+      def build_connection
+        Faraday.new(url: @host) do |conn|
+          # Set short timeouts to prevent hanging
+          conn.options.timeout = 2       # 2 seconds read timeout
+          conn.options.open_timeout = 2  # 2 seconds connection timeout
+
+          conn.request :authorization, :basic, @public_key, @secret_key
+          conn.request :json
+          conn.request :retry, {
+            max: 3,
+            interval: 0.5,
+            interval_randomness: 0.5,
+            backoff_factor: 2,
+            retry_statuses: [429, 500, 502, 503, 504],
+            methods: [:get, :post]
+          }
+          conn.response :json, content_type: /\bjson$/
+
+          # Enable debug logging if DEBUG=1
+          if ENV['DEBUG'] == '1'
+            conn.response :logger, nil, { headers: true, bodies: true }
+          end
+
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def request(method, path, params = {})
+        response = case method
+                   when :get
+                     @connection.get(path, params)
+                   when :post
+                     @connection.post(path, params)
+                   when :put
+                     @connection.put(path, params)
+                   when :delete
+                     @connection.delete(path, params)
+                   else
+                     raise ArgumentError, "Unsupported HTTP method: #{method}"
+                   end
+
+        handle_response(response)
+      rescue Faraday::TimeoutError => e
+        raise TimeoutError, "Request timed out. Please check your network connection and host URL."
+      rescue Faraday::ConnectionFailed => e
+        raise APIError, "Connection failed: #{e.message}"
+      end
+
+      def paginate(path, params = {})
+        page = params[:page] || 1
+        limit = params[:limit] || 50
+        requested_limit = limit  # Remember the original limit to stop pagination
+        all_results = []
+
+        loop do
+          response = request(:get, path, params.merge(page: page, limit: limit))
+
+          # Handle both array and hash responses
+          data = response.is_a?(Hash) && response['data'] ? response['data'] : response
+          break if data.nil? || (data.is_a?(Array) && data.empty?)
+
+          all_results.concat(Array(data))
+
+          # Stop if we've collected enough results
+          break if all_results.length >= requested_limit
+
+          # Check if there are more pages
+          meta = response.is_a?(Hash) ? response['meta'] : nil
+          break unless meta && meta['totalPages'] && page < meta['totalPages']
+
+          page += 1
+        end
+
+        # Return only the requested number of results
+        all_results.take(requested_limit)
+      end
+
+      def handle_response(response)
+        case response.status
+        when 200..299
+          response.body
+        when 401
+          raise AuthenticationError, "Authentication failed. Check your API keys."
+        when 404
+          raise NotFoundError, "Resource not found: #{response.body}"
+        when 429
+          raise RateLimitError, "Rate limit exceeded. Please try again later."
+        when 400..499
+          error_message = extract_error_message(response.body)
+          raise APIError, "Client error (#{response.status}): #{error_message}"
+        when 500..599
+          error_message = extract_error_message(response.body)
+          raise APIError, "Server error (#{response.status}): #{error_message}"
+        else
+          raise APIError, "Unexpected response status: #{response.status}"
+        end
+      end
+
+      def extract_error_message(body)
+        return body unless body.is_a?(Hash)
+        body['message'] || body['error'] || body.to_s
+      end
+
+      # Parameter builders
+      def build_trace_params(filters)
+        params = {}
+        params[:userId] = filters[:user_id] if filters[:user_id]
+        params[:name] = filters[:name] if filters[:name]
+        params[:sessionId] = filters[:session_id] if filters[:session_id]
+        params[:tags] = filters[:tags] if filters[:tags]
+        params[:fromTimestamp] = parse_timestamp(filters[:from]) if filters[:from]
+        params[:toTimestamp] = parse_timestamp(filters[:to]) if filters[:to]
+        params[:page] = filters[:page] if filters[:page]
+        params[:limit] = filters[:limit] if filters[:limit]
+        params
+      end
+
+      def build_session_params(filters)
+        params = {}
+        params[:fromTimestamp] = parse_timestamp(filters[:from]) if filters[:from]
+        params[:toTimestamp] = parse_timestamp(filters[:to]) if filters[:to]
+        params[:page] = filters[:page] if filters[:page]
+        params[:limit] = filters[:limit] if filters[:limit]
+        params
+      end
+
+      def build_observation_params(filters)
+        params = {}
+        params[:name] = filters[:name] if filters[:name]
+        params[:userId] = filters[:user_id] if filters[:user_id]
+        params[:traceId] = filters[:trace_id] if filters[:trace_id]
+        params[:type] = filters[:type] if filters[:type]
+        params[:fromTimestamp] = parse_timestamp(filters[:from]) if filters[:from]
+        params[:toTimestamp] = parse_timestamp(filters[:to]) if filters[:to]
+        params[:page] = filters[:page] if filters[:page]
+        params[:limit] = filters[:limit] if filters[:limit]
+        params
+      end
+
+      def build_score_params(filters)
+        params = {}
+        params[:name] = filters[:name] if filters[:name]
+        params[:fromTimestamp] = parse_timestamp(filters[:from]) if filters[:from]
+        params[:toTimestamp] = parse_timestamp(filters[:to]) if filters[:to]
+        params[:page] = filters[:page] if filters[:page]
+        params[:limit] = filters[:limit] if filters[:limit]
+        params
+      end
+
+      def parse_timestamp(timestamp)
+        return timestamp if timestamp.is_a?(String) && timestamp.match?(/^\d{4}-\d{2}-\d{2}T/)
+
+        # Try to parse with chronic if available
+        begin
+          require 'chronic'
+          parsed = Chronic.parse(timestamp)
+          parsed&.iso8601
+        rescue LoadError
+          timestamp
+        end
+      end
+    end
+  end
+end

data/lib/langfuse/cli/commands/config.rb

@@ -0,0 +1,176 @@
+require 'thor'
+require 'tty-prompt'
+
+module Langfuse
+  module CLI
+    module Commands
+      class ConfigCommand < Thor
+        namespace :config
+
+        def self.exit_on_failure?
+          true
+        end
+
+        desc 'setup', 'Interactive configuration setup (supports env vars for non-interactive mode)'
+        long_desc <<-LONGDESC
+          Set up Langfuse CLI configuration interactively or via environment variables.
+
+          Environment variables (for non-interactive mode):
+            LANGFUSE_PROJECT_NAME - Your Langfuse project name
+            LANGFUSE_PUBLIC_KEY   - Your Langfuse public key
+            LANGFUSE_SECRET_KEY   - Your Langfuse secret key
+            LANGFUSE_HOST         - Langfuse host URL (default: https://cloud.langfuse.com)
+            LANGFUSE_PROFILE      - Profile name to save as (default: default)
+
+          Examples:
+            # Interactive mode
+            $ lf config setup
+
+            # Non-interactive mode via environment variables
+            $ LANGFUSE_PROJECT_NAME=my-project \\
+              LANGFUSE_PUBLIC_KEY=pk-lf-xxx \\
+              LANGFUSE_SECRET_KEY=sk-lf-xxx \\
+              LANGFUSE_PROFILE=my-profile \\
+              lf config setup
+        LONGDESC
+        def setup
+          prompt = TTY::Prompt.new
+
+          # Check for environment variables for non-interactive mode
+          project_name = ENV['LANGFUSE_PROJECT_NAME']
+          public_key = ENV['LANGFUSE_PUBLIC_KEY']
+          secret_key = ENV['LANGFUSE_SECRET_KEY']
+          host = ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+          profile_name = ENV['LANGFUSE_PROFILE'] || 'default'
+
+          # Determine if we're in non-interactive mode
+          non_interactive = !public_key.nil? && !secret_key.nil?
+
+          if non_interactive
+            puts "🔑 Running in non-interactive mode (using environment variables)\n\n"
+          else
+            puts "\n🔑 Langfuse CLI Configuration Setup\n\n"
+          end
+
+          # Prompt for missing values in interactive mode
+          unless non_interactive
+            project_name ||= prompt.ask('Enter your Langfuse project name:', required: false)
+
+            # Show URL hint if project name was provided
+            if project_name && !project_name.empty?
+              settings_url = "#{host}/project/#{project_name}/settings"
+              prompt.say("💡 Visit: #{settings_url}")
+              prompt.say("   (to get your API keys)\n")
+            end
+
+            public_key = prompt.ask('Enter your Langfuse public key:', required: true)
+            secret_key = prompt.mask('Enter your Langfuse secret key:', required: true)
+            host = prompt.ask('Enter host:', default: 'https://cloud.langfuse.com')
+            profile_name = prompt.ask('Save as profile name:', default: 'default')
+          end
+
+          # Test connection
+          begin
+            config = Config.new(
+              public_key: public_key,
+              secret_key: secret_key,
+              host: host
+            )
+
+            client = Client.new(config)
+            client.list_traces(limit: 1)
+            prompt.ok('Testing connection... Success!')
+
+            # Save configuration
+            config.save(profile_name)
+            prompt.ok("Configuration saved to ~/.langfuse/config.yml")
+            puts "\nYou're all set! Try: langfuse traces list"
+          rescue Client::TimeoutError => e
+            prompt.error("Connection test failed: #{e.message}")
+            prompt.error("The host '#{host}' may be incorrect or unreachable.")
+            exit 1
+          rescue Client::AuthenticationError => e
+            prompt.error("Connection test failed: #{e.message}")
+            prompt.error("Please check your credentials and try again.")
+            exit 1
+          rescue Client::APIError => e
+            prompt.error("Connection test failed: #{e.message}")
+            exit 1
+          end
+        end
+
+        desc 'set PROFILE', 'Set configuration for a profile'
+        option :public_key, type: :string, required: true, desc: 'Langfuse public key'
+        option :secret_key, type: :string, required: true, desc: 'Langfuse secret key'
+        option :host, type: :string, default: 'https://cloud.langfuse.com', desc: 'Langfuse host URL'
+        def set(profile)
+          prompt = TTY::Prompt.new
+
+          config = Config.new(
+            public_key: options[:public_key],
+            secret_key: options[:secret_key],
+            host: options[:host]
+          )
+
+          config.save(profile)
+          prompt.ok("Configuration saved for profile: #{profile}")
+        end
+
+        desc 'show [PROFILE]', 'Show configuration for a profile'
+        def show(profile = 'default')
+          config = Config.new(profile: profile)
+
+          puts "\nConfiguration for profile: #{profile}"
+          puts "─" * 50
+          puts "Host:         #{config.host}"
+          puts "Public Key:   #{mask_key(config.public_key)}"
+          puts "Secret Key:   #{mask_key(config.secret_key)}"
+          puts "Output Format: #{config.output_format}"
+          puts "Page Limit:   #{config.page_limit}"
+          puts "─" * 50
+        end
+
+        desc 'list', 'List all configuration profiles'
+        def list
+          config_file = File.expand_path('~/.langfuse/config.yml')
+
+          unless File.exist?(config_file)
+            puts "No configuration file found at #{config_file}"
+            puts "Run 'langfuse config setup' to create one."
+            return
+          end
+
+          require 'yaml'
+          config_data = YAML.load_file(config_file)
+          profiles = config_data['profiles'] || {}
+
+          if profiles.empty?
+            puts "No profiles configured."
+            puts "Run 'langfuse config setup' to create one."
+            return
+          end
+
+          puts "\nConfigured Profiles:"
+          puts "─" * 50
+
+          profiles.each do |name, profile_config|
+            puts "\n#{name}:"
+            puts "  Host:       #{profile_config['host']}"
+            puts "  Public Key: #{mask_key(profile_config['public_key'])}"
+          end
+
+          puts "\n─" * 50
+        end
+
+        private
+
+        def mask_key(key)
+          return '' if key.nil? || key.empty?
+          return key if key.length < 8
+
+          "#{key[0..7]}#{'*' * (key.length - 8)}"
+        end
+      end
+    end
+  end
+end

data/lib/langfuse/cli/commands/metrics.rb

@@ -0,0 +1,193 @@
+require 'thor'
+require 'json'
+require 'sorbet-runtime'
+require_relative '../types'
+
+module Langfuse
+  module CLI
+    module Commands
+      class Metrics < Thor
+        extend T::Sig
+        namespace :metrics
+
+        def self.exit_on_failure?
+          true
+        end
+
+        desc 'query', 'Query metrics with custom parameters'
+        long_desc <<-LONGDESC
+          Query Langfuse metrics with flexible aggregations and dimensions.
+
+          REQUIRED OPTIONS:
+            --view: View type to query
+              Valid values: traces, observations, scores-numeric, scores-categorical
+
+            --measure: Metric to measure
+              Valid values: count, latency, value, tokens, cost
+
+            --aggregation: How to aggregate the measure
+              Valid values: count, sum, avg, p50, p95, p99, min, max, histogram
+
+          OPTIONAL:
+            --dimensions: Fields to group by (repeatable)
+              Examples: name, userId, sessionId, model, type
+
+            --from, --to: Time range (ISO 8601 or relative like "1 hour ago")
+
+            --granularity: Time bucketing
+              Valid values: minute, hour, day, week, month, auto
+
+          EXAMPLES:
+
+            # Count all traces
+            langfuse metrics query --view traces --measure count --aggregation count
+
+            # Average latency by trace name
+            langfuse metrics query --view observations --measure latency --aggregation avg --dimensions name
+
+            # Token usage with time range
+            langfuse metrics query --view observations --measure tokens --aggregation sum --from "2024-01-01" --to "2024-12-31"
+
+            # P95 latency grouped by model
+            langfuse metrics query --view observations --measure latency --aggregation p95 --dimensions model
+
+          API REFERENCE:
+            Full API documentation: https://api.reference.langfuse.com/
+            OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
+        LONGDESC
+        option :view, type: :string, required: true,
+               enum: %w[traces observations scores-numeric scores-categorical],
+               desc: 'View type'
+        option :measure, type: :string, required: true,
+               enum: %w[count latency value tokens cost],
+               desc: 'Measure type'
+        option :aggregation, type: :string, required: true,
+               enum: %w[count sum avg p50 p95 p99 min max histogram],
+               desc: 'Aggregation function'
+        option :dimensions, type: :array, desc: 'Fields to group by (e.g., name userId sessionId model)'
+        option :from, type: :string, desc: 'Start timestamp (ISO 8601 or relative)'
+        option :to, type: :string, desc: 'End timestamp (ISO 8601 or relative)'
+        option :granularity, type: :string,
+               enum: %w[minute hour day week month auto],
+               desc: 'Time granularity'
+        option :limit, type: :numeric, desc: 'Limit number of results', default: 100
+        def query
+          query_params = build_query(options)
+          result = client.query_metrics(query_params)
+
+          # Extract data from result if it's wrapped in a data key
+          output_data = result.is_a?(Hash) && result['data'] ? result['data'] : result
+          output_result(output_data)
+        rescue Client::AuthenticationError => e
+          puts "Authentication Error: #{e.message}"
+          exit 1
+        rescue Client::APIError => e
+          puts "Error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def client
+          @client ||= begin
+            config = load_config
+            unless config.valid?
+              error_message = "Missing required configuration: #{config.missing_fields.join(', ')}"
+              error_message += "\n\nPlease set environment variables or run: langfuse config setup"
+              raise Error, error_message
+            end
+            Client.new(config)
+          end
+        end
+
+        def load_config
+          Config.new(
+            profile: parent_options[:profile],
+            public_key: parent_options[:public_key],
+            secret_key: parent_options[:secret_key],
+            host: parent_options[:host],
+            format: parent_options[:format]
+          )
+        end
+
+        sig { params(opts: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
+        def build_query(opts)
+          # Validate enum values
+          Types::MetricsView.deserialize(opts[:view])
+          Types::Measure.deserialize(opts[:measure])
+          Types::Aggregation.deserialize(opts[:aggregation])
+          Types::TimeGranularity.deserialize(opts[:granularity]) if opts[:granularity]
+
+          # Build query using struct
+          query = Types::MetricsQuery.new(
+            view: opts[:view],
+            measure: opts[:measure],
+            aggregation: opts[:aggregation],
+            dimensions: opts[:dimensions],
+            from_timestamp: opts[:from] ? parse_timestamp(opts[:from]) : nil,
+            to_timestamp: opts[:to] ? parse_timestamp(opts[:to]) : nil,
+            granularity: opts[:granularity],
+            limit: opts[:limit]
+          )
+
+          query.to_h
+        end
+
+        sig { params(timestamp: String).returns(T.nilable(String)) }
+        def parse_timestamp(timestamp)
+          return timestamp if timestamp.match?(/^\d{4}-\d{2}-\d{2}T/)
+
+          # Try to parse with chronic if available
+          begin
+            require 'chronic'
+            parsed = Chronic.parse(timestamp)
+            parsed&.iso8601
+          rescue LoadError
+            timestamp
+          end
+        end
+
+        def output_result(data)
+          formatted = format_output(data)
+
+          if parent_options[:output]
+            File.write(parent_options[:output], formatted)
+            puts "Output written to #{parent_options[:output]}" if parent_options[:verbose]
+          else
+            puts formatted
+          end
+        end
+
+        def format_output(data)
+          format_type = parent_options[:format] || 'table'
+
+          case format_type
+          when 'json'
+            JSON.pretty_generate(data)
+          when 'csv'
+            require_relative '../formatters/csv_formatter'
+            Formatters::CSVFormatter.format(data)
+          when 'markdown'
+            require_relative '../formatters/markdown_formatter'
+            Formatters::MarkdownFormatter.format(data)
+          else # table
+            require_relative '../formatters/table_formatter'
+            Formatters::TableFormatter.format(data)
+          end
+        end
+
+        def parent_options
+          @parent_options ||= begin
+            if parent.respond_to?(:options)
+              parent.options
+            else
+              {}
+            end
+          rescue
+            {}
+          end
+        end
+      end
+    end
+  end
+end