sentiment_insights 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c3ede714068979aaa53076ed6fef752235b50d45ab57f388d9baf8a0e952baf
+  data.tar.gz: 6fc6b77e018b41a3503d45938b65575f0bd90dfbd8a16ac26257c738591709f3
+SHA512:
+  metadata.gz: d5025dc6ab42d5b4358d66084e3306773984e796da881acf917fd879d579375d152cb7458477d3071f080d43bbb90b0ea8b122833343b963f5b84aac15d11adf
+  data.tar.gz: 63f1abac85a05be6ee68006eeb5729bcc53f1a0f4932ad13067e9ca06f4b89be9ce62f88ca5c8008d647862b29fd7704658a6bb3153dcd8063923650a6c2eb63

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.env
+.idea/
+.travis.yml

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the maintainer at mathrails@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in sentiment_insights.gemspec
+gemspec
+
+gem "dotenv", "~> 2.8", :group => :development

data/Gemfile.lock

@@ -0,0 +1,57 @@
+PATH
+  remote: .
+  specs:
+    sentiment_insights (0.1.0)
+      aws-sdk-comprehend (~> 1.98.0)
+      sentimental (~> 1.4.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aws-eventstream (1.3.2)
+    aws-partitions (1.1094.0)
+    aws-sdk-comprehend (1.98.0)
+      aws-sdk-core (~> 3, >= 3.216.0)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-core (3.222.3)
+      aws-eventstream (~> 1, >= 1.3.0)
+      aws-partitions (~> 1, >= 1.992.0)
+      aws-sigv4 (~> 1.9)
+      base64
+      jmespath (~> 1, >= 1.6.1)
+      logger
+    aws-sigv4 (1.11.0)
+      aws-eventstream (~> 1, >= 1.0.2)
+    base64 (0.2.0)
+    diff-lcs (1.6.1)
+    dotenv (2.8.1)
+    jmespath (1.6.2)
+    logger (1.7.0)
+    rake (13.2.1)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    sentimental (1.4.1)
+
+PLATFORMS
+  arm64-darwin-24
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  dotenv (~> 2.8)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  sentiment_insights!
+
+BUNDLED WITH
+   2.4.21

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mathrailsAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 mathrailsAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,265 @@
+# SentimentInsights 💬📊
+
+**SentimentInsights** is a Ruby gem that helps you uncover meaningful insights from open-ended survey responses using Natural Language Processing (NLP). It supports multi-provider analysis via OpenAI, AWS Comprehend, or a local fallback engine.
+
+---
+
+## ✨ Features
+
+### ✅ 1. Sentiment Analysis
+
+Quickly classify and summarize user responses as positive, neutral, or negative — globally or by segment (e.g., age, region).
+
+#### 🔍 Example Call
+
+```ruby
+insight = SentimentInsights::Insights::Sentiment.new
+result = insight.analyze(entries)
+```
+
+#### 📾 Sample Output
+
+```ruby
+{:global_summary=>
+   {:total_count=>5,
+    :positive_count=>3,
+    :neutral_count=>0,
+    :negative_count=>2,
+    :positive_percentage=>60.0,
+    :neutral_percentage=>0.0,
+    :negative_percentage=>40.0,
+    :net_sentiment_score=>20.0},
+ :segment_summary=>
+   {:age=>
+      {"25-34"=>
+         {:total_count=>3,
+          :positive_count=>3,
+          :neutral_count=>0,
+          :negative_count=>0,
+          :positive_percentage=>100.0,
+          :neutral_percentage=>0.0,
+          :negative_percentage=>0.0,
+          :net_sentiment_score=>100.0}},
+    :top_positive_comments=>
+      [{:answer=>
+          "I absolutely loved the experience shopping with Everlane. The website is clean,\n" +
+            "product descriptions are spot-on, and my jeans arrived two days early with eco-friendly packaging.",
+        :score=>0.9}],
+    :top_negative_comments=>
+      [{:answer=>
+          "The checkout flow on your site was a nightmare. The promo code from your Instagram campaign didn’t work,\n" +
+            "and it kept redirecting me to the homepage. Shopify integration needs a serious fix.",
+        :score=>-0.7}],
+    :responses=>
+      [{:answer=>
+          "I absolutely loved the experience shopping with Everlane. The website is clean,\n" +
+            "product descriptions are spot-on, and my jeans arrived two days early with eco-friendly packaging.",
+        :segment=>{:age=>"25-34", :region=>"West"},
+        :sentiment_label=>:positive,
+        :sentiment_score=>0.9}]}}
+```
+
+### ✅ 2. Key Phrase Extraction
+
+Extract frequently mentioned phrases and identify their associated sentiment and segment spread.
+
+```ruby
+insight = SentimentInsights::Insights::KeyPhrases.new
+result = insight.extract(entries, question: question)
+```
+
+```ruby
+{:phrases=>
+   [{:phrase=>"everlane",
+     :mentions=>["r_1"],
+     :summary=>
+       {:total_mentions=>1,
+        :sentiment_distribution=>{:positive=>1, :negative=>0, :neutral=>0},
+        :segment_distribution=>{:age=>{"25-34"=>1}, :region=>{"West"=>1}}}}],
+ :responses=>
+   [{:id=>"r_1",
+     :sentence=>
+       "I absolutely loved the experience shopping with Everlane. The website is clean,\n" +
+         "product descriptions are spot-on, and my jeans arrived two days early with eco-friendly packaging.",
+     :sentiment=>:positive,
+     :segment=>{:age=>"25-34", :region=>"West"}}]}
+```
+
+### ✅ 3. Entity Recognition
+
+Identify named entities like organizations, products, and people, and track them by sentiment and segment.
+
+```ruby
+insight = SentimentInsights::Insights::Entities.new
+result = insight.extract(entries, question: question)
+```
+
+```ruby
+{:entities=>
+   [{:entity=>"everlane",
+     :type=>"ORGANIZATION",
+     :mentions=>["r_1"],
+     :summary=>
+       {:total_mentions=>1,
+        :segment_distribution=>{:age=>{"25-34"=>1}, :region=>{"West"=>1}}}},
+    {:entity=>"jeans",
+     :type=>"PRODUCT",
+     :mentions=>["r_1"],
+     :summary=>
+       {:total_mentions=>1,
+        :segment_distribution=>{:age=>{"25-34"=>1}, :region=>{"West"=>1}}}},
+    {:entity=>"24 hours",
+     :type=>"TIME",
+     :mentions=>["r_4"],
+     :summary=>
+       {:total_mentions=>1,
+        :segment_distribution=>{:age=>{"45-54"=>1}, :region=>{"Midwest"=>1}}}}],
+ :responses=>
+   [{:id=>"r_1",
+     :sentence=>
+       "I absolutely loved the experience shopping with Everlane. The website is clean,\n" +
+         "product descriptions are spot-on, and my jeans arrived two days early with eco-friendly packaging.",
+     :segment=>{:age=>"25-34", :region=>"West"}},
+    {:id=>"r_4",
+     :sentence=>
+       "I reached out to your Zendesk support team about a missing package, and while they responded within 24 hours,\n" +
+         "the response was copy-paste and didn't address my issue directly.",
+     :segment=>{:age=>"45-54", :region=>"Midwest"}}]}
+```
+
+### ✅ 4. Topic Modeling *(Coming Soon)*
+
+Automatically group similar responses into topics and subthemes.
+
+---
+
+## 🔌 Supported Providers
+
+| Feature            | OpenAI ✅       | AWS Comprehend ✅ | Sentimental (Local) ⚠️ |
+| ------------------ | -------------- | ---------------- | ---------------------- |
+| Sentiment Analysis | ✅              | ✅                | ✅                      |
+| Key Phrases        | ✅              | ✅                | ❌ Not supported        |
+| Entities           | ✅              | ✅                | ❌ Not supported        |
+| Topics             | 🔜 Coming Soon | 🔜 Coming Soon   | ❌                      |
+
+Legend: ✅ Supported | 🔜 Coming Soon | ❌ Not Available | ⚠️ Partial
+
+---
+
+## 📅 Example Input
+
+```ruby
+question = "What did you like or dislike about your recent shopping experience with us?"
+
+entries = [
+  {
+    answer: "I absolutely loved the experience shopping with Everlane. The website is clean,\nproduct descriptions are spot-on, and my jeans arrived two days early with eco-friendly packaging.",
+    segment: { age: "25-34", region: "West" }
+  },
+  {
+    answer: "The checkout flow on your site was a nightmare. The promo code from your Instagram campaign didn’t work,\nand it kept redirecting me to the homepage. Shopify integration needs a serious fix.",
+    segment: { age: "35-44", region: "South" }
+  },
+  {
+    answer: "Apple Pay made the mobile checkout super fast. I placed an order while waiting for my coffee at Starbucks.\nGreat job optimizing the app UX—this is a game-changer.",
+    segment: { age: "25-34", region: "West" }
+  },
+  {
+    answer: "I reached out to your Zendesk support team about a missing package, and while they responded within 24 hours,\nthe response was copy-paste and didn't address my issue directly.",
+    segment: { age: "45-54", region: "Midwest" }
+  },
+  {
+    answer: "Shipping delays aside, I really liked the personalized note inside the box. Small gestures like that\nmake the Uniqlo brand stand out. Will definitely recommend to friends.",
+    segment: { age: "25-34", region: "West" }
+  }
+]
+```
+
+---
+
+## 🚀 Quick Start
+
+```ruby
+# Install the gem
+$ gem install sentiment_insights
+
+# Configure the provider
+SentimentInsights.configure do |config|
+  config.provider = :openai  # or :aws, :sentimental
+end
+
+# Run analysis
+insight = SentimentInsights::Insights::Sentiment.new
+result = insight.analyze(entries)
+puts JSON.pretty_generate(result)
+```
+
+---
+
+## 🔑 Environment Variables
+
+### OpenAI
+
+```bash
+OPENAI_API_KEY=your_openai_key_here
+```
+
+### AWS Comprehend
+
+```bash
+AWS_ACCESS_KEY_ID=your_aws_key
+AWS_SECRET_ACCESS_KEY=your_aws_secret
+AWS_REGION=us-east-1
+```
+
+---
+
+## 💎 Ruby Compatibility
+
+- **Minimum Ruby version:** 2.7
+- Tested on: 2.7, 3.0, 3.1, 3.2
+
+---
+
+## 🔮 Testing
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## 📋 Roadmap
+
+- [x] Sentiment Analysis
+- [x] Key Phrase Extraction
+- [x] Entity Recognition
+- [ ] Topic Modeling
+- [ ] CSV/JSON Export Helpers
+- [ ] Visual Dashboard Add-on
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 🙌 Contributing
+
+Pull requests welcome! Please open an issue to discuss major changes first.
+
+---
+
+## 💬 Acknowledgements
+
+- [OpenAI GPT](https://platform.openai.com/docs)
+- [AWS Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html)
+- [Sentimental Gem](https://github.com/7compass/sentimental)
+
+---
+
+## 📢 Questions?
+
+File an issue or reach out on [GitHub](https://github.com/your-repo)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dotenv/load"
+require "sentiment_insights"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/sentiment_insights/analyzer.rb

@@ -0,0 +1,48 @@
+require "sentiment_insights/clients/sentiment/open_ai_client"
+require "sentiment_insights/clients/sentiment/aws_comprehend_client"
+require_relative "clients/sentiment/sentimental_client"
+
+require "sentiment_insights/insights/sentiment"
+require "sentiment_insights/insights/key_phrases"
+require "sentiment_insights/insights/entities"
+require "sentiment_insights/insights/topics"
+
+module SentimentInsights
+  class Analyzer
+    def initialize(provider: SentimentInsights.configuration.provider)
+      @provider = provider
+    end
+
+    # Sentiment Analysis
+    def sentiment(text)
+      SentimentInsights::Insights::Sentiment.new(@provider).analyze(text)
+    end
+
+    def sentiment_batch(texts)
+      SentimentInsights::Insights::Sentiment.new(@provider).analyze_batch(texts)
+    end
+
+    # Key Phrase Extraction
+    def key_phrases(text)
+      SentimentInsights::Insights::KeyPhrases.new(@provider).extract(text)
+    end
+
+    def key_phrases_batch(texts, options: {})
+      SentimentInsights::Insights::KeyPhrases.new(@provider).extract_batch(texts, options)
+    end
+
+    # Entity Recognition
+    def entities(text)
+      SentimentInsights::Insights::Entities.new(@provider).extract(text)
+    end
+
+    def entities_batch(texts, options: {})
+      SentimentInsights::Insights::Entities.new(@provider).extract_batch(texts, options)
+    end
+
+    # Topic Modeling
+    def topics_batch(texts, options: {})
+      SentimentInsights::Insights::Topics.new(@provider).model_topics(texts, options)
+    end
+  end
+end

data/lib/sentiment_insights/clients/entities/aws_client.rb

@@ -0,0 +1,84 @@
+require 'aws-sdk-comprehend'
+require 'logger'
+
+module SentimentInsights
+  module Clients
+    module Entities
+      class AwsClient
+        MAX_BATCH_SIZE = 25
+
+        def initialize(region: 'us-east-1')
+          @client = Aws::Comprehend::Client.new(region: region)
+          @logger = Logger.new($stdout)
+        end
+
+        def extract_batch(entries, question: nil)
+          responses = []
+          entity_map = Hash.new { |h, k| h[k] = [] }
+
+          entries.each_slice(MAX_BATCH_SIZE).with_index do |batch, batch_idx|
+            texts = batch.map { |e| e[:answer].to_s.strip[0...5000] }
+
+            begin
+              resp = @client.batch_detect_entities({
+                                                     text_list: texts,
+                                                     language_code: 'en'
+                                                   })
+
+              resp.result_list.each_with_index do |res, idx|
+                entry_index = (batch_idx * MAX_BATCH_SIZE) + idx
+                entry = entries[entry_index]
+                sentence = texts[idx]
+                response_id = "r_#{entry_index + 1}"
+
+                responses << {
+                  id: response_id,
+                  sentence: sentence,
+                  segment: entry[:segment] || {}
+                }
+
+                entities = res.entities.map do |e|
+                  {
+                    text: e.text.downcase.strip,
+                    type: e.type
+                  }
+                end.uniq { |e| [e[:text], e[:type]] }
+
+                entities.each do |ent|
+                  key = [ent[:text], ent[:type]]
+                  entity_map[key] << response_id
+                end
+              end
+
+              resp.error_list.each do |error|
+                @logger.warn "AWS entity error at index #{error.index}: #{error.error_code}"
+              end
+
+            rescue Aws::Comprehend::Errors::ServiceError => e
+              @logger.error "AWS Comprehend error: #{e.message}"
+              batch.each_with_index do |entry, i|
+                entry_index = (batch_idx * MAX_BATCH_SIZE) + i
+                responses << {
+                  id: "r_#{entry_index + 1}",
+                  sentence: entry[:answer],
+                  segment: entry[:segment] || {}
+                }
+              end
+            end
+          end
+
+          entities = entity_map.map do |(text, type), ref_ids|
+            {
+              entity: text,
+              type: type,
+              mentions: ref_ids.uniq,
+              summary: nil
+            }
+          end
+
+          { entities: entities, responses: responses }
+        end
+      end
+    end
+  end
+end