🧠 SmartProposal

سامانه متن‌باز هوشمند برای تحلیل، اصلاح و ارزیابی خودکار پروپوزال‌های فارسی

SmartProposal یک سامانه هوش مصنوعی متن‌باز است که برای تحلیل، ارزیابی و اصلاح خودکار پروپوزال‌های پژوهشی و پروژه‌ای طراحی شده است.
این سامانه فایل‌های .odt را می‌خواند، ایرادهای نگارشی، ساختاری و محتوایی را تشخیص می‌دهد، پیشنهادات اصلاحی ارائه می‌کند و در پایان تصمیمی خودکار برای تأیید یا نیاز به بازنگری صادر می‌کند.

تمامی خروجی‌ها، از جمله توضیحات و نظرات، به زبان فارسی تولید می‌شوند و مستقیماً در فایل ورودی به صورت کامنت‌های ODF درج می‌گردند.

---

✨ ویژگی‌ها

• 🔍 تحلیل خودکار ساختار، نگارش و محتوای پروپوزال‌های فارسی
• 📝 درج خودکار کامنت‌ها و پیشنهادها در همان فایل .odt
• 🧾 گزارش تفصیلی هوشمند شامل ایرادات و امتیازدهی هر بخش
• ✅ تولید تصمیم خودکار (تأیید / نیاز به بازنگری / رد) با توجیه دلایل
• 👀 نمایش نتایج برای کاربر با امکان تأیید یا رد هر پیشنهاد
• 🧠 یادگیری از بازخورد کاربران برای بهبود تدریجی مدل‌ها
• 🔐 پنل مدیریت (Admin Panel) برای مدیریت کاربران، تنظیمات و گزارش‌های عملکرد
• 🇮🇷 پشتیبانی کامل از زبان فارسی در تمام بخش‌ها

---

🏗️ معماری کلی

SmartProposal از چند لایه اصلی تشکیل شده است:

1. استخراج‌کننده ODF
   استخراج متن و ساختار از فایل .odt و نگهداری مسیرهای XML برای درج دقیق کامنت‌ها.

2. پردازش زبان فارسی (NLP)
   نرمال‌سازی، توکن‌سازی، برچسب‌گذاری اجزای کلام و تشخیص جملات فارسی.

3. ماژول‌های تحلیلی

   • بررسی ساختار (وجود و ترتیب بخش‌های استاندارد پروپوزال)
   • بررسی نگارشی و املایی
   • تحلیل محتوایی و کیفیت علمی
   • امتیازدهی و تصمیم‌گیری خودکار

4. درج کامنت‌ها در فایل ODF
   تبدیل پیشنهادات به annotation در .odt همراه با توضیحات فارسی.

5. رابط کاربری (UI)
   مشاهده نتایج، قبول/رد کامنت‌ها و ارائه بازخورد.

6. ماژول یادگیری از بازخورد
   ثبت بازخورد کاربران و استفاده از آن در بازآموزی مدل‌ها.

7. پنل ادمین
   مدیریت کاربران، تنظیمات سیستم، گزارش‌گیری و کنترل نسخه مدل‌ها.

---

⚙️ راه‌اندازی اولیه (Development Setup)

پیش‌نیازها

• Python 3.10+
• Node.js 18+
• PostgreSQL یا SQLite برای دیتابیس
• LibreOffice (برای پردازش .odt)
• Git و Docker (اختیاری برای استقرار)

---

نصب و اجرا

# دریافت کد پروژه
git clone https://github.com/YourUsername/SmartProposal.git
cd SmartProposal

# ساخت محیط مجازی
python -m venv venv
source venv/bin/activate   # در ویندوز: venv\Scripts\activate

# نصب وابستگی‌ها
pip install -r requirements.txt

# اجرای سرور بک‌اند
uvicorn app.main:app --reload

نرم افزار بررسی هوشمند پروپوزال «SmartProposal» (فارسی)

نمای کلی و طراحی مؤلفه‌ای سامانه متن‌باز تحلیل، اصلاح و ارزیابی خودکار پروپوزال‌های پروژه با فرمت .odt.

معماری، ماژول‌ها، گردش داده، قالب‌های نظرگذاری داخل فایل، یادگیری از بازخورد، پنل ادمین، امنیت در ادامه آمده است.

---

معرفی اجمالی

SmartProposal سامانه متن‌باز :

