Merge pull request #3 from mathrailsAI/feature/integrate-claudeai

Integrate Claude AI as a new provider

Author: mathrailsAI

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)
 

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