Metadata-Version: 2.4
Name: polvader
Version: 1.0.1
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

## Funding disclosure

This work was supported by Narodowe Centrum Nauki (National Science Centre, Poland) under Grant
2020/38/A/HS6/00066.
