sentimentscopeai 1.0.0__tar.gz

sentimentscopeai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vignesh Thondikulam
+
+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.

sentimentscopeai-1.0.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: sentimentscopeai
+Version: 1.0.0
+Summary: Transformer-based review sentiment analysis and actionable insight generation.
+Author: Vignesh Thondikulam
+License: MIT
+Project-URL: Homepage, https://github.com/VigneshT24/SentimentScopeAI
+Project-URL: Repository, https://github.com/VigneshT24/SentimentScopeAI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: transformers
+Dynamic: license-file
+
+# SentimentScopeAI
+## Fine-Grained Review Sentiment Analysis & Insight Generation
+
+SentimentScopeAI is a Python-based NLP system that leverages PyTorch and HuggingFace Transformers (pre-trained models) to move beyond binary sentiment classification and instead analyze, interpret, and reason over collections of user reviews to help companies improve their products/services
+
+Rather than treating sentiment analysis as a black-box prediction task, this project focuses on semantic interpretation, explainability, and the generation of aggregated insights, simulating how a human analyst would read and summarize large volumes of feedback.
+
+## Project Motivation
+
+SentimentScopeAI is designed to answer deeper, more practical questions:
+* What does a numerical rating actually mean in context?
+* How consistent are opinions across many reviews?
+* What actionable advice can be derived from collective sentiment?
+
+## Features
+
+1.) Pre-Trained Sentiment Modeling (PyTorch + HuggingFace)
+* Uses pre-trained transformer models from HuggingFace
+* Integrated via PyTorch for inference and extensibility
+* Enables robust sentiment understanding without training from scratch
+* Designed so downstream logic operates on model outputs, not raw text
+
+2.) Rating Meaning Inference
+* Implemented the infer_rating_meaning() function
+* Converts numerical ratings (1–5) into semantic interpretations
+* Uses sentiment signals, linguistic tone, and contextual cues
+* Handles:
+  * Mixed sentiment
+  * Neutral or ambiguous phrasing
+  * Disagreement between rating score and review text
+
+Example:
+```
+Rating: 3  
+→ "Mixed experience with noticeable positives and recurring issues."
+```
+
+3.) Structured Review Ingestion
+* Reviews are parsed in a structured format (JSON / Python objects)
+* Each review preserves:
+  * Company name
+  * Service or product name
+  * Full review text
+* Enables batch analysis across multiple reviews per service
+
+4.) Explainable, Deterministic Pipeline
+* Downstream reasoning is transparent and testable
+* No opaque end-to-end predictions
+* Model outputs are interpreted rather than blindly trusted
+* Designed for debugging, auditing, and future research extension
+
+5.) Cross-Review Advice Generation
+* Read all reviews for a given product or service
+* Aggregate sentiment signals across users
+* Detect recurring strengths and weaknesses
+* Generate actionable advice for stakeholders
+
+These steps transition the system from analysis → reasoning → recommendation generation.
+
+Example:
+```
+For <Service Name>: overall sentiment is mixed reflecting a balance
+of positive and negative feedback
+
+The following specific issues were extracted from negative reviews:
+
+1) missed a few appointments
+2) not signed into the right account
+3) interface is horrible
+4) find the interface confusing
+5) invitations and acceptances are terrible
+```
+
+## System Architecture Overview
+
+```
+Reviews
+  ↓
+Pre-trained Transformer (HuggingFace + PyTorch)
+  ↓
+Sentiment Signals
+  ↓
+Rating Meaning Inference
+  ↓
+Cross-Review Aggregation
+  ↓
+Advice Generation
+```
+
+## Tech-Stack
+
+* **Language**: Python
+* **Deep Learning**: PyTorch
+* **NLP Models**: HuggingFace Transformers (pre-trained), Flan-T5
+* **Concepts**:
+  * Sentiment analysis
+  * Semantic interpretation
+  * Explainable AI
+* **Aggregated reasoning**
+* **Data Handling**: JSON, Python data structures
+
+## Project Structure (Simplified)
+
+```
+SentimentScopeAI/
+│
+├── sentimentscopeAI.py        # Core sentiment + inference logic
+├── README.md                  # Documentation
+└── requirements.txt           # Dependencies (PyTorch, Transformers)
+```
+
+## Why SentimentScopeAI?
+
+Every organization collects feedback - but reading hundreds or thousands of reviews is time-consuming, inconsistent, and difficult to scale. Important insights are often buried in repetitive comments, while actionable criticism gets overlooked.
+
+SentimentScopeAI is designed to do the heavy lifting:
+* Reads and analyzes large volumes of reviews automatically
+* Identifies recurring pain points across users
+* Distills unstructured feedback into clear, constructive, and actionable advice
+* Helps teams focus on what to improve rather than sorting through raw text
+
+## Installation & Usage
+
+SentimentScopeAI is distributed as a Python package and can be installed via pip:
+
+```
+pip install sentimentscopeai
+```
+
+Requirements:
+* Python 3.9 or newer (Python 3.10 or above is recommended for best performance and compatibility)
+* PyTorch
+* HuggingFace Transformers
+* Internet connection on first run (to download pre-trained models)
+
+All required dependencies are automatically installed with the package.
+
+## Basic Usage:
+
+```python
+from sentimentscopeai import SentimentScopeAI
+
+# MAKE SURE TO PASS IN: current_folder/json_file_name, not just json_file_name
+review_bot = ssAI.SentimentScopeAI("Testing/companyreview.json")
+
+print(review_bot.generate_summary())
+```
+
+What Happens Internally
+
+* Reviews are parsed from a structured JSON file
+* Sentiment is inferred using pre-trained transformer models (PyTorch + HuggingFace)
+* Rating meanings are semantically interpreted
+* Flan-T5 generates human-readable, actionable advice based on aggregated feedback
+
+## IMPORTANT NOTICE:
+
+1.) Strict JSON Input Format (Required)
+
+SentimentScopeAI only accepts JSON input.
+The review file must follow this exact structure:
+
+```json
+[
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Full user review text goes here."
+  },
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Another review text."
+  }
+]
+```
+
+Missing fields, incorrect keys, or non-JSON formats will cause parsing errors.
+
+2.) JSON Must Be Valid
+
+* File must be UTF-8 encoded
+* No trailing commas
+* No comments
+* Must be a list ([]), not a single object
+
+You can use a JSON validator if you are unsure.
+
+3.) One Company & One Service per JSON File (Required)
+
+EXAMPLE:
+```json
+[
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "The interface is clean and easy to use."
+  },
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "Reminders are helpful, but syncing can be slow."
+  }
+]
+```
+
+This restriction is intentional:
+
+* Sentiment aggregation assumes a single shared context
+* Advice generation relies on consistent product-level patterns
+* Mixing services can produce misleading summaries and recommendations
+
+If you need to analyze multiple products or companies, create separate JSON files and run SentimentScopeAI independently for each dataset.
+
+4.) Model Loading Behavior
+
+* Transformer models are lazy-loaded
+* First run may take longer due to:
+  * Model downloads
+  * Tokenizer initialization
+* Subsequent runs are significantly faster
+
+This design improves startup efficiency and memory usage.
+
+
+**SentimentScopeAI is provided as-is and is not liable for any damages arising from its use.
+Do not include personal, sensitive, or confidential information in review data.
+All input data is processed locally and is not used for model training or retained beyond execution.
+Users are responsible for ensuring ethical and appropriate use of the system.**

