PerSent 1.3.3__tar.gz → 1.4.0__tar.gz

persent-1.4.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Environments
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+.ipynb_checkpoints/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Locally trained models
+/model/
+/models/
+PerSent/model/

persent-1.4.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+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
+
+### Added
+- `pyproject.toml` packaging (hatchling) with a single version source (`src/PerSent/_version.py`).
+- Support for Python 3.12 and 3.13 (requires Python ≥ 3.10).
+- Test suite (pytest), linting (ruff) and GitHub Actions CI on Linux, Windows and macOS.
+- Release workflow that publishes to PyPI with Trusted Publishing.
+- `CommentAnalyzer.analyzeTexts()` for lists of texts.
+- `CommentAnalyzer.train()` parameters `random_state`, `text_column`, `label_column`, `workers`; the split is now stratified.
+- `SentimentAnalyzer.train(reset=...)` to start from an empty model.
+- Exception hierarchy: `PerSentError`, `ModelNotLoadedError`, `ModelFileError`, `DataValidationError`
+  (all subclasses of `Exception`).
+- Type hints (`py.typed`) and `scripts/convert_legacy_models.py`.
+- Vendored hazm 0.9's suffix stemmer (MIT), so preprocessing — and therefore predictions — stay the same with
+  hazm 0.12 on Python 3.12+ (whose new stemmer changed ~10 % of predictions).
+
+### Changed
+- Pre-trained models are stored in pickle-free formats (`comment_model.npz`, `emotion_lexicon.json`).
+  Predictions are identical to 1.3.3; the wheel shrank from ~27 MB to ~14 MB.
+- `model_dir` now defaults to `None`: `loadModel()` loads the bundled model and `train()` only saves when a
+  `model_dir` is set. Legacy 1.3.x model files in an explicit `model_dir` still load (with a `DeprecationWarning`).
+- Status messages use `logging` (logger `"PerSent"`) instead of `print`.
+- Removed the `numpy<2` / `scipy<1.14` pins that made the package uninstallable on Python 3.12+.
+- Repository layout moved to `src/`.
+
+### Fixed
+- **Security:** `loadModel()` no longer loads (pickle) files from `./PerSent/model` in the current working
+  directory, and creating an analyzer no longer creates that folder.
+- `SentimentAnalyzer.train()` failed with its default arguments on the bundled dataset (`emotion_col` default).
+- `CommentAnalyzer` deleted all upper-case Latin letters ("iPhone" → "i hone") due to a regex range bug.
+- `CommentAnalyzer.train(vector_size=...)` crashed for any size other than 100.
+- Empty labels in the training CSV crashed training instead of being treated as `no_idea`.
+- `SentimentAnalyzer.loadLex()` crashed when columns were given by name.
+- Empty or digit-only texts were classified as `recommended`; they now return `no_idea`.
+- Missing values (NaN) in CSV text columns were analyzed as the word "nan".
+- With hazm >= 0.11, every text re-created hazm's `WordTokenizer` (~0.3 s per text); one instance is now reused.
+
+### Removed
+- `setup.py`, `setup.cfg`, `MANIFEST.in`, `requirements.txt`, committed `build/` output and `PKG-INFO`.
+- Draft JOSS paper files (`paper.md`, `paper.bib`).
+
+## [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.3.3]: https://pypi.org/project/PerSent/1.3.3/

persent-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 𝐑𝐞𝐳𝐚 𝐀𝐬𝐚𝐝𝐢
+
+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.