• استخراج متن از فایل‌های .odt،
• آنالیز ساختاری، نگارشی و محتوایی (تماماً به زبان فارسی)،
• درج کامنت‌های پیشنهادی مستقیماً در همان فایل ورودی (کامنت‌های ODF)،
• تولید گزارش تفصیلی و تصمیم اتوماتیک (تأیید/عدم‌تأیید) با توجیه،
• نمایش نتایج برای کاربر جهت تأیید و یادگیری از بازخورد او،
• داشتن پنل ادمین برای مدیریت کاربران، پیکربندی سیستم و گزارش‌های استفاده.

---

1. معماری کلی (لایه‌ها)

1. لایه ورود/بارگذاری

   • API وب / UI وب برای آپلود فایل .odt
   • تحلیل سریع متادیتا (نام، نویسنده، تاریخ، اندازه)

2. لایه استخراج محتوا

   • تبدیل .odt -> متن ساختاریافته (بخش‌بندی، عنوان‌ها، جداول، لیست‌ها، تصاویر، پاورقی‌ها)
   • نگهداری موقعیت‌ها (offsets) و مسیر‌های XML برای درج کامنت

3. لایه پیش‌پردازش زبان (فارسی)

   • نرمال‌سازی (اِعراب/نشانه‌ها)، توکن‌سازی مناسب فارسی، حذف نویز، تشخیص جملات، POS و NER مخصوص فارسی

4. ماژول‌های تحلیلی

   • تحلیل ساختاری (قاب‌بندی پروپوزال براساس قالب مورد انتظار)
   • بررسی نگارشی/دستوری/املایی (قواعد فارسی + مدل ML)
   • تحلیل محتوایی/موضوعی (پوشش موضوع، منطق، اهداف، روش‌شناسی، منابع)
   • بررسی سرقت ادبی (اختیاری، با منابع مجاز)
   • امتیازدهی کلی و تولید تصمیم (قوانین + مدل تصمیم‌گیری)

5. ماژول پیشنهادات و کامنت‌گذاری

   • تولید پیام‌های پیشنهادی فارسی قابل درج به‌عنوان comment در همان .odt
   • سطح پیشنهاد (اجباری، توصیه، خوب است) + توضیح مختصر + نمونه جایگزین

6. ماژول تعامل با کاربر

   • نمایش پیش‌نمایش نتایج در UI (مشخص کردن موقعیت متن، محتوای کامنت)
   • امکان قبول/رد/ویرایش هر کامنت توسط کاربر
   • فرم دلایل/توضیحات بازخورد کاربر

7. ماژول یادگیری (Feedback Loop)

   • ثبت بازخوردهای کاربر، ایجاد دیتاست برچسب‌خورده کاربری
   • آموزش دوره‌ای / incremental learning (با نگهداری نسخه‌ها)
   • سیاست اعتبارسنجی تا از افت کیفیت جلوگیری شود

8. پنل ادمین

   • مدیریت کاربران و نقش‌ها (ادمین، بازبین، نویسنده)
   • پیکربندی قواعد ارزیابی و آستانه‌های تصمیم
   • گزارش‌های استفاده، معیارهای کیفیت، آمار خطاها
   • مدیریت مدل‌ها و فرایند آموزش

9. ذخیره‌سازها و مدارک

   • ذخیره فایل‌های آپلود شده (نسخه‌های قبل/بعد)
   • دیتابیس متادیتا، لاگ‌ها، و بازخوردها
   • نگهداری مدل‌ها و نسخه‌بندی (model registry)

10. لایه امنیت و حریم خصوصی

    • رمزنگاری ذخیره / انتقال، دسترسی مبتنی بر نقش، پاکسازی موقت فایل‌ها، لاگ دسترسی

11. CI/CD و استقرار

    • کانتینریزه (Docker/Kubernetes)، نظارت، لاگینگ، بک‌آپ مدل‌ها

---

لایه های توسعه ای:

12. تحلیل معنایی عمیق (Deep Semantic Analysis)

    • استفاده از مدل‌های زبانی عمیق برای درک مفهوم پروپوزال‌ها و تشخیص استدلال ضعیف یا تناقض در متن

13. تحلیل سبک نگارشی و لحن (Writing Style & Tone Analysis)

    • تحلیل میزان رسمی بودن، روانی و سازگاری سبک نوشتار با اصول نگارش علمی فارسی

14. تحلیل استنادات و منابع (Reference & Citation Analysis)

    • بررسی صحت، کامل بودن و سبک ارجاع منابع علمی در متن پروپوزال

15. :پشتیبانی از تحلیل‌گر LM Studio و دانش ثانویه

    • از LM Studio به‌عنوان مدل تحلیل متن استفاده کند (در کنار OpenAI، Ollama، یا مدل داخلی).
    • از دانش ثانویه (مثلاً اصول نگارش پروپوزال، قانون ارزیابی علمی، چک‌لیست‌ها) که در قالب یک فایل JSON/Markdown بارگذاری می‌شود، هنگام تحلیل محتوا استفاده کند.
    • یک Knowledge Integrator اضافه شود برای ادغام این دانش با خروجی مدل.

