# سیستم کالچر (Culture System)

## مقدمه

سیستم کالچر یک لایه رفتاری است که بالای ایجنت اصلی قرار می‌گیرد و **قوانین ادب، لحن، فرمت و نحوه پاسخ‌دهی** هوش مصنوعی را کنترل می‌کند. هدف این سیستم این است که پاسخ‌های ایجنت همیشه مطابق با اصول اسلامی و ادب علمی باشد.

---

## معماری کلی

```
┌─────────────────────────────────────┐
│         manual_cultures.py          │  ← تعریف دستی قوانین کالچر (Master Copy)
│   CulturalKnowledge objects × 3     │
└──────────────┬──────────────────────┘
               │ import
               ▼
┌─────────────────────────────────────┐
│           culture.py                │  ← همگام‌سازی با دیتابیس + ساخت CultureManager
│   get_culture_manager()             │
└──────────────┬──────────────────────┘
               │ return CultureManager
               ▼
┌─────────────────────────────────────┐
│         base_agent.py               │  ← اتصال کالچر به ایجنت
│   IslamicScholarAgent               │
│   ├─ culture_manager=...            │
│   ├─ add_culture_to_context=True    │
│   └─ description=culture_text       │
└─────────────────────────────────────┘
```

---

## فایل‌ها و نقش هر کدام

### ۱. `src/knowledge/manual_cultures.py` — تعریف کالچرها

این فایل **نسخه اصلی (Master Copy)** قوانین رفتاری ایجنت است. سه آبجکت `CulturalKnowledge` در آن تعریف شده:

| کالچر | نام | هدف |
|--------|-----|------|
| **A** | `adab_culture` — ادب (Etiquette) | رعایت آداب اسلامی: بسم‌الله، صلوات، رضی‌الله‌عنه، الله اعلم |
| **B** | `nuance_culture` — ظرافت (Handling Conflict) | مدیریت اختلاف روایات بدون گفتن «تناقض»، پرهیز از اظهار نظر شخصی |
| **C** | `formatting_culture` — فرمت‌دهی (Formatting) | بولد کردن نام منابع، پاسخ به زبان کاربر |

هر آبجکت شامل فیلدهای زیر است:

```python
CulturalKnowledge(
    name="...",          # نام کالچر (کلید یکتا برای sync)
    summary="...",       # خلاصه یک‌خطی
    categories=[...],    # دسته‌بندی‌ها
    content="...",       # متن اصلی قوانین (این متن به LLM ارسال می‌شود)
    notes=[...],         # یادداشت‌های داخلی
)
```

در انتهای فایل، لیست `ALL_CULTURES` همه کالچرها را جمع می‌کند:

```python
ALL_CULTURES = [adab_culture, nuance_culture, formatting_culture]
```

---

### ۲. `src/core/culture.py` — همگام‌سازی و مدیریت

تابع `get_culture_manager()` سه کار انجام می‌دهد:

#### مرحله ۱: اتصال به دیتابیس
با استفاده از متغیرهای محیطی (`DB_USER`, `DB_PASSWORD`, ...) یک `PostgresDb` می‌سازد که جدول `agent_culture` را مدیریت می‌کند.

#### مرحله ۲: ساخت CultureManager
یک نمونه از `CultureManager` (از کتابخانه `agno`) ایجاد می‌شود که به مدل LLM و دیتابیس متصل است.

#### مرحله ۳: همگام‌سازی (Sync)
**کد پایتون به عنوان Master Copy عمل می‌کند.** منطق sync به این شکل است:

```
برای هر کالچر در ALL_CULTURES:
    اگر نامش در دیتابیس وجود دارد → رد شو (skip)
    اگر نامش وجود ندارد → آن را به دیتابیس اضافه کن (seed)
```

این یعنی:
- ✅ کالچرهای جدید **خودکار** به دیتابیس اضافه می‌شوند
- ✅ کالچرهای موجود دوباره اضافه **نمی‌شوند**
- ⚠️ اگر متن یک کالچر موجود تغییر کند، فعلاً آپدیت نمی‌شود (قابل توسعه در آینده)

