Merge f289602b54 into 175bd05ce5

docs/fa/concepts/architecture.md

@@ -0,0 +1,96 @@
+# معماری چند عامله
+
+در این بخش، معماری و ساختار سیستم‌های چند عامله را بررسی می‌کنیم و نحوه تعامل بین عامل‌ها را توضیح می‌دهیم.
+
+## اجزای اصلی معماری
+
+### ۱. عامل‌ها (Agents)
+هر عامل یک واحد مستقل است که:
+- وظیفه خاصی را انجام می‌دهد
+- دارای حافظه و وضعیت مخصوص به خود است
+- می‌تواند با دیگر عامل‌ها ارتباط برقرار کند
+
+### ۲. هماهنگ‌کننده (Coordinator)
+هماهنگ‌کننده مسئول:
+- توزیع وظایف بین عامل‌ها
+- مدیریت ارتباطات
+- نظارت بر پیشرفت کار
+
+### ۳. حافظه مشترک (Shared Memory)
+فضایی برای:
+- به اشتراک گذاشتن داده‌ها
+- ذخیره نتایج میانی
+- همگام‌سازی بین عامل‌ها
+
+## نمونه پیاده‌سازی
+
+```python
+from swarms import Agent, Swarm, Coordinator
+
+# ایجاد عامل‌ها
+data_collector = Agent(
+    name="collector",
+    task="جمع‌آوری داده"
+)
+
+data_processor = Agent(
+    name="processor",
+    task="پردازش داده"
+)
+
+report_generator = Agent(
+    name="generator",
+    task="تولید گزارش"
+)
+
+# ایجاد هماهنگ‌کننده
+coordinator = Coordinator(
+    agents=[data_collector, data_processor, report_generator],
+    memory_size=1000
+)
+
+# ایجاد سیستم چند عامله
+swarm = Swarm(
+    coordinator=coordinator,
+    workflow="sequential"
+)
+
+# اجرای پروژه
+result = swarm.run("تحلیل داده‌های فروش ماهانه")
+```
+
+## الگوهای ارتباطی
+
+### ۱. ارتباط مستقیم
+عامل‌ها مستقیماً با یکدیگر ارتباط برقرار می‌کنند.
+
+### ۲. ارتباط از طریق هماهنگ‌کننده
+همه ارتباطات از طریق هماهنگ‌کننده انجام می‌شود.
+
+### ۳. انتشار-اشتراک
+عامل‌ها نتایج خود را در حافظه مشترک منتشر می‌کنند.
+
+## مزایای معماری
+
+- **مدولار**: هر جزء می‌تواند به صورت مستقل توسعه یابد
+- **مقیاس‌پذیر**: امکان اضافه کردن عامل‌های جدید
+- **انعطاف‌پذیر**: امکان تغییر الگوی ارتباطی
+- **قابل نگهداری**: جداسازی مسئولیت‌ها
+
+## بهترین شیوه‌ها
+
+1. **تعریف واضح وظایف**: هر عامل باید وظیفه مشخصی داشته باشد
+2. **مدیریت حافظه**: استفاده بهینه از حافظه مشترک
+3. **برنامه‌ریزی خطا**: در نظر گرفتن سناریوهای خطا
+4. **مستندسازی**: ثبت دقیق تعاملات و وظایف
+
+## نتیجه‌گیری
+
+معماری چند عامله یک چارچوب قدرتمند برای ساخت سیستم‌های هوشمند است. با استفاده از این معماری، می‌توانید:
+
+- سیستم‌های پیچیده را به اجزای کوچکتر تقسیم کنید
+- از تخصص‌های مختلف بهره‌مند شوید
+- سیستم را به راحتی گسترش دهید
+- عملکرد را بهینه کنید
+
+برای اطلاعات بیشتر در مورد پیاده‌سازی عملی، به بخش [راهنمای پیاده‌سازی](../best-practices/implementation.md) مراجعه کنید. 

docs/fa/concepts/limitations.md

@@ -0,0 +1 @@
+ 

docs/fa/concepts/why-multi-agent.md