---

2. جریان داده (Sequence / Data flow) و فرآیند کلی سیستم

1. کاربر فایل .odt را آپلود می‌کند (وب/REST).
2. سیستم متادیتا را ذخیره می‌کند و نسخه «ورودی خام» را می‌نویسد.
3. استخراج‌گر ODF متن و ساختار را همراه با مسیرهای XML برمی‌گرداند.
4. پیش‌پردازش زبانی روی متن انجام می‌شود (جملات، پاراگراف‌ها نشانه‌گذاری می‌شوند).
5. هر ماژول تحلیلی (ساختاری، نگارشی، محتوایی) روی بخش‌های مرتبط اجرا می‌شود و مشکلات/توصیه‌ها تولید می‌شود.
6. ماژول تولید کامنت، هر توصیه را به یک comment object نگاشت می‌کند که حاوی: متن پیام فارسی، دسته (نگارشی/ساختاری/محتوایی)، شدت، موقعیت در ODF (XPath/offset) و شناسه پیشنهاد است.
7. کامنت‌ها به فایل .odt اضافه شده (نسخه پیشنهادی فایل با کامنت‌ها ساخته می‌شود).
8. تصمیم نهایی (تأیید/عدم‌تأیید/نیاز به اصلاح) تولید و در همان فایل یا در گزارش جداگانه درج می‌شود.
9. UI نتایج را نشان می‌دهد و کاربر می‌تواند هر کامنت را قبول/رد/ویرایش کند.
10. بازخوردها ثبت می‌شوند؛ در صورت پذیرفتن کاربر، کامنت می‌تواند به‌عنوان «تأیید شده» ثبت شود.
11. بازخوردها به مخزن یادگیری ارسال شده و برای آموزش بعدی یا به‌روزرسانی مدل استفاده می‌شوند.

---

3. قالب کامنت‌ها در فایل .odt- پیشنهادی

برای درج نظرات از قابلیت office:annotation یا مشابه در ODF استفاده می‌کنیم. هر کامنت شامل فیلدهای زیر باشد:

{
  "comment_id": "cmt-20251105-0001",
  "type": "نگارشی",               // نگارشی | ساختاری | محتوایی
  "severity": "توصیه",           // اجباری | توصیه | پیشنهاد
  "short_message": "استفاده از فعل مجهول در جمله اول پیشنهاد نمی‌شود.",
  "detailed_suggestion": "جمله 'پروژه اجرا خواهد شد' بهتر است تبدیل شود به 'ما پروژه را اجرا می‌کنیم' برای شفافیتِ فاعل.",
  "xpath": "/office:document-content/.../text:p[3]",
  "offset": {"start": 120, "end": 145},
  "example_replacement": "ما پروژه را اجرا خواهیم کرد.",
  "confidence": 0.87,
  "origin": "grammar-model-v1.3"
}

• هنگام درج در .odt، متن short_message به‌عنوان متن کامنت نمایش داده شده و detailed_suggestion در بدنهٔ کامنت قرار می‌گیرد.
• xpath یا mapping موقعیتی تضمین می‌کند که کامنت دقیقاً روی متن مورد نظر دیده شود.

---

4. ماژول‌های تحلیلی — جزئیات فنی

4.1 بررسی ساختاری (Structure Checker)

• تعریف قالب استاندارد پروپوزال (سربرگ، چکیده، مقدمه، اهداف، روش، برنامه زمانی، بودجه، منابع).
• بررسی وجود / ترتیب / طول منطقی هر بخش.
• الگوریتم: ترکیب قوانین (rule-based) و مدل طبقه‌بندی بخش (section classifier) — مدل‌های fine-tuned برای فارسی (BERT-based).

4.2 بررسی نگارشی و املایی (Grammar & Spelling)

• استفاده از مجموعه‌ای ترکیبی:

  • دیکشنری املایی فارسی (Aspell-like یا Hunspell با افزونه فارسی)،
  • مدل تصحیح مبتنی بر ترنسفورمر (مثلاً ParsBERT یا مدل‌های HooshvareLab برای پیشنهاد اصلاحات),
  • قواعد دستوری رایج (اسم-فعل، هماهنگی‌ها).

• خروجی: پیشنهاد جایگزین، دلیل، و درجه اطمینان.

4.3 تحلیل محتوایی و کیفیت علمی

