ragdoll-cli 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37690a904a95405edf1f83bcc0655d0933028ba81dc9d16862f2e46a197c86e2
-  data.tar.gz: 352ab870d8581d97b4aa0f53906614c5a4c1c07128cd7392693b810bef75a685
+  metadata.gz: 843beb22244ce386dadbe959585717710940767c066307b2a92d9cfeafa6c2c9
+  data.tar.gz: 3a47b7c95155ab97644063746998f3e2f9888f0ad7e757af1a35240baed67537
 SHA512:
-  metadata.gz: c49805896f34f099dc5a87421df3697996cb34700c371f75df37b587eb9984d6f81032b7b3b4457226fbcad2ebfa67cec1fb23f66665dc964bbbf490c6c71d91
-  data.tar.gz: e8183a1904f7a3877319d11a8e96110f9570ba036af175fe92dcd1b4dffe9cfbdd119c555af6d3edc8d49ee364121b2a2da32abd56e5cd49e55a4c1bc447a104
+  metadata.gz: d15dd454cec4f80ce738ffa100c6a0c00e8642e7881443aca0247436dcb9e321761467b7554439324b3ba5c9b1b232f76d87ce18a4a90547b88e899ea2e196b4
+  data.tar.gz: 14d92726298d5d0419075bc8d9f87bc0be0d0a34d2128c20da4fb768d68770cf0ded31735c588347cce462c94c705dc8252734317db7c09fafe25d73b19f29c6

