sentiment_insights 0.1.0

data/lib/sentiment_insights/insights/key_phrases.rb

@@ -0,0 +1,80 @@
+require_relative '../clients/key_phrases/open_ai_client'
+require_relative '../clients/key_phrases/aws_client'
+
+module SentimentInsights
+  module Insights
+    # Extracts and summarizes key phrases from survey responses
+    class KeyPhrases
+      def initialize(provider: nil, provider_client: nil)
+        effective_provider = provider || SentimentInsights.configuration&.provider || :sentimental
+
+        @provider_client = provider_client || case effective_provider
+                                              when :openai
+                                                Clients::KeyPhrases::OpenAIClient.new
+                                              when :aws
+                                                Clients::KeyPhrases::AwsClient.new
+                                              when :sentimental
+                                                raise NotImplementedError, "Key phrase extraction is not supported for the 'sentimental' provider"
+                                              else
+                                                raise ArgumentError, "Unsupported provider: #{effective_provider}"
+                                              end
+      end
+
+      # Extract key phrases and build a normalized, summarized output
+      # @param entries [Array<Hash>] each with :answer and optional :segment
+      # @param question [String, nil] optional context
+      # @return [Hash] { phrases: [...], responses: [...] }
+      def extract(entries, question: nil)
+        entries = entries.to_a
+        raw_result = @provider_client.extract_batch(entries, question: question)
+
+        responses = raw_result[:responses] || []
+        phrases  = raw_result[:phrases] || []
+        puts "phrases = #{phrases}"
+
+        puts "responses = #{responses}"
+        # Index responses by id for lookup
+        response_index = {}
+        responses.each do |r|
+          response_index[r[:id]] = r
+        end
+
+        enriched_phrases = phrases.map do |phrase_entry|
+          mentions = phrase_entry[:mentions] || []
+          mention_responses = mentions.map { |id| response_index[id] }.compact
+
+          sentiment_dist = Hash.new(0)
+          segment_dist = Hash.new { |h, k| h[k] = Hash.new(0) }
+
+          mention_responses.each do |resp|
+            sentiment = resp[:sentiment] || :neutral
+            sentiment_dist[sentiment] += 1
+
+            (resp[:segment] || {}).each do |seg_key, seg_val|
+              segment_dist[seg_key][seg_val] += 1
+            end
+          end
+
+          {
+            phrase: phrase_entry[:phrase],
+            mentions: mentions,
+            summary: {
+              total_mentions: mentions.size,
+              sentiment_distribution: {
+                positive: sentiment_dist[:positive],
+                negative: sentiment_dist[:negative],
+                neutral:  sentiment_dist[:neutral]
+              },
+              segment_distribution: segment_dist
+            }
+          }
+        end
+
+        {
+          phrases: enriched_phrases,
+          responses: responses
+        }
+      end
+    end
+  end
+end

data/lib/sentiment_insights/insights/sentiment.rb