• بررسی پوشش اهداف و انطباق روش با اهداف: استخراج هدف‌ها (NER+semantic matching).
• اعتبار روش‌شناسی: شناسایی ادعاهای بدون منبع، موارد نیازمند توضیح دقیق.
• اعتبار منابع: بررسی کیفیت مراجع (در صورت وجود لیست منابع).
• الگوریتم: ترکیبی از مدل‌های رتبه‌بندی متن، تشخیص مغایرت (inconsistency), و قواعد منطقی.

4.4 تصمیم‌گیر خودکار (Approval Decision)

• ورودی‌ها: امتیازات ماژول‌ها (وزن‌دار)، قوانین بیزین/قانونی، آستانه‌های کانفیگ.
• خروجی: Approved | Needs Revision | Rejected به همراه توضیح (top-k دلایل).

---

5. یادگیری از بازخورد کاربر (Feedback Loop)

1. جمع‌آوری بازخورد

   • برای هر کامنت: قبول/رد/ویرایش + توضیحات آزاد (فارسی).
   • برای تصمیم کلی: قبول تصمیم سیستم یا رد با دلایل.

2. ذخیره‌سازی و برچسب‌گذاری

   • بازخوردها به صورت ساختاری ذخیره شوند (comment_id, user_action, modified_text, timestamp).

3. استفاده از بازخورد

   • دسته‌بندی: بازخوردهای مثبت به‌عنوان examples تایید، بازخوردهای منفی به‌عنوان counterexamples.

   • دو روش آموزش:

     • Batch retraining (پیشنهاد شده برای امنیت و بررسی کیفیت): دوره‌ای (مثلاً هفته‌ای/ماهانه) داده‌ها را بررسی، پاکسازی و مدل‌ها را بازآموزی کن.
     • Online / Incremental learning (با مراقبت): برای بخش‌های با ضریب خطای کم، از یادگیری افزایشی استفاده شود.

4. اعتبارسنجی انسانی

   • قبل از انتشار مدل جدید، یک مجموعه آزمون (QA) و پنل تأیید انسانی (ادمین/بازبین) داشته باشیم.

5. پرایوتنس و انونیم‌سازی

   • قبل از استفاده در مدل، داده‌های حساس (نام افراد، ایمیل‌ها) را نشانه‌گذاری یا آنونیمایز کن.

---

6. پنل ادمین — امکانات

• مدیریت کاربران و نقش‌ها:

  • ایجاد/حذف/ویرایش کاربران، تعیین نقش (admin, reviewer, submitter).
  • تنظیم سطوح دسترسی (مثلاً چه کسانی بتوانند مدل را بازآموزی کنند).

• پیکربندی سیستم:

  • تنظیم آستانه‌های تصمیم‌گیری، وزن‌دهی ماژول‌ها، فعال/غیرفعال کردن بررسی‌های خاص.

• مدیریت مدل‌ها:

  • نمایش نسخه مدل‌ها، بازگردانی به نسخه قدیمی، آپلود مدل جدید، برنامه‌ریزی آموزش.

• گزارشات و آنالیتیکس:

  • تعداد پردازش‌ها، زمان‌های واکنش، نرخ قبول/رد پیشنهادات، خطاها، معیارهای کیفیت (precision/recall برای اصلاحات پذیرفته‌شده).

• قوانین سازمانی (policy rules):

  • اضافه کردن یا ویرایش قواعد rule-based برای بررسی‌های ساختاری یا امنیتی.

• مدیریت لاگ‌ها و امنیت:

  • مشاهده لاگ‌های دسترسی، تنظیم سیاست نگهداری فایل‌ها، ریپورت‌های امنیتی.

---

7. رابط کاربری (UX) — جریان بازبینی برای کاربر

• صفحه آپلود فایل → پیش‌نمایش سریع (متادیتا) → دکمه «شروع بررسی»

• پس از بررسی:

  • نمایش خلاصه تصمیم کلی و امتیازات هر بخش (اعداد و نمودار ساده).
  • لیست کامنت‌ها به ترتیب موقعیت در سند (با امکان پرش به آن قطعه متن).
  • هر کامنت: متن پیشنهادی، دکمه‌های [قبول] [رد] [ویرایش متن پیشنهاد] و فیلد توضیح (اختیاری).
  • دکمه «نهایی‌سازی و دانلود فایل با کامنت‌های تاییدشده» — فایل خروجی .odt با کامنت‌های نهایی و گزارش جداگانه.

• صفحه بازخورد جمعی: نمایش تأثیر بازخورد کاربر روی مدل (پس از هر بروزرسانی مدل).

---

8. سازگاری با .odt و تکنولوژی‌های پیشنهادی

