backbone-agents 4.0.0a1__tar.gz

backbone_agents-4.0.0a1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Secrets (CRITICAL — never commit)
+.env
+.env.*
+!.env.example
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Logs
+*.log
+
+# Backups (exp2/ legacy — never ship)
+*.bak
+*.bak2
+*.bak3
+*.bak4
+*.pym
+
+# IDE
+.vscode/
+.idea/
+*.swp
+# v4.0a archived baselines (kept for reference, not shipped)
+_archive/

backbone_agents-4.0.0a1/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to Backbone Agents are documented here.
+
+## [4.0.0a1] - 2026-11-01
+
+### Added — البنية المعمارية v4.0
+- `compilers/base.py`: `CompilerPlugin` Protocol + `REGISTRY` + `write_generated`.
+- `compilers/langgraph.py`: `LangGraphCompiler` class.
+- `compilers/pydantic_ai.py`: `PydanticAICompiler` class.
+- `compilers/__init__.py`: Auto-registration على الاستيراد.
+- `cli_v4.py`: CLI جديد يستخدم `REGISTRY` (بدلاً من `importlib`).
+- `pyproject.toml`: هيكل حزمة قابل للنشر على PyPI (hatchling).
+- `.gitignore`: حماية `.env` و`*.bak` و`__pycache__`.
+
+### Changed — إعادة هيكلة من `exp2/` إلى حزمة
+- `backbone.py` → `backbone_agents/cli.py` (يبقى كمرجع v3.1).
+- `linter.py` → `backbone_agents/linter.py`.
+- `export_langgraph.py` → `backbone_agents/compilers/langgraph.py`.
+- `export_pydantic_ai.py` → `backbone_agents/compilers/pydantic_ai.py`.
+
+### Fixed
+- `langgraph.py`: `from linter import` → `from ..linter import`.
+- `langgraph.py`: حذف `sys.path.insert` (لم يعد لازماً).
+- المسارات الثابتة (`BASE_DIR`, `PROJECT_PATH`, `OUTPUT_PATH`) — أصبحت معاملات في `compile(contract, output_dir)`.
+
+### Preserved — ما لم نلمسه
+- كل دوال `emit_*` في `langgraph.py` و`pydantic_ai.py`.
+- منطق `linter.py`.
+- `cli.py` (v3.1 CLI) — يبقى كمرجع تاريخي.
+
+### Known Limitations (v4.0.0a1)
+- `cli.py` القديم لا يعمل بعد التثبيت العالمي (يفترض بنية مسطحة).
+- `cli_v4.py` هو البديل الوظيفي.
+- لا Web UI، لا OpenTelemetry، لا Benchmark — هذه v4.4+.

backbone_agents-4.0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backbone System Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backbone_agents-4.0.0a1/PKG-INFO

@@ -0,0 +1,190 @@
+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** — لأن العقد يجب أن يكون هو المصدر الوحيد للحقيقة.

backbone_agents-4.0.0a1/README.md

@@ -0,0 +1,161 @@
+# 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** — لأن العقد يجب أن يكون هو المصدر الوحيد للحقيقة.

backbone_agents-4.0.0a1/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "backbone-agents"
+version = "4.0.0a1"
+description = "Agent Compiler — Contract is the single source of truth. Arabic-first, framework-agnostic."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Backbone System Authors" }]
+keywords = ["agents", "llm", "compiler", "langgraph", "pydantic-ai", "arabic"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Natural Language :: Arabic",
+]
+dependencies = [
+  "langgraph>=0.2",
+  "langchain-google-genai>=2.0",
+  "pydantic>=2.6",
+  "pydantic-ai-slim[google]>=0.1",
+  "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "mypy>=1.10",
+]
+
+[project.scripts]
+backbone = "backbone_agents.cli_v4:main"
+
+[project.urls]
+Homepage = "https://github.com/backbone-system/backbone-agents"
+Repository = "https://github.com/backbone-system/backbone-agents"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/backbone_agents"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = false
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/backbone_agents",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+]
+exclude = [
+    "_archive",
+    "examples",
+    "tests",
+    ".venv",
+]

backbone_agents-4.0.0a1/src/backbone_agents/__init__.py

@@ -0,0 +1,6 @@
+"""Backbone Agents — Agent Compiler.
+
+Contract is the single source of truth. Code is a projection.
+"""
+__version__ = "4.0.0a1"
+__all__ = ["__version__"]