backbone-agents 4.0.0a1__py3-none-any.whl

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__"]

backbone_agents/cli.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# backbone.py — CLI موحّد لنظام Backbone System
+# الاستخدام: python backbone.py <command> [args]
+
+import argparse
+import importlib.util
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+PROJECTS_DIR = os.path.join(HERE, "10_projects")
+EXPORTER = os.path.join(HERE, "export_langgraph.py")
+EXPORTER_PYDANTIC = os.path.join(HERE, "export_pydantic_ai.py")
+LINTER = os.path.join(HERE, "linter.py")
+
+# تحميل .env
+def load_env():
+    env_path = os.path.join(HERE, ".env")
+    if os.path.exists(env_path):
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)
+                    os.environ.setdefault(k.strip(), v.strip())
+
+def load_module(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+def get_project_path(name):
+    p = os.path.join(PROJECTS_DIR, name, "contracts.json")
+    if not os.path.exists(p):
+        print(f"❌ المشروع غير موجود: {p}")
+        sys.exit(1)
+    return p
+
+# =====================================================================
+# الأوامر
+# =====================================================================
+def cmd_lint(args):
+    linter = load_module("linter", LINTER)
+    path = get_project_path(args.project)
+    result = linter.lint_project(path)
+    linter.print_report(result, args.project)
+    sys.exit(0 if result["passed"] or args.lenient else 2)
+
+def cmd_export(args):
+    linter = load_module("linter", LINTER)
+    path = get_project_path(args.project)
+    result = linter.lint_project(path)
+    linter.print_report(result, args.project)
+
+    if not result["passed"] and not args.force:
+        print("❌ العقد معيب — توقف التوليد. استخدم --force للتخطي.")
+        sys.exit(2)
+
+    if not result["passed"] and args.force:
+        print("⚠️ متابعة مع --force…")
+
+    print()
+    os.environ["BACKBONE_PROJECT"] = args.project
+
+    exporter_name = getattr(args, "exporter", "langgraph") or "langgraph"
+    if exporter_name == "pydantic":
+        pyd_mod = load_module("export_pydantic_ai", EXPORTER_PYDANTIC)
+        pyd_mod.export_pydantic_ai(args.project)
+    else:
+        exporter = load_module("export_langgraph", EXPORTER)
+        # --force لأن Linter اجتاز بالفعل هنا
+        exporter.export_to_langgraph(force=True)
+
+def cmd_run(args):
+    # 1) lint
+    linter = load_module("linter", LINTER)
+    path = get_project_path(args.project)
+    result = linter.lint_project(path)
+    linter.print_report(result, args.project)
+    if not result["passed"] and not args.force:
+        sys.exit(2)
+
+    # 2) export
+    print()
+    os.environ["BACKBONE_PROJECT"] = args.project
+    exporter = load_module("export_langgraph", EXPORTER)
+    exporter.export_to_langgraph(force=args.force)
+
+    # 3) run
+    print()
+    load_env()
+    if not os.getenv("GOOGLE_API_KEY"):
+        print("❌ GOOGLE_API_KEY غير محمّل")
+        sys.exit(1)
+
+    gen_path = os.path.join(HERE, "06_exporters", "generated_graph.py")
+    mod = load_module("generated_graph", gen_path)
+
+    app = mod.app
+    extract_text = mod.extract_text
+    HumanMessage = mod.HumanMessage
+    MODEL = getattr(mod, "MODEL_NAME", "?")
+
+    # بناء الحالة الأولية
+    topic = args.topic
+    initial_state = {
+        "messages": [HumanMessage(content=topic)],
+        "current_agent": "",
+        "next_step": "",
+        "round_number": 0,
+    }
+
+    print("=" * 72)
+    print(f"🚀 تشغيل المشروع: {args.project}")
+    print(f"النموذج: {MODEL} | الموضوع: {topic[:80]}")
+    print("=" * 72)
+
+    step = 0
+    try:
+        for update in app.stream(initial_state, {"recursion_limit": 50}):
+            step += 1
+            for node_name, delta in update.items():
+                print(f"\n─── [خطوة {step}] 🔹 {node_name} ───")
+                for m in delta.get("messages", []) if isinstance(delta, dict) else []:
+                    if hasattr(m, "content"):
+                        print(extract_text(m))
+    except Exception as e:
+        print(f"\n❌ خطأ: {type(e).__name__}: {e}")
+        sys.exit(3)
+
+    print("\n" + "=" * 72)
+    print("✅ اكتمل التشغيل")
+    print("=" * 72)
+
+def cmd_patterns(args):
+    print("📐 الأنماط المدعومة في v3.0:")
+    print("   1. router     — وكيل تصنيف + توجيه شرطي")
+    print("   2. debate     — مناظرة 3 أدوار + حلقة + حكم")
+    print("   3. sequential — تدفق خطي A → B → C → END")
+
+def cmd_projects(args):
+    print(f"📂 المشاريع في {PROJECTS_DIR}:")
+    if not os.path.isdir(PROJECTS_DIR):
+        print("   (المجلد غير موجود)")
+        return
+    for p in sorted(os.listdir(PROJECTS_DIR)):
+        path = os.path.join(PROJECTS_DIR, p, "contracts.json")
+        if os.path.exists(path):
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                pattern = data.get("project_metadata", {}).get("selected_pattern", "?")
+                n_agents = len(data.get("agents", []))
+                print(f"   - {p:40} [{pattern:10}] {n_agents} وكيل")
+            except Exception:
+                print(f"   - {p:40} [JSON معطوب]")
+
+def cmd_status(args):
+    print("🎯 Backbone System — الحالة")
+    print("=" * 50)
+    print(f"📁 المجلد: {HERE}")
+    print(f"🐍 Python: {sys.version.split()[0]}")
+    print()
+    # فحص .env
+    has_key = bool(os.getenv("GOOGLE_API_KEY"))
+    print(f"🔑 GOOGLE_API_KEY: {'✅' if has_key else '❌'}")
+    print(f"🤖 النموذج: {os.getenv('BACKBONE_LLM_MODEL', 'gemini-2.5-flash')}")
+    print()
+    # فحص الملفات
+    files = [
+        ("المولّد", EXPORTER),
+        ("Linter", LINTER),
+        ("CLI", os.path.abspath(__file__)),
+    ]
+    for name, path in files:
+        ok = "✅" if os.path.exists(path) else "❌"
+        print(f"   {ok} {name}: {os.path.basename(path)}")
+    # مشاريع
+    if os.path.isdir(PROJECTS_DIR):
+        n = len([p for p in os.listdir(PROJECTS_DIR)
+                 if os.path.exists(os.path.join(PROJECTS_DIR, p, "contracts.json"))])
+        print(f"   📂 {n} مشروع")
+
+# =====================================================================
+# Main
+# =====================================================================
+def main():
+    load_env()
+
+    parser = argparse.ArgumentParser(
+        prog="backbone",
+        description="Backbone System — CLI موحّد"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # lint
+    p_lint = sub.add_parser("lint", help="فحص عقد مشروع")
+    p_lint.add_argument("project")
+    p_lint.add_argument("--lenient", action="store_true")
+    p_lint.set_defaults(func=cmd_lint)
+
+    # export
+    p_exp = sub.add_parser("export", help="فحص + توليد كود")
+    p_exp.add_argument("project")
+    p_exp.add_argument("--force", action="store_true")
+    p_exp.add_argument("--exporter", choices=["langgraph", "pydantic"],
+                       default="langgraph", help="المُصدّر الهدف")
+    p_exp.set_defaults(func=cmd_export)
+
+    # run
+    p_run = sub.add_parser("run", help="فحص + توليد + تشغيل")
+    p_run.add_argument("project")
+    p_run.add_argument("--topic", required=True)
+    p_run.add_argument("--force", action="store_true")
+    p_run.set_defaults(func=cmd_run)
+
+    # patterns
+    p_pat = sub.add_parser("patterns", help="عرض الأنماط")
+    p_pat.set_defaults(func=cmd_patterns)
+
+    # projects
+    p_proj = sub.add_parser("projects", help="عرض المشاريع")
+    p_proj.set_defaults(func=cmd_projects)
+
+    # status
+    p_st = sub.add_parser("status", help="حالة النظام")
+    p_st.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    args.func(args)
+
+if __name__ == "__main__":
+    main()

backbone_agents/cli_v4.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Backbone Agents CLI v4.0 — REGISTRY-based."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .linter import lint_project, print_report
+from .compilers import REGISTRY, get as get_compiler
+
+
+def resolve_projects_dir(cli_arg):
+    if cli_arg:
+        return Path(cli_arg).expanduser().resolve()
+    env = os.getenv("BACKBONE_PROJECTS_DIR")
+    if env:
+        return Path(env).expanduser().resolve()
+    return (Path.cwd() / "10_projects").resolve()
+
+
+def load_contract(projects_dir, project):
+    path = projects_dir / project / "contracts.json"
+    if not path.exists():
+        print(f"❌ المشروع غير موجود: {path}", file=sys.stderr)
+        sys.exit(1)
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), path
+    except json.JSONDecodeError as e:
+        print(f"❌ JSON معطوب في {path}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_lint(args):
+    projects_dir = resolve_projects_dir(args.projects_dir)
+    contract, path = load_contract(projects_dir, args.project)
+    result = lint_project(str(path))
+    print_report(result, args.project)
+    sys.exit(0 if result["passed"] or args.lenient else 2)
+
+
+def cmd_export(args):
+    projects_dir = resolve_projects_dir(args.projects_dir)
+    contract, path = load_contract(projects_dir, args.project)
+    result = lint_project(str(path))
+    print_report(result, args.project)
+    if not result["passed"] and not args.force:
+        print("❌ العقد معيب — توقف التوليد. استخدم --force.", file=sys.stderr)
+        sys.exit(2)
+    target = args.target
+    if target not in REGISTRY:
+        print(f"❌ المُصدّر غير متاح: {target}. المتاح: {sorted(REGISTRY)}", file=sys.stderr)
+        sys.exit(2)
+    output_dir = (Path(args.output_dir).expanduser().resolve()
+                  if args.output_dir else (projects_dir / args.project / "generated"))
+    print(f"\n🔧 تصدير إلى {target} → {output_dir}")
+    paths = get_compiler(target).compile(contract, output_dir)
+    for p in paths:
+        print(f"   ✅ {p}")
+
+
+def cmd_run(args):
+    args.output_dir = None
+    cmd_export(args)
+
+
+def cmd_patterns(args):
+    print("📐 الأنماط المدعومة:")
+    print("   1. router     — وكيل تصنيف + توجيه شرطي")
+    print("   2. debate     — مناظرة 3 أدوار + حلقة + حكم")
+    print("   3. sequential — تدفق خطي A → B → C → END")
+
+
+def cmd_projects(args):
+    projects_dir = resolve_projects_dir(args.projects_dir)
+    print(f"📂 المشاريع في {projects_dir}:")
+    if not projects_dir.is_dir():
+        print("   (المجلد غير موجود)")
+        return
+    for entry in sorted(projects_dir.iterdir()):
+        contract = entry / "contracts.json"
+        if not contract.is_file():
+            continue
+        try:
+            data = json.loads(contract.read_text(encoding="utf-8"))
+            pattern = data.get("project_metadata", {}).get("selected_pattern", "?")
+            n = len(data.get("agents", []))
+            print(f"   - {entry.name:40} [{pattern:10}] {n} وكيل")
+        except Exception:
+            print(f"   - {entry.name:40} [JSON معطوب]")
+
+
+def cmd_status(args):
+    print("🎯 Backbone Agents — الحالة")
+    print("=" * 50)
+    print(f"📦 الإصدار: {__version__}")
+    print(f"🐍 Python: {sys.version.split()[0]}")
+    print(f"🔑 GOOGLE_API_KEY: {'✅' if os.getenv('GOOGLE_API_KEY') else '❌'}")
+    print(f"🤖 النموذج: {os.getenv('BACKBONE_LLM_MODEL', 'gemini-3.5-flash-lite')}")
+    print()
+    print(f"🔧 المُصدّرات المسجلة ({len(REGISTRY)}):")
+    for name, plugin in sorted(REGISTRY.items()):
+        patterns = ", ".join(plugin.supported_patterns)
+        print(f"   ✅ {name:15} → {patterns}")
+    print()
+    projects_dir = resolve_projects_dir(getattr(args, "projects_dir", None))
+    print(f"📂 مجلد المشاريع: {projects_dir}")
+    if projects_dir.is_dir():
+        count = sum(1 for p in projects_dir.iterdir() if (p / "contracts.json").is_file())
+        print(f"   {count} مشروع")
+
+
+def cmd_init(args):
+    from .templates import get_template, TEMPLATES
+    if args.template not in TEMPLATES:
+        print(f"❌ القالب غير معروف: {args.template}", file=sys.stderr)
+        print(f"   المتاح: {TEMPLATES}", file=sys.stderr)
+        sys.exit(2)
+    projects_dir = resolve_projects_dir(args.projects_dir)
+    project_dir = projects_dir / args.name
+    if project_dir.exists():
+        print(f"❌ المشروع موجود مسبقاً: {project_dir}", file=sys.stderr)
+        sys.exit(2)
+    project_dir.mkdir(parents=True)
+    contract = get_template(args.template)
+    contract["project_metadata"]["name"] = args.name
+    (project_dir / "contracts.json").write_text(
+        json.dumps(contract, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    print(f"✅ مشروع جديد: {project_dir}")
+    print(f"   العقد: contracts.json (نمط: {args.template})")
+    print(f"   التالي: backbone lint {args.name} --projects-dir {projects_dir}")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="backbone",
+        description="Backbone Agents — Agent Compiler (v4.0)",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("lint", help="فحص عقد مشروع")
+    p.add_argument("project")
+    p.add_argument("--lenient", action="store_true")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_lint)
+
+    p = sub.add_parser("export", help="فحص + توليد كود")
+    p.add_argument("project")
+    p.add_argument("--target", choices=list(REGISTRY.keys()) or ["langgraph"], default="langgraph")
+    p.add_argument("--output-dir", default=None)
+    p.add_argument("--force", action="store_true")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_export)
+
+    p = sub.add_parser("run", help="فحص + توليد (التنفيذ في v4.4)")
+    p.add_argument("project")
+    p.add_argument("--target", default="langgraph")
+    p.add_argument("--topic", required=False)
+    p.add_argument("--force", action="store_true")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_run)
+
+    p = sub.add_parser("patterns", help="عرض الأنماط")
+    p.set_defaults(func=cmd_patterns)
+
+    p = sub.add_parser("projects", help="عرض المشاريع")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_projects)
+
+    p = sub.add_parser("status", help="حالة النظام")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("init", help="إنشاء مشروع جديد من قالب")
+    p.add_argument("name")
+    p.add_argument("--template", choices=["router", "debate", "sequential"], default="router")
+    p.add_argument("--projects-dir", default=None)
+    p.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