@@ -0,0 +1,152 @@
+require_relative '../clients/sentiment/open_ai_client'
+require_relative '../clients/sentiment/sentimental_client'
+
+module SentimentInsights
+  module Insights
+    # Analyzes sentiment of survey responses and produces summarized insights.
+    class Sentiment
+      DEFAULT_TOP_COUNT = 5
+
+      # Initialize with a specified provider or a concrete provider client.
+      # If no provider is given, default to the Sentimental (local) provider.
+      def initialize(provider: nil, provider_client: nil, top_count: DEFAULT_TOP_COUNT)
+        effective_provider = provider || SentimentInsights.configuration&.provider || :sentimental
+        @provider_client = provider_client || case effective_provider
+                                              when :openai
+                                                Clients::Sentiment::OpenAIClient.new
+                                              when :aws
+                                                require_relative '../clients/sentiment/aws_comprehend_client'
+                                                Clients::Sentiment::AwsComprehendClient.new
+                                              else
+                                                Clients::Sentiment::SentimentalClient.new
+                                              end
+        @top_count = top_count
+      end
+
+      # Analyze a batch of entries and return sentiment insights.
+      # @param entries [Array<Hash>] An array of response hashes, each with :answer and :segment.
+      # @param question [String, nil] Optional global question text or metadata for context.
+      # @return [Hash] Summary of sentiment analysis (global, segment-wise, top comments, and annotated responses).
+      def analyze(entries, question: nil)
+        # Ensure entries is an array of hashes with required keys
+        entries = entries.to_a
+        # Get sentiment results for each entry from the provider client
+        results = @provider_client.analyze_entries(entries, question: question)
+
+        # Combine original entries with sentiment results
+        annotated_responses = entries.each_with_index.map do |entry, idx|
+          res = results[idx] || {}
+          {
+            answer:  entry[:answer],
+            segment: entry[:segment] || {},
+            sentiment_label: res[:label],
+            sentiment_score: res[:score]
+          }
+        end
+
+        global_summary = prepare_global_summary(annotated_responses)
+        segment_summary = prepare_segment_summary(annotated_responses)
+
+        top_positive_comments, top_negative_comments = top_comments(annotated_responses)
+
+        # Assemble the result hash
+        {
+          global_summary:       global_summary,
+          segment_summary:      segment_summary,
+          top_positive_comments: top_positive_comments,
+          top_negative_comments: top_negative_comments,
+          responses:            annotated_responses
+        }
+      end
+
+      private
+
+      def prepare_global_summary(annotated_responses)
+        # Global sentiment counts
+        total_count    = annotated_responses.size
+        positive_count = annotated_responses.count { |r| r[:sentiment_label] == :positive }
+        negative_count = annotated_responses.count { |r| r[:sentiment_label] == :negative }
+        neutral_count  = annotated_responses.count { |r| r[:sentiment_label] == :neutral }
+
+        # Global percentages (avoid division by zero)
+        positive_pct = total_count > 0 ? (positive_count.to_f * 100.0 / total_count) : 0.0
+        negative_pct = total_count > 0 ? (negative_count.to_f * 100.0 / total_count) : 0.0
+        neutral_pct  = total_count > 0 ? (neutral_count.to_f * 100.0 / total_count) : 0.0
+
+        # Net sentiment score = positive% - negative%
+        net_sentiment = positive_pct - negative_pct
+
+        {
+          total_count:         total_count,
+          positive_count:      positive_count,
+          neutral_count:       neutral_count,
+          negative_count:      negative_count,
+          positive_percentage: positive_pct,
+          neutral_percentage:  neutral_pct,
+          negative_percentage: negative_pct,
+          net_sentiment_score: net_sentiment
+        }
+      end
+
+      def prepare_segment_summary(annotated_responses)
+        # Per-segment sentiment summary (for each segment attribute and value)
+        segment_summary = {}
+        annotated_responses.each do |resp|
+          resp[:segment].each do |seg_key, seg_val|
+            segment_summary[seg_key] ||= {}
+            segment_summary[seg_key][seg_val] ||= {
+              total_count:         0,
+              positive_count:      0,
+              neutral_count:       0,
+              negative_count:      0,
+              positive_percentage: 0.0,
+              neutral_percentage:  0.0,
+              negative_percentage: 0.0,
+              net_sentiment_score: 0.0
+            }
+            group = segment_summary[seg_key][seg_val]
+            # Increment counts per sentiment
+            group[:total_count] += 1
+            case resp[:sentiment_label]
+            when :positive then group[:positive_count] += 1
+            when :neutral  then group[:neutral_count]  += 1
+            when :negative then group[:negative_count] += 1
+            end
+          end
+        end
+
+        # Compute percentages and net sentiment for each segment group
+        segment_summary.each do |_, groups|
+          groups.each do |_, stats|
+            total = stats[:total_count]
+            if total > 0
+              stats[:positive_percentage] = (stats[:positive_count].to_f * 100.0 / total)
+              stats[:neutral_percentage]  = (stats[:neutral_count].to_f * 100.0 / total)
+              stats[:negative_percentage] = (stats[:negative_count].to_f * 100.0 / total)
+              stats[:net_sentiment_score] = stats[:positive_percentage] - stats[:negative_percentage]
+            else
+              stats[:positive_percentage] = stats[:neutral_percentage] = stats[:negative_percentage] = 0.0
+              stats[:net_sentiment_score] = 0.0
+            end
+          end
+        end
+      end
+
+      # Identify top N positive and negative responses by score
+      def top_comments(annotated_responses)
+        top_positive = annotated_responses.select { |r| r[:sentiment_label] == :positive }
+        top_positive.sort_by! { |r| -r[:sentiment_score].to_f }  # descending by score (if all 1.0, order remains as is)
+        top_negative = annotated_responses.select { |r| r[:sentiment_label] == :negative }
+        top_negative.sort_by! { |r| r[:sentiment_score].to_f }   # ascending by score (more negative first, since score is -1.0)
+
+        top_positive_comments = top_positive.first(@top_count).map do |r|
+          { answer: r[:answer], score: r[:sentiment_score] }
+        end
+        top_negative_comments = top_negative.first(@top_count).map do |r|
+          { answer: r[:answer], score: r[:sentiment_score] }
+        end
+        [top_positive_comments, top_negative_comments]
+      end
+    end
+  end
+end

