PerSent 1.4.0__tar.gz → 1.5.0__tar.gz

{persent-1.4.0 → persent-1.5.0}/CHANGELOG.md

@@ -4,7 +4,31 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
-## [1.4.0] - Unreleased
+## [1.5.0] - Unreleased
+
+### Added
+- New API with snake_case methods and result objects:
+  - `PolarityClassifier`: `pretrained()`, `load()`, `save()`, `predict()`, `predict_many()`, `predict_proba()`,
+    `analyze()` / `analyze_many()` (→ `PolarityResult` with per-label probabilities), `fit()` / `fit_csv()`
+    (→ `TrainingReport` with accuracy, macro-F1 and per-label metrics), `evaluate()` / `evaluate_csv()`
+    (→ `EvaluationReport` with a confusion matrix), `analyze_csv()` (optional probability columns) and `summarize()`.
+  - `EmotionAnalyzer`: `pretrained()`, `load()`, `save()`, `analyze()` / `analyze_many()` (→ `EmotionResult` with
+    `dominant`, `matched_words`, English names), `scores()`, `dominant()`, `fit_csv()`, `add_lexicon()`, `add_word()`,
+    `analyze_csv()` (one column per emotion plus `dominant_emotion`).
+  - Training/analysis methods accept a CSV path or a `pandas.DataFrame`; emotions may be given in Persian or English.
+- `persent` command-line tool (`polarity`, `emotion`, `csv`, `train`, `evaluate`), also as `python -m PerSent`.
+- `PolarityResult`, `EmotionResult`, `TrainingReport`, `EvaluationReport`, `EMOTIONS`, `EMOTION_NAMES_EN`, `LABELS`
+  exported from the package.
+
+### Changed
+- Polarity predictions are computed in batches (faster for CSV files); results are unchanged.
+- Emotion scores are always returned in the same order (شادی, غم, ترس, عصبانیت, تنفر, شگفتی, آرامش).
+
+### Deprecated
+- `CommentAnalyzer` and `SentimentAnalyzer` (and their camelCase methods) now emit a `DeprecationWarning`. They
+  keep their exact 1.4 behaviour and will be removed in PerSent 2.0. See the migration table in the README.
+
+## [1.4.0] - 2026-11-10
 
 ### Added
 - `pyproject.toml` packaging (hatchling) with a single version source (`src/PerSent/_version.py`).
@@ -48,5 +72,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 ## [1.3.3] - 2025-08-22
 - Last release with the original `setup.py` layout and pickle-based models.
 
-[1.4.0]: https://github.com/RezaGooner/PerSent/compare/088b919...HEAD
+[1.5.0]: https://github.com/RezaGooner/PerSent/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/RezaGooner/PerSent/compare/088b919...v1.4.0
 [1.3.3]: https://pypi.org/project/PerSent/1.3.3/