• خواندن/نوشتن ODF (.odt):

  • کتابخانه‌های پیشنهادی: odfpy (Python), python-uno (برای LibreOffice headless) یا lxml برای ویرایش XML ODF.
  • راهکار: از XML داخلی ODF استفاده کن؛ مکان دقیق (paragraph index / xpath) را ثبت و office:annotation اضافه کن.

• توجه به نسخه‌های مختلف ODF: تست با فایل‌های ساخته‌شده توسط LibreOffice، OpenOffice و Microsoft Word (در صورت تبدیل).

---

9. استک فنی پیشنهادی (مثال)

• زبان برنامه‌نویسی: Python (back-end NLP-heavy) + TypeScript/React برای UI
• فریم‌ورک وب: FastAPI یا Django REST Framework
• فرانت‌اند: React (i18n برای فارسی، RTL)، یا Vue.js
• پایگاه داده: PostgreSQL (متادیتا، بازخورد)، Elasticsearch (جستجوی متن/لاگ)، MinIO/S3 (ذخیره فایل‌های .odt)
• مدل‌ها: استفاده از Transformers (HuggingFace) + مدل‌های فارسی (ParsBERT, HooshvareLab, or custom fine-tuned)
• نُردینگ (orchestration): Docker, Kubernetes
• CI/CD: GitHub Actions / GitLab CI
• صف وظایف: Redis + Celery برای پردازش‌های سنگین (تحلیل سند)
• نسخه‌بندی مدل‌ها: MLflow یا DVC
• لاگ و مانیتورینگ: Prometheus + Grafana + Sentry
• llm: LmStudio with OpenaiAPI

---

10. اتصال LM Studio به سیستم مانند مدل OpenAI

LM Studio یک API ارائه می‌کند که 100٪ سازگار با ساختار OpenAI است. ساختار نمونه درخواست:

POST http://localhost:1234/v1/chat/completions
{
  "model": "phi3",
  "messages": [
    {"role": "system", "content": "You are a Persian academic proposal reviewer."},
    {"role": "user", "content": "متن پروپوزال این است ..."}
  ]
}

SmartProposal می‌تواند بدون تغییرات زیاد، این را به‌عنوان یک backend فعال استفاده کند.

✅ ۲) استفاده از دانش ثانویه

مثال فایل JSON:

{
  "sections": {
    "abstract": {
      "min_words": 100,
      "rules": [
        "چکیده باید شامل هدف، روش، و نتایج مورد انتظار باشد.",
        "نباید شامل ارجاع باشد."
      ]
    },
    "methodology": {
      "rules": [
        "روش باید با هدف اصلی کاملاً منطبق باشد.",
        "روش باید قابل تکرار باشد."
      ]
    }
  }
}

این دانش در prompt استفاده می‌شود:

این قواعد از دانش ثانویه استخراج شده‌اند:
- چکیده باید شامل هدف، روش و نتایج باشد.
- روش باید با هدف سازگار باشد.

با توجه به متن پروپوزال زیر، تحلیل دقیق ارائه کن...

---

11. معیارهای کیفیت و تست

• معیارهای کلیدی:

  • Precision/Recall برای پیشنهادات اصلاح نگارشی (با مجموعه تست فارسی برچسب‌خورده).
  • Accuracy بخش‌بندی ساختار (section classifier).
  • Consistency score (تغییرات پذیرفته‌شده توسط کاربر بعد از پیشنهاد).
  • Latency: زمان متوسط تاخورد پردازش هر فایل.

• تست‌ها:

  • واحد (unit), یکپارچگی (integration), E2E (با نمونه .odt)، آزمون‌های بار (load testing).

• جمع‌آوری dataset فارسی برای ارزیابی (نمونه‌های پروپوزال واقعی یا ساختگی با برچسب).

---

12. نمونه JSON خروجی گزارش نهایی (و به صورت کامنت در فایل ورودی)

{
  "file_id": "file-20251105-001",
  "summary": {
    "decision": "Needs Revision",
    "score": 62,
    "top_issues": [
      {"type":"نگارشی","count":12},
      {"type":"ساختاری","count":3},
      {"type":"محتوایی","count":2}
    ]
  },
  "comments": [
    {
      "comment_id":"cmt-1",
      "type":"نگارشی",
      "location":"بند 2، پاراگراف 1",
      "message":"واژه 'باید' در این جمله کلی است؛ لطفاً مشخص کنید چه کسی/چه زمانی.",
      "severity":"توصیه",
      "status":"pending"
    }
  ],
  "generated_at":"2025-11-05T18:46:00Z",
  "origin":"SmartProposal v0.9"
}