no measurement info (#24)

Author: mensfeld

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.9.0 (2025-10-17)
+- [Feature] **No AI Version Detection** - The `compare` command now detects when websites don't serve AI-optimized versions.
+  - Triggers when reduction is <5% (nearly identical content for human and AI User-Agents)
+  - Displays prominent warning: "WARNING: NO DEDICATED AI VERSION DETECTED"
+  - Shows potential savings estimates based on typical 83% reduction rate
+  - Provides page-specific calculations (estimated token savings, potential size)
+  - Includes implementation guide with actionable steps
+  - Helps identify opportunities to optimize documentation
+- [Enhancement] Updated `OutputFormatter#display_comparison_results` to include marketing message for unoptimized sites.
+- [Enhancement] Added utility script `probe_karafka_simple.rb` for batch comparison testing.
+
 ## 0.8.2 (2025-10-17)
 - [Fix] Fixed Docker workflow test to properly invoke help command (use `generate --help` instead of `--help`).
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    llm-docs-builder (0.8.2)
+    llm-docs-builder (0.9.0)
       zeitwerk (~> 2.6)
 
 GEM

README.md

@@ -442,10 +442,6 @@ generate_toc: true
 normalize_whitespace: true
 ```
 
-## Contributing
-
-Bug reports and pull requests welcome at [github.com/mensfeld/llm-docs-builder](https://github.com/mensfeld/llm-docs-builder).
-
 ## License
 
 Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

lib/llm_docs_builder/output_formatter.rb

@@ -8,6 +8,8 @@ module LlmDocsBuilder
   #
   # @api private
   class OutputFormatter
+    # Threshold percentage below which we consider there's no AI-optimized version
+    NO_AI_VERSION_THRESHOLD = 5
     # Format bytes into human-readable string
     #
     # @param bytes [Integer] number of bytes
@@ -56,10 +58,16 @@ def self.display_comparison_results(result)
 
       if result[:reduction_bytes].positive?
         display_reduction(result)
+
+        # Detect if there's no dedicated AI version
+        if result[:reduction_percent] < NO_AI_VERSION_THRESHOLD
+          display_no_ai_version_message(result)
+        end
       elsif result[:reduction_bytes].negative?
         display_increase(result)
       else
         puts 'Same size'
+        display_no_ai_version_message(result)
       end
 
       puts '=' * 60
@@ -89,5 +97,43 @@ def self.display_increase(result)
       puts "Token increase: #{format_number(token_increase)} tokens (#{token_increase_percent}%)"
       puts "Factor:         #{result[:factor]}x larger"
     end
+
+    # Display message when no dedicated AI version is detected
+    #
+    # @param result [Hash] comparison results
+    # @api private
+    def self.display_no_ai_version_message(result)
+      puts ''
+      puts 'WARNING: NO DEDICATED AI VERSION DETECTED'
+      puts ''
+      puts 'The server is returning nearly identical content to both human and AI'
+      puts 'User-Agents, indicating no AI-optimized version is currently served.'
+      puts ''
+      puts 'POTENTIAL SAVINGS WITH AI OPTIMIZATION:'
+      puts ''
+      puts 'Based on typical documentation optimization results, you could expect:'
+      puts '  • 67-95% token reduction (average 83%)'
+      puts '  • 3-20x smaller file sizes'
+      puts '  • Faster LLM processing times'
+      puts '  • Reduced API costs for AI queries'
+      puts '  • Improved response accuracy'
+      puts ''
+      puts "For this page specifically (~#{format_number(result[:human_tokens])} tokens):"
+      puts "  • Estimated savings: ~#{format_number((result[:human_tokens] * 0.83).round)} tokens (83% reduction)"
+      puts "  • Could reduce to: ~#{format_number((result[:human_tokens] * 0.17).round)} tokens"
+      puts "  • Potential size: ~#{format_bytes((result[:human_size] * 0.17).round)}"
+      puts ''
+      puts 'HOW TO IMPLEMENT AI-OPTIMIZED DOCUMENTATION:'
+      puts ''
+      puts '1. Transform your docs with llm-docs-builder:'
+      puts '   llm-docs-builder bulk-transform --docs ./docs --config llm-docs-builder.yml'
+      puts ''
+      puts '2. Configure your web server to serve .md files to AI bots:'
+      puts '   See: https://github.com/mensfeld/llm-docs-builder#serving-optimized-docs'
+      puts ''
+      puts '3. Measure your actual savings:'
+      puts '   llm-docs-builder compare --url <your-url> --file <local-md>'
+      puts ''
+    end
   end
 end

lib/llm_docs_builder/version.rb

@@ -2,5 +2,5 @@
 
 module LlmDocsBuilder
   # Current version of the LlmDocsBuilder gem
-  VERSION = '0.8.2'
+  VERSION = '0.9.0'
 end

spec/output_formatter_spec.rb

@@ -92,5 +92,85 @@
         described_class.display_comparison_results(result)
       end.to output(/Same size/).to_stdout
     end
+
+    it 'displays no AI version warning when reduction is less than 5%' do
+      result = {
+        human_size: 1000,
+        ai_size: 960,
+        reduction_bytes: 40,
+        reduction_percent: 4,
+        factor: 1.04,
+        human_tokens: 250,
+        ai_tokens: 240,
+        token_reduction: 10,
+        token_reduction_percent: 4,
+        human_source: 'https://example.com (User-Agent: human)',
+        ai_source: 'https://example.com (User-Agent: AI)'
+      }
+
+      output = capture_stdout do
+        described_class.display_comparison_results(result)
+      end
+
+      expect(output).to include('WARNING: NO DEDICATED AI VERSION DETECTED')
+      expect(output).to include('POTENTIAL SAVINGS WITH AI OPTIMIZATION')
+      expect(output).to include('67-95% token reduction (average 83%)')
+      expect(output).to include('For this page specifically (~250 tokens)')
+    end
+
+    it 'displays no AI version warning when sizes are exactly equal' do
+      result = {
+        human_size: 1000,
+        ai_size: 1000,
+        reduction_bytes: 0,
+        reduction_percent: 0,
+        factor: 1.0,
+        human_tokens: 250,
+        ai_tokens: 250,
+        token_reduction: 0,
+        token_reduction_percent: 0,
+        human_source: 'https://example.com (User-Agent: human)',
+        ai_source: 'https://example.com (User-Agent: AI)'
+      }
+
+      output = capture_stdout do
+        described_class.display_comparison_results(result)
+      end
+
+      expect(output).to include('WARNING: NO DEDICATED AI VERSION DETECTED')
+      expect(output).to include('POTENTIAL SAVINGS WITH AI OPTIMIZATION')
+    end
+
+    it 'does not display no AI version warning when reduction is 5% or more' do
+      result = {
+        human_size: 1000,
+        ai_size: 950,
+        reduction_bytes: 50,
+        reduction_percent: 5,
+        factor: 1.05,
+        human_tokens: 250,
+        ai_tokens: 237,
+        token_reduction: 13,
+        token_reduction_percent: 5,
+        human_source: 'https://example.com (User-Agent: human)',
+        ai_source: 'https://example.com (User-Agent: AI)'
+      }
+
+      output = capture_stdout do
+        described_class.display_comparison_results(result)
+      end
+
+      expect(output).not_to include('WARNING: NO DEDICATED AI VERSION DETECTED')
+      expect(output).to include('Reduction:')
+    end
+  end
+
+  def capture_stdout
+    original_stdout = $stdout
+    $stdout = StringIO.new
+    yield
+    $stdout.string
+  ensure
+    $stdout = original_stdout
   end
 end