sentix 1.0.0__py3-none-any.whl

sentix/__init__.py

@@ -0,0 +1,18 @@
+"""
+Sentix
+======
+
+A lightweight rule-based sentiment analysis library for Python.
+"""
+
+from .analyzer import SentimentAnalyzer
+from .result import SentimentResult
+
+
+__version__ = "1.0.0"
+
+
+__all__ = [
+    "SentimentAnalyzer",
+    "SentimentResult",
+]

sentix/analyzer.py

@@ -0,0 +1,224 @@
+from .tokenizer import tokenize
+
+from .scorer import (
+    score_tokens_with_evidence,
+    punctuation_modifier,
+)
+
+from .confidence import calculate_confidence
+from .result import SentimentResult
+
+from .rules.emotion import detect_emotions
+from .rules.aspect import detect_aspects
+from .rules.context import analyze_context
+from .rules.contrast import analyze_contrast
+
+
+def normalize_scores(
+    positive: float,
+    negative: float,
+) -> tuple[float, float, float]:
+    """
+    Convert positive / negative evidence into
+    normalized probabilities.
+
+    Neutral receives the remaining probability.
+    """
+
+    total = positive + negative
+
+    if total == 0:
+        return 0.0, 0.0, 1.0
+
+    positive_ratio = positive / total
+    negative_ratio = negative / total
+
+    return (
+        positive_ratio,
+        negative_ratio,
+        0.0,
+    )
+
+
+class SentimentAnalyzer:
+
+    def predict(
+        self,
+        text: str,
+    ) -> SentimentResult:
+
+        # ====================================================
+        # TOKENIZATION
+        # ====================================================
+
+        tokens = tokenize(text)
+
+        # ====================================================
+        # BASE SENTIMENT SCORING
+        # ====================================================
+
+        (
+            score,
+            positive,
+            negative,
+            evidence,
+        ) = score_tokens_with_evidence(
+            tokens,
+            text,
+        )
+
+        # ====================================================
+        # PUNCTUATION
+        # ====================================================
+
+        punctuation_factor = (
+            punctuation_modifier(text)
+        )
+
+        if punctuation_factor != 1.0:
+            raw_score = (
+                score / punctuation_factor
+            )
+        else:
+            raw_score = score
+
+        # ====================================================
+        # EMOTIONS
+        # ====================================================
+
+        emotions = detect_emotions(
+            tokens
+        )
+
+        # ====================================================
+        # CONTEXT
+        # ====================================================
+
+        context = analyze_context(
+            tokens
+        )
+
+        # ====================================================
+        # CONTRAST
+        # ====================================================
+
+        contrast = analyze_contrast(
+            tokens
+        )
+
+        # ====================================================
+        # NORMALIZED PROBABILITIES
+        # ====================================================
+
+        (
+            positive_prob,
+            negative_prob,
+            neutral_prob,
+        ) = normalize_scores(
+            positive,
+            negative,
+        )
+
+        # ====================================================
+        # LABEL DECISION
+        # ====================================================
+
+        label = None
+
+        # ----------------------------------------------------
+        # CONTRAST HAS HIGH PRIORITY
+        #
+        # If the contrast engine has identified a semantic
+        # relationship, use its decision before falling back
+        # to the global sentiment score.
+        # ----------------------------------------------------
+
+        if (
+            contrast.get("has_contrast")
+            and contrast.get("label") is not None
+        ):
+            label = contrast["label"]
+
+        # ----------------------------------------------------
+        # DIFFERENT SENTENCE TARGETS
+        #
+        # Example:
+        #
+        # The camera is terrible.
+        # The screen is amazing.
+        #
+        # -> mixed
+        # ----------------------------------------------------
+
+        elif (
+            context.get(
+                "different_sentence_targets",
+                False,
+            )
+            and positive > 0.5
+            and negative > 0.5
+        ):
+            label = "mixed"
+
+        # ----------------------------------------------------
+        # GENERAL MIXED SENTIMENT
+        # ----------------------------------------------------
+
+        elif (
+            positive > 0.5
+            and negative > 0.5
+            and abs(
+                positive - negative
+            ) < 0.75
+        ):
+            label = "mixed"
+
+        # ----------------------------------------------------
+        # POSITIVE
+        # ----------------------------------------------------
+
+        elif score > 0.05:
+            label = "positive"
+
+        # ----------------------------------------------------
+        # NEGATIVE
+        # ----------------------------------------------------
+
+        elif score < -0.05:
+            label = "negative"
+
+        # ----------------------------------------------------
+        # NEUTRAL
+        # ----------------------------------------------------
+
+        else:
+            label = "neutral"
+
+        # ====================================================
+        # CONFIDENCE
+        # ====================================================
+
+        confidence = calculate_confidence(
+            positive,
+            negative,
+            label,
+            tokens,
+        )
+
+        # ====================================================
+        # RESULT
+        # ====================================================
+
+        return SentimentResult(
+            label=label,
+            score=score,
+            positive=positive_prob,
+            negative=negative_prob,
+            neutral=neutral_prob,
+            confidence=confidence,
+            emotions=emotions,
+            aspects=detect_aspects(tokens),
+            evidence=evidence,
+            raw_score=raw_score,
+            punctuation_modifier=punctuation_factor,
+        )

