Backbone Agents
مترجم وكلاء (Agent Compiler). العقد هو المصدر الوحيد للحقيقة. الكود إسقاط منه. Agent Compiler. The contract is the single source of truth. Code is a projection.
الإصدار الحالي: 6.0.1 — 29 اختباراً ✅ — 3 أنماط — 3 مُصدّرين (LangGraph, Pydantic AI, CrewAI) — IR Layer ✅
ما هو 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 يكسر هذه الحلقة:
- العقد يبقى ثابتاً.
- الإطار يصبح تفصيلاً تنفيذياً.
- الاختبار يبقى على مستوى العقد، لا الكود.
Decompile (كود → عقد)
Backbone يستطيع أيضاً عكس العملية: استخراج العقد من كود مولّد.
backbone decompile examples/01_router_basic/hello_router/generated/generated_graph.py --framework langgraph --output contract.json
المتوقع:
✅ العقد المحلّل: contract.json
الوكلاء: 3
النمط: router
الحواف: 2
متى يفيد؟
- عند وجود كود LangGraph قديم، وتريد تحويله إلى عقد.
- لاختبار Roundtrip (عقد → كود → عقد).
القيود:
framework=langgraphفقط (v6.1). CrewAI + Pydantic AI في v6.2.in_scope/out_of_scopeغير مستخرجة (غير موجودة في الكود المولّد).
التركيب (Installation)
pip install backbone-agents
pip install backbone-agents[crewai] # مع دعم CrewAI
> **Note:** `crewai` requires Python 3.10–3.13. It does **not** support Python 3.14+ (as of Nov 2026). If you are on Python 3.14+, install without `[crewai]`; the `crewai` compiler plugin will still be available (it does not need `crewai` installed to generate code).
التركيب من المصدر (للمطورين):
git clone https://github.com/backbone-system/backbone-agents.git
cd backbone-agents
pip install -e ".[dev]"
الاستخدام السريع
1. أنشئ عقداً
{
"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. افحص العقد
backbone lint hello_router
3. صدّر الكود
# إلى 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)
كيف تُشغّله
# فحص شامل (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
المقارنة
| البُعد | 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 للتفاصيل.
دليل حي (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/:
# 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.
Backbone Agents — لأن العقد يجب أن يكون هو المصدر الوحيد للحقيقة.
Metadata
Release files for backbone-agents 6.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| backbone_agents-6.4.0.tar.gz | 48.7 kB | Without provenance | Details for backbone_agents-6.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| backbone_agents-6.4.0-py3-none-any.whl | Python 3 | none | any | Details for backbone_agents-6.4.0-py3-none-any.whl |
Total release size: 110.1 kB
Release files / backbone_agents-6.4.0.tar.gz
| Download URL | backbone_agents-6.4.0.tar.gz |
|---|---|
| Size | 48.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86661b50da270acf05e03be3eae64b653e1d8a09470a2cafbc05473cc659a1b8
|
|
BLAKE2b-256 checksum How to use checksums |
093c8fade947f0cd19664b516e7c261b98ccb7c9c80cbc834ba7f00c6ac4dff0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / backbone_agents-6.4.0-py3-none-any.whl
| Download URL | backbone_agents-6.4.0-py3-none-any.whl |
|---|---|
| Size | 61.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0e49572b2ccb72c51891a243e871815f5e561a222519913a893e16b90f3a16e7
|
|
BLAKE2b-256 checksum How to use checksums |
e7209a076f646220885de7985871d53ab868618d3f2cc00c43f262a244dad388
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for backbone-agents 6.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.