🧠 Agentic Swarm

نظام ذكاء اصطناعي متعدد الوكلاء يعمل محلياً بالكامل — Multi-Agent AI System Running 100% Offline

Quick Start • Requirements • Models • Usage • Architecture

📖 نظرة عامة — Overview

Agentic Swarm هو تطبيق سطح مكتب أصلي (Native Desktop Application) مبني بـ Python و PySide6، يُدير فريقاً من 5 وكلاء ذكاء اصطناعي يعملون بشكل تعاوني ومتسلسل في حلقة لا نهائية للعصف الذهني وتطوير الأفكار.

Agentic Swarm is a native desktop application built with Python & PySide6 that orchestrates a team of 5 AI agents working collaboratively in an infinite loop for brainstorming and iterative idea development. It runs 100% offline on your local hardware using Google's Gemma-4 model family.

✨ أبرز المميزات — Key Features

🖥️ لقطات الشاشة — Screenshots

⚡ Quick Start

# 1. Clone the repository
git clone https://github.com/alka2090/Agentic-Swarm.git
cd Agentic-Swarm

# 2. Download at least one Gemma-4 model (smallest first)
pip install huggingface_hub
huggingface-cli login
huggingface-cli download google/gemma-4-e2b-it

# 3. Run the application
.\run_project.ps1

⚠️ يتطلب كرت شاشة NVIDIA بذاكرة 12GB+ — Requires NVIDIA GPU with 12GB+ VRAM

📋 المتطلبات — Requirements

متطلبات الجهاز — Hardware Requirements

متطلبات البرمجيات — Software Requirements

🔧 التثبيت الكامل — Full Installation Guide

الخطوة 1: تثبيت Python

# تحميل Python 3.13 من الموقع الرسمي
# ⚠️ أثناء التثبيت: فعّل خيار "Add python.exe to PATH"

# التحقق:
python --version
# المتوقع: Python 3.13.x

الخطوة 2: تثبيت NVIDIA Driver + CUDA

# 1. ثبّت أحدث تعريف NVIDIA من: https://www.nvidia.com/Download/index.aspx
# 2. أعد تشغيل الكمبيوتر
# 3. ثبّت CUDA Toolkit 12.6 من: https://developer.nvidia.com/cuda-12-6-0-download-archive

# التحقق:
nvidia-smi
nvcc --version

الخطوة 3: تثبيت PyTorch مع دعم CUDA

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

# التحقق من أن PyTorch يرى كرت الشاشة:
python -c "import torch; print('CUDA:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0))"
# المتوقع: CUDA: True | GPU: NVIDIA GeForce RTX XXXX

الخطوة 4: تحميل نماذج Gemma-4

# تثبيت أداة HuggingFace
pip install huggingface_hub

# تسجيل الدخول (تحتاج حساب مجاني على huggingface.co)
huggingface-cli login

⚠️ يجب قبول ترخيص كل نموذج من صفحته على HuggingFace قبل التحميل (انظر قسم النماذج أدناه)

# تحميل النماذج (ابدأ بالأصغر):
huggingface-cli download google/gemma-4-e2b-it      # ~5GB  — ابدأ بهذا
huggingface-cli download google/gemma-4-e4b-it      # ~9GB  — اختياري
huggingface-cli download google/gemma-4-26b-a4b-it  # ~28GB — اختياري
huggingface-cli download google/gemma-4-31b-it      # ~35GB — اختياري

الخطوة 5: استنساخ وتشغيل المشروع

# استنساخ المشروع
git clone https://github.com/alka2090/Agentic-Swarm.git
cd Agentic-Swarm

# السماح بتشغيل السكربتات (مرة واحدة فقط)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# تشغيل البرنامج (يثبت المكتبات تلقائياً في أول مرة)
.\run_project.ps1

🤖 النماذج المستخدمة — Models

يستخدم المشروع نماذج Google Gemma-4 المفتوحة المصدر (Apache 2.0) من Google DeepMind.

1️⃣ عائلة النماذج الطرفية — Edge-Optimized Family

تتميز بتقنية "Per-Layer Embeddings" (PLE) لزيادة الكفاءة على الأجهزة الصغيرة.

Gemma 4 E2B — النموذج الأخف والأسرع

huggingface-cli download google/gemma-4-e2b-it

Gemma 4 E4B — المتوسط القوي

huggingface-cli download google/gemma-4-e4b-it

2️⃣ عائلة خليط الخبراء — MoE Family

معمارية هجينة فائقة الكفاءة — تفعّل فقط الخبراء المطلوبين.

Gemma 4 26B A4B (MoE) — السرعة مع الذكاء

huggingface-cli download google/gemma-4-26b-a4b-it

3️⃣ عائلة النماذج الكثيفة — Dense Frontier Family

النموذج الأضخم والأذكى في السلسلة.

Gemma 4 31B (Dense) — الوحش الحقيقي 🔥

huggingface-cli download google/gemma-4-31b-it

📊 جدول المقارنة الشامل

ℹ️ معلومات تقنية هامة

