استخدام LLM API من Python

# إنشاء بيئة افتراضية (ممارسة موصى بها)
python -m venv venv
source venv/bin/activate     # Linux/macOS
# أو: venv\Scripts\activate  # Windows

# تركيب الـ SDK
pip install openai

# في الـ shell (لا تضعها في الكود)
export OPENAI_API_KEY="sk-..."

# أو بشكل أكثر أمانًا، استخدم ملف .env مع python-dotenv:
# pip install python-dotenv

OPENAI_API_KEY=sk-...
OPENAI_MODEL=<model-id-يدعم-الميزة-المطلوبة>

import os
from openai import OpenAI

# قراءة الـ key من متغيّر بيئة (لا قيمة افتراضية = سيفشل صريحًا لو نُسي)
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# قراءة اسم النموذج من متغيّر بيئة — بدون قيمة افتراضية ثابتة.
# اختر نموذجًا يقدّم الميزة التي تحتاجها (Structured Outputs، Tool Calling، streaming...).
# راجع docs المزوّد لاختيار نموذج يدعم الميزة.
model = os.environ["OPENAI_MODEL"]

# أبسط request
response = client.responses.create(
    model=model,
    input="اشرح كلمة machine learning بالعربية في جملتين.",
)

print(response.output_text)

response = client.responses.create(
    model=model,                          # أيّ نموذج تستخدمه
    input="...",                          # النصّ الذي ترسله
    # max_output_tokens=200,              # حدّ المخرج (اختياري)
    # temperature=0.7,                    # تحكّم في التنوّع (اختياري)
    # top_p=0.9,                          # nucleus sampling (اختياري)
)

# response.output_text = اختصار للحصول على نصّ الردّ.
# المخرج الكامل (response.output) يحوي بنية كاملة لكل عنصر.

✅ افعل:
   - تخزين الـ key في متغيّر بيئة أو secret manager
   - استخدام .env محلي (مع .gitignore)
   - تدوير الـ keys دوريًا
   - تقييد الـ keys بنطاق (scope) محدود حيث أمكن

❌ لا تفعل:
   - كتابة الـ key في الكود (hardcode)
   - رفعها على GitHub أو أيّ مستودع
   - مشاركتها في رسائل خطأ أو logs
   - استخدامها من frontend (متصفّح) مباشرة

import os
from openai import OpenAI
from openai import (
    APIConnectionError,
    APITimeoutError,
    RateLimitError,
    BadRequestError,
    AuthenticationError,
)

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

def ask(question: str, model: str | None = None) -> str | None:
    model = model or os.environ["OPENAI_MODEL"]
    try:
        response = client.responses.create(
            model=model,
            input=question,
            timeout=30.0,           # ثوانٍ كحدّ أعلى للطلب
        )
        return response.output_text
    except AuthenticationError:
        print("API key غير صالح أو منتهي الصلاحية.")
        return None
    except RateLimitError:
        print("تجاوزت الحدّ المسموح. حاول بعد قليل.")
        return None
    except APITimeoutError:
        print("انتهت مهلة الاتصال بالمزوّد.")
        return None
    except APIConnectionError:
        print("تعذّر الاتصال بمزوّد الـ API.")
        return None
    except BadRequestError as e:
        print(f"طلب غير صالح: {e}")
        return None

# timeout شامل للـ SDK
client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    timeout=60.0,                  # 60 ثانية كحدّ أقصى لكل طلب
)

كل مزوّد يفرض حدودًا:
  - RPM: requests per minute
  - TPM: tokens per minute
  - على مستوى الـ key أو الـ organization

عند التجاوز: HTTP 429 Too Many Requests.
عليك backoff + retry (درس 112).

نموذج صغير + prompt قصير → ~1-3 ثوانٍ
نموذج كبير + prompt طويل → ~5-30 ثانية
streaming → أول token يظهر خلال ~0.5-2 ثانية

response = client.responses.create(
    model=model,
    input="اشرح الذكاء الاصطناعي بجملة واحدة.",
)

# بعد الطلب، response.usage يحوي:
#   input_tokens:    عدد tokens في prompt
#   output_tokens:   عدد tokens في الـ response
#   total_tokens:    المجموع

print(f"input:  {response.usage.input_tokens}")
print(f"output: {response.usage.output_tokens}")
print(f"total:  {response.usage.total_tokens}")

التكلفة التقريبية:
  cost ≈ input_tokens × input_rate + output_tokens × output_rate

حيث input_rate و output_rate يحدّدهما مزوّد الـ API.

import os

# متغيّر بيئة لاسم النموذج — بدون قيمة افتراضية ثابتة.
# اختر نموذجًا يقدّم الميزة المطلوبة (Structured Outputs، Tool Calling، streaming، ...).
model = os.environ["OPENAI_MODEL"]

# ❌ خطأ شائع جدًا
print(f"Using API key: {os.environ['OPENAI_API_KEY']}")   # لا تطبع الـ key أبدًا
print(f"Full request: {request_dict}")                     # احذر من طباعة request كامل يحوي headers

# ✅ أفضل
print(f"Model: {model}, input length: {len(question)} chars")

"""
llm_helper.py — غلاف بسيط لاستدعاء LLM API.

المتطلبات:
  pip install openai python-dotenv

الإعداد:
  export OPENAI_API_KEY="sk-..."
  export OPENAI_MODEL="<model-id-يدعم-الميزة-المطلوبة>"
"""
import os
from openai import OpenAI
from openai import (
    APIConnectionError,
    APITimeoutError,
    RateLimitError,
    BadRequestError,
    AuthenticationError,
)


def get_client() -> OpenAI:
    api_key = os.environ.get("OPENAI_API_KEY")
    if not api_key:
        raise RuntimeError(
            "OPENAI_API_KEY غير موجود. ضعه في متغيّر بيئة قبل التشغيل."
        )
    return OpenAI(api_key=api_key, timeout=30.0)


def ask(prompt: str, system: str | None = None) -> str | None:
    """استدعاء النموذج وإرجاع نصّ الردّ أو None عند الفشل."""
    client = get_client()
    model = os.environ["OPENAI_MODEL"]

    # مع Responses API، يمكنك تمرير input كنصّ بسيط أو كقائمة رسائل.
    if system:
        full_input = [
            {"role": "system", "content": system},
            {"role": "user", "content": prompt},
        ]
    else:
        full_input = prompt

    try:
        response = client.responses.create(
            model=model,
            input=full_input,
        )
    except AuthenticationError:
        print("[auth] API key غير صالح.")
        return None
    except RateLimitError:
        print("[rate] تجاوز الحدّ. أعد المحاولة لاحقًا.")
        return None
    except APITimeoutError:
        print("[timeout] انتهت المهلة.")
        return None
    except APIConnectionError:
        print("[conn] تعذّر الاتصال.")
        return None
    except BadRequestError as e:
        print(f"[bad-request] {e}")
        return None

    # خزّن آخر response على مستوى الـ module لاستخدامه في __main__
    global _last_response
    _last_response = response
    return response.output_text


_last_response = None  # يحفظ آخر response لاستخدامه عند عرض الـ usage


if __name__ == "__main__":
    answer = ask(
        "ما هي عاصمة اليابان؟ أجب بكلمة واحدة فقط.",
        system="أنت مساعد يجيب بإيجاز."
    )
    print("ANSWER:", answer)
    if _last_response is not None:
        print(
            "TOKENS (input/output/total):",
            _last_response.usage.input_tokens,
            "/",
            _last_response.usage.output_tokens,
            "/",
            _last_response.usage.total_tokens,
        )