data/lib/ragdoll/cli/commands/analytics.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'thor'
+
+module Ragdoll
+  module CLI
+    class Analytics < Thor
+      desc 'overview', 'Show search analytics overview'
+      method_option :days, type: :numeric, default: 30, aliases: '-d',
+                           desc: 'Number of days to analyze (default: 30)'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json)'
+      def overview
+        client = StandaloneClient.new
+        days = (options && options[:days]) || 30
+        analytics = client.search_analytics(days: days)
+
+        case (options && options[:format]) || 'table'
+        when 'json'
+          puts JSON.pretty_generate(analytics)
+        else
+          puts "Search Analytics (last #{days} days):"
+          puts
+          puts 'Metric'.ljust(30) + 'Value'
+          puts '-' * 50
+          
+          analytics.each do |key, value|
+            metric = format_metric_name(key).ljust(30)
+            formatted_value = format_metric_value(key, value)
+            puts "#{metric}#{formatted_value}"
+          end
+        end
+      rescue StandardError => e
+        puts "Error retrieving analytics: #{e.message}"
+      end
+
+      desc 'history', 'Show recent search history'
+      method_option :limit, type: :numeric, default: 20, aliases: '-l',
+                            desc: 'Number of searches to show (default: 20)'
+      method_option :user_id, type: :string, aliases: '-u',
+                              desc: 'Filter by user ID'
+      method_option :session_id, type: :string, aliases: '-s',
+                                  desc: 'Filter by session ID'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json, plain)'
+      def history
+        client = StandaloneClient.new
+        limit = (options && options[:limit]) || 20
+        filter_options = {}
+        filter_options[:user_id] = options[:user_id] if options && options[:user_id]
+        filter_options[:session_id] = options[:session_id] if options && options[:session_id]
+
+        searches = client.search_history(limit: limit, **filter_options)
+
+        case (options && options[:format]) || 'table'
+        when 'json'
+          puts JSON.pretty_generate(searches || [])
+        when 'plain'
+          if searches.nil? || searches.empty?
+            puts 'No search history found.'
+            return
+          end
+          searches.each_with_index do |search, index|
+            puts "#{index + 1}. #{search[:query]} (#{search[:search_type]})"
+            puts "   Time: #{search[:created_at]}"
+            puts "   Results: #{search[:results_count]}"
+            puts "   Execution: #{search[:execution_time_ms]}ms"
+            puts "   Session: #{search[:session_id]}" if search[:session_id]
+            puts "   User: #{search[:user_id]}" if search[:user_id]
+            puts
+          end
+        else
+          # Table format
+          if searches.nil? || searches.empty?
+            puts 'No search history found.'
+            return
+          end
+          
+          puts "Recent Search History (#{searches.length} searches):"
+          puts
+          puts 'Time'.ljust(20) + 'Query'.ljust(30) + 'Type'.ljust(10) + 'Results'.ljust(8) + 'Time(ms)'
+          puts '-' * 80
+
+          searches.each do |search|
+            time = format_time(search[:created_at]).ljust(20)
+            query = (search[:query] || 'N/A')[0..29].ljust(30)
+            type = (search[:search_type] || 'N/A')[0..9].ljust(10)
+            results = (search[:results_count] || 0).to_s.ljust(8)
+            exec_time = (search[:execution_time_ms] || 0).to_s
+
+            puts "#{time}#{query}#{type}#{results}#{exec_time}"
+          end
+        end
+      rescue StandardError => e
+        puts "Error retrieving search history: #{e.message}"
+      end
+
+      desc 'trending', 'Show trending search queries'
+      method_option :limit, type: :numeric, default: 10, aliases: '-l',
+                            desc: 'Number of queries to show (default: 10)'
+      method_option :days, type: :numeric, default: 7, aliases: '-d',
+                           desc: 'Time period in days (default: 7)'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json)'
+      def trending
+        client = StandaloneClient.new
+        limit = (options && options[:limit]) || 10
+        days = (options && options[:days]) || 7
+        trending_queries = client.trending_queries(limit: limit, days: days)
+
+        case (options && options[:format]) || 'table'
+        when 'json'
+          puts JSON.pretty_generate(trending_queries || [])
+        else
+          if trending_queries.nil? || trending_queries.empty?
+            puts "No trending queries found for the last #{days} days."
+            return
+          end
+          
+          puts "Trending Search Queries (last #{days} days):"
+          puts
+          puts 'Rank'.ljust(5) + 'Query'.ljust(40) + 'Count'.ljust(8) + 'Avg Results'
+          puts '-' * 80
+
+          trending_queries.each_with_index do |query_data, index|
+            rank = (index + 1).to_s.ljust(5)
+            query = (query_data[:query] || 'N/A')[0..39].ljust(40)
+            count = (query_data[:count] || 0).to_s.ljust(8)
+            avg_results = (query_data[:avg_results] || 0).round(1).to_s
+
+            puts "#{rank}#{query}#{count}#{avg_results}"
+          end
+        end
+      rescue StandardError => e
+        puts "Error retrieving trending queries: #{e.message}"
+      end
+
+      desc 'cleanup', 'Cleanup old search records'
+      method_option :days, type: :numeric, default: 30, aliases: '-d',
+                           desc: 'Remove searches older than N days (default: 30)'
+      method_option :dry_run, type: :boolean, default: true, aliases: '-n',
+                              desc: 'Show what would be deleted without actually deleting (default: true)'
+      method_option :force, type: :boolean, default: false, aliases: '-f',
+                            desc: 'Actually perform the cleanup (overrides dry_run)'
+      def cleanup
+        client = StandaloneClient.new
+        
+        days = (options && options[:days]) || 30
+        dry_run = if options && options.key?(:dry_run)
+                    options[:dry_run]
+                  else
+                    true  # Default to true
+                  end
+        force = (options && options[:force]) == true
+        
+        cleanup_options = {
+          days: days,
+          dry_run: dry_run && !force
+        }
+
+        if cleanup_options[:dry_run]
+          puts "DRY RUN: Showing what would be cleaned up (use --force to actually clean up)"
+          puts
+        else
+          puts "Performing actual cleanup of search records older than #{days} days..."
+          puts
+        end
+
+        result = client.cleanup_searches(**cleanup_options)
+
+        if result.is_a?(Hash)
+          puts "Cleanup Results:"
+          puts "  Orphaned searches: #{result[:orphaned_count] || 0}"
+          puts "  Old unused searches: #{result[:unused_count] || 0}"
+          puts "  Total cleaned: #{(result[:orphaned_count] || 0) + (result[:unused_count] || 0)}"
+        else
+          puts "Searches cleaned up: #{result}"
+        end
+
+        if cleanup_options[:dry_run]
+          puts
+          puts "Use --force to actually perform the cleanup"
+        end
+      rescue StandardError => e
+        puts "Error during cleanup: #{e.message}"
+      end
+
+      private
+
+      def format_metric_name(key)
+        key.to_s.tr('_', ' ').split.map(&:capitalize).join(' ')
+      end
+
+      def format_metric_value(key, value)
+        case key.to_s
+        when /time/
+          "#{value}ms"
+        when /rate/
+          "#{value}%"
+        when /count/
+          value.to_s
+        else
+          value.to_s
+        end
+      end
+
+      def format_time(timestamp)
+        return 'N/A' unless timestamp
+        
+        if timestamp.respond_to?(:strftime)
+          timestamp.strftime('%m/%d %H:%M')
+        else
+          # Handle string timestamps
+          Time.parse(timestamp.to_s).strftime('%m/%d %H:%M')
+        end
+      rescue
+        'N/A'
+      end
+    end
+  end
+end

