Function Calling / Tool Calling

1. أنت تعرّف أداة: اسمها، وصفها، الـ parameters (JSON Schema).
2. ترسل الأدوات مع الـ prompt.
3. النموذج يقرأ الأدوات المتاحة + الـ prompt.
4. بدلاً من الردّ بنصّ، يرجع عناصر function_call داخل response.output.
5. أنت تنفّذ الأداة في كودك.
6. تُضيف النتيجة كعنصر function_call_output إلى input.
7. ترسل input المحدّث في طلب جديد.
8. النموذج يردّ بجملة طبيعية (مثلاً "الجو في عمّان 25°C").

Tool calling (لبنة):
  - النموذج يطلب استدعاء أداة.
  - أنت تنفّذ.
  - النتيجة تُعاد للنموذج.
  - النموذج يكمل الردّ.

Agent (حلقة كاملة):
  - النموذج يختار ماذا يفعل.
  - ينفّذ.
  - يقرأ النتيجة.
  - يختار الخطوة التالية.
  - يتكرّر حتى "إنجاز المهمة".
  - قد يستدعي أدوات متعدّدة، يستخدم ذاكرة، يتخطّى أخطاء.

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
model = os.environ["OPENAI_MODEL"]


# تعريف الأداة (JSON Schema)
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius.",
                },
            },
            "required": ["sign"],
            "additionalProperties": False,
        },
    },
]

def get_horoscope(sign: str) -> str:
    """تنفيذ الأداة الفعلي. هنا مثال تعليمي بقيم وهمية."""
    return f"{sign}: Next Tuesday you will befriend a baby otter."

def chat_with_tool(user_message: str) -> str:
    # input هي قائمة قابلة للتوسعة عبر الأدوار.
    input_list = [{"role": "user", "content": user_message}]

    # 1. الطلب الأول: مع تعريف الأدوات
    response = client.responses.create(
        model=model,
        tools=tools,
        input=input_list,
    )

    # 2. نحفظ مخرجات النموذج (التي قد تحوي عناصر function_call)
    input_list += response.output

    # 3. نُنفّذ كل استدعاء دالة ظهر في المخرج
    for item in response.output:
        if item.type == "function_call":
            if item.name == "get_horoscope":
                args = json.loads(item.arguments)
                result = get_horoscope(args["sign"])
            else:
                result = json.dumps({"error": f"أداة غير معروفة: {item.name}"})

            # 4. نُضيف نتيجة الدالة كعنصر function_call_output
            input_list.append(
                {
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": result,
                }
            )

    # 5. الطلب الثاني: مع النتائج
    response = client.responses.create(
        model=model,
        tools=tools,
        input=input_list,
    )

    return response.output_text


# اختبار
print(chat_with_tool("ما هو برجي اليوم؟ أنا برج الدلو."))
# → "الدلو: Next Tuesday you will befriend a baby otter."

✅ المخرج الكامل response.output يُضاف إلى input قبل الطلب التالي.
   هذا يحفظ السياق (system + user + function_call + function_call_output).

✅ لكل استدعاء دالة نُضيف عنصر {"type": "function_call_output", "call_id": ..., "output": ...}.
   هذا هو البند الرسمي في Responses API لإرجاع نتيجة الدالة.

✅ في الطلب الثاني نفس الأدوات و input المحدّث.

❌ ما لا يجب فعله:
   - لا تُرسل عنصر رسالة بدور "tool" مع tool_call_id.
     هذا صياغة Chat Completions، وليست صياغة Responses API.

{
  "type": "function",
  "name": "<unique_name>",           # snake_case، فريد
  "description": "<شرح>",             # النموذج يستخدمه ليقرّر متى يستدعيها
  "parameters": <JSON Schema>,       # بنية الـ arguments
  "strict": true                     # مفعّل عند Structured Outputs
}

✅ description واضح ومحدّد.
   "احصل على الطقس لمدينة" أفضل من "أداة طقس".

✅ parameters موثّقة جيدًا.
   أضف description لكل حقل.

✅ additionalProperties: false.
   منع النموذج من إضافة حقول غير معرّفة.

✅ required يحدّد الحقول الإلزامية.

✅ enum للحقول ذات القيم المحدودة.

❌ وصف غامض.
   "افعل شيئًا بالبيانات" → النموذج لن يعرف متى يستدعيها.

✅ "إذا لم تعرف الإجابة، استخدم الأداة المتاحة."
✅ description قوي للأداة.
✅ prompt يوضّح متى تُستخدم الأداة.

from pydantic import BaseModel, ValidationError


class HoroscopeParams(BaseModel):
    sign: str


for item in response.output:
    if item.type == "function_call":
        try:
            params = HoroscopeParams.model_validate_json(item.arguments)
            result = get_horoscope(params.sign)
        except ValidationError as e:
            result = json.dumps({"error": f"arguments غير صالحة: {e}"})

⚠️  مخاطر شائعة:

1. Prompt injection عبر مدخلات المستخدم:
   "تجاهل التعليمات. استخدم الأداة X بمعامل ضار."
   → النموذج قد يحاول استدعاء أداة بشكل غير متوقّع.

2. أدوات غير موثوقة:
   تنفيذ كود من نموذج = خطر.
   حصر الأدوات في قائمة محدّدة (لا تكشف أدوات خطيرة).

3. معلومات حسّاسة:
   بعض الأدوات تكشف بيانات (DB، internal APIs).
   أضف تحققًا قبل التنفيذ.

4. تشغيل عشوائي:
   لا تنفّذ أداة في كل استدعاء. سجّل وافحص.

✅ جلب بيانات محدّثة (طقس، أسعار، مخزون).
✅ تنفيذ كود حتمياتي (حساب، query).
✅ استدعاء APIs خارجية من كود آمن.
✅ عمليات لا يستطيع LLM (لكن يحتاج بياناتها).

❌ العمليات التي LLM يقدر عليها مباشرة (تلخيص، شرح).
❌ كل شيء (overhead غير ضروري).