8.4 KiB

Raw Blame History

سیستم کالچر (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)	بولد کردن نام منابع، پاسخ به زبان کاربر

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

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

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

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

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

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

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

description=self._build_culture_description()

متد _build_culture_description() تمام کالچرها را از CultureManager می‌خواند و یک متن 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 بسازید:

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

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

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`

8.4 KiB Raw Blame History