sentix/certainty.py

@@ -0,0 +1,45 @@
+UNCERTAINTY_WORDS = {
+    "maybe": 0.75,
+    "perhaps": 0.75,
+    "possibly": 0.75,
+    "might": 0.75,
+    "could": 0.80,
+    "probably": 0.85,
+    "possibly": 0.75,
+    "seems": 0.85,
+    "seemingly": 0.85,
+    "guess": 0.80,
+    "think": 0.90,
+    "believe": 0.90,
+}
+
+
+CERTAINTY_WORDS = {
+    "definitely": 1.15,
+    "certainly": 1.15,
+    "clearly": 1.10,
+    "undoubtedly": 1.20,
+    "surely": 1.10,
+}
+
+
+def get_certainty_modifier(tokens: list[str]) -> float:
+    """
+    Calculate a confidence modifier from certainty/uncertainty words.
+
+    Values below 1.0 reduce confidence.
+    Values above 1.0 increase confidence.
+    """
+
+    modifier = 1.0
+
+    for token in tokens:
+        word = token.lower()
+
+        if word in UNCERTAINTY_WORDS:
+            modifier *= UNCERTAINTY_WORDS[word]
+
+        elif word in CERTAINTY_WORDS:
+            modifier *= CERTAINTY_WORDS[word]
+
+    return modifier

sentix/confidence.py

@@ -0,0 +1,53 @@
+import math
+
+from .certainty import get_certainty_modifier
+
+
+def calculate_confidence(
+    positive: float,
+    negative: float,
+    label: str,
+    tokens: list[str] | None = None,
+) -> float:
+    """
+    Calculate confidence in the predicted sentiment.
+
+    Confidence is based on:
+
+    1. Amount of sentiment evidence.
+    2. Dominance of the predicted sentiment.
+    3. Certainty or uncertainty expressed in the text.
+
+    Returns a value between 0.0 and 1.0.
+    """
+
+    evidence = positive + negative
+
+    # No sentiment evidence.
+    if evidence == 0:
+        return 0.5 if label == "neutral" else 0.0
+
+    # Calculate polarity dominance.
+    if label == "positive":
+        dominance = positive / evidence
+
+    elif label == "negative":
+        dominance = negative / evidence
+
+    elif label == "mixed":
+        dominance = 1.0 - abs(positive - negative) / evidence
+
+    else:
+        dominance = 0.0
+
+    # Convert evidence strength into a bounded value.
+    evidence_strength = 1.0 - math.exp(-evidence)
+
+    confidence = dominance * evidence_strength
+
+    # Apply certainty / uncertainty information.
+    if tokens is not None:
+        certainty_modifier = get_certainty_modifier(tokens)
+        confidence *= certainty_modifier
+
+    return min(max(confidence, 0.0), 1.0)