ragnar-cli 0.1.0.pre.1

data/lib/ragnar/topic_modeling/labeling_strategies.rb

@@ -0,0 +1,300 @@
+# Separate strategy classes for different labeling approaches
+module Ragnar
+  module TopicModeling
+    module LabelingStrategies
+      
+      # Base strategy class
+      class Base
+        def generate_label(topic:, terms:, documents:)
+          raise NotImplementedError, "Subclasses must implement generate_label"
+        end
+        
+        protected
+        
+        def select_representative_docs(documents, k: 3)
+          return documents if documents.length <= k
+          
+          # For now, just take first k
+          # Could be improved to select most central docs
+          documents.first(k)
+        end
+        
+        def capitalize_phrase(phrase)
+          phrase.split(/[\s_-]/).map(&:capitalize).join(' ')
+        end
+      end
+      
+      # Fast term-based labeling using c-TF-IDF terms
+      class TermBased < Base
+        def generate_label(topic:, terms:, documents:)
+          return { label: "Empty Topic", description: "No terms found" } if terms.empty?
+          
+          # Take top distinctive terms
+          label_terms = terms.first(3).select { |t| t.length > 3 }
+          
+          label = if label_terms.length >= 2
+            "#{capitalize_phrase(label_terms[0])} & #{capitalize_phrase(label_terms[1])}"
+          else
+            capitalize_phrase(label_terms.first || terms.first)
+          end
+          
+          {
+            label: label,
+            description: "Documents about #{terms.first(5).join(', ')}",
+            method: :term_based,
+            confidence: calculate_confidence(terms)
+          }
+        end
+        
+        private
+        
+        def calculate_confidence(terms)
+          # Simple heuristic: more distinctive terms = higher confidence
+          return 0.0 if terms.empty?
+          
+          # Assume terms come with scores if available
+          if terms.is_a?(Array) && terms.first.is_a?(Array)
+            # Terms are [word, score] pairs
+            avg_score = terms.first(5).map(&:last).sum / 5.0
+            [avg_score, 1.0].min
+          else
+            # Just have terms, use count as proxy
+            [terms.length / 20.0, 1.0].min
+          end
+        end
+      end
+      
+      # Quality LLM-based labeling
+      class LLMBased < Base
+        def initialize(llm_client: nil)
+          @llm_client = llm_client
+        end
+        
+        def generate_label(topic:, terms:, documents:)
+          unless llm_available?
+            # Fallback to term-based if LLM not available
+            return TermBased.new.generate_label(topic: topic, terms: terms, documents: documents)
+          end
+          
+          # Select best documents to send to LLM
+          sample_docs = select_representative_docs(documents, k: 3)
+          
+          # Generate comprehensive analysis
+          response = analyze_with_llm(sample_docs, terms)
+          
+          {
+            label: response[:label],
+            description: response[:description],
+            themes: response[:themes],
+            method: :llm_based,
+            confidence: response[:confidence] || 0.8
+          }
+        rescue => e
+          # Fallback on error
+          puts "LLM labeling failed: #{e.message}" if ENV['DEBUG']
+          TermBased.new.generate_label(topic: topic, terms: terms, documents: documents)
+        end
+        
+        private
+        
+        def llm_available?
+          return true if @llm_client
+          
+          # Try to create LLM adapter
+          begin
+            require_relative 'llm_adapter'
+            @llm_client = LLMAdapter.create(type: :auto)
+            @llm_client && @llm_client.available?
+          rescue LoadError, StandardError => e
+            puts "LLM not available: #{e.message}" if ENV['DEBUG']
+            false
+          end
+        end
+        
+        def analyze_with_llm(documents, terms)
+          prompt = build_analysis_prompt(documents, terms)
+          
+          response = @llm_client.generate(
+            prompt: prompt,
+            max_tokens: 150,
+            temperature: 0.3,
+            response_format: { type: "json_object" }
+          )
+          
+          # Parse JSON response
+          result = JSON.parse(response, symbolize_names: true)
+          
+          # Validate and clean
+          {
+            label: clean_label(result[:label]),
+            description: result[:description] || "Topic about #{result[:label]}",
+            themes: result[:themes] || [],
+            confidence: result[:confidence] || 0.8
+          }
+        end
+        
+        def build_analysis_prompt(documents, terms)
+          doc_samples = documents.map.with_index do |doc, i|
+            preview = doc.length > 300 ? "#{doc[0..300]}..." : doc
+            "Document #{i + 1}:\n#{preview}"
+          end.join("\n\n")
+          
+          <<~PROMPT
+            Analyze this cluster of related documents and provide a structured summary.
+            
+            Distinctive terms found: #{terms.first(10).join(', ')}
+            
+            Sample documents:
+            #{doc_samples}
+            
+            Provide a JSON response with:
+            {
+              "label": "A 2-4 word topic label",
+              "description": "One sentence describing what connects these documents",
+              "themes": ["theme1", "theme2", "theme3"],
+              "confidence": 0.0-1.0 score of how coherent this topic is
+            }
+            
+            Focus on what meaningfully connects these documents, not just common words.
+          PROMPT
+        end
+        
+        def clean_label(label)
+          return "Unknown Topic" unless label
+          
+          # Remove quotes, trim, limit length
+          cleaned = label.to_s.strip.gsub(/^["']|["']$/, '')
+          cleaned = cleaned.split("\n").first if cleaned.include?("\n")
+          
+          # Limit to reasonable length
+          if cleaned.length > 50
+            cleaned[0..47] + "..."
+          else
+            cleaned
+          end
+        end
+      end
+      
+      # Hybrid approach - uses terms to guide LLM for efficiency
+      class Hybrid < Base
+        def initialize(llm_client: nil)
+          @llm_client = llm_client
+          @term_strategy = TermBased.new
+        end
+        
+        def generate_label(topic:, terms:, documents:)
+          # Start with term-based analysis
+          term_result = @term_strategy.generate_label(
+            topic: topic, 
+            terms: terms, 
+            documents: documents
+          )
+          
+          # If no LLM available, return term-based result
+          unless llm_available?
+            return term_result.merge(method: :hybrid_fallback)
+          end
+          
+          # Enhance with focused LLM call
+          enhanced = enhance_with_llm(term_result, terms, documents)
+          
+          {
+            label: enhanced[:label] || term_result[:label],
+            description: enhanced[:description] || term_result[:description],
+            method: :hybrid,
+            confidence: (term_result[:confidence] + (enhanced[:confidence] || 0.5)) / 2,
+            term_label: term_result[:label],  # Keep original for comparison
+            themes: enhanced[:themes]
+          }
+        rescue => e
+          # Fallback to term-based
+          puts "Hybrid enhancement failed: #{e.message}" if ENV['DEBUG']
+          term_result.merge(method: :hybrid_fallback)
+        end
+        
+        private
+        
+        def llm_available?
+          return true if @llm_client
+          
+          begin
+            require_relative 'llm_adapter'
+            @llm_client = LLMAdapter.create(type: :auto)
+            @llm_client && @llm_client.available?
+          rescue LoadError, StandardError => e
+            puts "LLM not available for hybrid: #{e.message}" if ENV['DEBUG']
+            false
+          end
+        end
+        
+        def enhance_with_llm(term_result, terms, documents)
+          # Lighter-weight prompt using term analysis as starting point
+          prompt = build_enhancement_prompt(term_result[:label], terms, documents.first)
+          
+          response = @llm_client.generate(
+            prompt: prompt,
+            max_tokens: 100,
+            temperature: 0.3
+          )
+          
+          # Parse response (simpler format for speed)
+          parse_enhancement_response(response)
+        end
+        
+        def build_enhancement_prompt(term_label, terms, sample_doc)
+          doc_preview = sample_doc.length > 200 ? "#{sample_doc[0..200]}..." : sample_doc
+          
+          <<~PROMPT
+            Current topic label based on terms: "#{term_label}"
+            Key terms: #{terms.first(8).join(', ')}
+            
+            Sample document:
+            #{doc_preview}
+            
+            Provide a better topic label if possible (2-4 words), or confirm the current one.
+            Also provide a one-sentence description.
+            
+            Format:
+            Label: [your label]
+            Description: [one sentence]
+            Themes: [comma-separated list]
+          PROMPT
+        end
+        
+        def parse_enhancement_response(response)
+          result = {}
+          
+          # Simple line-based parsing
+          response.lines.each do |line|
+            if line.start_with?("Label:")
+              result[:label] = line.sub("Label:", "").strip
+            elsif line.start_with?("Description:")
+              result[:description] = line.sub("Description:", "").strip
+            elsif line.start_with?("Themes:")
+              themes_str = line.sub("Themes:", "").strip
+              result[:themes] = themes_str.split(",").map(&:strip)
+            end
+          end
+          
+          result[:confidence] = result[:label] ? 0.7 : 0.3
+          result
+        end
+      end
+      
+      # Factory method to get appropriate strategy
+      def self.create(method, llm_client: nil)
+        case method.to_sym
+        when :fast, :term_based, :terms
+          TermBased.new
+        when :quality, :llm_based, :llm
+          LLMBased.new(llm_client: llm_client)
+        when :hybrid, :auto, :smart
+          Hybrid.new(llm_client: llm_client)
+        else
+          # Default to hybrid
+          Hybrid.new(llm_client: llm_client)
+        end
+      end
+    end
+  end
+end

data/lib/ragnar/topic_modeling/llm_adapter.rb

@@ -0,0 +1,131 @@
+# Adapter to allow different LLM backends (red-candle, remote APIs, etc.)
+module Ragnar
+  module TopicModeling
+    class LLMAdapter
+      # Factory method to create appropriate LLM client
+      def self.create(type: :auto, **options)
+        case type
+        when :red_candle
+          RedCandleAdapter.new(**options)
+        when :openai
+          # Future: OpenAIAdapter.new(**options)
+          raise NotImplementedError, "OpenAI adapter not yet implemented"
+        when :anthropic
+          # Future: AnthropicAdapter.new(**options)
+          raise NotImplementedError, "Anthropic adapter not yet implemented"
+        when :auto
+          # Try red-candle first, then fall back to others
+          begin
+            RedCandleAdapter.new(**options)
+          rescue LoadError
+            nil  # No LLM available
+          end
+        else
+          raise ArgumentError, "Unknown LLM type: #{type}"
+        end
+      end
+    end
+    
+    # Adapter for red-candle (local LLMs)
+    class RedCandleAdapter
+      def initialize(model: nil, **options)
+        require 'candle'
+        
+        @model = model || default_model
+        @options = options
+        @llm = load_or_create_llm
+      end
+      
+      def generate(prompt:, max_tokens: 100, temperature: 0.3, response_format: nil)
+        # Red-candle specific generation
+        response = @llm.generate(
+          prompt,
+          max_length: max_tokens,
+          temperature: temperature,
+          do_sample: temperature > 0
+        )
+        
+        # Handle JSON response format if requested
+        if response_format && response_format[:type] == "json_object"
+          ensure_json_response(response)
+        else
+          response
+        end
+      end
+      
+      def available?
+        true
+      end
+      
+      private
+      
+      def default_model
+        # Use a small, fast model by default for topic labeling
+        "TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF"
+      end
+      
+      def load_or_create_llm
+        # Check if already loaded in ruby-rag
+        if defined?(Ragnar::LLMManager)
+          begin
+            return Ragnar::LLMManager.instance.get_llm(@model)
+          rescue
+            # Fall through to create new
+          end
+        end
+        
+        # Create new LLM instance
+        Candle::Model.new(
+          model_id: @model,
+          model_type: :llama,
+          quantized: true
+        )
+      end
+      
+      def ensure_json_response(response)
+        # Try to extract JSON from response
+        begin
+          # Look for JSON-like content
+          json_match = response.match(/\{.*\}/m)
+          if json_match
+            JSON.parse(json_match[0])
+            json_match[0]  # Return the JSON string if valid
+          else
+            # Generate a basic JSON response
+            generate_fallback_json(response)
+          end
+        rescue JSON::ParserError
+          generate_fallback_json(response)
+        end
+      end
+      
+      def generate_fallback_json(text)
+        # Create a simple JSON from text response
+        label = text.lines.first&.strip || "Unknown"
+        {
+          label: label,
+          description: text,
+          confidence: 0.5
+        }.to_json
+      end
+    end
+    
+    # Future adapter for remote LLMs
+    class RemoteAdapter
+      def initialize(api_key:, endpoint:, **options)
+        @api_key = api_key
+        @endpoint = endpoint
+        @options = options
+      end
+      
+      def generate(prompt:, max_tokens: 100, temperature: 0.3, response_format: nil)
+        # Make API call
+        raise NotImplementedError, "Remote LLM adapter coming soon"
+      end
+      
+      def available?
+        !@api_key.nil?
+      end
+    end
+  end
+end

data/lib/ragnar/topic_modeling/metrics.rb

@@ -0,0 +1,186 @@
+module Ragnar
+  module TopicModeling
+    module Metrics
+      extend self
+      
+      # Compute UMass Coherence for topic quality
+      # Higher coherence = more interpretable topic
+      def compute_coherence(terms, documents, top_n: 10)
+        return 0.0 if terms.empty? || documents.empty?
+        
+        # Use top N terms
+        eval_terms = terms.first(top_n)
+        return 0.0 if eval_terms.length < 2
+        
+        # Create document term matrix for co-occurrence
+        doc_term_counts = count_cooccurrences(eval_terms, documents)
+        
+        # Compute UMass coherence
+        coherence_sum = 0.0
+        pairs_count = 0
+        
+        eval_terms.each_with_index do |term_i, i|
+          eval_terms.each_with_index do |term_j, j|
+            next unless j < i  # Only upper triangle
+            
+            # P(term_i, term_j) = co-occurrence count
+            cooccur = doc_term_counts["#{term_i},#{term_j}"] || 0
+            # P(term_j) = document frequency
+            doc_freq_j = doc_term_counts[term_j] || 0
+            
+            if cooccur > 0 && doc_freq_j > 0
+              # UMass: log((cooccur + 1) / doc_freq_j)
+              coherence_sum += Math.log((cooccur + 1.0) / doc_freq_j)
+              pairs_count += 1
+            end
+          end
+        end
+        
+        return 0.0 if pairs_count == 0
+        
+        # Normalize by number of pairs
+        coherence = coherence_sum / pairs_count
+        
+        # Transform to 0-1 range (coherence is typically negative)
+        # More negative = less coherent, so we reverse and bound
+        normalized = 1.0 / (1.0 + Math.exp(-coherence))
+        normalized
+      end
+      
+      # Compute how distinct a topic is from others
+      def compute_distinctiveness(topic, other_topics)
+        return 1.0 if other_topics.empty?
+        
+        topic_terms = Set.new(topic.terms.first(20))
+        
+        # Compare with other topics
+        overlaps = other_topics.map do |other|
+          next if other.id == topic.id
+          
+          other_terms = Set.new(other.terms.first(20))
+          overlap = (topic_terms & other_terms).size.to_f
+          
+          # Jaccard similarity
+          union_size = (topic_terms | other_terms).size
+          union_size > 0 ? overlap / union_size : 0
+        end.compact
+        
+        return 1.0 if overlaps.empty?
+        
+        # Distinctiveness = 1 - average overlap
+        1.0 - (overlaps.sum / overlaps.length)
+      end
+      
+      # Compute diversity across all topics
+      def compute_diversity(topics)
+        return 0.0 if topics.length < 2
+        
+        # Collect all term sets
+        term_sets = topics.map { |t| Set.new(t.terms.first(20)) }
+        
+        # Compute pairwise Jaccard distances
+        distances = []
+        term_sets.each_with_index do |set_i, i|
+          term_sets.each_with_index do |set_j, j|
+            next unless j > i  # Only upper triangle
+            
+            intersection = (set_i & set_j).size.to_f
+            union = (set_i | set_j).size.to_f
+            
+            # Jaccard distance = 1 - Jaccard similarity
+            distance = union > 0 ? 1.0 - (intersection / union) : 1.0
+            distances << distance
+          end
+        end
+        
+        # Average distance = diversity
+        distances.sum / distances.length
+      end
+      
+      # Compute coverage (what fraction of docs are in topics vs outliers)
+      def compute_coverage(topics, total_documents)
+        return 0.0 if total_documents == 0
+        
+        docs_in_topics = topics.sum(&:size)
+        docs_in_topics.to_f / total_documents
+      end
+      
+      # Silhouette score for cluster quality
+      def compute_silhouette_score(topic, all_topics, embeddings)
+        return 0.0 if topic.embeddings.empty?
+        
+        silhouettes = []
+        
+        topic.embeddings.each_with_index do |embedding, idx|
+          # a(i) = average distance to other points in same cluster
+          if topic.embeddings.length > 1
+            a_i = topic.embeddings.each_with_index
+                      .reject { |_, j| j == idx }
+                      .map { |other, _| euclidean_distance(embedding, other) }
+                      .sum.to_f / (topic.embeddings.length - 1)
+          else
+            a_i = 0.0
+          end
+          
+          # b(i) = minimum average distance to points in other clusters
+          b_values = all_topics.reject { |t| t.id == topic.id }.map do |other_topic|
+            next if other_topic.embeddings.empty?
+            
+            avg_dist = other_topic.embeddings
+                                 .map { |other| euclidean_distance(embedding, other) }
+                                 .sum.to_f / other_topic.embeddings.length
+            avg_dist
+          end.compact
+          
+          b_i = b_values.min || a_i
+          
+          # Silhouette coefficient
+          if a_i == 0 && b_i == 0
+            s_i = 0
+          else
+            s_i = (b_i - a_i) / [a_i, b_i].max
+          end
+          
+          silhouettes << s_i
+        end
+        
+        # Average silhouette score for topic
+        silhouettes.sum / silhouettes.length
+      end
+      
+      private
+      
+      def count_cooccurrences(terms, documents)
+        counts = Hash.new(0)
+        
+        documents.each do |doc|
+          doc_lower = doc.downcase
+          
+          # Count individual term occurrences
+          terms.each do |term|
+            counts[term] += 1 if doc_lower.include?(term.downcase)
+          end
+          
+          # Count co-occurrences
+          terms.each_with_index do |term_i, i|
+            terms.each_with_index do |term_j, j|
+              next unless j < i
+              
+              if doc_lower.include?(term_i.downcase) && doc_lower.include?(term_j.downcase)
+                counts["#{term_i},#{term_j}"] += 1
+              end
+            end
+          end
+        end
+        
+        counts
+      end
+      
+      def euclidean_distance(vec1, vec2)
+        Math.sqrt(
+          vec1.zip(vec2).map { |a, b| (a - b) ** 2 }.sum
+        )
+      end
+    end
+  end
+end