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

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

pip install backbone-agents

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

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.0.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.0.0
File Size Uploaded Provenance Actions
backbone_agents-6.0.0.tar.gz 42.1 kB Without provenance Details for backbone_agents-6.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 94.6 kB

Release files / backbone_agents-6.0.0.tar.gz

Download URL backbone_agents-6.0.0.tar.gz
Size 42.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a0636d78a97280701524a4a1559cfd24602e23ca8ae304587426871dc487e5ab
BLAKE2b-256 checksum
How to use checksums
028c4e12f3b4372b969b2f3c271f23857b82d1ce01af95ec00b1713d28932b12
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.0.0-py3-none-any.whl

Download URL backbone_agents-6.0.0-py3-none-any.whl
Size 52.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
260183f3e2d51b1e4fef6578309356519c2f1b96d16033cab1741b5831c4a0df
BLAKE2b-256 checksum
How to use checksums
2d0aa0235c33900adf5d34a8da2d03420b434f690a9e4acfb8c762fb9b911acd
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.0.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