sentiment_insights 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '008d6ea6d7343f377abedc02ac6c28bd072c21f8f69d150fc5c5a2dd744fbf96'
-  data.tar.gz: 1cd6db74422570ea2ec02a6e9b8976cd9b8a91120d271ee900057431a4b4665e
+  metadata.gz: ab2970402e6ee32bfa46d70caaafa135d17e780528c76ab7d42c5a6d9a62acb5
+  data.tar.gz: ca8fcc08f054c4f348d53697c3a4fed6a9b36485d628c7b89b0112cc081b332f
 SHA512:
-  metadata.gz: e393148073465c4f022bff7440d11df6e2249b77aee022a2f7c6a6d941a7271c1541b331688f00c5d9cdf3928fcfb45dec8a087ea151316595830b769c9974e1
-  data.tar.gz: b8229c858ff529e53144214d567d679eb608c3f03dc5779a3541f07a2167e3eba6c56090bc0260b1c92ca7a32e4b2572ecf8ce5db315802c2a44b7f878c04e2c
+  metadata.gz: 1af62b7158097b907df3609521c75997f2919294c7a725f12bc7243d9b89721b66d1a0c982fc3daab1ab7e5623ed140db5360355b84e67b309d1392aaf515d21
+  data.tar.gz: e42bf88ffd443546a20617cfcab9818982c19180425047306e8ee59e022bc0d0de50b3908d2d3f2fed587fb373d31e6f4d7d7d799b79c40c10cbd33cb09bc964

data/Gemfile.lock

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

data/README.md

@@ -1,6 +1,6 @@
 # SentimentInsights
 
-**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 and AWS.
+**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.
 
 ---
 
@@ -43,7 +43,7 @@ gem install sentiment_insights
 
 ## Configuration
 
-Configure the provider and (if using OpenAI or AWS) your API key:
+Configure the provider and (if using OpenAI, Claude AI, or AWS) your API key:
 
 ```ruby
 require 'sentiment_insights'
@@ -54,6 +54,12 @@ SentimentInsights.configure do |config|
   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
@@ -68,6 +74,7 @@ end
 
 Supported providers:
 - `:openai`
+- `:claude`
 - `:aws`
 - `:sentimental` (local fallback, limited feature set)
 
@@ -121,11 +128,11 @@ result = insight.analyze(
 ```
 
 #### Available Options (`analyze`)
-| Option        | Type    | Description                                                            | Provider    |
-|---------------|---------|------------------------------------------------------------------------|-------------|
-| `question`    | String  | Contextual question for the batch                                     | OpenAI only |
-| `prompt`      | String  | Custom prompt text for LLM                                            | OpenAI only |
-| `batch_size`  | Integer | Number of entries per OpenAI completion call (default: 50)           | OpenAI only |
+| 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
 
@@ -211,11 +218,11 @@ result = insight.extract(
 ```
 
 #### Available Options (`extract`)
-| Option             | Type    | Description                                                | Provider     |
-|--------------------|---------|------------------------------------------------------------|--------------|
-| `question`         | String  | Context question to help guide phrase extraction           | OpenAI only  |
-| `key_phrase_prompt`| String  | Custom prompt for extracting key phrases                   | OpenAI only  |
-| `sentiment_prompt` | String  | Custom prompt for classifying tone of extracted phrases    | OpenAI only  |
+| 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
 
@@ -267,10 +274,10 @@ result = insight.extract(
 ```
 
 #### Available Options (`extract`)
-| Option      | Type    | Description                                       | Provider     |
-|-------------|---------|---------------------------------------------------|--------------|
-| `question`  | String  | Context question to guide entity extraction       | OpenAI only  |
-| `prompt`    | String  | Custom instructions for OpenAI entity extraction  | OpenAI only  |
+| 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
 
@@ -310,7 +317,7 @@ result = insight.extract(
 
 ## Provider Options & Custom Prompts
 
-> ⚠️ All advanced options (`question`, `prompt`, `key_phrase_prompt`, `sentiment_prompt`, `batch_size`) apply only to the `:openai` provider.  
+> ⚠️ 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`.
 
 ---
@@ -323,6 +330,12 @@ result = insight.extract(
 OPENAI_API_KEY=your_openai_key_here
 ```
 
+### Claude AI
+
+```bash
+CLAUDE_API_KEY=your_claude_key_here
+```
+
 ### AWS Comprehend
 
 ```bash
@@ -373,6 +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)
 

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/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/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/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

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

data/lib/sentiment_insights/insights/sentiment.rb

@@ -1,4 +1,5 @@
 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'
 
@@ -15,6 +16,8 @@ module SentimentInsights
         @provider_client = provider_client || case effective_provider
                                               when :openai
                                                 Clients::Sentiment::OpenAIClient.new
+                                              when :claude
+                                                Clients::Sentiment::ClaudeClient.new
                                               when :aws
                                                 Clients::Sentiment::AwsComprehendClient.new
                                               else

data/lib/sentiment_insights/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sentiment_insights
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mathrailsAI
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-26 00:00:00.000000000 Z
+date: 2025-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sentimental
@@ -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