backbone_agents/compilers/__init__.py

@@ -0,0 +1,36 @@
+"""Compiler plugins — each framework implements CompilerPlugin.
+
+Public API:
+    from backbone_agents.compilers import REGISTRY, get, register
+
+Plugins are auto-registered on import, but registration is defensive:
+if a plugin's framework dependencies are missing, it is silently skipped.
+This keeps `pip install -e .` working before optional deps are installed.
+"""
+from .base import CompilerPlugin, REGISTRY, get, register, write_generated
+
+__all__ = [
+    "CompilerPlugin",
+    "REGISTRY",
+    "get",
+    "register",
+    "write_generated",
+]
+
+
+def _auto_register() -> None:
+    """Best-effort registration of built-in plugins."""
+    try:
+        from .langgraph import LangGraphCompiler
+        register(LangGraphCompiler())
+    except ImportError:
+        pass  # langgraph not installed — plugin unavailable
+
+    try:
+        from .pydantic_ai import PydanticAICompiler
+        register(PydanticAICompiler())
+    except ImportError:
+        pass  # pydantic-ai not installed — plugin unavailable
+
+
+_auto_register()

backbone_agents/compilers/base.py

@@ -0,0 +1,68 @@
+"""Compiler plugin protocol — Layer 3 of v4.0 architecture.
+
+Every framework exporter (LangGraph, Pydantic AI, future frameworks)
+implements this Protocol. The CLI (Layer 5) never imports a concrete
+exporter directly — it dispatches through this interface.
+
+This is the architectural seam that makes the project "framework-agnostic":
+adding a new framework means adding one file under compilers/ and
+registering it in REGISTRY — zero changes to cli.py or linter.py.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CompilerPlugin(Protocol):
+    """Contract that every framework compiler must satisfy."""
+
+    name: str
+    """Short identifier: 'langgraph' | 'pydantic_ai'."""
+
+    supported_patterns: tuple[str, ...]
+    """Patterns this compiler can emit: ('router', 'debate', 'sequential')."""
+
+    def compile(self, contract: dict, output_dir: Path) -> list[Path]:
+        """Compile a contract into framework-specific source files.
+
+        Args:
+            contract: Parsed contracts.json (dict).
+            output_dir: Directory to write generated files into.
+
+        Returns:
+            List of generated file paths (absolute).
+
+        Raises:
+            ValueError: if contract.pattern not in supported_patterns.
+        """
+        ...
+
+
+# Registry — populated by compilers/__init__.py
+REGISTRY: dict[str, "CompilerPlugin"] = {}
+
+
+def register(plugin: CompilerPlugin) -> None:
+    """Register a compiler plugin by its .name."""
+    REGISTRY[plugin.name] = plugin
+
+
+def get(name: str) -> CompilerPlugin:
+    """Look up a registered compiler; raise KeyError if unknown."""
+    if name not in REGISTRY:
+        raise KeyError(
+            f"Unknown compiler '{name}'. Available: {sorted(REGISTRY)}"
+        )
+    return REGISTRY[name]
+
+
+def write_generated(
+    output_dir: Path, filename: str, lines: list[str]
+) -> Path:
+    """Write generated code lines to output_dir/filename; return path."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    path = output_dir / filename
+    path.write_text("".join(lines), encoding="utf-8")
+    return path