@@ -0,0 +1,55 @@
+# چرا سیستم‌های چند عامله؟
+
+سیستم‌های چند عامله یک رویکرد قدرتمند برای حل مسائل پیچیده با استفاده از همکاری بین عامل‌های هوش مصنوعی است. در این صفحه، مزایای اصلی و دلایل استفاده از این سیستم‌ها را بررسی می‌کنیم.
+
+## مزایای کلیدی
+
+### ۱. تقسیم وظایف پیچیده
+سیستم‌های چند عامله می‌توانند مسائل پیچیده را به زیر وظایف کوچکتر و قابل مدیریت تقسیم کنند. هر عامل می‌تواند روی یک جنبه خاص از مسئله تمرکز کند و با تخصص خود به حل آن بپردازد.
+
+### ۲. افزایش کارایی
+با تقسیم کار بین چندین عامل، می‌توان وظایف را به صورت موازی انجام داد و سرعت پردازش را افزایش داد. این موضوع به ویژه در پروژه‌های بزرگ و پیچیده اهمیت دارد.
+
+### ۳. انعطاف‌پذیری و مقیاس‌پذیری
+سیستم چند عامله به راحتی قابل گسترش است. می‌توانید عامل‌های جدید را اضافه کنید یا عامل‌های موجود را تغییر دهید بدون اینکه نیاز به تغییر کل سیستم باشد.
+
+## نمونه کاربردی
+
+```python
+from swarms import Agent, Swarm
+
+# تعریف عامل‌ها با تخصص‌های مختلف
+researcher = Agent(name="researcher", task="جمع‌آوری اطلاعات")
+analyst = Agent(name="analyst", task="تحلیل داده")
+writer = Agent(name="writer", task="نگارش گزارش")
+
+# ایجاد گروه با عامل‌های متخصص
+research_team = Swarm(
+    agents=[researcher, analyst, writer],
+    workflow="sequential"
+)
+
+# اجرای پروژه تحقیقاتی
+result = research_team.run("تحقیق در مورد روند‌های بازار و تهیه گزارش")
+```
+
+## مقایسه با سیستم‌های تک عامله
+
+| ویژگی | سیستم تک عامله | سیستم چند عامله |
+|-------|----------------|-----------------|
+| پیچیدگی | محدود به توانایی یک عامل | توزیع پیچیدگی بین عامل‌ها |
+| مقیاس‌پذیری | محدود | بالا |
+| انعطاف‌پذیری | کم | زیاد |
+| سرعت پردازش | متوسط | بالا (پردازش موازی) |
+| مدیریت خطا | نقطه شکست واحد | مقاوم در برابر خطا |
+
+## نتیجه‌گیری
+
+سیستم‌های چند عامله یک راه‌حل قدرتمند برای پروژه‌های پیچیده هستند. با تقسیم وظایف بین عامل‌های متخصص، می‌توانید:
+
+- کارایی را افزایش دهید
+- انعطاف‌پذیری بیشتری داشته باشید
+- مقیاس‌پذیری را بهبود بخشید
+- مدیریت خطا را بهتر کنید
+
+برای اطلاعات بیشتر در مورد پیاده‌سازی، به بخش [راهنمای پیاده‌سازی](../best-practices/implementation.md) مراجعه کنید. 

docs/fa/faq.md

