ورشة عمل قراءة القائمة وتخصيص البريد وإرساله

1. مراجعة الخطة الرئيسية: حلقة عمل الوكيل

قبل أن نبدأ التنفيذ، دعنا نلقي نظرة أخيرة على المنطق الكامل الذي يتبعه وكيلنا. هذا المنطق يتبع دورة "الإدراك - التفكير - التصرف" (Perceive - Think - Act) التي تعلمناها.

الكود الذي بنيناه في ملف main.py هو الترجمة البرمجية لهذه الحلقة:

1. الإدراك (Perceive): السطر recipients_list = read_recipients_from_file('recipients.csv') يجعل الوكيل "يقرأ" ويدرك قائمة المستلمين.
2. التفكير (Think): السطر email_body = generate_personalized_content(person) يجعل الوكيل "يفكر" في كل شخص على حدة ويصيغ رسالة مخصصة له باستخدام نموذج اللغة الكبير.
3. التصرف (Act): السطر send_email(person['email'], subject, email_body, ...) يجعل الوكيل "يتصرف" وينفذ مهمة إرسال البريد.

تتكرر هذه الدورة لكل مستلم في القائمة، مما يحول عملية يدوية مملة إلى سير عمل آلي وذكي.

2. مثال تطبيقي مشابه

لترسيخ فهمك لهذا النمط من البرامج، من المفيد جدًا رؤية مثال آخر يطبق نفس المبادئ. المشروع التالي الموضح في المقال يقوم بنفس الخطوات الأساسية التي قمنا بها: يقرأ بيانات من ملف، يطبق منطقًا لتحديد من يجب مراسلته، ثم يرسل رسائل مخصصة.

3. قائمة التحقق قبل الإطلاق

قبل تشغيل حملتنا، نحتاج إلى التأكد من أن كل شيء في مكانه الصحيح، تمامًا مثل قائمة التحقق قبل إطلاق صاروخ.

1. ملف المستلمين (recipients.csv):

   • تأكد من وجود الملف في نفس مجلد main.py.
   • للاختبار الأول، يُفضل أن يحتوي الملف على بريدك الإلكتروني الشخصي (أو بريد إلكتروني تجريبي) كمستلم واحد أو اثنين. هذا يسمح لك برؤية النتيجة بنفسك دون إزعاج الآخرين.

2. متغيرات البيئة (.env):

   • تأكد من أن ملف .env الخاص بك يحتوي على جميع المفاتيح والقيم الصحيحة:
     • OPENAI_API_KEY
     • SENDER_EMAIL (بريدك الذي سترسل منه)
     • SENDER_PASSWORD (كلمة مرور التطبيق الخاصة ببريدك)
     • SMTP_SERVER (مثل smtp.gmail.com لـ Gmail)
     • SMTP_PORT (عادة 587)

3. إعدادات أمان البريد الإلكتروني (مهم جدًا):

   • معظم مزودي خدمة البريد الإلكتروني (مثل Gmail) لا يسمحون للتطبيقات الخارجية بتسجيل الدخول باستخدام كلمة المرور العادية مباشرة.
   • ستحتاج إلى إنشاء "كلمة مرور للتطبيقات" (App Password). هذه كلمة مرور مكونة من 16 حرفًا تمنح تطبيقنا (السكربت الخاص بنا) الإذن بالوصول إلى حسابك في Gmail.
   • لإنشاء كلمة مرور تطبيقات في Gmail:
     1. اذهب إلى حساب Google الخاص بك.
     2. اختر "الأمان" (Security).
     3. تحت قسم "تسجيل الدخول إلى Google"، تأكد من أن "التحقق بخطوتين" (2-Step Verification) مُفعّل. لا يمكنك إنشاء كلمات مرور للتطبيقات بدونه.
     4. في نفس القسم، ابحث عن "كلمات مرور التطبيقات" (App Passwords).
     5. أنشئ كلمة مرور جديدة. اختر "بريد" (Mail) كـ "تطبيق" و"جهاز كمبيوتر يعمل بنظام Windows" (أو أي خيار آخر) كـ "جهاز".
     6. سيتم إنشاء كلمة مرور من 16 حرفًا. انسخ هذه الكلمة واستخدمها كقيمة للمتغير SENDER_PASSWORD في ملف .env.

4. تنفيذ حلقة العمل: من الاختبار إلى الواقع

الآن بعد أن أصبحت جميع الإعدادات جاهزة، لنقم بتشغيل وكيلنا.

الخطوة 1: الكود النهائي للمراجعة

هذا هو الكود الكامل لملف main.py الذي توصلنا إليه في الدرس السابق. تأكد من أن ملفك يبدو هكذا تمامًا.

# في ملف main.py

import os
import openai
from tools import read_recipients_from_file, send_email
from dotenv import load_dotenv

# --- الإعداد ---
load_dotenv() # تحميل متغيرات البيئة من ملف .env

# تأكد من أنك قمت بتعيين مفتاح OpenAI API كمتغير بيئة باسم OPENAI_API_KEY
try:
    openai.api_key = os.environ["OPENAI_API_KEY"]
except KeyError:
    print("خطأ: لم يتم العثور على متغير البيئة OPENAI_API_KEY.")
    print("يرجى تعيينه قبل تشغيل البرنامج.")
    exit()