persent-1.4.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: PerSent
+Version: 1.4.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 for **sentiment and emotion analysis of Persian (Farsi) text**.
+
+- **`CommentAnalyzer`** classifies product/service reviews as `recommended`, `not_recommended` or `no_idea`
+  (Word2Vec sentence embeddings + logistic regression).
+- **`SentimentAnalyzer`** scores seven emotions with a weighted lexicon:
+  شادی (happiness), غم (sadness), ترس (fear), عصبانیت (anger), تنفر (disgust), شگفتی (surprise), آرامش (calmness).
+- Single texts or whole CSV files, pre-trained models included, train your own models from CSV.
+
+## Installation
+
+```bash
+pip install PerSent
+```
+
+Requires Python 3.10–3.13. Pre-trained models are bundled with the package, so no download is needed at runtime.
+
+## Quick start
+
+### Review / comment polarity
+
+```python
+from PerSent import CommentAnalyzer
+
+analyzer = CommentAnalyzer()
+analyzer.loadModel()                         # bundled pre-trained model
+
+analyzer.analyzeText("کیفیت عالی داشت")       # 'recommended'
+analyzer.analyzeText("افتضاح بود")            # 'not_recommended'
+analyzer.analyzeTexts(["خوب بود", "بد بود"])   # list of labels
+```
+
+Batch-process a CSV file (adds a `sentiment` column):
+
+```python
+analyzer.analyzeCSV("comments.csv", "results.csv")                 # first column
+analyzer.analyzeCSV("comments.csv", "results.csv", None, -1)       # last column
+analyzer.analyzeCSV("comments.csv", "results.csv", None, "نظرات")  # column by name
+analyzer.analyzeCSV("comments.csv", "results.csv", "summary.csv")  # + summary report
+```
+
+### Emotions
+
+```python
+from PerSent import SentimentAnalyzer
+
+analyzer = SentimentAnalyzer()
+analyzer.loadModel()
+
+result = analyzer.analyzeText("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+for emotion, score in sorted(result.items(), key=lambda x: x[1], reverse=True):
+    print(f"{emotion}: {score:.2f}%")
+```
+
+```text
+غم: 36.00%
+عصبانیت: 36.00%
+ترس: 28.00%
+شادی: 0.00%
+...
+```
+
+```python
+analyzer.analyzeCSV("input.csv", "output.csv")   # text column 'text' -> 'sentiment_analysis'
+```
+
+## Training and saving your own models
+
+Pass a `model_dir` to keep your own models. Without it, `loadModel()` always loads the bundled
+pre-trained model and `train()` keeps the result in memory only.
+
+```python
+from PerSent import CommentAnalyzer, SentimentAnalyzer
+
+comments = CommentAnalyzer(model_dir="my_models")
+accuracy = comments.train("train.csv", random_state=42)   # saved to my_models/comment_model.npz
+comments.loadModel()                                        # later: loads from my_models/
+
+emotions = SentimentAnalyzer(model_dir="my_models")
+emotions.train("dataset/emotion_dataset.csv")              # saved to my_models/weighted_sentiment_model.json
+emotions.saveModel("custom")                                # my_models/custom.json
+emotions.loadModel("custom")
+```
+
+## API reference
+
+### `CommentAnalyzer(model_dir=None)`
+
+| Method | Description |
+|---|---|
+| `train(train_csv, test_size=0.2, vector_size=100, window=5, random_state=None, text_column="body", label_column="recommendation_status", workers=4)` | Train from a CSV. Labels must be `recommended`, `not_recommended` or `no_idea`; empty labels count as `no_idea`. Returns held-out accuracy. Saves to `model_dir` if set. |
+| `analyzeText(text)` | Label for one text. Texts without letters (empty, digits only, …) return `no_idea`. |
+| `analyzeTexts(texts, show_progress=False)` | Labels for many texts. |
+| `analyzeCSV(input_csv, output_path, summary_path=None, text_column=0)` | Analyze a CSV column (name or 0-based / negative index). Returns a DataFrame, or `None` on error. |
+| `saveModel(model_dir=None)` / `loadModel(model_dir=None)` | Save / load `comment_model.npz`. `loadModel` falls back to the bundled model. |
+
+### `SentimentAnalyzer(model_dir=None)`
+
+| Method | Description |
+|---|---|
+| `train(train_csv, text_col="text", emotion_col=None, weight_col="weight", reset=False)` | Learn weighted emotion words from a CSV. `emotion_col` defaults to `sentiment` (or `emotion`). Merges into the current model unless `reset=True`. Returns `{"status", "message"}`. |
+| `loadLex(csv_file, word_col=0, emotion_col=1, weight_col=2)` | Add a word/emotion/weight lexicon. Columns by index, or by name for CSVs with a header. Invalid weights default to 1.0. |
+| `analyzeText(text)` | `{emotion: percentage}` for the seven emotions (all 0.0 if no lexicon word is found). |
+| `analyzeCSV(input_csv, output_csv, text_col="text", output_col="sentiment_analysis")` | Analyze a CSV. Returns `True` / `False`. |
+| `saveModel(model_name="weighted_sentiment_model", model_dir=None)` / `loadModel(...)` | Save / load `<model_name>.json`. |
+
+Errors derive from `PerSent.PerSentError` (`ModelNotLoadedError`, `ModelFileError`, `DataValidationError`).
+Progress and status messages use the standard `logging` module (logger name `"PerSent"`).
+
+## Model quality and limitations
+
+- The bundled comment 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 common opinion words such as "خوب" and "عالی", which are removed before
+  classification.
+
+A larger training set is available [here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train).
+
+## Upgrading from 1.3.x
+
+- Models are stored in safe, pickle-free formats (`.npz` / `.json`). Models you saved with 1.3.x can still be loaded
+  with `CommentAnalyzer(model_dir=...)` / `SentimentAnalyzer(model_dir=...)` (a `DeprecationWarning` is shown);
+  call `saveModel()` once to convert them. `scripts/convert_legacy_models.py` converts a folder in one go.
+- PerSent no longer creates or reads a `PerSent/model` folder in the current working directory. Pass `model_dir`
+  explicitly to save and load your own models.
+
+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/README.fa.md