sentimentscopeai-1.0.0/README.md

@@ -0,0 +1,229 @@
+# SentimentScopeAI
+## Fine-Grained Review Sentiment Analysis & Insight Generation
+
+SentimentScopeAI is a Python-based NLP system that leverages PyTorch and HuggingFace Transformers (pre-trained models) to move beyond binary sentiment classification and instead analyze, interpret, and reason over collections of user reviews to help companies improve their products/services
+
+Rather than treating sentiment analysis as a black-box prediction task, this project focuses on semantic interpretation, explainability, and the generation of aggregated insights, simulating how a human analyst would read and summarize large volumes of feedback.
+
+## Project Motivation
+
+SentimentScopeAI is designed to answer deeper, more practical questions:
+* What does a numerical rating actually mean in context?
+* How consistent are opinions across many reviews?
+* What actionable advice can be derived from collective sentiment?
+
+## Features
+
+1.) Pre-Trained Sentiment Modeling (PyTorch + HuggingFace)
+* Uses pre-trained transformer models from HuggingFace
+* Integrated via PyTorch for inference and extensibility
+* Enables robust sentiment understanding without training from scratch
+* Designed so downstream logic operates on model outputs, not raw text
+
+2.) Rating Meaning Inference
+* Implemented the infer_rating_meaning() function
+* Converts numerical ratings (1–5) into semantic interpretations
+* Uses sentiment signals, linguistic tone, and contextual cues
+* Handles:
+  * Mixed sentiment
+  * Neutral or ambiguous phrasing
+  * Disagreement between rating score and review text
+
+Example:
+```
+Rating: 3  
+→ "Mixed experience with noticeable positives and recurring issues."
+```
+
+3.) Structured Review Ingestion
+* Reviews are parsed in a structured format (JSON / Python objects)
+* Each review preserves:
+  * Company name
+  * Service or product name
+  * Full review text
+* Enables batch analysis across multiple reviews per service
+
+4.) Explainable, Deterministic Pipeline
+* Downstream reasoning is transparent and testable
+* No opaque end-to-end predictions
+* Model outputs are interpreted rather than blindly trusted
+* Designed for debugging, auditing, and future research extension
+
+5.) Cross-Review Advice Generation
+* Read all reviews for a given product or service
+* Aggregate sentiment signals across users
+* Detect recurring strengths and weaknesses
+* Generate actionable advice for stakeholders
+
+These steps transition the system from analysis → reasoning → recommendation generation.
+
+Example:
+```
+For <Service Name>: overall sentiment is mixed reflecting a balance
+of positive and negative feedback
+
+The following specific issues were extracted from negative reviews:
+
+1) missed a few appointments
+2) not signed into the right account
+3) interface is horrible
+4) find the interface confusing
+5) invitations and acceptances are terrible
+```
+
+## System Architecture Overview
+
+```
+Reviews
+  ↓
+Pre-trained Transformer (HuggingFace + PyTorch)
+  ↓
+Sentiment Signals
+  ↓
+Rating Meaning Inference
+  ↓
+Cross-Review Aggregation
+  ↓
+Advice Generation
+```
+
+## Tech-Stack
+
+* **Language**: Python
+* **Deep Learning**: PyTorch
+* **NLP Models**: HuggingFace Transformers (pre-trained), Flan-T5
+* **Concepts**:
+  * Sentiment analysis
+  * Semantic interpretation
+  * Explainable AI
+* **Aggregated reasoning**
+* **Data Handling**: JSON, Python data structures
+
+## Project Structure (Simplified)
+
+```
+SentimentScopeAI/
+│
+├── sentimentscopeAI.py        # Core sentiment + inference logic
+├── README.md                  # Documentation
+└── requirements.txt           # Dependencies (PyTorch, Transformers)
+```
+
+## Why SentimentScopeAI?
+
+Every organization collects feedback - but reading hundreds or thousands of reviews is time-consuming, inconsistent, and difficult to scale. Important insights are often buried in repetitive comments, while actionable criticism gets overlooked.
+
+SentimentScopeAI is designed to do the heavy lifting:
+* Reads and analyzes large volumes of reviews automatically
+* Identifies recurring pain points across users
+* Distills unstructured feedback into clear, constructive, and actionable advice
+* Helps teams focus on what to improve rather than sorting through raw text
+
+## Installation & Usage
+
+SentimentScopeAI is distributed as a Python package and can be installed via pip:
+
+```
+pip install sentimentscopeai
+```
+
+Requirements:
+* Python 3.9 or newer (Python 3.10 or above is recommended for best performance and compatibility)
+* PyTorch
+* HuggingFace Transformers
+* Internet connection on first run (to download pre-trained models)
+
+All required dependencies are automatically installed with the package.
+
+## Basic Usage:
+
+```python
+from sentimentscopeai import SentimentScopeAI
+
+# MAKE SURE TO PASS IN: current_folder/json_file_name, not just json_file_name
+review_bot = ssAI.SentimentScopeAI("Testing/companyreview.json")
+
+print(review_bot.generate_summary())
+```
+
+What Happens Internally
+
+* Reviews are parsed from a structured JSON file
+* Sentiment is inferred using pre-trained transformer models (PyTorch + HuggingFace)
+* Rating meanings are semantically interpreted
+* Flan-T5 generates human-readable, actionable advice based on aggregated feedback
+
+## IMPORTANT NOTICE:
+
+1.) Strict JSON Input Format (Required)
+
+SentimentScopeAI only accepts JSON input.
+The review file must follow this exact structure:
+
+```json
+[
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Full user review text goes here."
+  },
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Another review text."
+  }
+]
+```
+
+Missing fields, incorrect keys, or non-JSON formats will cause parsing errors.
+
+2.) JSON Must Be Valid
+
+* File must be UTF-8 encoded
+* No trailing commas
+* No comments
+* Must be a list ([]), not a single object
+
+You can use a JSON validator if you are unsure.
+
+3.) One Company & One Service per JSON File (Required)
+
+EXAMPLE:
+```json
+[
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "The interface is clean and easy to use."
+  },
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "Reminders are helpful, but syncing can be slow."
+  }
+]
+```
+
+This restriction is intentional:
+
+* Sentiment aggregation assumes a single shared context
+* Advice generation relies on consistent product-level patterns
+* Mixing services can produce misleading summaries and recommendations
+
+If you need to analyze multiple products or companies, create separate JSON files and run SentimentScopeAI independently for each dataset.
+
+4.) Model Loading Behavior
+
+* Transformer models are lazy-loaded
+* First run may take longer due to:
+  * Model downloads
+  * Tokenizer initialization
+* Subsequent runs are significantly faster
+
+This design improves startup efficiency and memory usage.
+
+
+**SentimentScopeAI is provided as-is and is not liable for any damages arising from its use.
+Do not include personal, sensitive, or confidential information in review data.
+All input data is processed locally and is not used for model training or retained beyond execution.
+Users are responsible for ensuring ethical and appropriate use of the system.**

