sentiment_insights 0.1.0 → 0.3.0

checksums.yaml

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

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    sentiment_insights (0.1.0)
-      aws-sdk-comprehend (~> 1.98.0)
+    sentiment_insights (0.3.0)
+      aws-sdk-comprehend (>= 1.98.0)
       sentimental (~> 1.4.0)
 
 GEM

data/README.md

@@ -1,12 +1,101 @@
-# SentimentInsights 💬📊
+# 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.
+**SentimentInsights** is a Ruby gem for extracting sentiment, key phrases, and named entities from survey responses or free-form textual data. It offers a plug-and-play interface to different NLP providers, including OpenAI, Claude AI, and AWS.
 
 ---
 
-## ✨ Features
+## Table of Contents
 
-### ✅ 1. Sentiment Analysis
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+    - [Sentiment Analysis](#sentiment-analysis)
+    - [Key Phrase Extraction](#key-phrase-extraction)
+    - [Entity Extraction](#entity-extraction)
+- [Provider Options & Custom Prompts](#provider-options--custom-prompts)
+- [Full Example](#full-example)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sentiment_insights'
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install sentiment_insights
+```
+
+---
+
+## Configuration
+
+Configure the provider and (if using OpenAI, Claude AI, or AWS) your API key:
+
+```ruby
+require 'sentiment_insights'
+
+# For OpenAI
+SentimentInsights.configure do |config|
+  config.provider = :openai
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+end
+
+# For Claude AI
+SentimentInsights.configure do |config|
+  config.provider = :claude
+  config.claude_api_key = ENV["CLAUDE_API_KEY"]
+end
+
+# For AWS
+SentimentInsights.configure do |config|
+  config.provider = :aws
+  config.aws_region = 'us-east-1'
+end
+
+# For sentimental
+SentimentInsights.configure do |config|
+  config.provider = :sentimental
+end
+```
+
+Supported providers:
+- `:openai`
+- `:claude`
+- `:aws`
+- `:sentimental` (local fallback, limited feature set)
+
+---
+
+## Usage
+
+Data entries should be hashes with at least an `:answer` key. Optionally include segmentation info under `:segment`.
+
+```ruby
+entries = [
+  { answer: "Amazon Checkout was smooth!", segment: { age_group: "18-25", gender: "Female" } },
+  { answer: "Walmart Shipping was delayed.", segment: { age_group: "18-25", gender: "Female" } },
+  { answer: "Target Support was decent.", segment: { age_group: "26-35", gender: "Male" } },
+  { answer: "Loved the product!", segment: { age_group: "18-25", gender: "Male" } }
+]
+```
+
+---
+
+### Sentiment Analysis
 
 Quickly classify and summarize user responses as positive, neutral, or negative — globally or by segment (e.g., age, region).
 
@@ -17,6 +106,34 @@ insight = SentimentInsights::Insights::Sentiment.new
 result = insight.analyze(entries)
 ```
 
+With options:
+
+```ruby
+custom_prompt = <<~PROMPT
+  For each of the following customer responses, classify the sentiment as Positive, Neutral, or Negative, and assign a score between -1.0 (very negative) and 1.0 (very positive).
+
+            Reply with a numbered list like:
+            1. Positive (0.9)
+            2. Negative (-0.8)
+            3. Neutral (0.0)
+PROMPT
+
+insight = SentimentInsights::Insights::Sentiment.new
+result = insight.analyze(
+  entries,
+  question: "How was your experience today?",
+  prompt: custom_prompt,
+  batch_size: 10
+)
+```
+
+#### Available Options (`analyze`)
+| Option        | Type    | Description                                                            | Provider           |
+|---------------|---------|------------------------------------------------------------------------|--------------------|
+| `question`    | String  | Contextual question for the batch                                     | OpenAI, Claude only |
+| `prompt`      | String  | Custom prompt text for LLM                                            | OpenAI, Claude only |
+| `batch_size`  | Integer | Number of entries per completion call (default: 50)                  | OpenAI, Claude only |
+
 #### 📾 Sample Output
 
 ```ruby
@@ -59,15 +176,56 @@ result = insight.analyze(entries)
         :sentiment_score=>0.9}]}}
 ```
 
-### ✅ 2. Key Phrase Extraction
+---
+
+### 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)
+result = insight.extract(entries)
 ```
 
+With options:
+
+```ruby
+key_phrase_prompt = <<~PROMPT.strip
+  Extract the most important key phrases that represent the main ideas or feedback in the sentence below.
+  Ignore stop words and return each key phrase in its natural form, comma-separated.
+
+  Question: %{question}
+
+  Text: %{text}
+PROMPT
+
+sentiment_prompt = <<~PROMPT
+  For each of the following customer responses, classify the sentiment as Positive, Neutral, or Negative, and assign a score between -1.0 (very negative) and 1.0 (very positive).
+
+            Reply with a numbered list like:
+            1. Positive (0.9)
+            2. Negative (-0.8)
+            3. Neutral (0.0)
+PROMPT
+
+insight = SentimentInsights::Insights::KeyPhrases.new
+result = insight.extract(
+  entries,
+  question: "What are the recurring themes?",
+  key_phrase_prompt: key_phrase_prompt,
+  sentiment_prompt: sentiment_prompt
+)
+```
+
+#### Available Options (`extract`)
+| Option             | Type    | Description                                                | Provider           |
+|--------------------|---------|------------------------------------------------------------|--------------------|
+| `question`         | String  | Context question to help guide phrase extraction           | OpenAI, Claude only |
+| `key_phrase_prompt`| String  | Custom prompt for extracting key phrases                   | OpenAI, Claude only |
+| `sentiment_prompt` | String  | Custom prompt for classifying tone of extracted phrases    | OpenAI, Claude only |
+
+#### 📾 Sample Output
+
 ```ruby
 {:phrases=>
    [{:phrase=>"everlane",
@@ -85,15 +243,44 @@ result = insight.extract(entries, question: question)
      :segment=>{:age=>"25-34", :region=>"West"}}]}
 ```
 
-### ✅ 3. Entity Recognition
+---
 
-Identify named entities like organizations, products, and people, and track them by sentiment and segment.
+### Entity Extraction
 
 ```ruby
 insight = SentimentInsights::Insights::Entities.new
-result = insight.extract(entries, question: question)
+result = insight.extract(entries)
 ```
 
+With options:
+
+```ruby
+entity_prompt = <<~PROMPT.strip
+  Identify brand names, competitors, and product references in the sentence below.
+  Return each as a JSON object with "text" and "type" (e.g., BRAND, PRODUCT, COMPANY).
+
+  Question: %{question}
+
+  Sentence: "%{text}"
+PROMPT
+
+insight = SentimentInsights::Insights::Entities.new
+result = insight.extract(
+  entries,
+  question: "Which products or brands are mentioned?",
+  prompt: entity_prompt
+)
+
+```
+
+#### Available Options (`extract`)
+| Option      | Type    | Description                                       | Provider           |
+|-------------|---------|---------------------------------------------------|--------------------|
+| `question`  | String  | Context question to guide entity extraction       | OpenAI, Claude only |
+| `prompt`    | String  | Custom instructions for entity extraction         | OpenAI, Claude only |
+
+#### 📾 Sample Output
+
 ```ruby
 {:entities=>
    [{:entity=>"everlane",
@@ -126,73 +313,12 @@ result = insight.extract(entries, question: question)
          "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   | ❌                      |
+## Provider Options & Custom Prompts
 
-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)
-```
+> ⚠️ All advanced options (`question`, `prompt`, `key_phrase_prompt`, `sentiment_prompt`, `batch_size`) apply only to the `:openai` and `:claude` providers.  
+> They are safely ignored for `:aws` and `:sentimental`.
 
 ---
 
@@ -204,6 +330,12 @@ puts JSON.pretty_generate(result)
 OPENAI_API_KEY=your_openai_key_here
 ```
 
+### Claude AI
+
+```bash
+CLAUDE_API_KEY=your_claude_key_here
+```
+
 ### AWS Comprehend
 
 ```bash
@@ -217,7 +349,6 @@ AWS_REGION=us-east-1
 ## 💎 Ruby Compatibility
 
 - **Minimum Ruby version:** 2.7
-- Tested on: 2.7, 3.0, 3.1, 3.2
 
 ---
 
@@ -255,11 +386,7 @@ Pull requests welcome! Please open an issue to discuss major changes first.
 ## 💬 Acknowledgements
 
 - [OpenAI GPT](https://platform.openai.com/docs)
+- [Claude AI](https://docs.anthropic.com/claude/reference/getting-started-with-the-api)
 - [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/lib/sentiment_insights/clients/entities/aws_client.rb

@@ -12,7 +12,7 @@ module SentimentInsights
           @logger = Logger.new($stdout)
         end
 
-        def extract_batch(entries, question: nil)
+        def extract_batch(entries, question: nil, prompt: nil)
           responses = []
           entity_map = Hash.new { |h, k| h[k] = [] }
 

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

@@ -0,0 +1,131 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'logger'
+
+module SentimentInsights
+  module Clients
+    module Entities
+      class ClaudeClient
+        DEFAULT_MODEL   = "claude-3-haiku-20240307"
+        DEFAULT_RETRIES = 3
+
+        def initialize(api_key: ENV['CLAUDE_API_KEY'], model: DEFAULT_MODEL, max_retries: DEFAULT_RETRIES)
+          @api_key = api_key or raise ArgumentError, "Claude API key is required"
+          @model = model
+          @max_retries = max_retries
+          @logger = Logger.new($stdout)
+        end
+
+        def extract_batch(entries, question: nil, prompt: nil)
+          responses = []
+          entity_map = Hash.new { |h, k| h[k] = [] }
+
+          entries.each_with_index do |entry, index|
+            sentence = entry[:answer].to_s.strip
+            next if sentence.empty?
+
+            response_id = "r_#{index + 1}"
+            entities = extract_entities_from_sentence(sentence, question: question, prompt: prompt)
+
+            responses << {
+              id: response_id,
+              sentence: sentence,
+              segment: entry[:segment] || {}
+            }
+
+            entities.each do |ent|
+              next if ent[:text].to_s.empty? || ent[:type].to_s.empty?
+              key = [ent[:text].downcase, ent[:type]]
+              entity_map[key] << response_id
+            end
+          end
+
+          entity_records = entity_map.map do |(text, type), ref_ids|
+            {
+              entity: text,
+              type: type,
+              mentions: ref_ids.uniq,
+              summary: nil
+            }
+          end
+
+          { entities: entity_records, responses: responses }
+        end
+
+        private
+
+        def extract_entities_from_sentence(text, question: nil, prompt: nil)
+          # Default prompt with interpolation placeholders
+          default_prompt = <<~PROMPT
+            Extract named entities from this sentence based on the question.
+            Return them as a JSON array with each item having "text" and "type" (e.g., PERSON, ORGANIZATION, LOCATION, PRODUCT).
+            %{question}
+            Sentence: "%{text}"
+          PROMPT
+
+          # If a custom prompt is provided, interpolate %{text} and %{question} if present
+          if prompt
+            interpolated = prompt.dup
+            interpolated.gsub!('%{text}', text.to_s)
+            interpolated.gsub!('%{question}', question.to_s) if question
+            interpolated.gsub!('{text}', text.to_s)
+            interpolated.gsub!('{question}', question.to_s) if question
+            prompt_to_use = interpolated
+          else
+            question_line = question ? "Question: #{question}" : ""
+            prompt_to_use = default_prompt % { question: question_line, text: text }
+          end
+
+          body = build_request_body(prompt_to_use)
+          response = post_claude(body)
+
+          begin
+            raw_json = response.dig("content", 0, "text").to_s.strip
+            JSON.parse(raw_json, symbolize_names: true)
+          rescue JSON::ParserError => e
+            @logger.warn "Failed to parse entity JSON: #{e.message}"
+            []
+          end
+        end
+
+        def build_request_body(prompt)
+          {
+            model: @model,
+            max_tokens: 1000,
+            messages: [{ role: "user", content: prompt }]
+          }
+        end
+
+        def post_claude(body)
+          uri = URI("https://api.anthropic.com/v1/messages")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          attempt = 0
+          while attempt < @max_retries
+            attempt += 1
+
+            request = Net::HTTP::Post.new(uri)
+            request["Content-Type"] = "application/json"
+            request["x-api-key"] = @api_key
+            request["anthropic-version"] = "2023-06-01"
+            request.body = JSON.generate(body)
+
+            begin
+              response = http.request(request)
+              return JSON.parse(response.body) if response.code.to_i == 200
+              @logger.warn "Claude entity extraction failed (#{response.code}): #{response.body}"
+            rescue => e
+              @logger.error "Error during entity extraction: #{e.class} - #{e.message}"
+            end
+
+            sleep(2 ** (attempt - 1)) if attempt < @max_retries
+          end
+
+          {}
+        end
+      end
+    end
+  end
+end

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

@@ -17,7 +17,7 @@ module SentimentInsights
           @logger = Logger.new($stdout)
         end
 
-        def extract_batch(entries, question: nil)
+        def extract_batch(entries, question: nil, prompt: nil)
           responses = []
           entity_map = Hash.new { |h, k| h[k] = [] }
 
@@ -26,7 +26,7 @@ module SentimentInsights
             next if sentence.empty?
 
             response_id = "r_#{index + 1}"
-            entities = extract_entities_from_sentence(sentence)
+            entities = extract_entities_from_sentence(sentence, question: question, prompt: prompt)
 
             responses << {
               id: response_id,
@@ -35,6 +35,7 @@ module SentimentInsights
             }
 
             entities.each do |ent|
+              next if ent[:text].empty? || ent[:type].empty?
               key = [ent[:text].downcase, ent[:type]]
               entity_map[key] << response_id
             end
@@ -54,13 +55,29 @@ module SentimentInsights
 
         private
 
-        def extract_entities_from_sentence(text)
-          prompt = <<~PROMPT
-            Extract named entities from this sentence. Return them as a JSON array with each item having "text" and "type" (e.g., PERSON, ORGANIZATION, LOCATION, PRODUCT).
-            Sentence: "#{text}"
+        def extract_entities_from_sentence(text, question: nil, prompt: nil)
+          # Default prompt with interpolation placeholders
+          default_prompt = <<~PROMPT
+            Extract named entities from this sentence based on the question.
+            Return them as a JSON array with each item having "text" and "type" (e.g., PERSON, ORGANIZATION, LOCATION, PRODUCT).
+            %{question}
+            Sentence: "%{text}"
           PROMPT
 
-          body = build_request_body(prompt)
+          # If a custom prompt is provided, interpolate %{text} and %{question} if present
+          if prompt
+            interpolated = prompt.dup
+            interpolated.gsub!('%{text}', text.to_s)
+            interpolated.gsub!('%{question}', question.to_s) if question
+            interpolated.gsub!('{text}', text.to_s)
+            interpolated.gsub!('{question}', question.to_s) if question
+            prompt_to_use = interpolated
+          else
+            question_line = question ? "Question: #{question}" : ""
+            prompt_to_use = default_prompt % { question: question_line, text: text }
+          end
+
+          body = build_request_body(prompt_to_use)
           response = post_openai(body)
 
           begin

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

@@ -12,7 +12,7 @@ module SentimentInsights
           @logger = Logger.new($stdout)
         end
 
-        def extract_batch(entries, question: nil)
+        def extract_batch(entries, question: nil, key_phrase_prompt: nil, sentiment_prompt: nil)
           responses = []
           phrase_map = Hash.new { |h, k| h[k] = [] }
 

data/lib/sentiment_insights/clients/key_phrases/claude_client.rb

@@ -0,0 +1,151 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'logger'
+
+module SentimentInsights
+  module Clients
+    module KeyPhrases
+      class ClaudeClient
+        DEFAULT_MODEL = "claude-3-haiku-20240307"
+        DEFAULT_RETRIES = 3
+
+        def initialize(api_key: ENV['CLAUDE_API_KEY'], model: DEFAULT_MODEL, max_retries: DEFAULT_RETRIES)
+          @api_key = api_key or raise ArgumentError, "Claude API key is required"
+          @model = model
+          @max_retries = max_retries
+          @logger = Logger.new($stdout)
+        end
+
+        def extract_batch(entries, question: nil, key_phrase_prompt: nil, sentiment_prompt: nil)
+          responses = []
+          phrase_map = Hash.new { |h, k| h[k] = [] }
+
+          entries.each_with_index do |entry, index|
+            sentence = entry[:answer].to_s.strip
+            next if sentence.empty?
+
+            response_id = "r_#{index + 1}"
+            
+            # Extract key phrases
+            phrases = extract_key_phrases(sentence, question: question, prompt: key_phrase_prompt)
+            
+            # Get sentiment for this response
+            sentiment = get_sentiment(sentence, prompt: sentiment_prompt)
+
+            responses << {
+              id: response_id,
+              sentence: sentence,
+              sentiment: sentiment,
+              segment: entry[:segment] || {}
+            }
+
+            phrases.each do |phrase|
+              next if phrase.strip.empty?
+              phrase_map[phrase.downcase] << response_id
+            end
+          end
+
+          phrase_records = phrase_map.map do |phrase, ref_ids|
+            {
+              phrase: phrase,
+              mentions: ref_ids.uniq,
+              summary: nil
+            }
+          end
+
+          { phrases: phrase_records, responses: responses }
+        end
+
+        private
+
+        def extract_key_phrases(text, question: nil, prompt: nil)
+          default_prompt = <<~PROMPT.strip
+            Extract the most important key phrases that represent the main ideas or feedback in the sentence below.
+            Ignore stop words and return each key phrase in its natural form, comma-separated.
+
+            Question: %{question}
+
+            Text: %{text}
+          PROMPT
+
+          if prompt
+            interpolated = prompt.dup
+            interpolated.gsub!('%{text}', text.to_s)
+            interpolated.gsub!('%{question}', question.to_s) if question
+            interpolated.gsub!('{text}', text.to_s)
+            interpolated.gsub!('{question}', question.to_s) if question
+            prompt_to_use = interpolated
+          else
+            question_line = question ? question.to_s : ""
+            prompt_to_use = default_prompt % { question: question_line, text: text }
+          end
+
+          body = build_request_body(prompt_to_use)
+          response = post_claude(body)
+
+          content = response.dig("content", 0, "text").to_s.strip
+          content.split(',').map(&:strip).reject(&:empty?)
+        end
+
+        def get_sentiment(text, prompt: nil)
+          default_prompt = <<~PROMPT
+            Classify the sentiment of this text as Positive, Neutral, or Negative.
+            Reply with just the sentiment label.
+
+            Text: "#{text}"
+          PROMPT
+
+          prompt_to_use = prompt ? prompt.gsub('%{text}', text) : default_prompt
+
+          body = build_request_body(prompt_to_use)
+          response = post_claude(body)
+
+          content = response.dig("content", 0, "text").to_s.strip.downcase
+          case content
+          when /positive/ then :positive
+          when /negative/ then :negative
+          else :neutral
+          end
+        end
+
+        def build_request_body(prompt)
+          {
+            model: @model,
+            max_tokens: 1000,
+            messages: [{ role: "user", content: prompt }]
+          }
+        end
+
+        def post_claude(body)
+          uri = URI("https://api.anthropic.com/v1/messages")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          attempt = 0
+          while attempt < @max_retries
+            attempt += 1
+
+            request = Net::HTTP::Post.new(uri)
+            request["Content-Type"] = "application/json"
+            request["x-api-key"] = @api_key
+            request["anthropic-version"] = "2023-06-01"
+            request.body = JSON.generate(body)
+
+            begin
+              response = http.request(request)
+              return JSON.parse(response.body) if response.code.to_i == 200
+              @logger.warn "Claude key phrase extraction failed (#{response.code}): #{response.body}"
+            rescue => e
+              @logger.error "Error during key phrase extraction: #{e.class} - #{e.message}"
+            end
+
+            sleep(2 ** (attempt - 1)) if attempt < @max_retries
+          end
+
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/sentiment_insights/clients/key_phrases/open_ai_client.rb

@@ -8,7 +8,7 @@ module SentimentInsights
   module Clients
     module KeyPhrases
       class OpenAIClient
-        DEFAULT_MODEL   = "gpt-3.5-turbo"
+        DEFAULT_MODEL = "gpt-3.5-turbo"
         DEFAULT_RETRIES = 3
 
         def initialize(api_key: ENV['OPENAI_API_KEY'], model: DEFAULT_MODEL, max_retries: DEFAULT_RETRIES)
@@ -20,19 +20,19 @@ module SentimentInsights
         end
 
         # Extract key phrases from entries and enrich with sentiment
-        def extract_batch(entries, question: nil)
+        def extract_batch(entries, question: nil, key_phrase_prompt: nil, sentiment_prompt: nil)
           responses = []
           phrase_map = Hash.new { |h, k| h[k] = [] }
 
           # Fetch sentiments in batch from sentiment client
-          sentiments = @sentiment_client.analyze_entries(entries, question: question)
+          sentiments = @sentiment_client.analyze_entries(entries, question: question, prompt: sentiment_prompt)
 
           entries.each_with_index do |entry, index|
             sentence = entry[:answer].to_s.strip
             next if sentence.empty?
 
             response_id = "r_#{index + 1}"
-            phrases = extract_phrases_from_sentence(sentence)
+            phrases = extract_phrases_from_sentence(sentence, question: question, prompt: key_phrase_prompt)
 
             sentiment = sentiments[index] || { label: :neutral }
 
@@ -61,15 +61,33 @@ module SentimentInsights
 
         private
 
-        def extract_phrases_from_sentence(text)
-          prompt = <<~PROMPT
-          Extract the key phrases from this sentence:
-          "#{text}"
-          Return them as a comma-separated list.
+        def extract_phrases_from_sentence(text, question: nil, prompt: nil)
+          # Default prompt with interpolation placeholders
+          default_prompt = <<~PROMPT
+            Extract the most important key phrases that represent the main ideas or feedback in the sentence below.
+            Ignore stop words and return each key phrase in its natural form, comma-separated.
+            %{question}
+            Sentence: "%{text}"
           PROMPT
 
-          body = build_request_body(prompt)
+          # If a custom prompt is provided, attempt to interpolate %{text} and %{question} if present
+          if prompt
+            interpolated = prompt.dup
+            interpolated.gsub!('%{text}', text.to_s)
+            interpolated.gsub!('%{question}', question.to_s) if question
+            # For compatibility: if “{text}” is used instead of “%{text}”
+            interpolated.gsub!('{text}', text.to_s)
+            interpolated.gsub!('{question}', question.to_s) if question
+            prompt_to_use = interpolated
+          else
+            question_line = question ? "Question: #{question}" : ""
+            prompt_to_use = default_prompt % { question: question_line, text: text }
+          end
+
+          body = build_request_body(prompt_to_use)
           response = post_openai(body)
+
+          # The response is expected as a comma- or newline-separated list of key phrases
           parse_phrases(response)
         end
 

data/lib/sentiment_insights/clients/sentiment/aws_comprehend_client.rb

@@ -15,7 +15,7 @@ module SentimentInsights
         # Analyze a batch of entries using AWS Comprehend.
         # @param entries [Array<Hash>] each with :answer key
         # @return [Array<Hash>] each with :label (symbol) and :score (float)
-        def analyze_entries(entries, question: nil)
+        def analyze_entries(entries, question: nil, prompt: nil, batch_size: nil)
           results = []
 
           entries.each_slice(MAX_BATCH_SIZE) do |batch|

data/lib/sentiment_insights/clients/sentiment/claude_client.rb

@@ -0,0 +1,126 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'logger'
+
+module SentimentInsights
+  module Clients
+    module Sentiment
+      class ClaudeClient
+        DEFAULT_MODEL = "claude-3-haiku-20240307"
+        DEFAULT_RETRIES = 3
+
+        def initialize(api_key: ENV['CLAUDE_API_KEY'], model: DEFAULT_MODEL, max_retries: DEFAULT_RETRIES, return_scores: true)
+          @api_key = api_key or raise ArgumentError, "Claude API key is required"
+          @model = model
+          @max_retries = max_retries
+          @return_scores = return_scores
+          @logger = Logger.new($stdout)
+        end
+
+        def analyze_entries(entries, question: nil, prompt: nil, batch_size: 50)
+          all_sentiments = []
+
+          entries.each_slice(batch_size) do |batch|
+            prompt_content = build_prompt_content(batch, question: question, prompt: prompt)
+            request_body = {
+              model: @model,
+              max_tokens: 1000,
+              messages: [
+                { role: "user", content: prompt_content }
+              ]
+            }
+
+            uri = URI("https://api.anthropic.com/v1/messages")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+
+            response_content = nil
+            attempt = 0
+
+            while attempt < @max_retries
+              attempt += 1
+              request = Net::HTTP::Post.new(uri)
+              request["Content-Type"] = "application/json"
+              request["x-api-key"] = @api_key
+              request["anthropic-version"] = "2023-06-01"
+              request.body = JSON.generate(request_body)
+
+              begin
+                response = http.request(request)
+              rescue StandardError => e
+                @logger.error "Claude API request error: #{e.class} - #{e.message}"
+                raise
+              end
+
+              status = response.code.to_i
+              if status == 429
+                @logger.warn "Rate limit (HTTP 429) on attempt #{attempt}. Retrying..."
+                sleep(2 ** (attempt - 1))
+                next
+              elsif status != 200
+                @logger.error "Request failed (#{status}): #{response.body}"
+                raise "Claude API Error: #{status}"
+              else
+                data = JSON.parse(response.body)
+                response_content = data.dig("content", 0, "text")
+                break
+              end
+            end
+
+            sentiments = parse_sentiments(response_content, batch.size)
+            all_sentiments.concat(sentiments)
+          end
+
+          all_sentiments
+        end
+
+        private
+
+        def build_prompt_content(entries, question: nil, prompt: nil)
+          content = ""
+          content << "Question: #{question}\n\n" if question
+
+          # Use custom instructions or default
+          instructions = prompt || <<~DEFAULT
+            For each of the following customer responses, classify the sentiment as Positive, Neutral, or Negative, and assign a score between -1.0 (very negative) and 1.0 (very positive).
+
+            Reply with a numbered list like:
+            1. Positive (0.9)
+            2. Negative (-0.8)
+            3. Neutral (0.0)
+          DEFAULT
+
+          content << instructions.strip + "\n\n"
+
+          entries.each_with_index do |entry, index|
+            content << "#{index + 1}. \"#{entry[:answer]}\"\n"
+          end
+
+          content
+        end
+
+        def parse_sentiments(content, expected_count)
+          sentiments = []
+
+          content.to_s.strip.split(/\r?\n/).each do |line|
+            if line.strip =~ /^\d+[\.:)]?\s*(Positive|Negative|Neutral)\s*\(([-\d\.]+)\)/i
+              label = $1.downcase.to_sym
+              score = $2.to_f
+              sentiments << { label: label, score: score }
+            end
+          end
+
+          if sentiments.size != expected_count
+            @logger.warn "Expected #{expected_count} results, got #{sentiments.size}. Padding with neutral."
+            while sentiments.size < expected_count
+              sentiments << { label: :neutral, score: 0.0 }
+            end
+          end
+
+          sentiments.first(expected_count)
+        end
+      end
+    end
+  end
+end

data/lib/sentiment_insights/clients/sentiment/open_ai_client.rb

@@ -7,7 +7,7 @@ module SentimentInsights
   module Clients
     module Sentiment
       class OpenAIClient
-        DEFAULT_MODEL   = "gpt-3.5-turbo"
+        DEFAULT_MODEL = "gpt-3.5-turbo"
         DEFAULT_RETRIES = 3
 
         def initialize(api_key: ENV['OPENAI_API_KEY'], model: DEFAULT_MODEL, max_retries: DEFAULT_RETRIES, return_scores: true)
@@ -18,75 +18,85 @@ module SentimentInsights
           @logger = Logger.new($stdout)
         end
 
-        def analyze_entries(entries, question: nil)
-          prompt_content = build_prompt_content(entries, question)
-          request_body = {
-            model: @model,
-            messages: [
-              { role: "user", content: prompt_content }
-            ],
-            temperature: 0.0
-          }
-
-          uri = URI("https://api.openai.com/v1/chat/completions")
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true
-
-          response_content = nil
-          attempt = 0
-
-          while attempt < @max_retries
-            attempt += 1
-            request = Net::HTTP::Post.new(uri)
-            request["Content-Type"] = "application/json"
-            request["Authorization"] = "Bearer #{@api_key}"
-            request.body = JSON.generate(request_body)
-
-            begin
-              response = http.request(request)
-            rescue StandardError => e
-              @logger.error "OpenAI API request error: #{e.class} - #{e.message}"
-              raise
+        def analyze_entries(entries, question: nil, prompt: nil, batch_size: 50)
+          all_sentiments = []
+
+          entries.each_slice(batch_size) do |batch|
+            prompt_content = build_prompt_content(batch, question: question, prompt: prompt)
+            request_body = {
+              model: @model,
+              messages: [
+                { role: "user", content: prompt_content }
+              ],
+              temperature: 0.0
+            }
+
+            uri = URI("https://api.openai.com/v1/chat/completions")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = true
+
+            response_content = nil
+            attempt = 0
+
+            while attempt < @max_retries
+              attempt += 1
+              request = Net::HTTP::Post.new(uri)
+              request["Content-Type"] = "application/json"
+              request["Authorization"] = "Bearer #{@api_key}"
+              request.body = JSON.generate(request_body)
+
+              begin
+                response = http.request(request)
+              rescue StandardError => e
+                @logger.error "OpenAI API request error: #{e.class} - #{e.message}"
+                raise
+              end
+
+              status = response.code.to_i
+              if status == 429
+                @logger.warn "Rate limit (HTTP 429) on attempt #{attempt}. Retrying..."
+                sleep(2 ** (attempt - 1))
+                next
+              elsif status != 200
+                @logger.error "Request failed (#{status}): #{response.body}"
+                raise "OpenAI API Error: #{status}"
+              else
+                data = JSON.parse(response.body)
+                response_content = data.dig("choices", 0, "message", "content")
+                break
+              end
             end
 
-            status = response.code.to_i
-            if status == 429
-              @logger.warn "Rate limit (HTTP 429) on attempt #{attempt}. Retrying..."
-              sleep(2 ** (attempt - 1))
-              next
-            elsif status != 200
-              @logger.error "Request failed (#{status}): #{response.body}"
-              raise "OpenAI API Error: #{status}"
-            else
-              data = JSON.parse(response.body)
-              response_content = data.dig("choices", 0, "message", "content")
-              break
-            end
+            sentiments = parse_sentiments(response_content, batch.size)
+            all_sentiments.concat(sentiments)
           end
 
-          parse_sentiments(response_content, entries.size)
+          all_sentiments
         end
 
         private
 
-        def build_prompt_content(entries, question)
-          prompt = ""
-          prompt << "Question: #{question}\n" if question
-          prompt << <<~INSTRUCTIONS
-          For each of the following customer responses, classify the sentiment as Positive, Neutral, or Negative, and assign a score between -1.0 (very negative) and 1.0 (very positive).
+        def build_prompt_content(entries, question: nil, prompt: nil)
+          content = ""
+          content << "Question: #{question}\n\n" if question
+
+          # Use custom instructions or default
+          instructions = prompt || <<~DEFAULT
+            For each of the following customer responses, classify the sentiment as Positive, Neutral, or Negative, and assign a score between -1.0 (very negative) and 1.0 (very positive).
 
-          Reply with a numbered list like:
-          1. Positive (0.9)
-          2. Negative (-0.8)
-          3. Neutral (0.0)
+            Reply with a numbered list like:
+            1. Positive (0.9)
+            2. Negative (-0.8)
+            3. Neutral (0.0)
+          DEFAULT
 
-          INSTRUCTIONS
+          content << instructions.strip + "\n\n"
 
           entries.each_with_index do |entry, index|
-            prompt << "#{index + 1}. \"#{entry[:answer]}\"\n"
+            content << "#{index + 1}. \"#{entry[:answer]}\"\n"
           end
 
-          prompt
+          content
         end
 
         def parse_sentiments(content, expected_count)

data/lib/sentiment_insights/clients/sentiment/sentimental_client.rb

@@ -14,7 +14,7 @@ module SentimentInsights
         # @param entries [Array<Hash>] An array of response hashes (each with :answer).
         # @param question [String, nil] (unused) Global question context, not needed for local analysis.
         # @return [Array<Hash>] An array of hashes with sentiment classification and score for each entry.
-        def analyze_entries(entries, question: nil)
+        def analyze_entries(entries, question: nil, prompt: nil, batch_size: nil)
           puts "Inside sentimental"
           entries.map do |entry|
             text = entry[:answer].to_s.strip

data/lib/sentiment_insights/configuration.rb

@@ -1,10 +1,11 @@
 module SentimentInsights
   class Configuration
-    attr_accessor :provider, :openai_api_key, :aws_region
+    attr_accessor :provider, :openai_api_key, :aws_region, :claude_api_key
 
     def initialize
       @provider = :openai
       @openai_api_key = ENV["OPENAI_API_KEY"]
+      @claude_api_key = ENV["CLAUDE_API_KEY"]
       @aws_region = "us-east-1"
     end
   end

data/lib/sentiment_insights/insights/entities.rb

@@ -9,6 +9,9 @@ module SentimentInsights
                                               when :openai
                                                 require_relative '../clients/entities/open_ai_client'
                                                 Clients::Entities::OpenAIClient.new
+                                              when :claude
+                                                require_relative '../clients/entities/claude_client'
+                                                Clients::Entities::ClaudeClient.new
                                               when :aws
                                                 require_relative '../clients/entities/aws_client'
                                                 Clients::Entities::AwsClient.new
@@ -22,11 +25,10 @@ module SentimentInsights
       # Extract named entities and build summarized output
       # @param entries [Array<Hash>] each with :answer and optional :segment
       # @return [Hash] { entities: [...], responses: [...] }
-      def extract(entries, question: nil)
+      def extract(entries, question: nil, prompt: nil)
         entries = entries.to_a
-        raw_result = @provider_client.extract_batch(entries, question: question)
+        raw_result = @provider_client.extract_batch(entries, question: question, prompt: prompt)
 
-        puts "raw_result = #{raw_result}"
         responses = raw_result[:responses] || []
         entities  = raw_result[:entities] || []
 

data/lib/sentiment_insights/insights/key_phrases.rb

@@ -1,4 +1,5 @@
 require_relative '../clients/key_phrases/open_ai_client'
+require_relative '../clients/key_phrases/claude_client'
 require_relative '../clients/key_phrases/aws_client'
 
 module SentimentInsights
@@ -11,6 +12,8 @@ module SentimentInsights
         @provider_client = provider_client || case effective_provider
                                               when :openai
                                                 Clients::KeyPhrases::OpenAIClient.new
+                                              when :claude
+                                                Clients::KeyPhrases::ClaudeClient.new
                                               when :aws
                                                 Clients::KeyPhrases::AwsClient.new
                                               when :sentimental
@@ -24,9 +27,9 @@ module SentimentInsights
       # @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)
+      def extract(entries, question: nil, key_phrase_prompt: nil, sentiment_prompt: nil)
         entries = entries.to_a
-        raw_result = @provider_client.extract_batch(entries, question: question)
+        raw_result = @provider_client.extract_batch(entries, question: question, key_phrase_prompt: key_phrase_prompt, sentiment_prompt: sentiment_prompt)
 
         responses = raw_result[:responses] || []
         phrases  = raw_result[:phrases] || []
@@ -77,4 +80,4 @@ module SentimentInsights
       end
     end
   end
-end
+end

data/lib/sentiment_insights/insights/sentiment.rb

@@ -1,5 +1,7 @@
 require_relative '../clients/sentiment/open_ai_client'
+require_relative '../clients/sentiment/claude_client'
 require_relative '../clients/sentiment/sentimental_client'
+require_relative '../clients/sentiment/aws_comprehend_client'
 
 module SentimentInsights
   module Insights
@@ -14,8 +16,9 @@ module SentimentInsights
         @provider_client = provider_client || case effective_provider
                                               when :openai
                                                 Clients::Sentiment::OpenAIClient.new
+                                              when :claude
+                                                Clients::Sentiment::ClaudeClient.new
                                               when :aws
-                                                require_relative '../clients/sentiment/aws_comprehend_client'
                                                 Clients::Sentiment::AwsComprehendClient.new
                                               else
                                                 Clients::Sentiment::SentimentalClient.new
@@ -27,11 +30,11 @@ module SentimentInsights
       # @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)
+      def analyze(entries, question: nil, prompt: nil, batch_size: 50)
         # 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)
+        results = @provider_client.analyze_entries(entries, question: question, prompt: prompt, batch_size: batch_size)
 
         # Combine original entries with sentiment results
         annotated_responses = entries.each_with_index.map do |entry, idx|

data/lib/sentiment_insights/version.rb

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

data/sentiment_insights.gemspec

@@ -17,8 +17,6 @@ Gem::Specification.new do |spec|
   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
@@ -32,7 +30,7 @@ Gem::Specification.new do |spec|
 
   # Runtime dependencies
   spec.add_dependency "sentimental", "~> 1.4.0"
-  spec.add_dependency "aws-sdk-comprehend", "~> 1.98.0"
+  spec.add_dependency "aws-sdk-comprehend", ">= 1.98.0"
 
   # Development dependencies
   spec.add_development_dependency "bundler", "~> 2.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sentiment_insights
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mathrailsAI
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-03 00:00:00.000000000 Z
+date: 2025-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sentimental
@@ -28,14 +28,14 @@ dependencies:
   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
@@ -117,10 +117,13 @@ files:
 - lib/sentiment_insights.rb
 - lib/sentiment_insights/analyzer.rb
 - lib/sentiment_insights/clients/entities/aws_client.rb
+- lib/sentiment_insights/clients/entities/claude_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/claude_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/claude_client.rb
 - lib/sentiment_insights/clients/sentiment/open_ai_client.rb
 - lib/sentiment_insights/clients/sentiment/sentimental_client.rb
 - lib/sentiment_insights/configuration.rb
@@ -136,7 +139,6 @@ licenses:
 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: