polvader 1.0.0__tar.gz

polvader-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borys Jastrzębski
+
+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.

polvader-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: polvader
+Version: 1.0.0
+Summary: Lexicon-and-rule-based sentiment analysis for Polish text, in the style of VADER.
+Author: Borys Jastrzębski
+Author-email: Borys Jastrzębski <borys@stanford.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Natural Language :: Polish
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: accelerate>=1.14.0
+Requires-Dist: deep-translator>=1.11.4
+Requires-Dist: numpy>=2.2.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pip>=26.1.2
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: spacy>=3.8.10
+Requires-Dist: textual>=8.2.7
+Requires-Dist: tqdm>=3.67.3
+Requires-Dist: transformers>=5.13.0
+Requires-Dist: vadersentiment>=3.3.2
+Requires-Dist: xlrd>=2.0.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# polVADER
+
+Lexicon-and-rule-based sentiment analysis for Polish text, in the style of
+[VADER](https://github.com/cjhutto/vaderSentiment). No training required at
+inference time — polVADER scores text directly from a Polish sentiment
+lexicon plus a rule layer for negation, intensifiers, capitalization,
+punctuation emphasis, and contrastive conjunctions (`ale`, `jednak`, ...).
+
+## Install
+
+```bash
+pip install polvader
+python -m spacy download pl_core_news_lg
+```
+
+polVADER uses spaCy's `pl_core_news_lg` model for Polish tokenization and
+lemmatization; it is not bundled with the package and must be downloaded
+once after install.
+
+## Usage
+
+```python
+from polvader import Lexicon
+
+lex = Lexicon()
+scores = lex.polarity_scores("To był wspaniały dzień pełen szczęścia.")
+print(scores)
+# {'neg': 0.0, 'neu': 0.xxx, 'pos': 0.xxx, 'compound': 0.879}
+```
+
+`polarity_scores()` returns the same `{neg, neu, pos, compound}` contract as
+the original English VADER. `compound` is a single normalized score in
+`[-1, +1]`; `neg`/`neu`/`pos` are proportions of the text's sentiment-bearing
+content.
+
+Batch scoring (uses spaCy's `nlp.pipe` internally, much faster than a loop):
+
+```python
+results = lex.score_batch([
+    "Świetny produkt, polecam!",
+    "Nigdy więcej tu nie wrócę.",
+], batch_size=256)
+```
+
+For social-media text (tweets, comments — hashtags, @mentions, emoji), run
+`preprocess_social()` first:
+
+```python
+from polvader import preprocess_social
+
+text = preprocess_social(raw_tweet)
+scores = lex.polarity_scores(text)
+```
+
+## Lexicon
+
+By default `Lexicon()` loads the coverage-expanded, weight-tuned lexicon
+(~29.5k words): the original ~8.5k-word hand-built Polish valence lexicon,
+expanded via K-NN over PLLuM-8B's static input-embedding table (not a
+contextual/forward-pass embedding — benchmarked as equal-or-better and far
+cheaper to compute) across a multi-domain Polish corpus (tweets,
+product/hotel/service reviews, general sentiment text), then weight-tuned
+end-to-end against those same domains. Pass `expanded=False` for the
+smaller, untuned ~8.5k-word base lexicon instead:
+
+```python
+lex = Lexicon(expanded=False)
+```
+
+## Modifier system
+
+`polarity_scores()` applies, on top of the raw lexicon lookup:
+negation (`nie`, multi-word negators), booster/dampener adverbs, ALL-CAPS
+emphasis, exclamation/question-mark emphasis, sentence-aware scoring for
+multi-sentence text, and contrastive-conjunction reweighting (text after
+"ale"/"jednak" counts more than text before it). Each category can be
+disabled independently via keyword flags on `polarity_scores()` for
+ablation/diagnostic purposes — see its docstring for the full flag list.
+
+## License
+
+MIT

polvader-1.0.0/README.md

@@ -0,0 +1,82 @@
+# polVADER
+
+Lexicon-and-rule-based sentiment analysis for Polish text, in the style of
+[VADER](https://github.com/cjhutto/vaderSentiment). No training required at
+inference time — polVADER scores text directly from a Polish sentiment
+lexicon plus a rule layer for negation, intensifiers, capitalization,
+punctuation emphasis, and contrastive conjunctions (`ale`, `jednak`, ...).
+
+## Install
+
+```bash
+pip install polvader
+python -m spacy download pl_core_news_lg
+```
+
+polVADER uses spaCy's `pl_core_news_lg` model for Polish tokenization and
+lemmatization; it is not bundled with the package and must be downloaded
+once after install.
+
+## Usage
+
+```python
+from polvader import Lexicon
+
+lex = Lexicon()
+scores = lex.polarity_scores("To był wspaniały dzień pełen szczęścia.")
+print(scores)
+# {'neg': 0.0, 'neu': 0.xxx, 'pos': 0.xxx, 'compound': 0.879}
+```
+
+`polarity_scores()` returns the same `{neg, neu, pos, compound}` contract as
+the original English VADER. `compound` is a single normalized score in
+`[-1, +1]`; `neg`/`neu`/`pos` are proportions of the text's sentiment-bearing
+content.
+
+Batch scoring (uses spaCy's `nlp.pipe` internally, much faster than a loop):
+
+```python
+results = lex.score_batch([
+    "Świetny produkt, polecam!",
+    "Nigdy więcej tu nie wrócę.",
+], batch_size=256)
+```
+
+For social-media text (tweets, comments — hashtags, @mentions, emoji), run
+`preprocess_social()` first:
+
+```python
+from polvader import preprocess_social
+
+text = preprocess_social(raw_tweet)
+scores = lex.polarity_scores(text)
+```
+
+## Lexicon
+
+By default `Lexicon()` loads the coverage-expanded, weight-tuned lexicon
+(~29.5k words): the original ~8.5k-word hand-built Polish valence lexicon,
+expanded via K-NN over PLLuM-8B's static input-embedding table (not a
+contextual/forward-pass embedding — benchmarked as equal-or-better and far
+cheaper to compute) across a multi-domain Polish corpus (tweets,
+product/hotel/service reviews, general sentiment text), then weight-tuned
+end-to-end against those same domains. Pass `expanded=False` for the
+smaller, untuned ~8.5k-word base lexicon instead:
+
+```python
+lex = Lexicon(expanded=False)
+```
+
+## Modifier system
+
+`polarity_scores()` applies, on top of the raw lexicon lookup:
+negation (`nie`, multi-word negators), booster/dampener adverbs, ALL-CAPS
+emphasis, exclamation/question-mark emphasis, sentence-aware scoring for
+multi-sentence text, and contrastive-conjunction reweighting (text after
+"ale"/"jednak" counts more than text before it). Each category can be
+disabled independently via keyword flags on `polarity_scores()` for
+ablation/diagnostic purposes — see its docstring for the full flag list.
+
+## License
+
+MIT

polvader-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "polvader"
+version = "1.0.0"
+description = "Lexicon-and-rule-based sentiment analysis for Polish text, in the style of VADER."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "accelerate>=1.14.0",
+    "deep-translator>=1.11.4",
+    "numpy>=2.2.0",
+    "openpyxl>=3.1.5",
+    "pandas>=2.0.0",
+    "pip>=26.1.2",
+    "scikit-learn>=1.5.0",
+    "scipy>=1.17.1",
+    "spacy>=3.8.10",
+    "textual>=8.2.7",
+    "tqdm>=3.67.3",
+    "transformers>=5.13.0",
+    "vadersentiment>=3.3.2",
+    "xlrd>=2.0.2",
+]
+authors = [
+  { name="Borys Jastrzębski", email="borys@stanford.edu" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Natural Language :: Polish",
+    "License :: OSI Approved :: MIT License",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.2.0",
+    "twine>=6.2.0",
+]
+
+[build-system]
+requires = ["uv_build >= 0.10.7, <0.11.0"]
+build-backend = "uv_build"
+
+# [project.urls]
+# Homepage = "https://github.com/pypa/sampleproject"
+# Issues = "https://github.com/pypa/sampleproject/issues"

polvader-1.0.0/src/polvader/__init__.py

@@ -0,0 +1,34 @@
+"""
+polVADER - Polish VADER Sentiment Analysis
+
+A Python package for Polish sentiment analysis based on VADER methodology.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Borys Jastrzębski <borys@stanford.edu>"
+
+
+from .models import (
+    Lexicon,
+    string_preprocessing,
+    preprocess_social,
+    _BOOSTER_DICT,
+    _NEGATION_WORDS,
+    _MULT_NEGATION_WORDS,
+    _BUT_WORDS,
+    _OPINION_MARKERS,
+    _SOCIAL_MEDIA_SUPPLEMENT,
+)
+
+__all__ = [
+    "Lexicon",
+    "string_preprocessing",
+    "preprocess_social",
+    "_BOOSTER_DICT",
+    "_NEGATION_WORDS",
+    "_MULT_NEGATION_WORDS",
+    "_BUT_WORDS",
+    "_OPINION_MARKERS",
+    "_SOCIAL_MEDIA_SUPPLEMENT",
+    "__version__",
+]

polvader-1.0.0/src/polvader/models.py

@@ -0,0 +1,866 @@
+"""
+Core model classes for polVADER sentiment analysis.
+"""
+
+import importlib.resources as data
+import math
+import pickle
+import re
+import string
+
+import spacy
+
+# ── VADER-style modifier constants ────────────────────────────────────────────
+# [CHANGE 2] B_INCR/B_DECR tuned down from VADER's ±0.293.
+# English VADER was calibrated on a ~7,500-word lexicon; the Polish lexicon is
+# smaller, so each booster fires at higher relative frequency and the original
+# constant over-shifts ~97 % of texts by a mean of 0.30 units.  Halving to
+# 0.15 reduces the mean shift while preserving the ordinal ranking of boosted
+# vs. unboosted scores.
+_B_INCR = 0.35    # amplifier boost (additive) — calibrated on PolEmo fit split; was 0.15
+_B_DECR = -0.35   # diminisher boost          — was -0.15
+# Reverted from −1.15 to −0.74 (original VADER value). −1.15 amplifies negated
+# words beyond their original magnitude, causing systematic positive-skew for
+# texts with negated negative words ("nie zły" → strongly positive). −0.74
+# dampens instead, keeping "not bad" < "good" in magnitude.
+_N_SCALAR = -0.74 # negation scalar
+_C_INCR   = 0.733 # ALL-CAPS emphasis per word
+_ALPHA    = 20    # normalisation constant    — calibrated; was 15
+
+# [CHANGE 3] Balance detector constants.
+# When a text has both positive and negative sentiment signals in similar
+# proportions the document-level sentiment is ambiguous even if individual
+# word scores are strong.  We dampen the compound toward zero proportionally
+# to how balanced the opposing signals are.
+_BALANCE_THRESHOLD = 0.20  # min(pos,|neg|)/max(pos,|neg|) ratio to trigger
+_BALANCE_DAMP      = 0.60  # compound is multiplied by (1 − ratio×DAMP)
+
+# [CHANGE 6] Subjectivity pre-filter constants.
+# Texts that lack subjective/opinion markers and have a moderate compound
+# are likely factual rather than opinionated, so their compound is dampened.
+_SUBJ_THRESHOLD = 0.75  # only fires when |compound| < this value
+_SUBJ_DAMP      = 0.65  # multiplier when no opinion markers are present
+
+# Polish opinion markers: first-person pronouns, opinion verbs, evaluative
+# stance words, and common review feedback words (all lemma forms).
+_OPINION_MARKERS: frozenset[str] = frozenset({
+    # first-person pronouns
+    "ja", "mi", "mnie", "mój", "moja", "moje", "moim", "moją",
+    "my", "nam", "nas", "nasz", "nasza", "nasze",
+    # opinion / evaluative verbs
+    "uważać", "myśleć", "sądzić", "wydawać", "czuć", "wierzyć",
+    "polecać", "odradzać", "radzić", "lubić", "kochać", "nienawidzić",
+    "preferować", "zachwycać", "rozczarować",
+    # evaluative stance markers
+    "niestety", "żal", "szkoda",
+    # common direct-feedback words in reviews
+    "polecam", "odradzam", "wracam", "wrócimy", "wróciłem", "wróciłam",
+    "żałować", "polecić",
+})
+
+# Polish amplifiers and diminishers — additive boost applied to a neighbouring
+# sentiment word.  Sign-aware application means amplifiers always increase
+# magnitude and diminishers always reduce it, regardless of direction.
+_BOOSTER_DICT: dict[str, float] = {
+    # ── Standard intensifiers ────────────────────────────────────────────────
+    "bardzo":            _B_INCR,  # very
+    "niezmiernie":       _B_INCR,  # immensely
+    "niezwykle":         _B_INCR,  # remarkably
+    "wyjątkowo":         _B_INCR,  # exceptionally
+    "szczególnie":       _B_INCR,  # particularly
+    "ekstremalnie":      _B_INCR,  # extremely
+    "absolutnie":        _B_INCR,  # absolutely
+    "całkowicie":        _B_INCR,  # completely
+    "zupełnie":          _B_INCR,  # totally
+    "kompletnie":        _B_INCR,  # completely (colloquial)
+    "ogromnie":          _B_INCR,  # enormously
+    "mocno":             _B_INCR,  # strongly
+    "niesamowicie":      _B_INCR,  # incredibly
+    "fenomenalnie":      _B_INCR,  # phenomenally
+    "zdecydowanie":      _B_INCR,  # decidedly
+    "wyraźnie":          _B_INCR,  # clearly
+    "naprawdę":          _B_INCR,  # truly / really
+    "totalnie":          _B_INCR,  # totally (colloquial)
+    "nadzwyczajnie":     _B_INCR,  # extraordinarily
+    "niewiarygodnie":    _B_INCR,  # unbelievably
+    "głęboko":           _B_INCR,  # deeply
+    "niesłychanie":      _B_INCR,  # incredibly
+    "niebywale":         _B_INCR,  # extraordinarily
+    "wręcz":             _B_INCR,  # outright
+    "doprawdy":          _B_INCR,  # indeed / truly
+    "wielce":            _B_INCR,  # greatly (formal)
+    "istotnie":          _B_INCR,  # indeed / significantly
+    "niewyobrażalnie":   _B_INCR,  # unimaginably
+    "nieprawdopodobnie": _B_INCR,  # improbably (as intensifier)
+    "zadziwiająco":      _B_INCR,  # surprisingly
+    "niezaprzeczalnie":  _B_INCR,  # undeniably
+    "bezsprzecznie":     _B_INCR,  # indisputably
+    "ewidentnie":        _B_INCR,  # evidently
+    "definitywnie":      _B_INCR,  # definitively
+    "jednoznacznie":     _B_INCR,  # unequivocally
+    # ── Colloquial / social-media intensifiers ───────────────────────────────
+    "mega":              _B_INCR,  # mega (online)
+    "super":             _B_INCR,  # super (very common Polish intensifier)
+    "hiper":             _B_INCR,  # hyper-
+    "ultra":             _B_INCR,  # ultra-
+    "ekstra":            _B_INCR,  # extra / great (colloquial)
+    "strasznie":         _B_INCR,  # terribly (as intensifier)
+    "cholernie":         _B_INCR,  # damn / bloody (intensifier)
+    "diabelnie":         _B_INCR,  # devilishly (intensifier)
+    "szalenie":          _B_INCR,  # madly (intensifier)
+    "potwornie":         _B_INCR,  # monstrously (intensifier)
+    "okrutnie":          _B_INCR,  # cruelly (colloquial intensifier)
+    "kurewsko":          _B_INCR,  # intensifier (vulgar, very common on Twitter)
+    "zajebicie":         _B_INCR,  # intensifier (vulgar, common on Twitter)
+    "aż":                _B_INCR,  # "so/as" emphasiser ("aż tak dobry" = "that good")
+    "tak":               _B_INCR,  # "so" emphasiser before adjective ("tak piękny")
+    # ── Formal / news / political amplifiers ─────────────────────────────────
+    "rażąco":            _B_INCR,  # glaringly
+    "surowo":            _B_INCR,  # severely
+    "drastycznie":       _B_INCR,  # drastically
+    "dramatycznie":      _B_INCR,  # dramatically
+    "gwałtownie":        _B_INCR,  # sharply
+    "dotkliwie":         _B_INCR,  # painfully
+    "poważnie":          _B_INCR,  # seriously
+    "znacznie":          _B_INCR,  # considerably
+    "znacząco":          _B_INCR,  # significantly
+    "ostro":             _B_INCR,  # harshly
+    "bezwzględnie":      _B_INCR,  # ruthlessly
+    "przerażająco":      _B_INCR,  # frighteningly
+    "zatrważająco":      _B_INCR,  # alarmingly
+    "imponująco":        _B_INCR,  # impressively
+    "skandalicznie":     _B_INCR,  # scandalously
+    "katastrofalnie":    _B_INCR,  # catastrophically
+    "tragicznie":        _B_INCR,  # tragically
+    "fatalnie":          _B_INCR,  # terribly
+    "okropnie":          _B_INCR,  # horribly
+    # ── Warm / positive formal amplifiers ────────────────────────────────────
+    "serdecznie":        _B_INCR,  # warmly
+    "gorąco":            _B_INCR,  # fervently
+    "szczerze":          _B_INCR,  # sincerely
+    "cudownie":          _B_INCR,  # wonderfully
+    "genialnie":         _B_INCR,  # brilliantly
+    "wybitnie":          _B_INCR,  # outstandingly
+    "rewelacyjnie":      _B_INCR,  # awesomely
+    "doskonale":         _B_INCR,  # excellently
+    "świetnie":          _B_INCR,  # great
+    # ── Diminishers ──────────────────────────────────────────────────────────
+    "trochę":            _B_DECR,  # a bit
+    "nieco":             _B_DECR,  # somewhat
+    "odrobinę":          _B_DECR,  # a little
+    "troszkę":           _B_DECR,  # a tiny bit
+    "lekko":             _B_DECR,  # slightly
+    "delikatnie":        _B_DECR,  # gently
+    "prawie":            _B_DECR,  # almost
+    "ledwo":             _B_DECR,  # barely
+    "ledwie":            _B_DECR,  # barely
+    "zaledwie":          _B_DECR,  # merely
+    "raczej":            _B_DECR,  # rather (hedging)
+    "dość":              _B_DECR,  # fairly
+    "dosyć":             _B_DECR,  # fairly
+    "mniej":             _B_DECR,  # less
+    "mało":              _B_DECR,  # little
+    "niezbyt":           _B_DECR,  # not very
+    "niejako":           _B_DECR,  # somewhat
+    "poniekąd":          _B_DECR,  # in a way
+    "częściowo":         _B_DECR,  # partially
+    "umiarkowanie":      _B_DECR,  # moderately
+    "względnie":         _B_DECR,  # relatively
+    "jakby":             _B_DECR,  # kind of
+    "niby":              _B_DECR,  # supposedly
+    "stosunkowo":        _B_DECR,  # relatively
+    "marginalnie":       _B_DECR,  # marginally
+    "minimalnie":        _B_DECR,  # minimally
+    "nieznacznie":       _B_DECR,  # slightly
+    "powierzchownie":    _B_DECR,  # superficially
+    "pobieżnie":         _B_DECR,  # cursorily
+    "przeciętnie":       _B_DECR,  # averagely
+}
+
+# Fixed negators: apply N_SCALAR regardless of their own lexical value.
+_NEGATION_WORDS: frozenset[str] = frozenset({"nie", "bez", "ani", "brak"})
+
+# Multiplicative negators: scale the target word's valence by their own
+# lexicon value (falls back to N_SCALAR when OOV).
+_MULT_NEGATION_WORDS: frozenset[str] = frozenset({
+    "nigdy", "nigdzie", "nikt", "nic", "wcale", "bynajmniej",
+    "żaden", "żadna", "żadne", "żadnego", "żadnej", "żadnemu",
+    "żadnym", "żadnych", "żadnymi",
+})
+
+# Contrastive conjunctions: words after these carry more weight.
+_BUT_WORDS: frozenset[str] = frozenset({
+    "ale", "jednak", "natomiast", "lecz", "jednakże",
+    "tymczasem", "niemniej", "pomimo", "chociaż", "mimo",
+})
+
+# [CHANGE 5] Informal / social-media vocabulary supplement.
+# These words are common on Twitter and informal Polish but under-represented
+# in the formal sentiment lexicon.  Added via setdefault so they don't
+# overwrite existing entries.
+_SOCIAL_MEDIA_SUPPLEMENT: dict[str, float] = {
+    # informal positives
+    "spoko":          1.5,   # cool / ok
+    "spoczko":        1.5,   # cool (variant)
+    "git":            2.0,   # great
+    "kapitalny":      2.2,   # capital / great
+    "bomba":          2.2,   # great (slang)
+    "odlotowy":       2.3,   # awesome
+    "zajefajny":      2.5,   # super cool (colloquial intensified)
+    "zarąbisty":      2.5,   # awesome (colloquial)
+    "elegancko":      1.5,   # cool (slang)
+    "cudo":           2.2,   # wonder / great thing
+    "petarda":        2.2,   # firecracker / awesome
+    "miodzio":        2.0,   # sweet / great (colloquial)
+    "odpad":          2.0,   # great (ironic slang — context-dependent; lexicon wins)
+    # informal negatives
+    "słabo":         -1.8,   # weak / bad
+    "żenada":        -2.5,   # cringe / embarrassing
+    "żenujący":      -2.2,   # embarrassing
+    "masakra":       -2.0,   # disaster (slang for awful)
+    "kupa":          -2.2,   # crap (vulgar)
+    "beznadziejnie": -2.0,   # hopelessly
+    "dno":           -2.5,   # rock-bottom / the worst
+    "szajs":         -2.2,   # junk / shit (Polonized)
+    "żałosny":       -2.2,   # pathetic
+    "obrzydliwy":    -2.5,   # disgusting
+    "kiepski":       -1.5,   # poor / bad
+    "paskudny":      -2.0,   # ugly / disgusting
+    "wstyd":         -1.5,   # shame
+    "odpad":         -2.0,   # drop-out / rubbish (overloaded; lexicon wins if present)
+}
+
+# ── Pre-compiled social-media preprocessing regexes ──────────────────────────
+_MENTION_RE = re.compile(r"@\S+")
+_URL_RE      = re.compile(r"https?://\S+|www\.\S+")
+_HASHTAG_RE  = re.compile(r"#(\w+)")
+_SPACE_RE    = re.compile(r"\s+")
+
+
+def preprocess_social(text: str) -> str:
+    """[CHANGE 4] Strip @mentions and URLs; convert #hashtag → hashtag."""
+    text = _MENTION_RE.sub(" ", text)
+    text = _URL_RE.sub(" ", text)
+    text = _HASHTAG_RE.sub(r"\1", text)
+    return _SPACE_RE.sub(" ", text).strip()
+
+
+def string_preprocessing(piece):
+    return (
+        piece.translate(str.maketrans("", "", string.punctuation))
+        .strip()
+        .replace("  ", " ")
+        .lower()
+        .split(" ")
+    )
+
+
+class Lexicon:
+    def _merge(self, dict1, dict2):
+        return {**dict1, **dict2}
+
+    def __init__(self, synonym_weight=0.75, derivative_weight=1,
+                 valence_floor: float = 0.0,
+                 valence_clamp: tuple[float, float] | None = None,
+                 b_incr: float | None = None,
+                 n_scalar: float | None = None,
+                 alpha: float | None = None,
+                 expanded: bool = True,
+                 pos_scale: float = 1.0,
+                 neg_scale: float = 1.0):
+        # [CHANGE 1] Enable sentencizer for sentence-aware scoring.
+        # The full parser is disabled to keep inference fast; the sentencizer
+        # provides sentence boundaries via punctuation heuristics.
+        self.nlp = spacy.load("pl_core_news_lg", disable=["parser", "ner"])
+        if "sentencizer" not in self.nlp.pipe_names:
+            self.nlp.add_pipe("sentencizer")
+
+        self._synonym_weight    = synonym_weight
+        self._derivative_weight = derivative_weight
+
+        # Parameterised rule constants — default to module-level values.
+        # Overriding these allows calibration without re-running spaCy.
+        self._b_incr   = b_incr   if b_incr   is not None else _B_INCR
+        self._n_scalar = n_scalar if n_scalar  is not None else _N_SCALAR
+        self._alpha    = alpha    if alpha     is not None else _ALPHA
+
+        # Scale booster dict proportionally when b_incr differs from default.
+        scale = self._b_incr / _B_INCR if _B_INCR != 0 else 1.0
+        self._booster_dict = (
+            _BOOSTER_DICT if scale == 1.0
+            else {k: v * scale for k, v in _BOOSTER_DICT.items()}
+        )
+
+        self._load_data(expanded=expanded)
+        self.lexicon = self._final_lex
+
+        # [OPT 1] Valence floor: drop low-signal lexicon entries.
+        # Neutral texts accumulate many weak-valence hits that partially cancel
+        # but leave a residual compound that pushes them out of the neutral band.
+        # Pruning entries below the floor removes noise hits without losing the
+        # decisive words that carry clear sentiment.
+        if valence_floor > 0.0:
+            self.lexicon = {
+                k: v for k, v in self.lexicon.items() if abs(v) >= valence_floor
+            }
+
+        # [OPT 2] Valence clamp: keep all entries but constrain magnitude to
+        # [clamp_min, clamp_max].  Unlike the floor (which prunes entries),
+        # clamping preserves lexicon coverage (OOV rate unchanged) while
+        # equalising weak signals up and/or strong outliers down.
+        if valence_clamp is not None:
+            clamp_lo, clamp_hi = valence_clamp
+            self.lexicon = {
+                k: math.copysign(min(max(abs(v), clamp_lo), clamp_hi), v)
+                for k, v in self.lexicon.items()
+            }
+
+        # Per-sign valence scaling: calibrate positive/negative signal strength
+        # independently, e.g. to correct corpus-level pos/neg asymmetry.
+        if pos_scale != 1.0 or neg_scale != 1.0:
+            self.lexicon = {
+                k: v * (pos_scale if v > 0 else neg_scale)
+                for k, v in self.lexicon.items()
+            }
+
+        # [CHANGE 5] Merge social-media supplement: setdefault preserves
+        # existing entries so the core lexicon is not overwritten.
+        for word, score in _SOCIAL_MEDIA_SUPPLEMENT.items():
+            apply = True
+            if valence_floor > 0.0 and abs(score) < valence_floor:
+                apply = False
+            if apply:
+                if valence_clamp is not None:
+                    clamp_lo, clamp_hi = valence_clamp
+                    score = math.copysign(min(max(abs(score), clamp_lo), clamp_hi), score)
+                if pos_scale != 1.0 or neg_scale != 1.0:
+                    score = score * (pos_scale if score > 0 else neg_scale)
+                self.lexicon.setdefault(word, score)
+
+    def _lemmatize(self, piece):
+        return [self.nlp(word)[0].lemma_ for word in piece]
+
+    def _load_data(self, expanded: bool = False):
+        with open(
+            data.files("polvader.lexicons") / "synonyms_dobry_slownik.dat", "rb"
+        ) as f:
+            self._synonyms_dobry_slownik = pickle.load(f)
+
+        with open(
+            data.files("polvader.lexicons") / "synonyms_kazojc.dat", "rb"
+        ) as f:
+            self._synonyms_kazojc = pickle.load(f)
+
+        # expanded_lexicon.dat: coverage-expanded (PLLuM K-NN, stages/coverage.py)
+        # + Adam-tuned (stages/adam.py, trained on all 5 corpus sources) —
+        # this is the default and best-benchmarked lexicon (see
+        # annotation-data/benchmark_translate_vader_results.json). Pass
+        # expanded=False for the smaller, untuned hand-built base lexicon.
+        expanded_path = (
+            data.files("polvader.lexicons") / "expanded_lexicon.dat"
+        )
+        base_path = (
+            data.files("polvader.lexicons")
+            / "fem_big_imbir_and_nencki_lex_with_kazojc_adjectives.dat"
+        )
+        lex_path = expanded_path if (
+            expanded and expanded_path.is_file()
+        ) else base_path
+        with open(lex_path, "rb") as f:
+            self._final_lex = pickle.load(f)
+
+    def _modify_synonym_weights(self, new_weight):
+        self._weighted_synonyms = {
+            k: v * new_weight for k, v in self.synonyms.items()
+        }
+        self.lexicon = self._merge(self.lexicon, self._weighted_synonyms)
+        self.lexicon = {k: round(v, 2) for k, v in self.lexicon.items()}
+
+    def _integrate_derivative_forms(self, weight):
+        self._weighted_derivatives = {
+            k: v * weight for k, v in self.derivatives.items()
+        }
+        self.lexicon = self._merge(self.lexicon, self._weighted_derivatives)
+        self.lexicon = {k: round(v, 2) for k, v in self.lexicon.items()}
+
+    def _round_neutrals(self):
+        new_lex = {}
+        for k, v in self.lexicon.items():
+            if 1 > v >= 0.5:
+                new_lex[k] = 1
+            elif -0.5 >= v > -1:
+                new_lex[k] = -1
+            else:
+                new_lex[k] = v
+        self.lexicon = new_lex
+
+    def score(self, text, preprocess=True):
+        """Simple lexicon lookup (no modifiers).  Returns per-word scores."""
+        words = string_preprocessing(text) if preprocess else text
+        inner = [self.lexicon.get(w, False) for w in words]
+        n = len(words)
+        return inner, {
+            "neg": sum(1 for x in inner if x and x < 0) / n,
+            "unk": sum(1 for x in inner if x is False) / n,
+            "pos": sum(1 for x in inner if x and x > 0) / n,
+        }
+
+    # ── Internal per-token scoring ────────────────────────────────────────────
+
+    def _score_token_lists(
+        self,
+        surfaces: list[str],
+        lemmas:   list[str],
+        is_word:  list[bool],
+        ep_count: int = 0,
+        qm_count: int = 0,
+        return_sentiments: bool = False,
+        *,
+        use_negation:    bool = True,
+        use_boosters:    bool = True,
+        use_caps:        bool = True,
+        use_balance:     bool = True,
+        use_subjectivity: bool = True,
+        use_nie_prefix:  bool = True,
+        use_punct:       bool = True,
+        use_contrastive: bool = True,
+    ) -> dict:
+        """
+        Core VADER-style scoring on pre-tokenised token lists.
+
+        Modifier rules (in order):
+          1. ALL-CAPS emphasis (±C_INCR per capped word in mixed-case text).
+          2. Boosters / diminishers in the 3-word window before each sentiment
+             word (distance damping: ×0.95 at −2, ×0.90 at −3).
+          3. Negation in the same window (N_SCALAR flip or multiplicative scale).
+          4. nie-prefix productive splitting ("niedobry" → −lex["dobry"]).
+          5. Balance detector: dampen compound when pos ≈ neg signals.
+          6. Contrastive conjunction (ale/jednak/…): last occurrence wins;
+             words before get ×0.5, words after get ×1.5.
+          7. Punctuation amplification (! and ?).
+          8. Subjectivity pre-filter: moderate compounds without opinion
+             markers are dampened toward neutral.
+
+        Ablation flags (keyword-only):
+          use_negation    — fixed "nie/bez/ani/brak" and mult negation
+          use_boosters    — intensifier/diminisher window
+          use_caps        — ALL-CAPS emphasis
+          use_balance     — balance detector
+          use_subjectivity — subjectivity pre-filter
+          use_nie_prefix  — fused nie-prefix forms ("niedobry")
+          use_punct       — !/?  punctuation amplification
+          use_contrastive — ale/jednak contrastive conjunction
+        """
+        word_surfaces = [s for s, w in zip(surfaces, is_word) if w]
+        has_mixed_case = bool(word_surfaces) and (
+            any(s.isupper() for s in word_surfaces)
+            and not all(s.isupper() for s in word_surfaces)
+        )
+
+        sentiments: list[float] = []
+        sentiment_positions: list[int] = []
+
+        for i, lemma in enumerate(lemmas):
+            if not is_word[i]:
+                continue
+
+            if lemma in _NEGATION_WORDS or lemma in _MULT_NEGATION_WORDS or lemma in _BOOSTER_DICT:
+                continue
+
+            # Find the nearest preceding word token (may be a modifier)
+            prev_lemma = None
+            for j in range(i - 1, -1, -1):
+                if is_word[j]:
+                    prev_lemma = lemmas[j]
+                    break
+
+            # Bigram lookup: "nie_dobry", "bardzo_dobry" etc.
+            # If a bigram entry exists it overrides the unigram + context path.
+            bigram_key = f"{prev_lemma}_{lemma}" if prev_lemma else None
+            if bigram_key and bigram_key in self.lexicon:
+                valence = self.lexicon[bigram_key]
+                if use_caps and surfaces[i].isupper() and has_mixed_case:
+                    valence += _C_INCR if valence > 0 else -_C_INCR
+                sentiments.append(valence)
+                sentiment_positions.append(i)
+                continue
+
+            # Determine valence: plain lexicon or nie-prefix fused form
+            is_nie_prefix = False
+            if lemma in self.lexicon:
+                valence: float = self.lexicon[lemma]
+            elif use_nie_prefix and lemma.startswith("nie") and len(lemma) > 5:
+                base = lemma[3:]
+                if base not in self.lexicon:
+                    continue
+                valence = self.lexicon[base] * self._n_scalar
+                is_nie_prefix = True
+            else:
+                continue
+
+            if use_caps and surfaces[i].isupper() and has_mixed_case:
+                valence += _C_INCR if valence > 0 else -_C_INCR
+
+            n_fixed_neg  = 0
+            had_mult_neg = False
+            words_seen   = 0
+            for j in range(i - 1, -1, -1):
+                if not is_word[j]:
+                    continue
+                words_seen += 1
+                if words_seen > 3:
+                    break
+                ctx = lemmas[j]
+
+                if use_negation and ctx in _NEGATION_WORDS:
+                    n_fixed_neg += 1
+                    continue
+
+                if use_negation and ctx in _MULT_NEGATION_WORDS:
+                    valence *= self.lexicon.get(ctx, self._n_scalar)
+                    had_mult_neg = True
+                    continue
+
+                if use_boosters:
+                    b = self._booster_dict.get(ctx, 0.0)
+                    if b:
+                        if words_seen == 2:
+                            b *= 0.95
+                        elif words_seen == 3:
+                            b *= 0.90
+                        valence += b if valence >= 0 else -b
+                        continue
+
+                if ctx in self.lexicon or (
+                    ctx.startswith("nie") and len(ctx) > 5 and ctx[3:] in self.lexicon
+                ):
+                    break
+
+            if is_nie_prefix:
+                # Word already carries its own negation via the nie- prefix.
+                # A context "nie" produces a weak double-negative (mildly
+                # positive) rather than a full re-flip with amplification.
+                # "nie niedobry" ≈ "not un-good" → weakly positive, dampened.
+                if use_negation and n_fixed_neg > 0:
+                    valence = abs(valence) * 0.5
+                if use_negation and had_mult_neg:
+                    valence = -abs(valence)
+            else:
+                if n_fixed_neg > 0:
+                    valence *= self._n_scalar
+                    if n_fixed_neg > 1:
+                        # Polish grammatical double-negation stays negative.
+                        valence = -abs(valence)
+                if had_mult_neg and n_fixed_neg > 0:
+                    valence = -abs(valence)
+
+            sentiments.append(valence)
+            sentiment_positions.append(i)
+
+        # Balance detector ────────────────────────────────────────────────────
+        if use_balance and sentiments:
+            pos_raw = sum(s for s in sentiments if s > 0)
+            neg_raw = abs(sum(s for s in sentiments if s < 0))
+            if pos_raw > 0 and neg_raw > 0:
+                balance = min(pos_raw, neg_raw) / max(pos_raw, neg_raw)
+                if balance > _BALANCE_THRESHOLD:
+                    damp = 1.0 - balance * _BALANCE_DAMP
+                    sentiments = [s * damp for s in sentiments]
+
+        # Contrastive conjunction (last occurrence wins) ───────────────────────
+        if use_contrastive:
+            but_idx = None
+            for i, w in enumerate(lemmas):
+                if w in _BUT_WORDS:
+                    but_idx = i
+            if but_idx is not None and sentiments:
+                sentiments = [
+                    s * 0.5 if pos < but_idx else s * 1.5
+                    for s, pos in zip(sentiments, sentiment_positions)
+                ]
+
+        # Aggregate with punctuation amplifier ────────────────────────────────
+        sum_s = sum(sentiments) if sentiments else 0.0
+
+        if use_punct:
+            punct_amp = ep_count * 0.292
+            if qm_count > 1:
+                punct_amp += (min(qm_count, 3) * 0.18) if qm_count <= 3 else 0.96
+            if sum_s > 0:
+                sum_s += punct_amp
+            elif sum_s < 0:
+                sum_s -= punct_amp
+        else:
+            punct_amp = 0.0
+
+        compound = round(
+            max(-1.0, min(1.0, sum_s / math.sqrt(sum_s ** 2 + self._alpha))), 4
+        )
+
+        # Subjectivity pre-filter ─────────────────────────────────────────────
+        if use_subjectivity and 0 < abs(compound) < _SUBJ_THRESHOLD:
+            has_opinion = any(
+                lemmas[i] in _OPINION_MARKERS for i in range(len(lemmas)) if is_word[i]
+            )
+            if not has_opinion:
+                compound = round(compound * _SUBJ_DAMP, 4)
+
+        # Pos / neg proportions ───────────────────────────────────────────────
+        pos_sum = sum(s for s in sentiments if s > 0)
+        neg_sum = sum(s for s in sentiments if s < 0)
+
+        if use_punct:
+            if pos_sum > abs(neg_sum):
+                pos_sum += punct_amp
+            elif pos_sum < abs(neg_sum):
+                neg_sum -= punct_amp
+
+        sent_total = pos_sum + abs(neg_sum)
+
+        # [OPT 3] neu = OOV rate: fraction of alpha words NOT in the lexicon.
+        # Previously neu counted zero-valence lexicon hits (~0.01 universally).
+        # OOV rate is informative: neutral texts contain many non-lexicon words
+        # (factual content, proper nouns, domain terms) while opinionated texts
+        # hit the lexicon more selectively.  This makes neu a real signal.
+        n_words = sum(is_word)
+        n_oov   = sum(
+            1 for i in range(len(lemmas))
+            if is_word[i] and lemmas[i] not in self.lexicon
+        )
+        neu_oov = round(n_oov / n_words, 3) if n_words > 0 else 0.0
+
+        if sent_total == 0:
+            return {"neg": 0.0, "neu": neu_oov, "pos": 0.0, "compound": compound}
+
+        out = {
+            "neg":      round(abs(neg_sum) / sent_total, 3),
+            "neu":      neu_oov,
+            "pos":      round(pos_sum      / sent_total, 3),
+            "compound": compound,
+        }
+        if return_sentiments:
+            out["_sentiments"] = sentiments
+        return out
+
+    # ── Public scoring API ────────────────────────────────────────────────────
+
+    def polarity_scores(
+        self,
+        text: str,
+        sentence_aware: bool = True,
+        *,
+        use_negation:    bool = True,
+        use_boosters:    bool = True,
+        use_caps:        bool = True,
+        use_balance:     bool = True,
+        use_subjectivity: bool = True,
+        use_nie_prefix:  bool = True,
+        use_punct:       bool = True,
+        use_contrastive: bool = True,
+    ) -> dict:
+        """
+        VADER-style scoring with all Polish modifier improvements.
+
+        Parameters
+        ----------
+        text : str
+            Raw Polish text.  Use preprocess_social() first for tweets.
+        sentence_aware : bool
+            When True (default), texts with multiple sentences are scored
+            sentence-by-sentence and the sentence compounds are averaged.
+            This prevents long mixed-sentiment texts from accumulating a
+            spuriously strong compound.  Single-sentence texts are unaffected.
+        use_negation, use_boosters, use_caps, use_balance, use_subjectivity,
+        use_nie_prefix, use_punct, use_contrastive : bool
+            Ablation flags — disable individual modifier categories for
+            diagnostic purposes.  All True by default (full modifier system).
+
+        Returns
+        -------
+        dict with keys 'neg', 'neu', 'pos', 'compound'  (VADER contract).
+        """
+        flags = dict(
+            use_negation=use_negation, use_boosters=use_boosters,
+            use_caps=use_caps, use_balance=use_balance,
+            use_subjectivity=use_subjectivity, use_nie_prefix=use_nie_prefix,
+            use_punct=use_punct, use_contrastive=use_contrastive,
+        )
+
+        ep_count = min(text.count("!"), 3)
+        qm_count = text.count("?")
+
+        doc      = self.nlp(text)
+        sents    = list(doc.sents)
+
+        if sentence_aware and len(sents) > 1:
+            # Score each sentence independently, then aggregate.
+            compounds, neg_scores, pos_scores, neu_scores = [], [], [], []
+            for sent in sents:
+                s_surf   = [t.text          for t in sent]
+                s_lemmas = [t.lemma_.lower() for t in sent]
+                s_iw     = [t.is_alpha       for t in sent]
+                sd = self._score_token_lists(s_surf, s_lemmas, s_iw, **flags)
+                if sd["compound"] != 0.0:
+                    compounds.append(sd["compound"])
+                neg_scores.append(sd["neg"])
+                pos_scores.append(sd["pos"])
+                neu_scores.append(sd["neu"])   # OOV rate per sentence
+
+            if not compounds:
+                neu_agg = round(float(sum(neu_scores) / len(neu_scores)), 3) if neu_scores else 0.0
+                return {"neg": 0.0, "neu": neu_agg, "pos": 0.0, "compound": 0.0}
+
+            avg = sum(compounds) / len(compounds)
+            if use_punct:
+                if avg > 0:
+                    avg += ep_count * 0.292
+                elif avg < 0:
+                    avg -= ep_count * 0.292
+            compound = round(max(-1.0, min(1.0, avg)), 4)
+
+            # Aggregate neg/pos as mean of per-sentence proportions;
+            # neu is mean OOV rate across all sentences (not derived from compound).
+            neg_ = round(float(sum(neg_scores) / len(neg_scores)), 3)
+            pos_ = round(float(sum(pos_scores) / len(pos_scores)), 3)
+            neu_ = round(float(sum(neu_scores) / len(neu_scores)), 3)
+            return {"neg": neg_, "neu": neu_, "pos": pos_, "compound": compound}
+
+        # Single-sequence scoring (or sentence_aware=False)
+        surfaces = [t.text          for t in doc]
+        lemmas   = [t.lemma_.lower() for t in doc]
+        is_word  = [t.is_alpha       for t in doc]
+        return self._score_token_lists(surfaces, lemmas, is_word, ep_count, qm_count, **flags)
+
+    def score_batch(
+        self,
+        texts: list[str],
+        sentence_aware: bool = True,
+        batch_size: int = 256,
+        n_process: int = 1,
+        desc: str | None = None,
+        *,
+        use_negation:    bool = True,
+        use_boosters:    bool = True,
+        use_caps:        bool = True,
+        use_balance:     bool = True,
+        use_subjectivity: bool = True,
+        use_nie_prefix:  bool = True,
+        use_punct:       bool = True,
+        use_contrastive: bool = True,
+    ) -> list[dict]:
+        """
+        Score a list of texts using nlp.pipe() for batched spaCy inference.
+        Produces identical output to calling polarity_scores() per text but
+        is 3–5× faster for large corpora.
+
+        Parameters
+        ----------
+        texts : list[str]
+            Pre-processed texts (apply preprocess_social() before passing).
+        batch_size : int
+            spaCy pipe batch size (default 256).
+        n_process : int
+            Number of worker processes for spaCy (default 1; set -1 for all CPUs,
+            but fork-safety varies by platform).
+        desc : str | None
+            If given, show a tqdm progress bar with this label.
+        """
+        try:
+            from tqdm import tqdm as _tqdm
+            _have_tqdm = True
+        except ImportError:
+            _have_tqdm = False
+
+        flags = dict(
+            use_negation=use_negation, use_boosters=use_boosters,
+            use_caps=use_caps, use_balance=use_balance,
+            use_subjectivity=use_subjectivity, use_nie_prefix=use_nie_prefix,
+            use_punct=use_punct, use_contrastive=use_contrastive,
+        )
+
+        ep_counts = [min(t.count("!"), 3) for t in texts]
+        qm_counts = [t.count("?")         for t in texts]
+
+        results = []
+        docs = self.nlp.pipe(texts, batch_size=batch_size, n_process=n_process)
+        it = zip(docs, ep_counts, qm_counts)
+        if desc is not None and _have_tqdm:
+            it = _tqdm(it, total=len(texts), desc=desc, unit="text")
+        for doc, ep_count, qm_count in it:
+            sents = list(doc.sents)
+            if sentence_aware and len(sents) > 1:
+                compounds, neg_scores, pos_scores, neu_scores = [], [], [], []
+                for sent in sents:
+                    s_surf   = [t.text          for t in sent]
+                    s_lemmas = [t.lemma_.lower() for t in sent]
+                    s_iw     = [t.is_alpha       for t in sent]
+                    sd = self._score_token_lists(s_surf, s_lemmas, s_iw, **flags)
+                    if sd["compound"] != 0.0:
+                        compounds.append(sd["compound"])
+                    neg_scores.append(sd["neg"])
+                    pos_scores.append(sd["pos"])
+                    neu_scores.append(sd["neu"])
+
+                if not compounds:
+                    neu_agg = round(float(sum(neu_scores) / len(neu_scores)), 3) if neu_scores else 0.0
+                    results.append({"neg": 0.0, "neu": neu_agg, "pos": 0.0, "compound": 0.0})
+                    continue
+
+                avg = sum(compounds) / len(compounds)
+                if use_punct:
+                    if avg > 0:
+                        avg += ep_count * 0.292
+                    elif avg < 0:
+                        avg -= ep_count * 0.292
+                compound = round(max(-1.0, min(1.0, avg)), 4)
+                neg_ = round(float(sum(neg_scores) / len(neg_scores)), 3)
+                pos_ = round(float(sum(pos_scores) / len(pos_scores)), 3)
+                neu_ = round(float(sum(neu_scores) / len(neu_scores)), 3)
+                results.append({"neg": neg_, "neu": neu_, "pos": pos_, "compound": compound})
+            else:
+                surfaces = [t.text          for t in doc]
+                lemmas   = [t.lemma_.lower() for t in doc]
+                is_word  = [t.is_alpha       for t in doc]
+                results.append(self._score_token_lists(surfaces, lemmas, is_word, ep_count, qm_count, **flags))
+        return results
+
+    def score_token_cache(self, cache: list[dict]) -> list[dict]:
+        """
+        Score from a pre-built token cache (output of build_token_cache).
+        Avoids re-running spaCy — used by calibrate_constants.py to sweep
+        (b_incr, n_scalar, alpha) without paying the NLP cost each time.
+
+        Each cache entry is a dict with keys:
+          surfaces, lemmas, is_word, ep_count, qm_count,
+          sents: list of (surf_list, lemma_list, is_word_list)
+        """
+        results = []
+        for entry in cache:
+            sents = entry["sents"]
+            ep    = entry["ep_count"]
+            qm    = entry["qm_count"]
+            if len(sents) > 1:
+                compounds, neg_s, pos_s, neu_s = [], [], [], []
+                for s_surf, s_lem, s_iw in sents:
+                    sd = self._score_token_lists(s_surf, s_lem, s_iw)
+                    if sd["compound"] != 0.0:
+                        compounds.append(sd["compound"])
+                    neg_s.append(sd["neg"]); pos_s.append(sd["pos"]); neu_s.append(sd["neu"])
+                if not compounds:
+                    neu_agg = round(float(sum(neu_s) / len(neu_s)), 3) if neu_s else 0.0
+                    results.append({"neg": 0.0, "neu": neu_agg, "pos": 0.0, "compound": 0.0})
+                    continue
+                avg = sum(compounds) / len(compounds)
+                if avg > 0: avg += ep * 0.292
+                elif avg < 0: avg -= ep * 0.292
+                compound = round(max(-1.0, min(1.0, avg)), 4)
+                results.append({
+                    "neg": round(float(sum(neg_s)/len(neg_s)), 3),
+                    "neu": round(float(sum(neu_s)/len(neu_s)), 3),
+                    "pos": round(float(sum(pos_s)/len(pos_s)), 3),
+                    "compound": compound,
+                })
+            else:
+                surf, lem, iw = entry["surfaces"], entry["lemmas"], entry["is_word"]
+                results.append(self._score_token_lists(surf, lem, iw, ep, qm))
+        return results

polvader-1.0.0/src/polvader/utils.py

@@ -0,0 +1,15 @@
+"""
+Utility functions for polVADER.
+"""
+
+def make_lex_dict(lexicon_full_filepath):
+    """
+    Convert lexicon file to a dictionary.
+    
+    Args:
+        lexicon_full_filepath: Path to the lexicon file
+        
+    Returns:
+        Dictionary with lexicon data
+    """
+    pass