sentimentscopeai-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sentimentscopeai"
+version = "1.0.0"
+description = "Transformer-based review sentiment analysis and actionable insight generation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Vignesh Thondikulam" }
+]
+
+dependencies = [
+  "torch",
+  "transformers"
+]
+
+[project.urls]
+Homepage = "https://github.com/VigneshT24/SentimentScopeAI"
+Repository = "https://github.com/VigneshT24/SentimentScopeAI"

sentimentscopeai-1.0.0/sentimentscopeai/__init__.py

@@ -0,0 +1,2 @@
+from .core import SentimentScopeAI
+__all__ = ["SentimentScopeAI"]

sentimentscopeai-1.0.0/sentimentscopeai/core.py

@@ -0,0 +1,373 @@
+import torch
+import json
+import os
+import string
+import random
+import textwrap
+from transformers import (AutoTokenizer, AutoModelForSequenceClassification, AutoModelForSeq2SeqLM, T5ForConditionalGeneration, T5Tokenizer, set_seed)
+
+class SentimentScopeAI:
+    ## Private attributes
+    __hf_model_name = None
+    __hf_tokenizer = None
+    __hf_model = None
+    __pytorch_model_name = None
+    __pytorch_tokenizer = None
+    __pytorch_model = None
+    __json_file_path = None
+    __service_name = None
+    __device = None
+    __notable_negatives = []
+    __extraction_model = None
+    __extraction_tokenizer = None
+
+    def __init__(self, file_path):
+        """Initialize the SentimentScopeAI class with the specified JSON file path."""
+        self.__hf_model_name = "Vamsi/T5_Paraphrase_Paws"
+        self.__pytorch_model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
+        self.__extraction_model_name = "google/flan-t5-large"
+        self.__json_file_path = os.path.abspath(file_path)
+        self.__device = "cuda" if torch.cuda.is_available() else "cpu"
+
+    @property
+    def hf_model(self):
+        """Lazy loader for the Paraphrase Model."""
+        if self.__hf_model is None:
+            self.__hf_model = AutoModelForSeq2SeqLM.from_pretrained(self.__hf_model_name)
+        return self.__hf_model
+
+    @property
+    def hf_tokenizer(self):
+        """Lazy loader for the T5 Tokenizer."""
+        if self.__hf_tokenizer is None:
+            self.__hf_tokenizer = T5Tokenizer.from_pretrained(self.__hf_model_name, legacy=True)
+        return self.__hf_tokenizer
+
+    @property
+    def pytorch_tokenizer(self):
+        """Lazy loader for the PyTorch Tokenizer."""
+        if self.__pytorch_tokenizer is None:
+            self.__pytorch_tokenizer = AutoTokenizer.from_pretrained(self.__pytorch_model_name)
+        return self.__pytorch_tokenizer
+
+    @property
+    def pytorch_model(self):
+        """Lazy loader for the PyTorch Model."""
+        if self.__pytorch_model is None:
+            self.__pytorch_model = AutoModelForSequenceClassification.from_pretrained(
+                self.__pytorch_model_name
+            ).to(self.__device)
+        return self.__pytorch_model
+
+    @property
+    def extraction_model(self):
+        """Lazy loader for the Flan-T5 extraction model."""
+        if self.__extraction_model is None:
+            self.__extraction_model = T5ForConditionalGeneration.from_pretrained(
+                self.__extraction_model_name
+            ).to(self.__device)
+        return self.__extraction_model
+
+    @property
+    def extraction_tokenizer(self):
+        """Lazy loader for the Flan-T5 tokenizer."""
+        if self.__extraction_tokenizer is None:
+            self.__extraction_tokenizer = AutoTokenizer.from_pretrained(
+                self.__extraction_model_name
+            )
+        return self.__extraction_tokenizer
+
+    def __get_predictive_star(self, text) -> int:
+        """
+            Predict the sentiment star rating for the given text review.
+
+            Args:
+                text (str): The text review to analyze.
+            Returns:
+                int: The predicted star rating (1 to 5).
+        """
+        inputs = self.pytorch_tokenizer(text, return_tensors="pt").to(self.__device)
+
+        with torch.no_grad():
+            outputs = self.pytorch_model(**inputs)
+
+        logits = outputs.logits
+        prediction = torch.argmax(logits, dim=-1).item()
+
+        num_star = prediction + 1
+        return num_star
+
+    def __calculate_all_review(self) -> int:
+        """
+            Calculate and print the predicted star ratings for all reviews in the JSON file.
+
+            Args:
+                None
+            Returns:
+                tuple: A tuple containing the total number of reviews and the average star rating.
+        """
+        try:
+            with open(self.__json_file_path, 'r') as reviews_file:
+                all_reviews = json.load(reviews_file)
+                sum = 0
+                num_reviews = 0
+                for i, entry in enumerate(all_reviews, 1):
+                    single_review_rating = self.__get_predictive_star(entry['review'])
+                    sum += single_review_rating
+                    self.__service_name = entry['service_name']
+                    num_reviews = i
+            return (sum / num_reviews) if num_reviews != 0 else 0
+        except FileNotFoundError:
+            print("The JSON file you inputted doesn't exist. Please input a valid company review file.")
+        except json.JSONDecodeError:
+            print("Could not decode JSON file. Check for valid JSON syntax.")
+        except PermissionError:
+            print("Permission denied to open the JSON file.")
+        except Exception as e:
+            print(f"An unexpected error occured: {e}")
+    
+    def __paraphrase_statement(self, statement: str) -> list[str]:
+        """Generates multiple unique paraphrased variations of a given string.
+
+        Uses a Hugging Face transformer model to generate five variations of the 
+        input statement. Results are normalized (lowercased, stripped of 
+        punctuation, and whitespace-cleaned) to ensure uniqueness.
+
+        Args:
+            statement (str): The text to be paraphrased.
+
+        Returns:
+            list[str]: A list of unique, cleaned paraphrased strings. 
+                Returns [""] if the input is None, empty, or whitespace.
+        """
+        set_seed(random.randint(0, 2**32 - 1))
+        
+        if statement is None or statement.isspace() or statement == "":
+            return [""]
+
+        prompt = f"paraphrase: {statement}"
+        encoder = self.hf_tokenizer(prompt, return_tensors="pt", truncation=True)
+
+        output = self.hf_model.generate(
+            **encoder,
+            max_length=48,
+            do_sample=True,
+            top_p=0.99,
+            top_k=50,
+            temperature= 1.0,
+            num_return_sequences=5,
+            repetition_penalty=1.2,
+        )
+
+        resultant = self.hf_tokenizer.batch_decode(output, skip_special_tokens=True)
+        
+        seen = set()
+        unique = []
+        translator = str.maketrans('', '', string.punctuation)
+
+        for list_sentence in resultant:
+            list_sentence = list_sentence.lower().strip()
+            list_sentence = list_sentence.translate(translator)
+            while (list_sentence[-1:] == ' '):
+                list_sentence = list_sentence[:-1]
+            seen.add(list_sentence)
+
+        for set_sentence in seen:
+            unique.append(set_sentence)
+
+        return unique
+    
+    def __infer_rating_meaning(self) -> str:
+        """Translates numerical rating scores into descriptive, paraphrased sentiment.
+
+        Calculates the aggregate review score and maps it to a sentiment category 
+        (ranging from 'Very Negative' to 'Very Positive'). To avoid repetitive 
+        output, the final description is passed through an AI paraphrasing 
+        engine and a random variation is selected.
+
+        Returns:
+            str: A randomly selected paraphrased sentence describing the 
+                overall service sentiment.
+        """
+        overall_rating = self.__calculate_all_review()
+
+        def generate_sentence(rating_summ):
+            return f"For {self.__service_name}: " + random.choice(self.__paraphrase_statement(rating_summ)).strip()
+
+        if 1.0 <= overall_rating < 2.0:
+            return generate_sentence("Overall sentiment is very negative, indicating widespread dissatisfaction among users.")
+        elif 2.0 <= overall_rating < 3.0:
+            return generate_sentence("Overall sentiment is negative, suggesting notable dissatisfaction across reviews.")
+        elif 3.0 <= overall_rating < 4.0:
+            return generate_sentence("Overall sentiment is mixed, reflecting a balance of positive and negative feedback.")
+        elif 4.0 <= overall_rating < 5.0:
+            return generate_sentence("Overall sentiment is positive, indicating general user satisfaction.")
+        else:
+            return generate_sentence("Overall sentiment is very positive, reflecting strong user approval and satisfaction.")
+
+    def __extract_negative_aspects(self, review: str) -> list[str]:
+        """
+        Extract actionable negative aspects from a review using AI-based text generation.
+        
+        This method uses the Flan-T5 language model to identify specific, constructive
+        problems mentioned in a review. Unlike simple sentiment analysis, this extracts
+        concrete issues that describe what is broken, missing, or difficult - filtering
+        out vague emotional words like "horrible" or "bad".
+        
+        The extraction focuses on actionable feedback that can help improve a product
+        or service, such as "notifications arrive at wrong times" rather than just
+        "notifications are bad".
+        
+        Args:
+            review (str): The review text to analyze for negative aspects.
+        
+        Returns:
+            list[str]: A list of specific problem phrases extracted from the review.
+                    Each phrase describes a concrete issue. Returns an empty list
+                    if the review is empty, contains only whitespace, or no 
+                    problems are identified.
+        
+        Note:
+            This method uses the Flan-T5 model which is loaded lazily on first use.
+            Processing time depends on review length and available hardware (CPU/GPU).
+            Very short outputs (≤3 characters) are filtered out as likely artifacts.
+        """
+        if not review or review.isspace():
+            return []
+        
+        prompt = f"""What problems does this review mention? List each as a brief phrase.
+        Each problem should be describing what is wrong, DON'T OUTPUT one word lines like "horrible" or "bad".
+        Make sure they are CONSTRUCTIVE CRITICISM THAT CAN HELP SOMEONE IMPROVE
+
+        Review: {review}
+
+        Problems mentioned:"""
+
+        inputs = self.extraction_tokenizer(
+            prompt, 
+            return_tensors="pt",
+            max_length=512,
+            truncation=True
+        ).to(self.__device)
+
+        outputs = self.extraction_model.generate(
+            **inputs,
+            max_length=150,
+            num_beams=4,
+            temperature=0.7,
+            do_sample=True,
+            top_p=0.9,
+            early_stopping=True
+        )
+
+        result = self.extraction_tokenizer.decode(outputs[0], skip_special_tokens=True)
+        if result.strip().lower() in ['none', 'none.', 'no problems', '']:
+            return[]
+        
+        issues = []
+        for line in result.split('\n'):
+            line = line.strip()
+            line = line.lstrip('•-*1234567890.) ')
+            if line and len(line) > 3:
+                issues.append(line)
+        
+        return issues
+    
+    def output_all_reviews(self) -> None:
+        """
+            Output all reviews from the JSON file in a formatted manner.
+
+            Args:
+                None
+            Returns:
+                None
+        """
+        try:
+            with open(self.__json_file_path, 'r') as file:
+                company_reviews = json.load(file)
+                for i, entry in enumerate(company_reviews, 1):
+                    print(f"Review #{i}")
+                    print(f"Company Name: {entry['company_name']}")
+                    print(f"Service Name: {entry['service_name']}")
+                    print(f"Review: {textwrap.fill(entry['review'], width=70)}")
+                    print("\n\n")
+        except FileNotFoundError:
+            print("The JSON file you inputted doesn't exist. Please input a valid company review file.")
+        except json.JSONDecodeError:
+            print("Could not decode JSON file. Check for valid JSON syntax.")
+        except PermissionError:
+            print("Permission denied to open the JSON file.")
+        except Exception as e:
+            print(f"An unexpected error occured: {e}")
+
+    def generate_summary(self) -> str:
+        """
+        Generate a formatted sentiment summary based on user reviews for a service.
+
+        This method reads a JSON file containing user reviews, infers the overall
+        sentiment rating, and produces a structured, human-readable summary.
+        The summary includes:
+            - A concise explanation of the inferred sentiment rating
+            - A numbered list of representative negative reviews (up to 3)
+            - A numbered list of representative positive reviews (up to 3)
+
+        Long-form reviews are wrapped to a fixed line width while preserving
+        list structure and readability.
+
+        The method is resilient to common file and parsing errors and will
+        emit descriptive messages if the input file cannot be accessed or
+        decoded properly.
+
+        Returns:
+            str
+                A multi-paragraph, text-wrapped sentiment summary suitable for
+                console output, logs, or reports.
+
+        Raises:
+            None
+                All exceptions are handled internally with descriptive error
+                messages to prevent interruption of execution.
+        """
+        try:
+            reviews = []
+            with open(self.__json_file_path, 'r') as file:
+                company_reviews = json.load(file)
+                for i, entry in enumerate(company_reviews, 1):
+                    if self.__get_predictive_star(entry['review']) <= 2:
+                        for part in self.__extract_negative_aspects(entry['review']):
+                            self.__notable_negatives.append(part)
+                    self.__service_name = entry['service_name']
+                    reviews.append(entry['review'])
+        except FileNotFoundError:
+            print("The JSON file you inputted doesn't exist. Please input a valid company review file.")
+        except json.JSONDecodeError:
+            print("Could not decode JSON file. Check for valid JSON syntax.")
+        except PermissionError:
+            print("Permission denied to open the JSON file.")
+        except Exception as e:
+            print(f"An unexpected error occured: {e}")
+
+        def format_numbered_list(items):
+            if not items:
+                return "None found"
+
+            lines = []
+            for i, item in enumerate(items, start=1):
+                prefix = f"{i}) "
+                wrapper = textwrap.TextWrapper(
+                    width=70,
+                    initial_indent=prefix,
+                    subsequent_indent=" " * len(prefix) + "   "
+                )
+                lines.append(wrapper.fill(str(item)))
+            return "\n".join(lines)
+
+        rating_meaning = self.__infer_rating_meaning()
+            
+        parts = [
+            textwrap.fill(rating_meaning, width=70),
+            textwrap.fill("The following reviews highlight some concerns users have expressed:", width=70),
+            format_numbered_list(self.__notable_negatives)
+        ]
+
+        return "\n\n".join(parts)

