Metadata-Version: 2.5
Name: backbone-agents
Version: 5.0.1
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.

[![PyPI](https://img.shields.io/pypi/v/backbone-agents.svg)](https://pypi.org/project/backbone-agents/)
[![Python](https://img.shields.io/pypi/pyversions/backbone-agents.svg)](https://pypi.org/project/backbone-agents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-49%20passing-brightgreen.svg)](https://github.com/backbone-system/backbone-agents/tree/main/tests)

**الإصدار الحالي:** `4.0.0a3` — **49 اختباراً ✅** — **3 أنماط** — **2 مُصدّرين** — **Test Generation** ✅

---

## ما هو 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 توليفات تعمل.**

---

## مثال حي: Backbone Studio (Dogfooding)

**Backbone Studio** هو أول تطبيق حقيقي يُبنى بـ Backbone — 3 مهام بنفس المحرك:

| المهمة | النمط | الوصف |
|---|---|---|
| `design` | router (3 فروع) | تصميم بصري (ألوان، تخطيط، تايبوغرافي) |
| `code` | sequential | توليد كود (intake → generate → test → deliver) |
| `explain` | sequential | شرح مبسّط (intake → explain → deliver) |

### البنية (7 ملفات)

```
10_projects/backbone_studio/
├── contracts.json              ← الموجّه الرئيسي (master_router)
├── tasks/
│   ├── design_task.json       ← مهمة router (3 فروع)
│   ├── code_task.json         ← مهمة sequential
│   └── explain_task.json      ← مهمة sequential
├── tasks_registry.json         ← سجل المهام (task_id → ملف)
├── tools_spec.json             ← 8 أدوات (ToolProtocol)
└── generated/
    ├── generated_graph.py     ← الكود المُولَّد (LangGraph)
    └── test_backbone_studio_generated.py  ← اختبارات مولّدة (v4.3)
```

### كيف تُشغّله

```bash
# فحص شامل (master + 3 مهام فرعية)
backbone lint backbone_studio

# تصدير الكود + اختبارات
backbone export backbone_studio --target langgraph --tests
```

**النتيجة:** 4 ملفات JSON → كود Python + 4 اختبارات pytest. **صفر كود يدوي.**

📖 **الدليل الكامل:** [`docs/CASE_STUDIES/00_backbone_studio.md`](docs/CASE_STUDIES/00_backbone_studio.md)

---

## المقارنة

| البُعد | LangGraph | CrewAI | AutoGen | Backbone |
|---|---|---|---|---|
| مصدر الحقيقة | كود | كود | كود | **عقد (JSON)** |
| إضافة مهمة | كود جديد | كود جديد | كود جديد | **ملف JSON** |
| IR وسيط | لا | لا | لا | **نعم** |
| Linter | لا | لا | لا | **نعم (5/5 × 4)** |
| Test Generation | لا | لا | لا | **نعم (v4.3)** |
| ToolProtocol | لا | لا | لا | **نعم** |
| Tasks (لا Users) | لا | لا | لا | **نعم** |

**Backbone ليس نسخة من LangGraph/CrewAI/AutoGen** — بل **مكمّل** (عقود، IR، Tasks، ToolProtocol). راجع [`docs/REFERENCE_MODELS.md`](docs/REFERENCE_MODELS.md) للتفاصيل.

---


---

## دليل حي (Proof of Work)

Backbone ليس وعوداً — بل **يعمل**. لقطات حقيقية:

### 1. backbone lint — 5/5 × 4

```
🔍 فحص العقد: backbone_studio  (pattern=router)
   [1/5] Coverage        ✅ 4 وكيل، 0 حافة — متوافق
   [2/5] Overlap         ✅ تحذير: 3 مهمة مشتركة بين وكلاء
   [3/5] Contract Match  ✅ جميع consumed_by متوافقة
   [4/5] Escalation      ✅ جميع مسارات التصعيد صالحة
   [5/5] Loop Detection  ✅ لا توجد حلقات
📊 النتيجة: 5/5 ✅

📋 المهام الفرعية:
   ✅ design: 5/5 ✅
   ✅ code: 5/5 ✅
   ✅ explain: 5/5 ✅
```

### 2. backbone export --tests — كود + اختبارات

```
🔧 تصدير إلى langgraph → generated/
   ✅ generated_graph.py
   ✅ test_backbone_studio_generated.py
```

### 3. backbone_studio حياً مع Gemini

**المدخل:** "أريد ألواناً متناسقة لشعار شركة تقنية"

**Router اختار:** design_task

**الرد (Gemini):** "أهلاً بك. بصفتي مهمة التصميم البصري... الخيار الأول: المستقبل الذكي..."

**ملاحظة:** Gemini أعاد 503 UNAVAILABLE (مؤقت)، Retrying نجح → 200 OK.

### 4. الاختبارات — 49 ✅

```
pytest tests/ -v → 10 passed (test_smoke + test_linter_subtasks)
python3 tests/test_ir_regression.py → 35 passed
اختبارات مُولَّدة → 4 passed
```

---

## خارطة الطريق

| المرحلة | الميزة | الحالة |
|---|---|---|
| v4.0a/b | Package + IR Layer | ✅ |
| **v4.0c** | **README احترافي** | **✅ (الآن)** |
| v4.0d | PyPI مستقر 4.0.0 | ⏳ |
| v4.1 | Linter يدعم المهام الفرعية | ✅ |
| v4.2 | CrewAI Plugin | ⏸️ (مؤجَّل — غير متاح في Termux) |
| v4.3 | Test Generation | ✅ |
| v4.4-v4.6 | Analyzer v2 (20+ فحصاً) | ⏳ |
| v4.7-v4.9 | Benchmark + Cost tracking | ⏳ |
| v4.10-v4.12 | OpenTelemetry + Dashboard | ⏳ |
| v4.13-v4.15 | Composite patterns + Web UI | ⏳ |
| v5.0 | الإصدار المستقر | ⏳ |

---

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

```
src/backbone_agents/
├── cli_v4.py             ← CLI الرئيسي (يدعم --tests)
├── linter.py             ← 5 فحوصات + فحص المهام الفرعية (v4.1)
├── ir/
│   ├── schema.py         ← IRGraph, IRNode, IREdge
│   └── analyze.py        ← analyze() — نقطة قراءة العقد الوحيدة
├── compilers/
│   ├── base.py           ← Protocol + REGISTRY
│   ├── langgraph.py      ← LangGraphCompiler (v4.0b2)
│   ├── pydantic_ai.py    ← PydanticAICompiler
│   └── test_generator.py ← generate_tests() — v4.3 (جديد)
└── templates/            ← عقود جاهزة
```

**العقد → `analyze()` → `IRGraph` → `compile()` → كود Python** (+ اختبارات مع `--tests`).

---

## إضافة إطار جديد (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** — لأن العقد يجب أن يكون هو المصدر الوحيد للحقيقة.
