Skip to main content

Backbone Agents

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

PyPI Python License: MIT Tests

الإصدار الحالي: 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.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for backbone-agents 6.5.0
File Size Uploaded Provenance Actions
backbone_agents-6.5.0.tar.gz 49.6 kB Without provenance Details for backbone_agents-6.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for backbone-agents 6.5.0
File Interpreter ABI Platform Actions
backbone_agents-6.5.0-py3-none-any.whl Python 3 none any Details for backbone_agents-6.5.0-py3-none-any.whl

Total release size: 112.2 kB

Release files / backbone_agents-6.5.0.tar.gz

Download URL backbone_agents-6.5.0.tar.gz
Size 49.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d71b93f16c38fdab09bdd60b64acf75cec78bd22a035af605a2590b856bdc849
BLAKE2b-256 checksum
How to use checksums
170cd40eb9b420acbd3aed6018229e12258fac26cec72aa209ca2245378cc68c
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.5.0-py3-none-any.whl

Download URL backbone_agents-6.5.0-py3-none-any.whl
Size 62.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c11587892a73bacd41c349906dcbf855cc63088d6b12aab2d6063fb0ac781ae
BLAKE2b-256 checksum
How to use checksums
6025ea26bec97186770b0c773237266819e38573b13a488a4bbf9880a42b489b
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.5.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page