sentimentscopeai-1.0.0/sentimentscopeai.egg-info/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: sentimentscopeai
+Version: 1.0.0
+Summary: Transformer-based review sentiment analysis and actionable insight generation.
+Author: Vignesh Thondikulam
+License: MIT
+Project-URL: Homepage, https://github.com/VigneshT24/SentimentScopeAI
+Project-URL: Repository, https://github.com/VigneshT24/SentimentScopeAI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: transformers
+Dynamic: license-file
+
+# SentimentScopeAI
+## Fine-Grained Review Sentiment Analysis & Insight Generation
+
+SentimentScopeAI is a Python-based NLP system that leverages PyTorch and HuggingFace Transformers (pre-trained models) to move beyond binary sentiment classification and instead analyze, interpret, and reason over collections of user reviews to help companies improve their products/services
+
+Rather than treating sentiment analysis as a black-box prediction task, this project focuses on semantic interpretation, explainability, and the generation of aggregated insights, simulating how a human analyst would read and summarize large volumes of feedback.
+
+## Project Motivation
+
+SentimentScopeAI is designed to answer deeper, more practical questions:
+* What does a numerical rating actually mean in context?
+* How consistent are opinions across many reviews?
+* What actionable advice can be derived from collective sentiment?
+
+## Features
+
+1.) Pre-Trained Sentiment Modeling (PyTorch + HuggingFace)
+* Uses pre-trained transformer models from HuggingFace
+* Integrated via PyTorch for inference and extensibility
+* Enables robust sentiment understanding without training from scratch
+* Designed so downstream logic operates on model outputs, not raw text
+
+2.) Rating Meaning Inference
+* Implemented the infer_rating_meaning() function
+* Converts numerical ratings (1–5) into semantic interpretations
+* Uses sentiment signals, linguistic tone, and contextual cues
+* Handles:
+  * Mixed sentiment
+  * Neutral or ambiguous phrasing
+  * Disagreement between rating score and review text
+
+Example:
+```
+Rating: 3  
+→ "Mixed experience with noticeable positives and recurring issues."
+```
+
+3.) Structured Review Ingestion
+* Reviews are parsed in a structured format (JSON / Python objects)
+* Each review preserves:
+  * Company name
+  * Service or product name
+  * Full review text
+* Enables batch analysis across multiple reviews per service
+
+4.) Explainable, Deterministic Pipeline
+* Downstream reasoning is transparent and testable
+* No opaque end-to-end predictions
+* Model outputs are interpreted rather than blindly trusted
+* Designed for debugging, auditing, and future research extension
+
+5.) Cross-Review Advice Generation
+* Read all reviews for a given product or service
+* Aggregate sentiment signals across users
+* Detect recurring strengths and weaknesses
+* Generate actionable advice for stakeholders
+
+These steps transition the system from analysis → reasoning → recommendation generation.
+
+Example:
+```
+For <Service Name>: overall sentiment is mixed reflecting a balance
+of positive and negative feedback
+
+The following specific issues were extracted from negative reviews:
+
+1) missed a few appointments
+2) not signed into the right account
+3) interface is horrible
+4) find the interface confusing
+5) invitations and acceptances are terrible
+```
+
+## System Architecture Overview
+
+```
+Reviews
+  ↓
+Pre-trained Transformer (HuggingFace + PyTorch)
+  ↓
+Sentiment Signals
+  ↓
+Rating Meaning Inference
+  ↓
+Cross-Review Aggregation
+  ↓
+Advice Generation
+```
+
+## Tech-Stack
+
+* **Language**: Python
+* **Deep Learning**: PyTorch
+* **NLP Models**: HuggingFace Transformers (pre-trained), Flan-T5
+* **Concepts**:
+  * Sentiment analysis
+  * Semantic interpretation
+  * Explainable AI
+* **Aggregated reasoning**
+* **Data Handling**: JSON, Python data structures
+
+## Project Structure (Simplified)
+
+```
+SentimentScopeAI/
+│
+├── sentimentscopeAI.py        # Core sentiment + inference logic
+├── README.md                  # Documentation
+└── requirements.txt           # Dependencies (PyTorch, Transformers)
+```
+
+## Why SentimentScopeAI?
+
+Every organization collects feedback - but reading hundreds or thousands of reviews is time-consuming, inconsistent, and difficult to scale. Important insights are often buried in repetitive comments, while actionable criticism gets overlooked.
+
+SentimentScopeAI is designed to do the heavy lifting:
+* Reads and analyzes large volumes of reviews automatically
+* Identifies recurring pain points across users
+* Distills unstructured feedback into clear, constructive, and actionable advice
+* Helps teams focus on what to improve rather than sorting through raw text
+
+## Installation & Usage
+
+SentimentScopeAI is distributed as a Python package and can be installed via pip:
+
+```
+pip install sentimentscopeai
+```
+
+Requirements:
+* Python 3.9 or newer (Python 3.10 or above is recommended for best performance and compatibility)
+* PyTorch
+* HuggingFace Transformers
+* Internet connection on first run (to download pre-trained models)
+
+All required dependencies are automatically installed with the package.
+
+## Basic Usage:
+
+```python
+from sentimentscopeai import SentimentScopeAI
+
+# MAKE SURE TO PASS IN: current_folder/json_file_name, not just json_file_name
+review_bot = ssAI.SentimentScopeAI("Testing/companyreview.json")
+
+print(review_bot.generate_summary())
+```
+
+What Happens Internally
+
+* Reviews are parsed from a structured JSON file
+* Sentiment is inferred using pre-trained transformer models (PyTorch + HuggingFace)
+* Rating meanings are semantically interpreted
+* Flan-T5 generates human-readable, actionable advice based on aggregated feedback
+
+## IMPORTANT NOTICE:
+
+1.) Strict JSON Input Format (Required)
+
+SentimentScopeAI only accepts JSON input.
+The review file must follow this exact structure:
+
+```json
+[
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Full user review text goes here."
+  },
+  {
+    "company_name": "Company Name",
+    "service_name": "Product or Service Name",
+    "review": "Another review text."
+  }
+]
+```
+
+Missing fields, incorrect keys, or non-JSON formats will cause parsing errors.
+
+2.) JSON Must Be Valid
+
+* File must be UTF-8 encoded
+* No trailing commas
+* No comments
+* Must be a list ([]), not a single object
+
+You can use a JSON validator if you are unsure.
+
+3.) One Company & One Service per JSON File (Required)
+
+EXAMPLE:
+```json
+[
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "The interface is clean and easy to use."
+  },
+  {
+    "company_name": "Google",
+    "service_name": "Google Calendar",
+    "review": "Reminders are helpful, but syncing can be slow."
+  }
+]
+```
+
+This restriction is intentional:
+
+* Sentiment aggregation assumes a single shared context
+* Advice generation relies on consistent product-level patterns
+* Mixing services can produce misleading summaries and recommendations
+
+If you need to analyze multiple products or companies, create separate JSON files and run SentimentScopeAI independently for each dataset.
+
+4.) Model Loading Behavior
+
+* Transformer models are lazy-loaded
+* First run may take longer due to:
+  * Model downloads
+  * Tokenizer initialization
+* Subsequent runs are significantly faster
+
+This design improves startup efficiency and memory usage.
+
+
+**SentimentScopeAI is provided as-is and is not liable for any damages arising from its use.
+Do not include personal, sensitive, or confidential information in review data.
+All input data is processed locally and is not used for model training or retained beyond execution.
+Users are responsible for ensuring ethical and appropriate use of the system.**

sentimentscopeai-1.0.0/sentimentscopeai.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+sentimentscopeai/__init__.py
+sentimentscopeai/core.py
+sentimentscopeai.egg-info/PKG-INFO
+sentimentscopeai.egg-info/SOURCES.txt
+sentimentscopeai.egg-info/dependency_links.txt
+sentimentscopeai.egg-info/requires.txt
+sentimentscopeai.egg-info/top_level.txt

sentimentscopeai-1.0.0/sentimentscopeai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sentimentscopeai-1.0.0/sentimentscopeai.egg-info/requires.txt

@@ -0,0 +1,2 @@
+torch
+transformers

sentimentscopeai-1.0.0/sentimentscopeai.egg-info/top_level.txt

@@ -0,0 +1 @@
+sentimentscopeai

sentimentscopeai-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+