@@ -0,0 +1,163 @@
+<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) یک کتابخانهٔ سبک پایتون برای **تحلیل احساسات و هیجان‌های متن فارسی** است.
+
+- **`CommentAnalyzer`**: نظر کاربران دربارهٔ کالا یا خدمات را در یکی از سه دستهٔ `recommended` (پیشنهاد می‌کند)، `not_recommended` (پیشنهاد نمی‌کند) و `no_idea` (نظری ندارد) قرار می‌دهد.
+- **`SentimentAnalyzer`**: درصد هفت حس شادی، غم، ترس، عصبانیت، تنفر، شگفتی و آرامش را در متن، با یک واژه‌نامهٔ وزن‌دار محاسبه می‌کند.
+- تحلیل تک‌متن یا کل یک فایل CSV، همراه با مدل‌های ازپیش‌آموزش‌دیده و امکان آموزش مدل با داده‌های خودتان.
+
+## نصب
+
+</div>
+
+```bash
+pip install PerSent
+```
+
+<div dir="rtl">
+
+به پایتون ۳.۱۰ تا ۳.۱۳ نیاز دارد. مدل‌های ازپیش‌آموزش‌دیده داخل خود بسته هستند و هنگام اجرا چیزی دانلود نمی‌شود.
+
+## شروع سریع
+
+### تحلیل نظرات
+
+</div>
+
+```python
+from PerSent import CommentAnalyzer
+
+analyzer = CommentAnalyzer()
+analyzer.loadModel()                         # مدل آمادهٔ همراه کتابخانه
+
+analyzer.analyzeText("کیفیت عالی داشت")       # 'recommended'
+analyzer.analyzeText("افتضاح بود")            # 'not_recommended'
+analyzer.analyzeTexts(["خوب بود", "بد بود"])   # فهرست برچسب‌ها
+```
+
+<div dir="rtl">
+
+تحلیل یک فایل CSV (یک ستون `sentiment` به خروجی اضافه می‌شود):
+
+</div>
+
+```python
+analyzer.analyzeCSV("comments.csv", "results.csv")                 # ستون اول
+analyzer.analyzeCSV("comments.csv", "results.csv", None, -1)       # ستون آخر
+analyzer.analyzeCSV("comments.csv", "results.csv", None, "نظرات")  # با نام ستون
+analyzer.analyzeCSV("comments.csv", "results.csv", "summary.csv")  # همراه با فایل خلاصه
+```
+
+<div dir="rtl">
+
+فایل خلاصه تعداد و درصد نظرات هر دسته و تعداد کل نظرات را نشان می‌دهد.
+
+### تحلیل احساس
+
+</div>
+
+```python
+from PerSent import SentimentAnalyzer
+
+analyzer = SentimentAnalyzer()
+analyzer.loadModel()
+
+result = analyzer.analyzeText("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+for emotion, score in sorted(result.items(), key=lambda x: x[1], reverse=True):
+    print(f"{emotion}: {score:.2f}%")
+```
+
+```text
+غم: 36.00%
+عصبانیت: 36.00%
+ترس: 28.00%
+شادی: 0.00%
+...
+```
+
+```python
+analyzer.analyzeCSV("input.csv", "output.csv")   # ستون متن: text ← ستون خروجی: sentiment_analysis
+```
+
+<div dir="rtl">
+
+## آموزش و ذخیرهٔ مدل‌های خودتان
+
+برای نگه داشتن مدل‌های خودتان، پارامتر `model_dir` را بدهید. اگر ندهید، `loadModel()` همیشه مدل آمادهٔ کتابخانه را بارگذاری می‌کند و `train()` چیزی روی دیسک نمی‌نویسد.
+
+</div>
+
+```python
+from PerSent import CommentAnalyzer, SentimentAnalyzer
+
+comments = CommentAnalyzer(model_dir="my_models")
+accuracy = comments.train("train.csv", random_state=42)   # ذخیره در my_models/comment_model.npz
+comments.loadModel()                                        # بعداً: بارگذاری از my_models
+
+emotions = SentimentAnalyzer(model_dir="my_models")
+emotions.train("dataset/emotion_dataset.csv")              # ذخیره در my_models/weighted_sentiment_model.json
+emotions.saveModel("custom")                                # my_models/custom.json
+emotions.loadModel("custom")
+```
+
+<div dir="rtl">
+
+- فایل آموزش `CommentAnalyzer` باید ستون‌های `body` (متن) و `recommendation_status` (برچسب) را داشته باشد. برچسب‌ها یکی از `recommended`، `not_recommended` یا `no_idea` هستند و برچسب خالی `no_idea` در نظر گرفته می‌شود. خروجی `train` دقت مدل روی دادهٔ آزمون است.
+- فایل آموزش `SentimentAnalyzer` ستون‌های `text`، `sentiment` (یکی از هفت حس) و `weight` (وزن) دارد. نمونه‌اش در [`dataset/emotion_dataset.csv`](dataset/emotion_dataset.csv) است. با `reset=True` مدل قبلی پاک می‌شود. در غیر این صورت داده‌های جدید به آن اضافه می‌شوند.
+- با `loadLex(csv_file, word_col=0, emotion_col=1, weight_col=2)` می‌توانید یک واژه‌نامهٔ «کلمه، حس، وزن» اضافه کنید. ستون‌ها را با شماره یا، اگر فایل سرستون دارد، با نام مشخص کنید.
+
+جدول کامل پارامترها در [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.3
+
+- مدل‌ها حالا با قالب‌های امن و بدون pickle (`.npz` و `.json`) ذخیره می‌شوند. مدل‌هایی را که با نسخهٔ 1.3 ذخیره کرده‌اید هنوز می‌توانید با `model_dir` بارگذاری کنید (یک `DeprecationWarning` نمایش داده می‌شود). یک بار `saveModel()` را صدا بزنید تا به قالب جدید تبدیل شوند.
+- کتابخانه دیگر پوشهٔ `PerSent/model` را در پوشهٔ جاری نمی‌سازد و از آنجا هم نمی‌خواند. برای مدل‌های خودتان `model_dir` را صریحاً بدهید.
+
+فهرست کامل تغییرات در [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.4.0/README.md

@@ -0,0 +1,161 @@
+# 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 for **sentiment and emotion analysis of Persian (Farsi) text**.
+
+- **`CommentAnalyzer`** classifies product/service reviews as `recommended`, `not_recommended` or `no_idea`
+  (Word2Vec sentence embeddings + logistic regression).
+- **`SentimentAnalyzer`** scores seven emotions with a weighted lexicon:
+  شادی (happiness), غم (sadness), ترس (fear), عصبانیت (anger), تنفر (disgust), شگفتی (surprise), آرامش (calmness).
+- Single texts or whole CSV files, pre-trained models included, train your own models from CSV.
+
+## Installation
+
+```bash
+pip install PerSent
+```
+
+Requires Python 3.10–3.13. Pre-trained models are bundled with the package, so no download is needed at runtime.
+
+## Quick start
+
+### Review / comment polarity
+
+```python
+from PerSent import CommentAnalyzer
+
+analyzer = CommentAnalyzer()
+analyzer.loadModel()                         # bundled pre-trained model
+
+analyzer.analyzeText("کیفیت عالی داشت")       # 'recommended'
+analyzer.analyzeText("افتضاح بود")            # 'not_recommended'
+analyzer.analyzeTexts(["خوب بود", "بد بود"])   # list of labels
+```
+
+Batch-process a CSV file (adds a `sentiment` column):
+
+```python
+analyzer.analyzeCSV("comments.csv", "results.csv")                 # first column
+analyzer.analyzeCSV("comments.csv", "results.csv", None, -1)       # last column
+analyzer.analyzeCSV("comments.csv", "results.csv", None, "نظرات")  # column by name
+analyzer.analyzeCSV("comments.csv", "results.csv", "summary.csv")  # + summary report
+```
+
+### Emotions
+
+```python
+from PerSent import SentimentAnalyzer
+
+analyzer = SentimentAnalyzer()
+analyzer.loadModel()
+
+result = analyzer.analyzeText("امتحانم رو خراب کردم. احساس می‌کنم یک شکست خورده‌ی تمام عیارم.")
+for emotion, score in sorted(result.items(), key=lambda x: x[1], reverse=True):
+    print(f"{emotion}: {score:.2f}%")
+```
+
+```text
+غم: 36.00%
+عصبانیت: 36.00%
+ترس: 28.00%
+شادی: 0.00%
+...
+```
+
+```python
+analyzer.analyzeCSV("input.csv", "output.csv")   # text column 'text' -> 'sentiment_analysis'
+```
+
+## Training and saving your own models
+
+Pass a `model_dir` to keep your own models. Without it, `loadModel()` always loads the bundled
+pre-trained model and `train()` keeps the result in memory only.
+
+```python
+from PerSent import CommentAnalyzer, SentimentAnalyzer
+
+comments = CommentAnalyzer(model_dir="my_models")
+accuracy = comments.train("train.csv", random_state=42)   # saved to my_models/comment_model.npz
+comments.loadModel()                                        # later: loads from my_models/
+
+emotions = SentimentAnalyzer(model_dir="my_models")
+emotions.train("dataset/emotion_dataset.csv")              # saved to my_models/weighted_sentiment_model.json
+emotions.saveModel("custom")                                # my_models/custom.json
+emotions.loadModel("custom")
+```
+
+## API reference
+
+### `CommentAnalyzer(model_dir=None)`
+
+| Method | Description |
+|---|---|
+| `train(train_csv, test_size=0.2, vector_size=100, window=5, random_state=None, text_column="body", label_column="recommendation_status", workers=4)` | Train from a CSV. Labels must be `recommended`, `not_recommended` or `no_idea`; empty labels count as `no_idea`. Returns held-out accuracy. Saves to `model_dir` if set. |
+| `analyzeText(text)` | Label for one text. Texts without letters (empty, digits only, …) return `no_idea`. |
+| `analyzeTexts(texts, show_progress=False)` | Labels for many texts. |
+| `analyzeCSV(input_csv, output_path, summary_path=None, text_column=0)` | Analyze a CSV column (name or 0-based / negative index). Returns a DataFrame, or `None` on error. |
+| `saveModel(model_dir=None)` / `loadModel(model_dir=None)` | Save / load `comment_model.npz`. `loadModel` falls back to the bundled model. |
+
+### `SentimentAnalyzer(model_dir=None)`
+
+| Method | Description |
+|---|---|
+| `train(train_csv, text_col="text", emotion_col=None, weight_col="weight", reset=False)` | Learn weighted emotion words from a CSV. `emotion_col` defaults to `sentiment` (or `emotion`). Merges into the current model unless `reset=True`. Returns `{"status", "message"}`. |
+| `loadLex(csv_file, word_col=0, emotion_col=1, weight_col=2)` | Add a word/emotion/weight lexicon. Columns by index, or by name for CSVs with a header. Invalid weights default to 1.0. |
+| `analyzeText(text)` | `{emotion: percentage}` for the seven emotions (all 0.0 if no lexicon word is found). |
+| `analyzeCSV(input_csv, output_csv, text_col="text", output_col="sentiment_analysis")` | Analyze a CSV. Returns `True` / `False`. |
+| `saveModel(model_name="weighted_sentiment_model", model_dir=None)` / `loadModel(...)` | Save / load `<model_name>.json`. |
+
+Errors derive from `PerSent.PerSentError` (`ModelNotLoadedError`, `ModelFileError`, `DataValidationError`).
+Progress and status messages use the standard `logging` module (logger name `"PerSent"`).
+
+## Model quality and limitations
+
+- The bundled comment 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 common opinion words such as "خوب" and "عالی", which are removed before
+  classification.
+
+A larger training set is available [here](https://github.com/RezaGooner/Sentiment-Survey-Analyzer/tree/main/Dataset/big_train).
+
+## Upgrading from 1.3.x
+
+- Models are stored in safe, pickle-free formats (`.npz` / `.json`). Models you saved with 1.3.x can still be loaded
+  with `CommentAnalyzer(model_dir=...)` / `SentimentAnalyzer(model_dir=...)` (a `DeprecationWarning` is shown);
+  call `saveModel()` once to convert them. `scripts/convert_legacy_models.py` converts a folder in one go.
+- PerSent no longer creates or reads a `PerSent/model` folder in the current working directory. Pass `model_dir`
+  explicitly to save and load your own models.
+
+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)