data/lib/ragdoll/cli/commands/search.rb

@@ -14,21 +14,79 @@ module Ragdoll
 
         search_options = {}
         search_options[:limit] = options[:limit] if options[:limit]
+        search_options[:threshold] = options[:threshold] if options[:threshold]
         search_options[:content_type] = options[:content_type] if options[:content_type]
         search_options[:classification] = options[:classification] if options[:classification]
         search_options[:keywords] = options[:keywords].split(',').map(&:strip) if options[:keywords]
         search_options[:tags] = options[:tags].split(',').map(&:strip) if options[:tags]
+        
+        # Add search tracking options
+        search_options[:session_id] = options[:session_id] if options[:session_id]
+        search_options[:user_id] = options[:user_id] if options[:user_id]
+        search_options[:track_search] = options[:track_search] if options.respond_to?(:key?) ? options.key?(:track_search) : options.track_search
 
-        search_response = client.search(query: query, **search_options)
+        # Select search method based on search_type
+        search_response = case options[:search_type]
+                         when 'hybrid'
+                           client.hybrid_search(query: query, **search_options)
+                         when 'fulltext'
+                           # Note: fulltext search would need to be implemented in client
+                           client.search(query: query, **search_options)
+                         else
+                           client.search(query: query, **search_options)
+                         end
         
         # Extract the actual results array from the response
         results = search_response[:results] || search_response['results'] || []
 
         if results.empty?
+          # Get statistics for better feedback
+          statistics = search_response[:statistics] || search_response['statistics']
+          execution_time = search_response[:execution_time_ms] || search_response['execution_time_ms']
           total = search_response[:total_results] || search_response['total_results'] || 0
+          
           puts "No results found for '#{query}'"
