# استخراج‌گر کلیدواژه جملات فارسی

این پروژه یک اسکریپت پایتون (`p5_representer.py`) برای استخراج **کلیدواژه‌ها** از جملات و سکشن‌های متون حقوقی فارسی با استفاده از **مدل‌های مبتنی بر Transformer** است.

## نحوه عملکرد
این اسکریپت از مدل **Meta-Llama-3.1-8B-Instruct** (با فشرده‌سازی و کوانتش برای کارایی بیشتر) استفاده می‌کند.  
ابتدا متن ورودی دریافت شده، با استفاده از پرامپت‌های سیستمی و کاربری آماده‌سازی می‌شود و سپس کلمات کلیدی مرتبط از متن استخراج می‌شوند.

## پیش‌نیازها
- پایتون 3.8 یا بالاتر
- کتابخانه‌های torch، transformers، bitsandbytes
- کلاس ElasticHelper برای بارگذاری داده‌ها
- سایر ابزارها در فایل `requirements.txt`

برای مشاهده نسخه دقیق کتابخانه‌ها به فایل **`requirements.txt`** مراجعه کنید.

## استفاده از پرامپت‌ها
- **پرامپت سیستمی (SYS_PROMPT):** نقش دستیار را تعریف می‌کند. نمونه: "شما یک دستیار حقوقی هستید."
- **پرامپت کاربری (USER_PROMPT):** به مدل می‌گوید حداقل تعداد مشخصی کلیدواژه استخراج کند. خروجی باید فهرستی فارسی باشد، بدون علائم اضافی.

این ترکیب باعث پایداری و دقت در استخراج کلیدواژه می‌شود.

## متدهای اصلی

### `format_prompt(SENTENCE: str) -> str`
متن خام فارسی را به فرمت مناسب برای مدل تبدیل می‌کند.  
**ورودی:** یک جمله فارسی (`str`)  
**خروجی:** متن قالب‌بندی‌شده (`str`)  

### `kw_count_calculator(text: str) -> int`
تعداد کلیدواژه‌ها را بر اساس طول متن محاسبه می‌کند.  
**ورودی:** متن (`str`)  
**خروجی:** تعداد کلیدواژه‌ها (`int`)  

### `generate(formatted_prompt: str) -> str`
متد اصلی برای ارسال پرامپت به مدل و دریافت خروجی.  
**ورودی:** پرامپت آماده‌شده (`str`)  
**خروجی:** متن کلیدواژه‌ها (`str`)  

### `single_section_get_keyword(sentence: str) -> list[str]`
متد اصلی برای استخراج کلیدواژه‌ها از یک جمله.  
**ورودی:** جمله (`str`)  
**خروجی:** لیستی از کلیدواژه‌های یکتا (`list[str]`)  

### `get_sections() -> dict`
بارگذاری سکشن‌ها از فایل فشرده JSON با کمک کلاس ElasticHelper.  
**خروجی:** دیکشنری سکشن‌ها (`dict`)  

### `convert_to_dict(sections: list) -> dict`
تبدیل لیست سکشن‌ها به دیکشنری با کلید ID.  

### `do_keyword_extract(sections: dict) -> tuple`
حلقه اصلی پردازش سکشن‌ها، ذخیره خروجی در فایل JSON و ثبت خطاها.  
**ورودی:** سکشن‌ها (`dict`)  
**خروجی:** تاپل `(operation_result: bool, sections: dict)`  

## مثال ورودی/خروجی

**ورودی:**  
```text
"حقوق و تکالیف شهروندی در قانون اساسی ایران مورد تاکید قرار گرفته است."
```

**خروجی:**  
```text
حقوق شهروندی
قانون اساسی
تکالیف
ایران
```

## نکات
- مدل‌های بزرگ (Llama 3.1) به GPU با حافظه بالا نیاز دارند.  
- کلیدواژه‌های تکراری حذف می‌شوند.  
- نتایج پردازش به‌صورت خودکار در فایل JSON ذخیره می‌شود.