---

### ۳. `src/agents/base_agent.py` — اتصال به ایجنت

در کلاس `IslamicScholarAgent` کالچر از **دو مسیر** به ایجنت تزریق می‌شود:

#### مسیر ۱: پارامترهای مستقیم Agno

```python
self.agent = ContextAwareAgent(
    ...
    culture_manager=self.culture_manager,      # ← CultureManager تزریق شده
    add_culture_to_context=True,               # ← فعال‌سازی خودکار agno
    ...
)
```

با فعال بودن `add_culture_to_context=True`، فریمورک `agno` به‌صورت خودکار محتوای کالچرها را به context ایجنت اضافه می‌کند.

#### مسیر ۲: توضیحات (Description) ایجنت

```python
description=self._build_culture_description()
```

متد `_build_culture_description()` تمام کالچرها را از `CultureManager` می‌خواند و یک متن Markdown تولید می‌کند:

```markdown
### Behavioral Guidelines (Culture)
**Adab (Etiquette)**:
- Greeting: Always begin formal responses with ...
- Honorifics: ...

**Nuance (Handling Conflict)**:
- Ikhtilaf: ...

**Formatting**:
- Citations: ...
```

این متن در `description` ایجنت قرار می‌گیرد و به عنوان بخشی از system prompt به LLM ارسال می‌شود.

---

## جریان کامل اجرا (Execution Flow)

```
1. اپلیکیشن شروع می‌شود
   │
2. IslamicScholarAgent.__init__() فراخوانی می‌شود
   │
3. get_culture_manager() اجرا می‌شود:
   │  ├─ اتصال به PostgreSQL
   │  ├─ ساخت CultureManager
   │  └─ Sync: کالچرهای manual_cultures.py → جدول agent_culture
   │
4. _build_culture_description() متن کالچرها را به Markdown تبدیل می‌کند
   │
5. ContextAwareAgent با پارامترهای زیر ساخته می‌شود:
   │  ├─ culture_manager → CultureManager آماده
   │  ├─ add_culture_to_context=True → agno خودکار کالچر را inject می‌کند
   │  └─ description → متن Markdown کالچرها
   │
6. کاربر سؤال می‌پرسد
   │
7. ایجنت با آگاهی از قوانین کالچر پاسخ می‌دهد:
      ├─ بسم‌الله در ابتدا (ادب)
      ├─ صلوات بعد از نام پیامبر (ادب)
      ├─ «روایات مختلفی وجود دارد» به جای «تناقض» (ظرافت)
      ├─ نام منابع بولد (فرمت)
      └─ پاسخ به زبان کاربر (فرمت)
```

---

## نحوه اضافه کردن کالچر جدید

۱. یک آبجکت `CulturalKnowledge` جدید در `src/knowledge/manual_cultures.py` بسازید:

```python
new_culture = CulturalKnowledge(
    name="نام یکتا",
    summary="خلاصه",
    categories=["دسته‌بندی"],
    content="- قانون ۱\n- قانون ۲",
    notes=["یادداشت"],
)
```

۲. آن را به لیست `ALL_CULTURES` اضافه کنید:

```python
ALL_CULTURES = [adab_culture, nuance_culture, formatting_culture, new_culture]
```

۳. اپلیکیشن را ری‌استارت کنید. سیستم sync خودکار کالچر جدید را در دیتابیس seed می‌کند.

---

## ذخیره‌سازی در دیتابیس

| آیتم | مقدار |
|------|-------|
| **جدول** | `agent_culture` |
| **دیتابیس** | PostgreSQL (همان DB اصلی اپلیکیشن) |
| **کتابخانه** | `agno.db.postgres.PostgresDb` |
| **Sync** | یک‌طرفه — کد Python → دیتابیس |

---

## خلاصه

| فایل | مسئولیت |
|------|---------|
| `manual_cultures.py` | تعریف قوانین رفتاری (Master Copy) |
| `culture.py` | Sync با دیتابیس + ساخت `CultureManager` |
| `base_agent.py` | تزریق کالچر به ایجنت از طریق `culture_manager` و `description` |