@@ -0,0 +1,88 @@
+# سوالات متداول
+
+در این بخش به سوالات متداول درباره سیستم‌های چند عامله پاسخ می‌دهیم.
+
+## سوالات عمومی
+
+### سیستم چند عامله چیست؟
+سیستم چند عامله یک چارچوب نرم‌افزاری است که در آن چندین عامل هوش مصنوعی با هم همکاری می‌کنند تا وظایف پیچیده را انجام دهند. هر عامل روی بخش خاصی از کار تمرکز می‌کند و با دیگر عامل‌ها ارتباط برقرار می‌کند.
+
+### چه تفاوتی با سیستم‌های تک عامله دارد؟
+سیستم‌های تک عامله محدود به توانایی‌های یک عامل هستند، در حالی که سیستم‌های چند عامله:
+- می‌توانند وظایف را به صورت موازی انجام دهند
+- از تخصص‌های مختلف بهره‌مند می‌شوند
+- در برابر خطاها مقاوم‌تر هستند
+- انعطاف‌پذیری بیشتری دارند
+
+## سوالات فنی
+
+### چگونه می‌توانم یک سیستم چند عامله ایجاد کنم؟
+```python
+from swarms import Agent, Swarm
+
+# ایجاد عامل‌ها
+agent1 = Agent(name="agent1", task="تحلیل داده")
+agent2 = Agent(name="agent2", task="تولید گزارش")
+
+# ایجاد گروه
+swarm = Swarm(agents=[agent1, agent2])
+
+# اجرای وظیفه
+result = swarm.run("تحلیل داده‌های فروش")
+```
+
+### چگونه عامل‌ها با هم ارتباط برقرار می‌کنند؟
+عامل‌ها می‌توانند از طریق:
+- حافظه مشترک
+- پیام‌های مستقیم
+- هماهنگ‌کننده مرکزی
+با یکدیگر ارتباط برقرار کنند.
+
+### چگونه خطاها را مدیریت کنیم؟
+سیستم چند عامله دارای چندین ویژگی برای مدیریت خطا است:
+- تکرار خودکار وظایف ناموفق
+- توزیع مجدد وظایف در صورت خطا
+- گزارش‌دهی خودکار خطاها
+
+## سوالات مربوط به مقیاس‌پذیری
+
+### آیا می‌توانم عامل‌های جدید اضافه کنم؟
+بله، سیستم به گونه‌ای طراحی شده است که به راحتی می‌توانید عامل‌های جدید اضافه کنید:
+```python
+# اضافه کردن عامل جدید
+new_agent = Agent(name="new_agent", task="وظیفه جدید")
+swarm.add_agent(new_agent)
+```
+
+### چگونه عملکرد سیستم را بهینه کنم؟
+برای بهینه‌سازی عملکرد می‌توانید:
+- تعداد عامل‌ها را متناسب با حجم کار تنظیم کنید
+- از الگوهای ارتباطی مناسب استفاده کنید
+- حافظه مشترک را بهینه کنید
+- وظایف را به درستی توزیع کنید
+
+## سوالات مربوط به امنیت
+
+### چگونه داده‌های حساس را محافظت کنیم؟
+سیستم دارای چندین لایه امنیتی است:
+- رمزنگاری داده‌ها
+- کنترل دسترسی
+- ممیزی فعالیت‌ها
+- جداسازی وظایف
+
+### آیا می‌توانم سیستم را در محیط‌های مختلف اجرا کنم؟
+بله، سیستم در محیط‌های مختلف قابل اجراست:
+- محیط‌های ابری
+- سرورهای محلی
+- محیط‌های ترکیبی
+
+## پشتیبانی
+
+### چگونه می‌توانم کمک بگیرم؟
+برای دریافت کمک می‌توانید:
+- از [مستندات](https://swarms.readthedocs.io) استفاده کنید
+- در [انجمن](https://github.com/swarms/discussions) سوال بپرسید
+- مشکلات را در [گیت‌هاب](https://github.com/swarms/issues) گزارش دهید
+
+### آیا آموزش‌های ویدیویی موجود است؟
+بله، می‌توانید آموزش‌های ویدیویی را در [کانال یوتیوب](https://youtube.com/swarms) مشاهده کنید. 

docs/fa/index.md

@@ -0,0 +1,56 @@
+# سیستم‌های چند عامله LLM
+
+به راهنمای جامع سیستم‌های چند عامله خوش آمدید! این مستندات به شما کمک می‌کند تا سیستم‌های چند عامله قدرتمند و کارآمد را با استفاده از مدل‌های زبانی بزرگ (LLMs) ایجاد و مدیریت کنید.
+
+## مزایای اصلی
+
+* 🤝 **همکاری هوشمند** - عامل‌های متعدد که برای حل مسائل پیچیده با هم همکاری می‌کنند
+* 🎯 **تخصص متمرکز** - هر عامل روی یک وظیفه خاص تمرکز می‌کند
+* 🔄 **انعطاف‌پذیری** - سیستم قابل تطبیق با نیازهای در حال تغییر
+* 📈 **مقیاس‌پذیری** - افزودن عامل‌های جدید برای گسترش قابلیت‌ها
+
+## شروع سریع
+
+برای شروع کار با سیستم چند عامله، این مراحل را دنبال کنید:
+
+```python
+from swarms import Agent, Swarm
+
+# ایجاد عامل‌ها
+agent1 = Agent(name="agent1", task="تحلیل داده")
+agent2 = Agent(name="agent2", task="تولید گزارش")
+
+# ایجاد گروه
+swarm = Swarm(agents=[agent1, agent2])
+
+# اجرای وظیفه
+result = swarm.run("تحلیل داده‌های فروش و تولید گزارش")
+```
+
+## ساختار پروژه
+
+- `swarms/` - کتابخانه اصلی
+- `examples/` - نمونه‌های کاربردی
+- `docs/` - مستندات
+- `tests/` - تست‌های واحد
+
+## نصب
+
+```bash
+pip install swarms
+```
+
+## مشارکت
+
+ما از مشارکت‌های جامعه استقبال می‌کنیم! لطفاً [راهنمای مشارکت](contributing.md) ما را مطالعه کنید.
+
+## پشتیبانی
+
+برای سوالات و پشتیبانی:
+- 📖 [مستندات](https://swarms.readthedocs.io)
+- 💬 [انجمن](https://github.com/swarms/discussions)
+- 🐛 [گزارش مشکلات](https://github.com/swarms/issues)
+
+## مجوز
+
+این پروژه تحت مجوز MIT منتشر شده است. برای جزئیات بیشتر [فایل مجوز](LICENSE) را ببینید. 

examples/persian_example.py

@@ -0,0 +1,43 @@
+from swarms import Agent, Swarm
+from swarms.utils.language_config import Language
+
+def main():
+    # ایجاد عامل‌ها با زبان فارسی
+    agent1 = Agent(
+        name="تحلیل‌گر",
+        task="تحلیل داده‌های فروش",
+        language=Language.PERSIAN
+    )
+
+    agent2 = Agent(
+        name="گزارش‌گر",
+        task="تولید گزارش تحلیلی",
+        language=Language.PERSIAN
+    )
+
+    # ایجاد گروه با زبان فارسی
+    swarm = Swarm(
+        agents=[agent1, agent2],
+        language=Language.PERSIAN
+    )
+
+    # اجرای وظیفه
+    task = """
+    لطفاً داده‌های فروش سه ماه گذشته را تحلیل کنید و یک گزارش تحلیلی تهیه کنید.
+    در گزارش موارد زیر را بررسی کنید:
+    1. روند فروش ماهانه
+    2. محصولات پرفروش
+    3. پیشنهادات برای بهبود فروش
+    """
+
+    try:
+        results = swarm.run(task)
+        print("\nنتایج:")
+        for agent_name, result in results.items():
+            print(f"\n{agent_name}:")
+            print(result)
+    except Exception as e:
+        print(f"خطا در اجرای وظیفه: {str(e)}")
+
+if __name__ == "__main__":
+    main() 

mkdocs.yml

@@ -59,6 +59,26 @@ plugins:
   - search
   - minify:
       minify_html: true
+  - i18n:
+      default_language: en
+      languages:
+        en: English
+        fa: فارسی
+      nav_translations:
+        fa:
+          Home: خانه
+          "Core Concepts": مفاهیم اصلی
+          "Why Multi-Agent Systems?": چرا سیستم‌های چند عامله؟
+          "Limitations of Individual Agents": محدودیت‌های عامل‌های انفرادی
+          "Multi-Agent Architecture": معماری چند عامله
+          "Best Practices": بهترین شیوه‌ها
+          "Implementation Guide": راهنمای پیاده‌سازی
+          "Communication Protocols": پروتکل‌های ارتباطی
+          "Error Handling": مدیریت خطا
+          "Performance Optimization": بهینه‌سازی عملکرد
+          "FAQ": سوالات متداول
+          "Tips & Troubleshooting": نکات و عیب‌یابی
+          "Glossary": واژه‌نامه
 
 extra:
   social:

requirements.txt

@@ -23,3 +23,4 @@ networkx
 aiofiles
 httpx
 # vllm>=0.2.0
+mkdocs-i18n>=0.4.4

swarms/structs/agent.py

@@ -64,6 +64,7 @@ from swarms.utils.history_output_formatter import (
 from swarms.utils.litellm_tokenizer import count_tokens
 from swarms.utils.litellm_wrapper import LiteLLM
 from swarms.utils.pdf_to_text import pdf_to_text
+from ..utils.language_config import language_config, Language
 
 
 # Utils
@@ -2779,3 +2780,20 @@ class Agent:
                 role="Output Cleaner",
                 content=response,
             )
+
+    def run(self, task: str) -> str:
+        """Run the agent with the given task."""
+        try:
+            print(language_config.get_translation("status_messages", "task_started"))
+            result = self._execute_task(task)
+            print(language_config.get_translation("status_messages", "task_completed"))
+            return result
+        except Exception as e:
+            error_msg = language_config.get_translation("error_messages", "task_failed")
+            print(f"{error_msg}: {str(e)}")
+            raise
+
+    def _execute_task(self, task: str) -> str:
+        """Execute the given task."""
+        print(language_config.get_translation("status_messages", "task_in_progress"))
+        // ... existing code ...

swarms/structs/swarm.py

@@ -0,0 +1,36 @@
+from ..utils.language_config import language_config, Language
+
+class Swarm:
+    def __init__(
+        self,
+        agents: List[Agent],
+        language: Language = Language.ENGLISH,
+        **kwargs
+    ):
+        self.agents = agents
+        self.language = language
+        language_config.set_language(language)
+
+    def run(self, task: str) -> Dict[str, Any]:
+        """Run the swarm with the given task."""
+        try:
+            print(language_config.get_translation("status_messages", "task_started"))
+            results = {}
+            
+            for agent in self.agents:
+                print(f"{agent.name}: {language_config.get_translation('status_messages', 'task_in_progress')}")
+                results[agent.name] = agent.run(task)
+            
+            print(language_config.get_translation("status_messages", "task_completed"))
+            return results
+        except Exception as e:
+            error_msg = language_config.get_translation("error_messages", "task_failed")
+            print(f"{error_msg}: {str(e)}")
+            raise
+
+    def add_agent(self, agent: Agent) -> None:
+        """Add a new agent to the swarm."""
+        if agent.name in [a.name for a in self.agents]:
+            error_msg = language_config.get_translation("error_messages", "agent_not_found")
+            raise ValueError(f"{error_msg}: {agent.name}")
+        self.agents.append(agent) 

swarms/utils/language_config.py

@@ -0,0 +1,63 @@
+from typing import Dict, Optional
+from enum import Enum
+
+class Language(Enum):
+    ENGLISH = "en"
+    PERSIAN = "fa"
+
+class LanguageConfig:
+    def __init__(self, default_language: Language = Language.ENGLISH):
+        self.default_language = default_language
+        self.current_language = default_language
+        self.translations: Dict[str, Dict[Language, str]] = {
+            "error_messages": {
+                Language.ENGLISH: {
+                    "agent_not_found": "Agent not found",
+                    "task_failed": "Task failed to execute",
+                    "invalid_input": "Invalid input provided",
+                },
+                Language.PERSIAN: {
+                    "agent_not_found": "عامل یافت نشد",
+                    "task_failed": "اجرای وظیفه با شکست مواجه شد",
+                    "invalid_input": "ورودی نامعتبر است",
+                }
+            },
+            "status_messages": {
+                Language.ENGLISH: {
+                    "task_started": "Task started",
+                    "task_completed": "Task completed",
+                    "task_in_progress": "Task in progress",
+                },
+                Language.PERSIAN: {
+                    "task_started": "وظیفه شروع شد",
+                    "task_completed": "وظیفه تکمیل شد",
+                    "task_in_progress": "وظیفه در حال انجام است",
+                }
+            }
+        }
+
+    def set_language(self, language: Language) -> None:
+        """Set the current language for the system."""
+        self.current_language = language
+
+    def get_translation(self, category: str, key: str, language: Optional[Language] = None) -> str:
+        """Get a translation for a specific message."""
+        lang = language or self.current_language
+        try:
+            return self.translations[category][lang][key]
+        except KeyError:
+            # Fallback to English if translation not found
+            return self.translations[category][Language.ENGLISH][key]
+
+    def add_translation(self, category: str, key: str, translations: Dict[Language, str]) -> None:
+        """Add new translations to the system."""
+        if category not in self.translations:
+            self.translations[category] = {}
+        
+        for lang, text in translations.items():
+            if lang not in self.translations[category]:
+                self.translations[category][lang] = {}
+            self.translations[category][lang][key] = text
+
+# Global language configuration instance
+language_config = LanguageConfig()