def generate_personalized_content(recipient):
    """
    ينشئ محتوى بريد إلكتروني مخصص باستخدام LLM.
    هذه هي وظيفة 'التفكير' في وكيلنا.
    
    :param recipient: قاموس يحتوي على بيانات المستلم (مثل name, city).
    :return: سلسلة نصية تحتوي على جسم البريد الإلكتروني المخصص.
    """
    prompt = f"""
    تصرف كخبير تسويق عبر البريد الإلكتروني متخصص في التواصل الشخصي.
    مهمتك هي كتابة نص بريد إلكتروني قصير جداً وودود.

    سياق الرسالة: نحن شركة ناشئة تقدم خدمة توصيل طعام صحي.
    المستلم هو {recipient.get('name', 'عميلنا العزيز')}، وهو يعيش في مدينة {recipient.get('city', 'مدينتك')}.

    الهدف: إثارة اهتمامه لتجربة خدمتنا.

    اكتب نص البريد الإلكتروني. يجب أن:
    1. يبدأ بتحية شخصية (مرحباً [اسم الشخص]).
    2. يذكر بشكل طبيعي أنه من سكان مدينة [اسم المدينة].
    3. يكون قصيراً ومباشراً (لا يتجاوز 3-4 جمل).
    4. ينتهي بدعوة لتجربة الخدمة.
    """
    
    try:
        print(f"يتم التفكير في رسالة مخصصة لـ {recipient.get('name')}...")
        response = openai.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[
                {"role": "system", "content": "أنت مساعد تسويقي خبير."},
                {"role": "user", "content": prompt}
            ],
            temperature=0.7,
            max_tokens=150
        )
        content = response.choices[0].message.content.strip()
        return content
    except Exception as e:
        print(f"حدث خطأ أثناء التواصل مع OpenAI: {e}")
        return None

# --- حلقة العمل الرئيسية للوكيل ---
if __name__ == "__main__":
    recipients_list = read_recipients_from_file('recipients.csv')

    if not recipients_list:
        print("لم يتم العثور على مستلمين. سيتم إنهاء البرنامج.")
    else:
        for person in recipients_list:
            email_body = generate_personalized_content(person)
            
            if email_body:
                subject = f"عرض خاص لسكان {person.get('city', 'مدينتكم')}!"
                # الخطوة التالية هي تغيير dry_run إلى False
                send_email(person['email'], subject, email_body, dry_run=False) 
            else:
                print(f"تم تخطي إرسال البريد إلى {person.get('name')} بسبب خطأ في إنشاء المحتوى.")
            
            print("\n" + "="*30 + "\n")

الخطوة 2: الإطلاق!

1. التشغيل التجريبي الأخير (اختياري): في main.py، تأكد من أن استدعاء الدالة send_email يحتوي على dry_run=True. قم بتشغيل السكربت من الطرفية: python main.py. يجب أن ترى نصوص البريد الإلكتروني مطبوعة في الطرفية. هذا يؤكد أن منطق قراءة البيانات والتفكير يعمل بشكل صحيح.

2. الإطلاق الفعلي: قم بتغيير dry_run=True إلى dry_run=False في استدعاء الدالة send_email. هذا هو التغيير الذي يجعل الوكيل يرسل رسائل بريد إلكتروني حقيقية.

3. احفظ الملف وشغّل السكربت مرة أخرى من الطرفية:

   python main.py
   

الآن، راقب الطرفية. يجب أن ترى رسائل مثل:
يتم التفكير في رسالة مخصصة لـ [اسم المستلم]...
ثم
تم إرسال البريد بنجاح إلى [بريد المستلم]

الخطوة 3: التحقق من النتيجة

اللحظة الحاسمة! افتح صندوق الوارد الخاص بالبريد الإلكتروني الذي استخدمته كمستلم في ملف recipients.csv. يجب أن تجد رسالة جديدة من وكيلك الذكي!

لمشاهدة تمثيل مرئي لما يجب أن يحدث، شاهد هذا المقطع القصير. إنه يوضح تمامًا لحظة إرسال نتيجة عمل الوكيل إلى البريد والتحقق منها.

تهانينا! لقد قمت بتنفيذ أول حملة بريدية آلية ومخصصة بالكامل بواسطة وكيل ذكاء اصطناعي من بنائك.

خلاصة الدرس

في هذا الدرس، قمنا بالخطوة الأكثر أهمية في مشروعنا: تنفيذ حلقة العمل الكاملة لوكيل إدارة الحملات البريدية. لقد:

• راجعنا الخطة الكاملة للوكيل وكيف يترجم كودنا دورة "الإدراك - التفكير - التصرف".
• تأكدنا من جميع الإعدادات والمتطلبات الأساسية، بما في ذلك "كلمات مرور التطبيقات" الحيوية.
• أطلقنا الوكيل لينفذ مهمته: قراءة قائمة المستلمين، وتخصيص رسالة لكل منهم باستخدام LLM، وإرسالها عبر البريد الإلكتروني.
• تحققنا من وصول الرسائل بنجاح إلى صندوق الوارد.

لقد انتقلت الآن من مرحلة بناء المكونات إلى مرحلة تشغيل نظام متكامل.

ماذا بعد؟

وكيلنا يعمل الآن ويرسل رسائل مخصصة. ولكن، هل هذا التخصيص جيد؟ هل الرسائل فعالة وجذابة؟ في الدرس القادم، وهو الأخير في هذا المشروع، سنتعلم كيفية تقييم جودة التخصيص في رسائل البريد الإلكتروني المرسلة. سننتقل من التقييم الفني (هل يعمل؟) إلى التقييم النوعي (هل هو جيد؟).