data/lib/sentiment_insights/version.rb

@@ -0,0 +1,3 @@
+module SentimentInsights
+  VERSION = "0.1.0"
+end

data/lib/sentiment_insights.rb

@@ -0,0 +1,15 @@
+require "sentiment_insights/configuration"
+require "sentiment_insights/analyzer"
+require "sentiment_insights/insights/sentiment"
+
+module SentimentInsights
+  class Error < StandardError; end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+end

data/sentiment_insights.gemspec

@@ -0,0 +1,42 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "sentiment_insights/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "sentiment_insights"
+  spec.version       = SentimentInsights::VERSION
+  spec.authors       = ["mathrailsAI"]
+  spec.email         = ["mathrails@gmail.com"]
+
+  spec.summary       = "Analyze and extract sentiment insights from text data easily."
+  spec.description   = "SentimentInsights is a Ruby gem that helps analyze sentiment from survey responses, feedback, and other text sources. Built for developers who need quick and actionable sentiment extraction."
+
+  spec.homepage      = "https://github.com/mathrailsAI/sentiment_insights"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/mathrailsAI/sentiment_insights"
+    spec.metadata["changelog_uri"] = "https://github.com/mathrailsAI/sentiment_insights/blob/main/CHANGELOG.md"
+    # Removed allowed_push_host — usually not needed unless you have a private server
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "sentimental", "~> 1.4.0"
+  spec.add_dependency "aws-sdk-comprehend", "~> 1.98.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "dotenv", "~> 2.8"
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: sentiment_insights
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mathrailsAI
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sentimental
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-comprehend
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.98.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.98.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: SentimentInsights is a Ruby gem that helps analyze sentiment from survey
+  responses, feedback, and other text sources. Built for developers who need quick
+  and actionable sentiment extraction.
+email:
+- mathrails@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/sentiment_insights.rb
+- lib/sentiment_insights/analyzer.rb
+- lib/sentiment_insights/clients/entities/aws_client.rb
+- lib/sentiment_insights/clients/entities/open_ai_client.rb
+- lib/sentiment_insights/clients/key_phrases/aws_client.rb
+- lib/sentiment_insights/clients/key_phrases/open_ai_client.rb
+- lib/sentiment_insights/clients/sentiment/aws_comprehend_client.rb
+- lib/sentiment_insights/clients/sentiment/open_ai_client.rb
+- lib/sentiment_insights/clients/sentiment/sentimental_client.rb
+- lib/sentiment_insights/configuration.rb
+- lib/sentiment_insights/insights/entities.rb
+- lib/sentiment_insights/insights/key_phrases.rb
+- lib/sentiment_insights/insights/sentiment.rb
+- lib/sentiment_insights/insights/topics.rb
+- lib/sentiment_insights/version.rb
+- sentiment_insights.gemspec
+homepage: https://github.com/mathrailsAI/sentiment_insights
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mathrailsAI/sentiment_insights
+  source_code_uri: https://github.com/mathrailsAI/sentiment_insights
+  changelog_uri: https://github.com/mathrailsAI/sentiment_insights/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Analyze and extract sentiment insights from text data easily.
+test_files: []