• المستودع الرسمي: google-deepmind/gemma
• الترخيص: Apache 2.0 (مفتوحة بالكامل)
• تحديث المكتبات:

  pip install -U transformers huggingface_hub
  

🏛️ البنية المعمارية — Architecture

┌─────────────────────────────────────────────────────────────┐
│                    🖥️ Presentation Layer                    │
│    main_window.py │ customization_dialog.py │ components.py │
│    app_style.py │ details_dialog.py │ diagnosis_dialog.py   │
├─────────────────────────────────────────────────────────────┤
│                    🔄 Orchestration Layer                   │
│              ai_worker.py │ orchestrator.py                 │
├─────────────────────────────────────────────────────────────┤
│                    🧠 AI Engine Layer                       │
│                       ai_engine.py                          │
├─────────────────────────────────────────────────────────────┤
│                    💾 Data Layer                             │
│          database.py │ SQLite │ JSON Configs                │
└─────────────────────────────────────────────────────────────┘

📁 هيكل المشروع — Project Structure

Agentic-Swarm/
├── 📄 desktop_app.py          ← Entry point — نقطة الدخول
├── 📄 run_project.ps1         ← Auto-launch script — سكربت التشغيل التلقائي
├── 📄 fix_os_1455.ps1         ← Virtual memory fix — إصلاح الذاكرة الافتراضية
├── 📄 requirements.txt        ← Python dependencies — المكتبات المطلوبة
├── 📁 backend/
│   ├── 📄 ai_engine.py        ← AI model loader/generator — محرك الذكاء الاصطناعي
│   ├── 📄 orchestrator.py     ← Agent orchestration — المنسق المركزي
│   └── 📄 database.py         ← SQLite database — قاعدة البيانات
├── 📁 gui/
│   ├── 📄 main_window.py      ← Main window (3-panel layout) — النافذة الرئيسية
│   ├── 📄 customization_dialog.py ← Agent customization — تخصيص الوكلاء
│   ├── 📄 diagnosis_dialog.py ← Live diagnostics — التشخيص الحي
│   ├── 📄 details_dialog.py   ← Model details viewer — عارض التفاصيل
│   ├── 📄 components.py       ← Custom widgets — مكونات مخصصة
│   ├── 📄 app_style.py        ← WhatsApp Dark QSS — أنماط التصميم
│   ├── 📄 ai_worker.py        ← Background QThreads — خيوط العمل
│   └── 📄 models_data.py      ← Model specs HTML — بيانات النماذج
└── 📁 config/
    ├── 📄 current_config.json ← Active agent config — إعدادات الوكلاء
    └── 📄 settings.json       ← Global settings — الإعدادات العامة

💡 كيف يعمل؟ — How It Works

المستخدم يكتب فكرة → SwarmWorker (QThread) → Orchestrator → حلقة لا نهائية:
  │
  ├── الوكيل #1: تحميل النموذج → توليد (Streaming) → تفريغ VRAM
  ├── الوكيل #2: تحميل النموذج → توليد (Streaming) → تفريغ VRAM
  ├── الوكيل #3: تحميل النموذج → توليد (Streaming) → تفريغ VRAM
  ├── الوكيل #4: تحميل النموذج → توليد (Streaming) → تفريغ VRAM
  └── الوكيل #5: تحميل النموذج → توليد (Streaming) → تفريغ VRAM → حفظ المسودة
        │
        └── العودة للوكيل #1 (دورة جديدة) ← ∞

استراتيجية إدارة الذاكرة — VRAM Management

التفريغ النووي بعد كل وكيل:

accelerate.release_memory(model) → del model → gc.collect() → torch.cuda.empty_cache() → torch.cuda.synchronize()

🎮 الاستخدام — Usage

بدء جلسة عصف ذهني

1. شغّل البرنامج عبر .\run_project.ps1
2. اكتب فكرتك في مربع الإدخال
3. اضغط Enter — الوكلاء سيبدأون العمل تلقائياً

تخصيص الوكلاء

• اضغط 🎛️ تخصيص النماذج والوكلاء
• غيّر اسم كل وكيل ودوره والنموذج المستخدم
• أو اكتب وصفاً واضغط "بدء تخصيص الكل" للتخصيص بالذكاء الاصطناعي

التدخل أثناء العمل

• اكتب رسالة جديدة أثناء عمل الوكلاء → ستُحقن كـ "أمر إداري"

🛠️ التقنيات المستخدمة — Tech Stack

❓ حل المشاكل الشائعة — Troubleshooting

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

📄 الترخيص — License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

The Gemma-4 models are also licensed under Apache 2.0 by Google DeepMind.

🙏 شكر وتقدير — Acknowledgments

• Google DeepMind — لنماذج Gemma-4 المفتوحة
• Hugging Face — لاستضافة النماذج ومكتبة Transformers
• The Qt Company — لإطار عمل Qt 6 و PySide6
• PyTorch — لمحرك الحساب التنسوري

_{Built with ❤️ for the open-source AI community}