Metadata-Version: 2.5
Name: backbone-agents
Version: 4.0.0a1
Summary: Agent Compiler — Contract is the single source of truth. Arabic-first, framework-agnostic.
Project-URL: Homepage, https://github.com/backbone-system/backbone-agents
Project-URL: Repository, https://github.com/backbone-system/backbone-agents
Author: Backbone System Authors
License: MIT
License-File: LICENSE
Keywords: agents,arabic,compiler,langgraph,llm,pydantic-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Arabic
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: langchain-google-genai>=2.0
Requires-Dist: langgraph>=0.2
Requires-Dist: pydantic-ai-slim[google]>=0.1
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Backbone Agents

> **مترجم وكلاء (Agent Compiler).** العقد هو المصدر الوحيد للحقيقة. الكود إسقاط منه.
> **Agent Compiler.** The contract is the single source of truth. Code is a projection.

---

## ما هو Backbone Agents؟

**Backbone Agents** هو أول مترجم وكلاء (Agent Compiler) مفتوح المصدر بالعربية.
يقرأ **عقداً** (contract) بصيغة JSON، ويُنتج كوداً جاهزاً للتشغيل لإطار عمل الوكلاء الذي تختاره — دون تغيير سطر واحد في العقد.

### الفكرة المحورية

```
         ┌─────────────┐
         │  Contract   │  ← المصدر الوحيد للحقيقة
         │  (JSON)     │
         └──────┬──────┘
                │
       ┌────────┼────────┐
       ▼        ▼        ▼
   LangGraph  Pydantic   Future
              AI        Framework
```

**نفس العقد** → **كود LangGraph** أو **كود Pydantic AI** أو **أي إطار مستقبلي**.
**صفر تغييرات في العقد.** **صفر تغييرات في CLI.**

### لماذا هذا مهم؟

معظم أطر الوكلاء (LangGraph, CrewAI, AutoGen, Pydantic AI) تُجبرك على كتابة كود خاص بها.
إذا قررت تغيير الإطار، تُعيد كتابة كل شيء. **Backbone يكسر هذه الحلقة:**

- **العقد** يبقى ثابتاً.
- **الإطار** يصبح تفصيلاً تنفيذياً.
- **الاختبار** يبقى على مستوى العقد، لا الكود.

---

## التركيب (Installation)

```bash
pip install backbone-agents
```

التركيب من المصدر (للمطورين):

```bash
git clone https://github.com/backbone-system/backbone-agents.git
cd backbone-agents
pip install -e ".[dev]"
```

---

## الاستخدام السريع

### 1. أنشئ عقداً

```json
{
  "project_metadata": {
    "name": "hello_router",
    "selected_pattern": "router"
  },
  "agents": [
    {
      "role_id": "message_router",
      "in_scope": ["greeting", "farewell"],
      "out_of_scope": ["coding", "math"]
    },
    {
      "role_id": "greeter",
      "in_scope": ["greeting"]
    },
    {
      "role_id": "fareweller",
      "in_scope": ["farewell"]
    }
  ],
  "artifact_flow": []
}
```

### 2. افحص العقد

```bash
backbone lint hello_router
```

### 3. صدّر الكود

```bash
# إلى LangGraph
backbone export hello_router --target langgraph

# أو إلى Pydantic AI
backbone export hello_router --target pydantic_ai
```

**نفس العقد، إطاران مختلفان، صفر تغييرات.**

---

## الأنماط المدعومة (Patterns)

| النمط | الوصف |
|---|---|
| `router` | وكيل تصنيف يوجّه إلى وكلاء متخصصين |
| `debate` | مناظرة 3 أدوار + حكم |
| `sequential` | تدفق خطي A → B → C |

**3 أنماط × إطاران مدعومان = 6 توليفات تعمل.**

---

## البنية المعمارية

```
src/backbone_agents/
├── cli.py              ← v3.1 CLI (مرجع تاريخي)
├── cli_v4.py           ← v4.0 CLI (يستخدم REGISTRY)
├── linter.py           ← 5 فحوصات للعقد
├── compilers/
│   ├── base.py         ← Protocol + REGISTRY
│   ├── langgraph.py    ← LangGraphCompiler
│   └── pydantic_ai.py  ← PydanticAICompiler
└── templates/          ← عقود جاهزة
```

---

## إضافة إطار جديد (Extending)

أضف ملفاً واحداً في `src/backbone_agents/compilers/`:

```python
# compilers/crewai.py
from .base import write_generated

class CrewAICompiler:
    name = "crewai"
    supported_patterns = ("sequential", "router")

    def compile(self, contract, output_dir):
        # ... توليد الكود ...
        return [write_generated(output_dir, "crew.py", code)]
```

ثم سطر واحد في `compilers/__init__.py`. **انتهى.**

---

## الترخيص

MIT — راجع [LICENSE](LICENSE).

---

**Backbone Agents** — لأن العقد يجب أن يكون هو المصدر الوحيد للحقيقة.
