دردشة وكيلية — مشروع تعليمي متكامل من البداية إلى النهاية للطلاب

النسخة العربية. هذه هي النسخة الأساسية، وملفها هو README.md في جذر المستودع. تعرض صفحة الدروس في الجذر / دليل دردشة وكيلية على /ai-chat/، ونسخته الإنجليزية على /en/ai-chat/، وكل درس موجود باللغتين.

ما الذي ستبنيه

تطبيق دردشة متكامل (full-stack) تتحدّث فيه مع مساعد ذكاء اصطناعي. ستبني:

  • واجهة خلفية بـ Python وFlask مع SQLite تخزّن رسائل الدردشة وتستدعي نموذجًا لغويًا كبيرًا (LLM) من OpenAI أو Anthropic أو غيرهما
  • تطبيق جوال بـ React Native (Expo) مع واجهة دردشة
  • ذكاء اصطناعي وكيلي يستطيع استخدام أدوات (آلة حاسبة، بحث) للإجابة عن الأسئلة

أهداف التعلّم

بنهاية هذا المشروع ستكون قادرًا على:

  1. إعداد خادم ويب بـ Python وFlask مع تخزين في قاعدة بيانات
  2. بناء نقاط نهاية REST API (GET، POST، DELETE)
  3. استدعاء واجهات API خارجية للذكاء الاصطناعي (OpenAI وAnthropic وGoogle وغيرها)
  4. بناء تطبيق دردشة للجوال باستخدام React Native / Expo
  5. جعل الذكاء الاصطناعي «وكيليًا» — بإعطائه أدوات ليفكّر بها ويتصرّف
  6. إضافة RAG (التوليد المعزّز بالاسترجاع) للإجابة اعتمادًا على قاعدة معرفة
  7. كتابة اختبارات آلية لجميع المكوّنات
  8. فحص الكود وتنسيقه باستخدام ruff
  9. إضافة المراقبة (فحوص الصحة، المقاييس، التسجيل المنظّم)
  10. إعداد CI/CD للاختبار الآلي والنشر
  11. نشر تطبيقك في الإنتاج

المتطلبات الأساسية

لا نفترض أي خبرة سابقة في Flask أو React Native أو الذكاء الاصطناعي. ويكفي أن:

  • تكون مرتاحًا في استخدام الحاسوب (تثبيت البرامج، استخدام المتصفح)
  • تمتلك معرفة برمجية أساسية (بأي لغة)

إذا احتجت إلى تعلّم الأساسيات أولًا، فابدأ بقسم المتطلبات الأساسية.

كيف تتنقّل في هذا المشروع

prerequisites/      → الطرفية، git، Python، TypeScript، لوحة المفاتيح العربية — ابدأ من هنا إن كنت جديدًا
concepts/           → ما هو API؟ كيف تقرأ الأخطاء؟ مقارنة بين النماذج اللغوية؟
cheatsheets/        → بطاقات مرجعية سريعة عن Flask وSQLAlchemy وReact Native وOpenAI
deployment/         → النشر في الإنتاج (Hugging Face Spaces، CI/CD، ترحيل PostgreSQL)
backend/            → بناء واجهة دردشة API بـ Python وFlask (6 خطوات + تحديات + اختبارات)
mobile/             → بناء تطبيق دردشة React Native (5 خطوات + تحديات)
advanced/agentic/   → اجعل روبوت الدردشة وكيليًا (5 خطوات + تحديات + اختبارات)
advanced/rag/       → أضف RAG باستخدام pgvector والتضمينات وقاعدة معرفة (5 خطوات + اختبارات)
concepts/           → يغطي أيضًا الحاويات وDocker ومبادئ التطوير
glossary.md         → جميع المصطلحات التقنية مشروحة
final-runbook.md    → تشغيل كل شيء من البداية إلى النهاية

ترتيب القراءة المقترح

  1. prerequisites/00-system-setup.md — جهّز حاسوبك
  2. من prerequisites/01-terminal.md إلى 05-typescript-scripting.md، بالإضافة إلى 06-arabic-keyboard.md
  3. concepts/01-what-is-an-api.md
  4. من backend/step-01-setup.md إلى step-06-cors.md
  5. من mobile/step-01-setup.md إلى step-05-polish.md
  6. concepts/05-llm-comparison.md — استكشف نماذج ذكاء اصطناعي أخرى
  7. final-runbook.md — شغّل المشروع كاملًا
  8. advanced/agentic/ — اجعله وكيليًا
  9. advanced/rag/ — أضف قاعدة معرفة RAG
  10. deployment/ — انشر في الإنتاج (يتضمن CI/CD)

التقنيات المستخدمة

الطبقة التقنية
إطار عمل الواجهة الخلفية Flask (Python)
قاعدة البيانات SQLite (بيئة التطوير)، PostgreSQL (الإنتاج)
نماذج الذكاء الاصطناعي OpenAI GPT-4o-mini (افتراضي)، ويمكن التبديل إلى Anthropic وGoogle وDeepSeek وLlama وMistral
تطبيق الجوال React Native مع Expo (TypeScript)
النشر Hugging Face Spaces (الواجهة الخلفية)، EAS Build (الجوال)
الاختبار pytest وruff (فحص الكود)
المراقبة نقطة نهاية فحص الصحة، تسجيل منظّم، مقاييس الطلبات
CI/CD GitHub Actions (اختبار آلي + نشر آلي)

بنية المشروع

agentic_chat_tutorial/
├── README.md              ← النسخة العربية (الأساسية)
├── TRANSLATING.md         ← دليل الترجمة + المصطلحات
├── en/                    ← النسخة الإنجليزية (تحاكي مسار كل درس)
├── prerequisites/         ← الدروس (10 ملفات)
├── concepts/              ← (6 ملفات)
├── cheatsheets/           ← (4 ملفات)
├── backend/               ← البرنامج التعليمي + app/ (كود Flask) + tests/
├── mobile/                ← البرنامج التعليمي + App.tsx
├── advanced/              ← agentic/ + rag/ + الاختبارات + Docker compose
├── deployment/            ← (6 ملفات)
├── website/               ← مولّد موقع ثابت ثنائي اللغة + القوالب
├── final-runbook.md
├── glossary.md
└── .github/workflows/     ← سير عمل CI + CD

لماذا العربية؟

هذا المستودع عربي أولًا: لا ينبغي أن يضطر المتعلّمون الناطقون بالعربية إلى تعلّم لغة جديدة قبل تعلّم البرمجة. الدروس والشروح وجولات معالجة الأخطاء بالعربية، بينما يبقى الكود بالإنجليزية لأن الأدوات والمكتبات ورسائل الأخطاء تستخدمها. ويحصل القرّاء الإنجليز على المحتوى نفسه تحت en/. نرحّب بالترجمات والتصحيحات — راجع TRANSLATING.md.

الترخيص

رخصة Creative Commons Attribution 4.0 (CC BY 4.0)