persent-1.5.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: PerSent
+Version: 1.5.0
+Summary: Persian sentiment and emotion analysis toolkit
+Project-URL: Homepage, https://github.com/RezaGooner/PerSent
+Project-URL: Source, https://github.com/RezaGooner/PerSent
+Project-URL: Issues, https://github.com/RezaGooner/PerSent/issues
+Project-URL: Changelog, https://github.com/RezaGooner/PerSent/blob/main/CHANGELOG.md
+Author-email: Reza Asadi <RezaAsadiProgrammer@Gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: emotion-detection,farsi,nlp,persian,sentiment-analysis,text-classification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Persian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: gensim>=4.3.2
+Requires-Dist: hazm>=0.9.3
+Requires-Dist: joblib>=1.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: tqdm>=4.62
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PerSent (Persian Sentiment Analyzer)
+
+[![PyPI](https://img.shields.io/pypi/v/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![Python](https://img.shields.io/pypi/pyversions/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![CI](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml/badge.svg)](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Persian](https://img.shields.io/badge/Persian-فارسی-blue.svg)](README.fa.md)
+
+![PerSent Logo](https://github.com/user-attachments/assets/6bb1633b-6ed3-47fa-aae2-f97886dc4e22)
+
+PerSent is a lightweight Python library and command-line tool for **sentiment and emotion analysis of Persian (Farsi) text**.
+
+- **`PolarityClassifier`** labels product/service reviews as `recommended`, `not_recommended` or `no_idea`, with probabilities.
+- **`EmotionAnalyzer`** scores seven emotions with a weighted lexicon:
+  شادی (happiness), غم (sadness), ترس (fear), عصبانیت (anger), تنفر (disgust), شگفتی (surprise), آرامش (calmness).
+- Pre-trained models included (no download at runtime), CSV in/out, train and evaluate your own models.
+
+## Installation
+
+```bash
+pip install PerSent
+```
+
+Requires Python 3.10–3.13.
+
+## Quick start
+
+### Review polarity
+
+```python
+from PerSent import PolarityClassifier
+
+clf = PolarityClassifier.pretrained()
+
+clf.predict("کیفیت عالی داشت")                 # 'recommended'
+clf.predict_proba("کیفیت عالی داشت")           # {'not_recommended': 0.13, 'recommended': 0.74, 'no_idea': 0.13}
+
+result = clf.analyze("افتضاح بود")
+result.label, result.confidence                # ('not_recommended', 0.9998)
+
+clf.predict_many(["خوب بود", "پولم هدر رفت"])    # batch
+```
+
+### Emotions
+
+```python
+from PerSent import EmotionAnalyzer
+
+emo = EmotionAnalyzer.pretrained()
+result = emo.analyze("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+
+result.scores          # {'شادی': 0.0, 'غم': 36.0, 'ترس': 28.0, 'عصبانیت': 36.0, ...}
+result.dominant        # 'غم'
+result.matched_words   # lexicon words that produced the scores
+result.scores_en()     # {'happiness': 0.0, 'sadness': 36.0, 'fear': 28.0, 'anger': 36.0, ...}
+result.to_dict(lang="en")
+```
+
+### CSV files
+
+```python
+clf.analyze_csv("comments.csv", "results.csv", text_column="نظرات",   # name or 0-based / negative index
+                include_scores=True, summary_csv="summary.csv")
+
+emo.analyze_csv("texts.csv", "emotions.csv", text_column="text", lang="en")  # one column per emotion
+```
+
+Both methods also accept a `pandas.DataFrame` and return the resulting DataFrame. Output files are UTF-8 with BOM, so
+they open correctly in Excel.
+
+### Command line
+
+```bash
+persent polarity "کیفیت عالی داشت" "افتضاح بود" --proba
+echo "خیلی خوشحالم" | persent emotion --lang en
+persent emotion --file texts.txt --json                    # one JSON object per line
+persent csv comments.csv -o results.csv -c نظرات --scores --summary summary.csv
+persent csv texts.csv -o emotions.csv --task emotion -c text
+persent train polarity train.csv -o my_model/ --seed 42
+persent evaluate test.csv -m my_model/
+```
+
+`python -m PerSent ...` works as well. Run `persent <command> --help` for all options.
+
+## Training, evaluating and saving models
+
+```python
+from PerSent import PolarityClassifier, EmotionAnalyzer
+
+clf = PolarityClassifier()
+report = clf.fit_csv("dataset/train.csv", random_state=42)   # columns: body, recommendation_status
+print(report)                  # Trained on ... texts, tested on ...: accuracy=..., macro-F1=...
+clf.save("my_model/")          # -> my_model/comment_model.npz
+clf = PolarityClassifier.load("my_model/")
+print(clf.evaluate_csv("test.csv"))
+
+emo = EmotionAnalyzer.pretrained()          # or EmotionAnalyzer() to start empty
+emo.fit_csv("dataset/emotion_dataset.csv")  # columns: text, sentiment, weight
+emo.add_lexicon("my_words.csv")             # word, emotion, weight
+emo.add_word("سرمست", "happiness", weight=1.5)   # single words only
+emo.save("my_emotions.json")
+emo = EmotionAnalyzer.load("my_emotions.json")
+```
+
+Models are stored as plain `.npz` / `.json` files — loading them never executes code.
+
+## API reference
+
+### `PolarityClassifier`
+
+| Member | Description |
+|---|---|
+| `PolarityClassifier.pretrained()` | Bundled model. |
+| `PolarityClassifier.load(path)` / `save(path)` | Directory (`comment_model.npz`) or `.npz` file. 1.x pickle folders load with a warning. |
+| `predict(text)` / `predict_many(texts)` | Label(s). Texts without letters return `no_idea`. |
+| `predict_proba(text)` | `{label: probability}`. |
+| `analyze(text)` / `analyze_many(texts)` | `PolarityResult(text, label, scores)` with `.confidence`, `.label_fa`, `.to_dict()`. |
+| `fit(texts, labels, *, vector_size=100, window=5, min_count=1, epochs=5, test_size=0.2, random_state=None, C=1.0, ...)` | Train Word2Vec + logistic regression. Returns a `TrainingReport` (accuracy, macro-F1, per-label metrics on a stratified hold-out split). |
+| `fit_csv(data, text_column="body", label_column="recommendation_status", **fit_kwargs)` | `fit` on a CSV path or DataFrame. |
+| `evaluate(texts, labels)` / `evaluate_csv(data, ...)` | `EvaluationReport` with accuracy, macro-F1, per-label metrics and confusion matrix. |
+| `analyze_csv(input, output=None, *, text_column=0, output_column="sentiment", include_scores=False, summary_csv=None)` | Analyze a column; returns a DataFrame. |
+
+### `EmotionAnalyzer`
+
+| Member | Description |
+|---|---|
+| `EmotionAnalyzer.pretrained()` | Bundled lexicon. |
+| `EmotionAnalyzer.load(path)` / `save(path)` | `.json` file or directory. |
+| `analyze(text)` / `analyze_many(texts)` | `EmotionResult(text, scores, matched_words)` with `.dominant`, `.dominant_en`, `.scores_en()`, `.to_dict(lang)`. |
+| `scores(text)` / `dominant(text)` | Shortcuts. |
+| `fit_csv(data, text_column="text", emotion_column=None, weight_column="weight", *, reset=False)` | Learn emotion words from labelled texts (merged into the current lexicon unless `reset=True`). |
+| `add_lexicon(data, word_column=0, emotion_column=1, weight_column=2)` | Add a word/emotion/weight table. Emotions may be Persian or English names. |
+| `add_word(word, emotion, weight=1.0)` | Add a single word. |
+| `analyze_csv(input, output=None, *, text_column="text", expand=True, lang="fa")` | One column per emotion plus `dominant_emotion`. |
+
+Errors derive from `PerSent.PerSentError`: `ModelNotLoadedError`, `ModelFileError`, `DataValidationError`
+(which is also a `ValueError`). Messages are logged with the standard `logging` module (logger `"PerSent"`).
+
+## Model quality and limitations
+
+- The bundled polarity model reaches about **65 % accuracy** (macro-F1 ≈ 0.64) on a 10 000-review sample of
+  [`dataset/train.csv`](dataset/train.csv) — three balanced classes, so chance level is 33 %. Better models are planned.
+- The emotion analyzer is lexicon-based and does **not handle negation** yet ("خوشحال نیستم" is scored as happiness).
+- hazm's stop-word list contains opinion words such as "خوب", "بد" and "عالی", which are removed before
+  classification; short reviews made only of such words are therefore unreliable.
+
+A larger training set is available [here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train).
+
+## Upgrading from 1.x
+
+`CommentAnalyzer` and `SentimentAnalyzer` still work exactly as before but emit a `DeprecationWarning`; they will be
+removed in PerSent 2.0.
+
+| 1.x | 1.5+ |
+|---|---|
+| `a = CommentAnalyzer(); a.loadModel()` | `clf = PolarityClassifier.pretrained()` |
+| `a.analyzeText(t)` | `clf.predict(t)` (or `clf.analyze(t)` for probabilities) |
+| `a.analyzeTexts(ts)` | `clf.predict_many(ts)` |
+| `a.train(csv)` → accuracy | `clf.fit_csv(csv)` → `TrainingReport` |
+| `a.saveModel()` / `a.loadModel()` with `model_dir` | `clf.save(dir)` / `PolarityClassifier.load(dir)` |
+| `a.analyzeCSV(i, o, s, col)` → DataFrame or `None` | `clf.analyze_csv(i, o, text_column=col, summary_csv=s)` (raises on error) |
+| `s = SentimentAnalyzer(); s.loadModel()` | `emo = EmotionAnalyzer.pretrained()` |
+| `s.analyzeText(t)` | `emo.analyze(t).scores` |
+| `s.train(csv)` → `{"status": ...}` | `emo.fit_csv(csv)` (raises on error) |
+| `s.loadLex(csv)` | `emo.add_lexicon(csv)` |
+| `s.saveModel(name)` / `s.loadModel(name)` | `emo.save(path)` / `EmotionAnalyzer.load(path)` |
+| `s.analyzeCSV(i, o)` → `True` / `False` | `emo.analyze_csv(i, o)` |
+
+See [CHANGELOG.md](CHANGELOG.md) for all changes.
+
+## Development
+
+```bash
+git clone https://github.com/RezaGooner/PerSent.git
+cd PerSent
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome — see [CONTRIBUTING](.github/CONTRIBUTING.md).
+
+- [Open an issue](https://github.com/RezaGooner/PerSent/issues/new/choose)
+- [Fork and send a pull request](https://github.com/RezaGooner/PerSent/fork)
+- Email: `RezaAsadiProgrammer@gmail.com` · Telegram: `@RezaGooner`
+
+The project grew out of [Sentiment-Survey-Analyzer](https://github.com/RezaGooner/Sentiment-Survey-Analyzer).
+
+## License
+
+[MIT](LICENSE)

persent-1.5.0/README.fa.md

@@ -0,0 +1,194 @@
+<div dir="rtl">
+
+# PerSent پرسنت
+
+[![PyPI](https://img.shields.io/pypi/v/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![Python](https://img.shields.io/pypi/pyversions/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![CI](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml/badge.svg)](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml)
+[![English](https://img.shields.io/badge/English-انگلیسی-blue.svg)](README.md)
+
+![PerSent Logo](https://github.com/user-attachments/assets/6bb1633b-6ed3-47fa-aae2-f97886dc4e22)
+
+پرسنت (Persian Sentiment Analyzer) یک کتابخانهٔ سبک پایتون و ابزار خط فرمان برای **تحلیل احساسات و هیجان‌های متن فارسی** است.
+
+- **`PolarityClassifier`**: نظر کاربران دربارهٔ کالا یا خدمات را همراه با احتمال هر دسته در یکی از سه دستهٔ `recommended` (پیشنهاد می‌کنم)، `not_recommended` (پیشنهاد نمی‌کنم) و `no_idea` (نظری ندارم) قرار می‌دهد.
+- **`EmotionAnalyzer`**: درصد هفت حس شادی، غم، ترس، عصبانیت، تنفر، شگفتی و آرامش را با یک واژه‌نامهٔ وزن‌دار محاسبه می‌کند.
+- مدل‌های آماده داخل خود بسته هستند و هنگام اجرا چیزی دانلود نمی‌شود. ورودی و خروجی CSV، و آموزش و ارزیابی مدل با داده‌های خودتان هم پشتیبانی می‌شود.
+
+## نصب
+
+</div>
+
+```bash
+pip install PerSent
+```
+
+<div dir="rtl">
+
+به پایتون ۳.۱۰ تا ۳.۱۳ نیاز دارد.
+
+## شروع سریع
+
+### تحلیل نظرات
+
+</div>
+
+```python
+from PerSent import PolarityClassifier
+
+clf = PolarityClassifier.pretrained()
+
+clf.predict("کیفیت عالی داشت")                 # 'recommended'
+clf.predict_proba("کیفیت عالی داشت")           # {'not_recommended': 0.13, 'recommended': 0.74, 'no_idea': 0.13}
+
+result = clf.analyze("افتضاح بود")
+result.label, result.confidence                # ('not_recommended', 0.9998)
+result.label_fa                                # 'پیشنهاد نمی‌کنم'
+
+clf.predict_many(["خوب بود", "پولم هدر رفت"])    # چند متن با هم
+```
+
+<div dir="rtl">
+
+### تحلیل احساس
+
+</div>
+
+```python
+from PerSent import EmotionAnalyzer
+
+emo = EmotionAnalyzer.pretrained()
+result = emo.analyze("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+
+result.scores          # {'شادی': 0.0, 'غم': 36.0, 'ترس': 28.0, 'عصبانیت': 36.0, ...}
+result.dominant        # 'غم'
+result.matched_words   # کلمه‌هایی از واژه‌نامه که در متن پیدا شدند
+result.scores_en()     # همان امتیازها با نام انگلیسی احساس‌ها
+```
+
+<div dir="rtl">
+
+### فایل CSV
+
+</div>
+
+```python
+clf.analyze_csv("comments.csv", "results.csv", text_column="نظرات",   # نام ستون یا شمارهٔ آن (از ۰)
+                include_scores=True, summary_csv="summary.csv")
+
+emo.analyze_csv("texts.csv", "emotions.csv", text_column="text")      # یک ستون برای هر احساس
+```
+
+<div dir="rtl">
+
+هر دو متد به‌جای مسیر فایل، `DataFrame` پانداس هم می‌پذیرند و نتیجه را به شکل DataFrame برمی‌گردانند. فایل‌های خروجی با کدگذاری UTF-8 همراه BOM ذخیره می‌شوند تا در Excel درست نمایش داده شوند.
+
+### خط فرمان
+
+</div>
+
+```bash
+persent polarity "کیفیت عالی داشت" "افتضاح بود" --proba
+echo "خیلی خوشحالم" | persent emotion
+persent emotion --file texts.txt --json
+persent csv comments.csv -o results.csv -c نظرات --scores --summary summary.csv
+persent csv texts.csv -o emotions.csv --task emotion -c text
+persent train polarity train.csv -o my_model/ --seed 42
+persent evaluate test.csv -m my_model/
+```
+
+<div dir="rtl">
+
+دستور `python -m PerSent ...` هم همین کار را می‌کند. برای دیدن همهٔ گزینه‌ها `persent <command> --help` را اجرا کنید.
+
+## آموزش، ارزیابی و ذخیرهٔ مدل
+
+</div>
+
+```python
+from PerSent import PolarityClassifier, EmotionAnalyzer
+
+clf = PolarityClassifier()
+report = clf.fit_csv("dataset/train.csv", random_state=42)   # ستون‌ها: body و recommendation_status
+print(report)                  # دقت و macro-F1 روی دادهٔ آزمون
+clf.save("my_model/")
+clf = PolarityClassifier.load("my_model/")
+print(clf.evaluate_csv("test.csv"))
+
+emo = EmotionAnalyzer.pretrained()          # یا EmotionAnalyzer() برای شروع از صفر
+emo.fit_csv("dataset/emotion_dataset.csv")  # ستون‌ها: text، sentiment و weight
+emo.add_lexicon("my_words.csv")             # کلمه، حس، وزن
+emo.add_word("سرمست", "شادی", weight=1.5)    # فقط تک‌کلمه
+emo.save("my_emotions.json")
+emo = EmotionAnalyzer.load("my_emotions.json")
+```
+
+<div dir="rtl">
+
+مدل‌ها به شکل فایل‌های ساده `.npz` و `.json` ذخیره می‌شوند و بارگذاری آن‌ها هیچ کدی اجرا نمی‌کند.
+
+- برچسب‌های آموزش `PolarityClassifier` یکی از `recommended`، `not_recommended` یا `no_idea` هستند و برچسب خالی `no_idea` در نظر گرفته می‌شود.
+- نام احساس‌ها در `EmotionAnalyzer` را می‌توانید فارسی (`شادی`) یا انگلیسی (`happiness`) بنویسید.
+
+جدول کامل متدها در [README انگلیسی](README.md#api-reference) آمده است.
+
+## کیفیت مدل و محدودیت‌ها
+
+- دقت مدل آمادهٔ تحلیل نظرات روی نمونه‌ای ۱۰٬۰۰۰تایی از [`dataset/train.csv`](dataset/train.csv) حدود **۶۵٪** است (macro-F1 ≈ ۰.۶۴). سه دسته متوازن‌اند و دقت تصادفی ۳۳٪ است. بهبود مدل در برنامهٔ نسخه‌های بعدی است.
+- تحلیلگر احساس بر پایهٔ واژه‌نامه کار می‌کند و **هنوز منفی‌سازی را تشخیص نمی‌دهد**. مثلاً «خوشحال نیستم» شادی حساب می‌شود.
+- لیست ایست‌واژه‌های hazm کلمه‌هایی مثل «خوب»، «بد» و «عالی» را هم شامل می‌شود و این کلمه‌ها پیش از دسته‌بندی حذف می‌شوند. به همین دلیل نتیجه برای نظرهای خیلی کوتاه قابل اعتماد نیست.
+
+مجموعه‌دادهٔ بزرگ‌تر برای آموزش: [اینجا](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train)
+
+## ارتقا از نسخهٔ 1.x
+
+`CommentAnalyzer` و `SentimentAnalyzer` دقیقاً مثل قبل کار می‌کنند، ولی یک `DeprecationWarning` نشان می‌دهند و در نسخهٔ 2.0 حذف خواهند شد.
+
+</div>
+
+| 1.x | 1.5+ |
+|---|---|
+| `a = CommentAnalyzer(); a.loadModel()` | `clf = PolarityClassifier.pretrained()` |
+| `a.analyzeText(t)` | `clf.predict(t)` / `clf.analyze(t)` |
+| `a.train(csv)` | `clf.fit_csv(csv)` |
+| `a.saveModel()` / `a.loadModel()` | `clf.save(dir)` / `PolarityClassifier.load(dir)` |
+| `a.analyzeCSV(i, o, s, col)` | `clf.analyze_csv(i, o, text_column=col, summary_csv=s)` |
+| `s = SentimentAnalyzer(); s.loadModel()` | `emo = EmotionAnalyzer.pretrained()` |
+| `s.analyzeText(t)` | `emo.analyze(t).scores` |
+| `s.train(csv)` / `s.loadLex(csv)` | `emo.fit_csv(csv)` / `emo.add_lexicon(csv)` |
+| `s.saveModel(name)` / `s.loadModel(name)` | `emo.save(path)` / `EmotionAnalyzer.load(path)` |
+| `s.analyzeCSV(i, o)` | `emo.analyze_csv(i, o)` |
+
+<div dir="rtl">
+
+متدهای جدید در صورت خطا exception می‌دهند، نه `None` یا `False`. فهرست کامل تغییرات در [CHANGELOG.md](CHANGELOG.md) است.
+
+## توسعه
+
+</div>
+
+```bash
+git clone https://github.com/RezaGooner/PerSent.git
+cd PerSent
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+<div dir="rtl">
+
+## مشارکت
+
+خوشحال می‌شوم پیشنهادها، گزارش باگ و Pull Requestهایتان را ببینم. راهنمای مشارکت در [CONTRIBUTING](.github/CONTRIBUTING.md) است.
+
+- [ثبت Issue](https://github.com/RezaGooner/PerSent/issues/new/choose)
+- [Fork و ارسال Pull Request](https://github.com/RezaGooner/PerSent/fork)
+- ایمیل: `RezaAsadiProgrammer@gmail.com` · تلگرام: `@RezaGooner`
+
+این پروژه از مخزن [Sentiment-Survey-Analyzer](https://github.com/RezaGooner/Sentiment-Survey-Analyzer) شکل گرفته است.
+
+## مجوز
+
+[MIT](LICENSE)
+
+</div>

persent-1.5.0/README.md

@@ -0,0 +1,193 @@
+# PerSent (Persian Sentiment Analyzer)
+
+[![PyPI](https://img.shields.io/pypi/v/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![Python](https://img.shields.io/pypi/pyversions/PerSent.svg)](https://pypi.org/project/PerSent/)
+[![CI](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml/badge.svg)](https://github.com/RezaGooner/PerSent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Persian](https://img.shields.io/badge/Persian-فارسی-blue.svg)](README.fa.md)
+
+![PerSent Logo](https://github.com/user-attachments/assets/6bb1633b-6ed3-47fa-aae2-f97886dc4e22)
+
+PerSent is a lightweight Python library and command-line tool for **sentiment and emotion analysis of Persian (Farsi) text**.
+
+- **`PolarityClassifier`** labels product/service reviews as `recommended`, `not_recommended` or `no_idea`, with probabilities.
+- **`EmotionAnalyzer`** scores seven emotions with a weighted lexicon:
+  شادی (happiness), غم (sadness), ترس (fear), عصبانیت (anger), تنفر (disgust), شگفتی (surprise), آرامش (calmness).
+- Pre-trained models included (no download at runtime), CSV in/out, train and evaluate your own models.
+
+## Installation
+
+```bash
+pip install PerSent
+```
+
+Requires Python 3.10–3.13.
+
+## Quick start
+
+### Review polarity
+
+```python
+from PerSent import PolarityClassifier
+
+clf = PolarityClassifier.pretrained()
+
+clf.predict("کیفیت عالی داشت")                 # 'recommended'
+clf.predict_proba("کیفیت عالی داشت")           # {'not_recommended': 0.13, 'recommended': 0.74, 'no_idea': 0.13}
+
+result = clf.analyze("افتضاح بود")
+result.label, result.confidence                # ('not_recommended', 0.9998)
+
+clf.predict_many(["خوب بود", "پولم هدر رفت"])    # batch
+```
+
+### Emotions
+
+```python
+from PerSent import EmotionAnalyzer
+
+emo = EmotionAnalyzer.pretrained()
+result = emo.analyze("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+
+result.scores          # {'شادی': 0.0, 'غم': 36.0, 'ترس': 28.0, 'عصبانیت': 36.0, ...}
+result.dominant        # 'غم'
+result.matched_words   # lexicon words that produced the scores
+result.scores_en()     # {'happiness': 0.0, 'sadness': 36.0, 'fear': 28.0, 'anger': 36.0, ...}
+result.to_dict(lang="en")
+```
+
+### CSV files
+
+```python
+clf.analyze_csv("comments.csv", "results.csv", text_column="نظرات",   # name or 0-based / negative index
+                include_scores=True, summary_csv="summary.csv")
+
+emo.analyze_csv("texts.csv", "emotions.csv", text_column="text", lang="en")  # one column per emotion
+```
+
+Both methods also accept a `pandas.DataFrame` and return the resulting DataFrame. Output files are UTF-8 with BOM, so
+they open correctly in Excel.
+
+### Command line
+
+```bash
+persent polarity "کیفیت عالی داشت" "افتضاح بود" --proba
+echo "خیلی خوشحالم" | persent emotion --lang en
+persent emotion --file texts.txt --json                    # one JSON object per line
+persent csv comments.csv -o results.csv -c نظرات --scores --summary summary.csv
+persent csv texts.csv -o emotions.csv --task emotion -c text
+persent train polarity train.csv -o my_model/ --seed 42
+persent evaluate test.csv -m my_model/
+```
+
+`python -m PerSent ...` works as well. Run `persent <command> --help` for all options.
+
+## Training, evaluating and saving models
+
+```python
+from PerSent import PolarityClassifier, EmotionAnalyzer
+
+clf = PolarityClassifier()
+report = clf.fit_csv("dataset/train.csv", random_state=42)   # columns: body, recommendation_status
+print(report)                  # Trained on ... texts, tested on ...: accuracy=..., macro-F1=...
+clf.save("my_model/")          # -> my_model/comment_model.npz
+clf = PolarityClassifier.load("my_model/")
+print(clf.evaluate_csv("test.csv"))
+
+emo = EmotionAnalyzer.pretrained()          # or EmotionAnalyzer() to start empty
+emo.fit_csv("dataset/emotion_dataset.csv")  # columns: text, sentiment, weight
+emo.add_lexicon("my_words.csv")             # word, emotion, weight
+emo.add_word("سرمست", "happiness", weight=1.5)   # single words only
+emo.save("my_emotions.json")
+emo = EmotionAnalyzer.load("my_emotions.json")
+```
+
+Models are stored as plain `.npz` / `.json` files — loading them never executes code.
+
+## API reference
+
+### `PolarityClassifier`
+
+| Member | Description |
+|---|---|
+| `PolarityClassifier.pretrained()` | Bundled model. |
+| `PolarityClassifier.load(path)` / `save(path)` | Directory (`comment_model.npz`) or `.npz` file. 1.x pickle folders load with a warning. |
+| `predict(text)` / `predict_many(texts)` | Label(s). Texts without letters return `no_idea`. |
+| `predict_proba(text)` | `{label: probability}`. |
+| `analyze(text)` / `analyze_many(texts)` | `PolarityResult(text, label, scores)` with `.confidence`, `.label_fa`, `.to_dict()`. |
+| `fit(texts, labels, *, vector_size=100, window=5, min_count=1, epochs=5, test_size=0.2, random_state=None, C=1.0, ...)` | Train Word2Vec + logistic regression. Returns a `TrainingReport` (accuracy, macro-F1, per-label metrics on a stratified hold-out split). |
+| `fit_csv(data, text_column="body", label_column="recommendation_status", **fit_kwargs)` | `fit` on a CSV path or DataFrame. |
+| `evaluate(texts, labels)` / `evaluate_csv(data, ...)` | `EvaluationReport` with accuracy, macro-F1, per-label metrics and confusion matrix. |
+| `analyze_csv(input, output=None, *, text_column=0, output_column="sentiment", include_scores=False, summary_csv=None)` | Analyze a column; returns a DataFrame. |
+
+### `EmotionAnalyzer`
+
+| Member | Description |
+|---|---|
+| `EmotionAnalyzer.pretrained()` | Bundled lexicon. |
+| `EmotionAnalyzer.load(path)` / `save(path)` | `.json` file or directory. |
+| `analyze(text)` / `analyze_many(texts)` | `EmotionResult(text, scores, matched_words)` with `.dominant`, `.dominant_en`, `.scores_en()`, `.to_dict(lang)`. |
+| `scores(text)` / `dominant(text)` | Shortcuts. |
+| `fit_csv(data, text_column="text", emotion_column=None, weight_column="weight", *, reset=False)` | Learn emotion words from labelled texts (merged into the current lexicon unless `reset=True`). |
+| `add_lexicon(data, word_column=0, emotion_column=1, weight_column=2)` | Add a word/emotion/weight table. Emotions may be Persian or English names. |
+| `add_word(word, emotion, weight=1.0)` | Add a single word. |
+| `analyze_csv(input, output=None, *, text_column="text", expand=True, lang="fa")` | One column per emotion plus `dominant_emotion`. |
+
+Errors derive from `PerSent.PerSentError`: `ModelNotLoadedError`, `ModelFileError`, `DataValidationError`
+(which is also a `ValueError`). Messages are logged with the standard `logging` module (logger `"PerSent"`).
+
+## Model quality and limitations
+
+- The bundled polarity model reaches about **65 % accuracy** (macro-F1 ≈ 0.64) on a 10 000-review sample of
+  [`dataset/train.csv`](dataset/train.csv) — three balanced classes, so chance level is 33 %. Better models are planned.
+- The emotion analyzer is lexicon-based and does **not handle negation** yet ("خوشحال نیستم" is scored as happiness).
+- hazm's stop-word list contains opinion words such as "خوب", "بد" and "عالی", which are removed before
+  classification; short reviews made only of such words are therefore unreliable.
+
+A larger training set is available [here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train).
+
+## Upgrading from 1.x
+
+`CommentAnalyzer` and `SentimentAnalyzer` still work exactly as before but emit a `DeprecationWarning`; they will be
+removed in PerSent 2.0.
+
+| 1.x | 1.5+ |
+|---|---|
+| `a = CommentAnalyzer(); a.loadModel()` | `clf = PolarityClassifier.pretrained()` |
+| `a.analyzeText(t)` | `clf.predict(t)` (or `clf.analyze(t)` for probabilities) |
+| `a.analyzeTexts(ts)` | `clf.predict_many(ts)` |
+| `a.train(csv)` → accuracy | `clf.fit_csv(csv)` → `TrainingReport` |
+| `a.saveModel()` / `a.loadModel()` with `model_dir` | `clf.save(dir)` / `PolarityClassifier.load(dir)` |
+| `a.analyzeCSV(i, o, s, col)` → DataFrame or `None` | `clf.analyze_csv(i, o, text_column=col, summary_csv=s)` (raises on error) |
+| `s = SentimentAnalyzer(); s.loadModel()` | `emo = EmotionAnalyzer.pretrained()` |
+| `s.analyzeText(t)` | `emo.analyze(t).scores` |
+| `s.train(csv)` → `{"status": ...}` | `emo.fit_csv(csv)` (raises on error) |
+| `s.loadLex(csv)` | `emo.add_lexicon(csv)` |
+| `s.saveModel(name)` / `s.loadModel(name)` | `emo.save(path)` / `EmotionAnalyzer.load(path)` |
+| `s.analyzeCSV(i, o)` → `True` / `False` | `emo.analyze_csv(i, o)` |
+
+See [CHANGELOG.md](CHANGELOG.md) for all changes.
+
+## Development
+
+```bash
+git clone https://github.com/RezaGooner/PerSent.git
+cd PerSent
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome — see [CONTRIBUTING](.github/CONTRIBUTING.md).
+
+- [Open an issue](https://github.com/RezaGooner/PerSent/issues/new/choose)
+- [Fork and send a pull request](https://github.com/RezaGooner/PerSent/fork)
+- Email: `RezaAsadiProgrammer@gmail.com` · Telegram: `@RezaGooner`
+
+The project grew out of [Sentiment-Survey-Analyzer](https://github.com/RezaGooner/Sentiment-Survey-Analyzer).
+
+## License
+
+[MIT](LICENSE)

{persent-1.4.0 → persent-1.5.0}/pyproject.toml

@@ -40,6 +40,9 @@ dependencies = [
     "tqdm>=4.62",
 ]
 
+[project.scripts]
+persent = "PerSent.cli:main"
+
 [project.optional-dependencies]
 dev = ["pytest>=7", "pytest-cov", "ruff>=0.6", "build", "twine"]