-          puts "(Total documents in system: #{total})" if total > 0
-          puts "Try adjusting your search terms or check if documents have been processed."
+          puts
+          
+          if statistics
+            threshold = statistics[:threshold_used] || statistics['threshold_used']
+            highest = statistics[:highest_similarity] || statistics['highest_similarity']
+            lowest = statistics[:lowest_similarity] || statistics['lowest_similarity']
+            average = statistics[:average_similarity] || statistics['average_similarity']
+            above_threshold = statistics[:similarities_above_threshold] || statistics['similarities_above_threshold']
+            total_checked = statistics[:total_embeddings_checked] || statistics['total_embeddings_checked']
+            
+            puts "Search Analysis:"
+            puts "  • Similarity threshold: #{threshold&.round(3) || 'N/A'}"
+            puts "  • Embeddings analyzed: #{total_checked || 0}"
+            if highest && lowest && average
+              puts "  • Similarity range: #{lowest.round(3)} - #{highest.round(3)} (avg: #{average.round(3)})"
+            end
+            puts "  • Results above threshold: #{above_threshold || 0}"
+            puts "  • Search time: #{execution_time || 0}ms"
+            puts
+            
+            # Provide actionable suggestions
+            if highest && threshold
+              if highest < threshold
+                suggested_threshold = (highest * 0.9).round(3)
+                puts "💡 Suggestions:"
+                puts "  • Lower the similarity threshold (highest found: #{highest.round(3)})"
+                puts "  • Try: ragdoll search '#{query}' --threshold=#{suggested_threshold}"
+                if highest < 0.3
+                  puts "  • Your query might not match the document content well"
+                  puts "  • Try different or more specific search terms"
+                end
+              elsif above_threshold > 0
+                puts "💡 Note: Found #{above_threshold} similar content above threshold #{threshold}"
+                puts "  This suggests an issue with result processing."
+              end
+            end
+          else
+            puts "(Total documents in system: #{total})" if total > 0
+            puts "Try adjusting your search terms or check if documents have been processed."
+          end
+          
           return
         end
 

data/lib/ragdoll/cli/commands/update.rb

@@ -18,7 +18,7 @@ module Ragdoll
           return
         end
 
-        result = client.update_document(id, update_options)
+        result = client.update_document(id, **update_options)
 
         if result[:success]
           puts "Document ID #{id} updated successfully."

data/lib/ragdoll/cli/standalone_client.rb

@@ -4,6 +4,7 @@ module Ragdoll
   module CLI
     class StandaloneClient
       include DebugMe
+
       def add_document(path, **options)
         Ragdoll.add_document(path: path, **options)
       end
@@ -34,8 +35,12 @@ module Ragdoll
       end
 
 
-      def search(query, **options)
-        Ragdoll.search(query: query, **options)
+      def search(query = nil, **options)
+        if query
+          Ragdoll.search(query: query, **options)
+        else
+          Ragdoll.search(**options)
+        end
       end
 
 
@@ -53,6 +58,68 @@ module Ragdoll
         Ragdoll.stats
       end
 
+      def search_analytics(days: 30)
+        # TODO: This will delegate to Ragdoll core when analytics are implemented
+        if defined?(Ragdoll) && Ragdoll.respond_to?(:search_analytics)
+          Ragdoll.search_analytics(days: days)
+        else
+          # Placeholder response for now
+          {
+            total_searches: 0,
+            unique_queries: 0,
+            avg_results_per_search: 0.0,
+            avg_execution_time: 0.0,
+            search_types: {},
+            searches_with_results: 0,
+            avg_click_through_rate: 0.0
+          }
+        end
+      end
+
+      def search_history(limit: 20, **options)
+        # TODO: This will delegate to Ragdoll core when analytics are implemented
+        if defined?(Ragdoll) && Ragdoll.respond_to?(:search_history)
+          Ragdoll.search_history(limit: limit, **options)
+        else
+          # Placeholder response for now
+          []
+        end
+      end
+
+      def trending_queries(limit: 10, days: 7)
+        # TODO: This will delegate to Ragdoll core when analytics are implemented
+        if defined?(Ragdoll) && Ragdoll.respond_to?(:trending_queries)
+          Ragdoll.trending_queries(limit: limit, days: days)
+        else
+          # Placeholder response for now
+          []
+        end
+      end
+
+      def cleanup_searches(**options)
+        # TODO: This will delegate to Ragdoll core when analytics are implemented
+        if defined?(Ragdoll) && Ragdoll.respond_to?(:cleanup_searches)
+          Ragdoll.cleanup_searches(**options)
+        else
+          # Placeholder response for now
+          { orphaned_count: 0, unused_count: 0 }
+        end
+      end
+
+      def hybrid_search(query = nil, **options)
+        # TODO: This will delegate to Ragdoll core when hybrid search is implemented
+        if defined?(Ragdoll) && Ragdoll.respond_to?(:hybrid_search)
+          if query
+            Ragdoll.hybrid_search(query: query, **options)
+          else
+            Ragdoll.hybrid_search(**options)
+          end
+        else
+          # Fallback to regular search for now
+          result = search(query, **options)
+          result.is_a?(Hash) ? result.merge(search_type: 'hybrid') : { search_type: 'hybrid', results: [] }
+        end
+      end
 
       def healthy?
         Ragdoll.healthy?

