المشغّلات (Operators)

الـoperator عقدة تنفّذ إجراءً حتميًا: بلا LLM، وبلا عشوائية. ولأي إدخال معطى، يكون الإخراج متوقَّعًا.

لماذا تستخدمها

أي منطق يمكن كتابته صراحةً ينبغي أن يُكتب كذلك. فنموذج LLM الذي «يحسب مجموعًا» أو «يهيّئ تاريخًا» هو نمط مضادّ: فهو أبطأ وأغلى وقد يخطئ.

قاعدة عملية: إذا استطعت كتابة الدالة في 5 أسطر من Python، فهي operator — لا agent.

الأنواع المتاحة

operator HTTP

يجري استدعاء HTTP (REST، GraphQL). التهيئة:

• عنوان URL (مع عناصر نائبة من السياق)
• الطريقة، الترويسات، المتن
• المصادقة: bearer، basic، api_key_header (ترويسة مخصّصة)، أو oauth2 (انظر أدناه)
• ربط الاستجابة بالخانات

operator DB

ينفّذ استعلامًا على قاعدة بيانات مُسجَّلة في الإدارة ← قواعد البيانات. ويدعم Postgres وMySQL وMongoDB وقاعدة بيانات betool الداخلية للجداول المُعرَّفة من المستخدم.

file_transform

يحوّل ملفًا. المحوّلات المدمجة:

• القراءة (PDF مع OCR، DOCX، XLSX، CSV)
• التقطيع (Chunking) (حسب الصفحة، حسب كتلة التوكِنات)
• التحويل (HTML ← نصّ، Markdown ↔ HTML)
• استخراج البنية (JSON من مخطَّط)

compute

الحسابات والتجميعات على خانات السياق:

• التصفية / التعيين / الاختزال (filter / map / reduce) على القوائم
• إحصاءات عمودًا بعمود (العدد، المجموع، النسبة المئوية)
• إسقاطات المخطَّط
• شروط منطقية مركّبة

payload_mapper

يركّب حمولة إخراج من خانات السياق. مفيد لإعداد متن operator HTTP لاحق.

code_step

عندما يتجاوز المنطق الحتمي ما يستطيع compute التعامل معه، تنفّذ خطوة كود كودًا مخصّصًا في sandbox — مقفلة بمراجعة بشرية. راجع خطوات الكود المُحكَمة.

المصادقة والأسرار

المشغّلات التي تتواصل مع نظام خارجي (HTTP، DB) تشير إلى حساب مُسجَّل داخل المؤسسة. ولا تكون بيانات الاعتماد مرئية أبدًا داخل الـpipeline نفسه — بل يُشار إلى اسم حساب فقط.

نتيجةً لذلك، فإنّ تدوير كلمة مرور لا يتطلّب أي تعديل على أي pipeline.

OAuth2 الصادر (client_credentials)

بالنسبة إلى واجهات API التي تتطلّب رمز OAuth2 مميّزًا (السحابة المؤسسية، ERP، مزوّدو الطرف الثالث)، يدعم operator HTTP وضع oauth2. تسجّل بيانات اعتماد OAuth2 في المؤسسة — token_url، client_id، client_secret، scope — ولا تشير العقدة إلا إلى مُعرِّف غير حسّاس.

عند وقت الاستدعاء، يحصل betool على رمز مميّز ويُعيد استخدامه ما دام صالحًا؛ ويجدّده بكسل (lazily) عند انتهاء الصلاحية، بلا مهمّة في الخلفية. ولا يُعيد الـadministration API الـclient_secret أبدًا (بل يُعرَض مؤشّر has_secret فقط)، ويوضَع الرمز المميّز المُحصَّل عليه بصيغة Authorization: Bearer … على الطلب الصادر.

تدوير السرّ بعد تدوير على جانب المزوّد لا يتطلّب أي تعديل على الـpipeline: فالاستدعاء التالي يجدّده تلقائيًا.

الخاصّية الاحترازية (Idempotency)

أي operator يُنتج أثرًا جانبيًا (HTTP POST، DB INSERT، إرسال بريد) يجب تصميمه ليكون احترازيًا على جانب الهدف. الممارسة المُوصى بها:

• ضمِّن idempotency_key في الحمولة (عادةً exchange_id).
• تحقّق على جانب الهدف مما إذا كان المفتاح قد عُولِج بالفعل.

لا يُعيد betool تلقائيًا محاولة operator فاشل: بل من مسؤولية الـpipeline لديك تنسيق استراتيجية إعادة المحاولة (loop + condition).