data/lib/ragdoll/cli/version.rb

@@ -3,6 +3,6 @@
 
 module Ragdoll
   module CLI
-    VERSION = "0.1.8"
+    VERSION = "0.1.9"
   end
 end

data/lib/ragdoll/cli.rb

@@ -14,6 +14,7 @@ require_relative 'cli/commands/search'
 require_relative 'cli/commands/config'
 require_relative 'cli/commands/delete'
 require_relative 'cli/commands/update'
+require_relative 'cli/commands/analytics'
 
 module Ragdoll
   module CLI
@@ -37,6 +38,8 @@ module Ragdoll
       desc 'search QUERY', 'Search for documents matching the query'
       method_option :limit, type: :numeric, default: 10, aliases: '-l',
                             desc: 'Maximum number of results to return'
+      method_option :threshold, type: :numeric,
+                               desc: 'Similarity threshold (0.0-1.0, lower = more results)'
       method_option :content_type, type: :string, aliases: '-c',
                                    desc: 'Filter by content type (text, image, audio)'
       method_option :classification, type: :string, aliases: '-C',
@@ -47,6 +50,14 @@ module Ragdoll
                            desc: 'Filter by tags (comma-separated)'
       method_option :format, type: :string, default: 'table', aliases: '-f',
                              desc: 'Output format (table, json, plain)'
+      method_option :session_id, type: :string, aliases: '-s',
+                                 desc: 'Session ID for search tracking'
+      method_option :user_id, type: :string, aliases: '-u',
+                               desc: 'User ID for search tracking'
+      method_option :track_search, type: :boolean, default: true, aliases: '-t',
+                                   desc: 'Enable search tracking (default: true)'
+      method_option :search_type, type: :string, default: 'semantic', aliases: '-S',
+                                  desc: 'Search type: semantic, hybrid, fulltext (default: semantic)'
       def search(query)
         Search.new.call(query, options)
       end
@@ -54,6 +65,9 @@ module Ragdoll
       desc 'config SUBCOMMAND', 'Manage configuration'
       subcommand 'config', Config
 
+      desc 'analytics SUBCOMMAND', 'Search analytics and reporting'
+      subcommand 'analytics', Analytics
+
       desc 'stats', 'Show document and embedding statistics'
       def stats
         client = StandaloneClient.new
@@ -78,11 +92,36 @@ module Ragdoll
           end
         end
 
-        return unless stats[:content_types]
+        if stats[:content_types]
+          puts "\nContent Types:"
+          stats[:content_types].each do |type, count|
+            puts "  #{type}: #{count}"
+          end
+        end
 
-        puts "\nContent Types:"
-        stats[:content_types].each do |type, count|
-          puts "  #{type}: #{count}"
+        # Add search analytics if available
+        begin
+          search_analytics = client.search_analytics(days: 30)
+          if search_analytics && !search_analytics.empty?
+            puts "\nSearch Analytics (last 30 days):"
+            puts "  Total searches: #{search_analytics[:total_searches] || 0}"
+            puts "  Unique queries: #{search_analytics[:unique_queries] || 0}"
+            puts "  Avg results per search: #{search_analytics[:avg_results_per_search] || 0}"
+            puts "  Avg execution time: #{search_analytics[:avg_execution_time] || 0}ms"
+            
+            if search_analytics[:search_types]
+              puts "  Search types:"
+              search_analytics[:search_types].each do |type, count|
+                puts "    #{type}: #{count}"
+              end
+            end
+            
+            puts "  Searches with results: #{search_analytics[:searches_with_results] || 0}"
+            puts "  Avg click-through rate: #{search_analytics[:avg_click_through_rate] || 0}%"
+          end
+        rescue StandardError => e
+          # Search analytics not available - silently continue
+          puts "\nSearch analytics: Not available (#{e.message})"
         end
       end
 
@@ -354,27 +393,152 @@ module Ragdoll
       end
 
       desc 'context QUERY', 'Get context for RAG applications'
-      method_option :limit, type: :numeric, default: 5, aliases: '-l', desc: 'Maximum number of context chunks'
+      method_option :limit, type: :numeric, default: 10, aliases: '-l', desc: 'Maximum number of context chunks'
+      method_option :threshold, type: :numeric, desc: 'Similarity threshold (0.0-1.0, lower = more results)'
       def context(query)
         client = StandaloneClient.new
-        ctx = client.get_context(query, limit: options[:limit])
-        puts JSON.pretty_generate(ctx)
+        context_options = { limit: options[:limit] }
+        context_options[:threshold] = options[:threshold] if options[:threshold]
+        ctx = client.get_context(query, **context_options)
+        
+        # Check if no context was found and provide enhanced feedback
+        if ctx[:context_chunks].empty?
+          # Get the underlying search response for statistics
+          search_response = client.search(query, **context_options)
+          display_no_results_feedback(query, search_response, 'context')
+        else
+          puts JSON.pretty_generate(ctx)
+        end
       end
 
       desc 'enhance PROMPT', 'Enhance a prompt with context'
-      method_option :context_limit, type: :numeric, default: 5, aliases: '-l', desc: 'Number of context chunks to include'
+      method_option :limit, type: :numeric, default: 10, aliases: '-l', desc: 'Maximum number of context chunks to include'
+      method_option :threshold, type: :numeric, desc: 'Similarity threshold (0.0-1.0, lower = more results)'
       def enhance(prompt)
         client = StandaloneClient.new
-        enhanced = client.enhance_prompt(prompt, context_limit: options[:context_limit])
-        puts enhanced
+        enhance_options = { context_limit: options[:limit] }
+        enhance_options[:threshold] = options[:threshold] if options[:threshold]
+        enhanced = client.enhance_prompt(prompt, **enhance_options)
+        
+        # Check if no context was found and provide enhanced feedback
+        if enhanced[:context_count] == 0
+          # Get the underlying search response for statistics
+          search_response = client.search(prompt, limit: enhance_options[:context_limit], threshold: enhance_options[:threshold])
+          display_no_results_feedback(prompt, search_response, 'enhance')
+        else
+          puts enhanced[:enhanced_prompt]
+        end
+      end
+
+      desc 'search-history', 'Show recent search history'
+      method_option :limit, type: :numeric, default: 20, aliases: '-l',
+                            desc: 'Number of searches to show (default: 20)'
+      method_option :user_id, type: :string, aliases: '-u',
+                              desc: 'Filter by user ID'
+      method_option :session_id, type: :string, aliases: '-s',
+                                  desc: 'Filter by session ID'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json, plain)'
+      def search_history
+        analytics = Analytics.new
+        analytics.options = options
+        analytics.history
+      end
+
+      desc 'search-stats', 'Show detailed search analytics'
+      method_option :days, type: :numeric, default: 30, aliases: '-d',
+                           desc: 'Number of days to analyze (default: 30)'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json)'
+      def search_stats
+        analytics = Analytics.new
+        analytics.options = options
+        analytics.overview
       end
 
+      desc 'trending', 'Show trending search queries'
+      method_option :limit, type: :numeric, default: 10, aliases: '-l',
+                            desc: 'Number of queries to show (default: 10)'
+      method_option :days, type: :numeric, default: 7, aliases: '-d',
+                           desc: 'Time period in days (default: 7)'
+      method_option :format, type: :string, default: 'table', aliases: '-f',
+                             desc: 'Output format (table, json)'
+      def trending
+        analytics = Analytics.new
+        analytics.options = options
+        analytics.trending
+      end
+
+      desc 'cleanup-searches', 'Cleanup old search records'
+      method_option :days, type: :numeric, default: 30, aliases: '-d',
+                           desc: 'Remove searches older than N days (default: 30)'
+      method_option :dry_run, type: :boolean, default: true, aliases: '-n',
+                              desc: 'Show what would be deleted without actually deleting (default: true)'
+      method_option :force, type: :boolean, default: false, aliases: '-f',
+                            desc: 'Actually perform the cleanup (overrides dry_run)'
+      def cleanup_searches
+        analytics = Analytics.new
+        analytics.options = options
+        analytics.cleanup
+      end
 
       private
 
       def load_configuration
         ConfigurationLoader.new.load
       end
+
+      def display_no_results_feedback(query, search_response, command_type)
+        # Extract the actual results array from the response
+        results = search_response[:results] || search_response['results'] || []
+        
+        puts "No results found for '#{query}'"
+        puts
+        
+        # Get statistics for better feedback
+        statistics = search_response[:statistics] || search_response['statistics']
+        execution_time = search_response[:execution_time_ms] || search_response['execution_time_ms']
+        total = search_response[:total_results] || search_response['total_results'] || 0
+        
+        if statistics
+          threshold = statistics[:threshold_used] || statistics['threshold_used']
+          highest = statistics[:highest_similarity] || statistics['highest_similarity']
+          lowest = statistics[:lowest_similarity] || statistics['lowest_similarity']
+          average = statistics[:average_similarity] || statistics['average_similarity']
+          above_threshold = statistics[:similarities_above_threshold] || statistics['similarities_above_threshold']
+          total_checked = statistics[:total_embeddings_checked] || statistics['total_embeddings_checked']
+          
+          puts "Search Analysis:"
+          puts "  • Similarity threshold: #{threshold&.round(3) || 'N/A'}"
+          puts "  • Embeddings analyzed: #{total_checked || 0}"
+          if highest && lowest && average
+            puts "  • Similarity range: #{lowest.round(3)} - #{highest.round(3)} (avg: #{average.round(3)})"
+          end
+          puts "  • Results above threshold: #{above_threshold || 0}"
+          puts "  • Search time: #{execution_time || 0}ms"
+          puts
+          
+          # Provide actionable suggestions
+          if highest && threshold
+            if highest < threshold
+              suggested_threshold = (highest * 0.9).round(3)
+              puts "💡 Suggestions:"
+              puts "  • Lower the similarity threshold (highest found: #{highest.round(3)})"
+              puts "  • Try: ragdoll #{command_type} '#{query}' --threshold=#{suggested_threshold}"
+              if highest < 0.3
+                puts "  • Your query might not match the document content well"
+                puts "  • Try different or more specific search terms"
+              end
+            elsif above_threshold > 0
+              puts "💡 Note: Found #{above_threshold} similar content above threshold #{threshold}"
+              puts "  This suggests an issue with result processing."
+            end
+          end
+        else
+          puts "No similarity statistics available."
+          puts "💡 Try lowering the similarity threshold with --threshold=0.5"
+        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,182 @@
 --- !ruby/object:Gem::Specification
 name: ragdoll-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Dewayne VanHoozer
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ragdoll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug_me
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: undercover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Under development.  Contributors welcome.
 email:
 - dvanhoozer@gmail.com
@@ -21,6 +189,7 @@ files:
 - Rakefile
 - bin/ragdoll
 - lib/ragdoll/cli.rb
+- lib/ragdoll/cli/commands/analytics.rb
 - lib/ragdoll/cli/commands/config.rb
 - lib/ragdoll/cli/commands/delete.rb
 - lib/ragdoll/cli/commands/health.rb