ثبّت Python SDK وأرسل أول طلب: يعمل خلال 10 دقائق
حصلت على المفتاح في الدرس السابق. في هذا الدرس ستستخدمه: أكمل تثبيت typesafe-sdk وشغّل المثال الرسمي — تذكرة عميل واحدة، وطلب واحد يسأل ثلاثة أسئلة في آنٍ واحد، فتحصل على ثلاث إجابات: «إلى أي مجموعة تُوجَّه، وكم يبدو العميل محبطًا، وهل هي عاجلة». كل ذلك خلال 10 دقائق.
ماذا ستستطيع أن تفعل بعد هذا الدرس
- إكمال تثبيت typesafe-sdk في بيئة افتراضية مستقلة (بايثون 3.10+)
- تشغيل مثال أسئلة التذكرة الثلاثة الرسمي، ورؤية ثلاثة أسطر مخرجات
technical/0.67/0.99 - فهم
choiceوscoreوnoulفي ملف JSON المُرجَع، بالإضافة إلىconfidenceوprobabilities - معرفة أن الـ SDK يقرأ متغيرات البيئة تلقائيًا ويتعامل مع إعادة المحاولة عند تحديد المعدل تلقائيًا، دون كتابة المفتاح في الكود
- معرفة أي درس تراجع إليه لاستكشاف الأخطاء عندما لا يعمل التشغيل
مشكلتك الحالية
- حصلت على المفتاح، لكن بعد التثبيت عبر pip يفشل الاستيراد فورًا، ولا تفرّق بين مشكلة إصدار بايثون ومشكلة البيئة
- يعمل المثال، لكن المخرجات كتلة JSON واحدة، ولا تدري أي حقل هو «الإجابة»
- تريد أن يعمل أولًا ثم تفكر، ولا تريد أن تبدأ بقراءة وثائق API كاملة من أول لحظة
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- استدعاء Jev من بايثون على حاسوبك، وتشغيل أول طلب حقيقي
- طريقة تثبيت نظيفة لا تلوّث بايثون النظام
ولا تريد:
- تثبيت الـ SDK في بايثون النظام فيتعارض مع مشاريع أخرى
- أن تكتب طلبات HTTP وترويسات المصادقة ومنطق إعادة المحاولة يدويًا من البداية
🎒 تجهيزات قبل البدء
- مفتاح الدرس السابق محفوظ في متغيرات البيئة
TYPESAFE_API_KEY - بايثون 3.10 أو أحدث (متطلب إصدار الـ SDK الرسمي؛ يمكن التحقق عبر
python3 --versionفي الطرفية) - مثبَّت pip (تربط الوثائق الرسمية بصفحة تثبيت pip الرسمية، فثبّته أولًا إن لم يكن مثبتًا)
- سطر الأوامر هو Bash (macOS / Linux / Windows WSL — أوامر البدء السريع الرسمي مكتوبة لهذه البيئة)
الفكرة الأساسية
ما الذي نثبّته. اسم حزمة pip للـ Python SDK الرسمي هو typesafe-sdk، واسم الاستيراد هو typesafe_sdk. إنه يتولى «تجميع طلب HTTP، والمصادقة، والضغط، وإعادة المحاولة عند تحديد المعدل» كله، فتكتب أنت state والأسئلة فقط.
لماذا venv. مسار pip في البدء السريع الرسمي هو «venv + pip»: البيئة الافتراضية تثبّت الـ SDK في .venv داخل مجلد المشروع دون المساس ببايثون النظام، وحذف المجلد يعني إزالة نظيفة.
كيف يبدو الطلب الأول. يستخدم المثال الرسمي تذكرة عميل واحدة كـ state، ويسأل ثلاثة أسئلة في طلب واحد:
| السؤال | نوع السؤال | الحقل المُرجَع |
|---|---|---|
| أي مجموعة تعالج هذه التذكرة | Choice | choice + probabilities لكل خيار + confidence |
| كم يبدو العميل محبطًا | Score | (score 0–2، قد يقع بين درجتين) + confidence |
| هل هي عاجلة | Noul | (noul احتمال 0–1) |
تُقيَّم الأسئلة الثلاثة بالتوازي على نفس الـ state وتُرجَع كلها في مرة واحدة — هذه هي طريقة العمل الأساسية في Jev، وسيُستغلّها الدرس اللاحق حول الأسئلة المتوازية إلى أقصى حد.
يقوم الـ SDK بثلاثة أشياء نيابة عنك.
| الأمر | ما يفعله الـ SDK |
|---|---|
| المصادقة | يقرأ متغيرات البيئة تلقائيًا TYPESAFE_API_KEY |
| اختيار النموذج | model="jev-latest"؛ وعند عدم التحديد يكون الإعداد الافتراضي للـ SDK أيضًا jev-latest (يشير حاليًا إلى Jev 1.14) |
| إعادة المحاولة عند تحديد المعدل | عند مواجهة 429 يعيد المحاولة تلقائيًا افتراضيًا مع إطالة زمن الانتظار تدريجيًا، ويحترم retry-after |
معيار نجاح التشغيل. المخرجات المتوقعة للمثال الرسمي هي ثلاثة أسطر:
technical
0.67
0.99تذكّر الوثائق الرسمية في الوقت نفسه بأن هذه نتائج مثال، وقد تتغير القيم مع إصدار Jev.
اتبع خطواتي
الخطوة 1: أنشئ مجلد المشروع وتحقق من متغيرات البيئة
لماذا: يبدأ البدء السريع الرسمي من مجلد نظيف؛ يجب أن يكون المفتاح في متغيرات البيئة حتى يتمكن الـ SDK من قراءته تلقائيًا.
mkdir typesafe-quickstart
cd typesafe-quickstart
export TYPESAFE_API_KEY="your-api-key"استبدل your-api-key بمفتاحك (إذا حفظته في الدرس السابق، فعليك إعادة export مرة أخرى في أي طرفية جديدة تفتحها).
ينبغي أن ترى: الأوامر الثلاثة لا تُظهر أي خطأ؛ echo $TYPESAFE_API_KEY يستطيع طباعة مفتاحك.
الخطوة 2: إكمال تثبيت typesafe-sdk (venv + pip)
لماذا: يثبّت venv الـ SDK داخل مجلد .venv الخاص بالمشروع دون تلويث بايثون النظام — وهذه هي الممارسة القياسية في مسار pip الرسمي.
python3 -m venv .venv
.venv/bin/pip install typesafe-sdkينبغي أن ترى: يسرد pip الحزم المطلوب تثبيتها ويعرض نجاح التثبيت، وتظهر typesafe-sdk في قائمة الحزم.
- ظهر مجلد
.venvداخل مجلد المشروع
💡 لمن اعتاد على uv
يدعم المسؤول أيضًا مسار uv: بعد uv init --bare نفّذ uv add typesafe-sdk. الطريقة الكاملة لـ uv وnpm وcurl المباشر موجودة في درس طرق التثبيت البديلة.
الخطوة 3: كتابة المثال الرسمي route_ticket.py
لماذا: شغّل المثال الرسمي كما هو أولًا، ثم عدّله إلى محتواك الخاص — بهذه الطريقة يكون لديك دائمًا خط أساس «معروف الصحة» عند استكشاف الأخطاء.
أنشئ باستخدام محرر النصوص ملف route_ticket.py في مجلد المشروع، والصق فيه المثال الكامل من البدء السريع الرسمي:
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed."
with TypeSafeClient(model="jev-latest") as client: # Reads TYPESAFE_API_KEY.
response = client.system_one(
state=ticket,
questions={
"department": Choice(
instructions="Which team should handle this",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"frustration": Score(
instructions="How frustrated the customer appears",
criteria=[
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
],
),
"is_urgent": Noul(
instructions="The message conveys urgency or time-sensitivity",
),
},
)
print(response.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)ينبغي أن ترى: الملف محفوظ في typesafe-quickstart/route_ticket.py.
الخطوة 4: تشغيله والحصول على ثلاثة إجابات
لماذا: هذه الخطوة هي هدف الدرس بأكمله — أول استدعاء Jev حقيقي لك.
.venv/bin/python route_ticket.pyاستخدم .venv/bin/python وليس python الخاص بالنظام، للتأكد من أنك تستخدم البيئة التي ثُبّت فيها الـ SDK للتو.
ينبغي أن ترى: ثلاثة أسطر من المخرجات —
technical
0.67
0.99- رأيت ثلاثة أسطر من المخرجات، السطر الأول هو
technical(توجيه التذكرة إلى الفريق التقني)
الخطوة 5: فهم الاستجابة الكاملة
لماذا: طبعت الدالة print ثلاث قيم فقط؛ في المشاريع الحقيقية غالبًا ما ستحتاج إلى probabilities وconfidence لكتابة منطق التفرع.
الاستجابة الكاملة بصيغة JSON كما وردت في البدء السريع الرسمي (قيم نموذجية، تتغير مع الإصدارات):
الاستجابة الكاملة بصيغة JSON للمثال الرسمي
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"confidence": 1.0,
"probabilities": {
"technical": 1.0,
"billing": 0.0,
"sales": 0.0
}
},
"frustration": {
"type": "score",
"score": 0.67,
"confidence": 0.5,
"legend": {
"0": "Calm, just stating facts",
"1": "Frustrated but civil",
"2": "Very angry, strong language"
},
"probabilities": {
"0": 0.33,
"1": 0.67,
"2": 0.0
}
},
"is_urgent": {
"type": "noul",
"noul": 0.99
}
},
"usage": {
"input_tokens": 428,
"output_tokens": 73
}
}ثلاث نقاط تستحق الانتباه:
| الحقل | أين يوجد | المعنى |
|---|---|---|
confidence | في إجابات Choice / Score | مدى ثقة النموذج في هذه الإجابة (إجابة Noul لا تحتوي على هذا الحقل) |
probabilities | في كل إجابة | التوزيع الاحتمالي الكامل: department يرجّح technical بنسبة 100% |
usage | في المستوى الأعلى | الاستهلاك هذه المرة: 428 token إدخال و73 token إخراج (تُحسب الفاتورة على الإدخال، والإخراج مجاني) |
القيمة "model": "jev-1.13.0" في JSON النموذجي هي القيمة وقت تسجيل مثال الوثائق الرسمية؛ إذا شغّلت jev-latest الآن، فإن حقل model في الاستجابة يعتمد على إصدار النموذج الحالي. أما كيفية استخدام confidence لكتابة التفرع فتُشرح بالتفصيل في درس ثقة Confidence.
نقطة تحقق ✅
- typesafe-sdk مثبّت في
.venvوليس في بايثون النظام - لا يظهر مفتاح API في الكود الخاص بي (الـ SDK يقرأ متغيرات البيئة تلقائيًا)
- حصلت على ثلاثة أسطر من المخرجات، وأعرف أنها إجابات Choice / Score / Noul على التوالي
- أعرف أن الإجابات تُخزَّن حسب معرّف السؤال في
response.choices/.scores/.nouls - أعرف أن القيم النموذجية قد تتغير مع الإصدارات، فلا داعي للتردد بين 0.67 و0.66
تنبيهات العثرات
❌ ModuleNotFoundError: No module named 'typesafe_sdk'
الحزمة لم تُثبَّت في نسخة بايثون التي تستخدمها حاليًا. السبب الأكثر شيوعًا: تشغيل مشروع مثبّت في .venv باستخدام python الخاص بالنظام. الطريقة الصحيحة: التشغيل بـ .venv/bin/python route_ticket.py كما في المثال الرسمي؛ ومن اعتاد على تفعيل البيئة أولًا، يمكنه بعد source .venv/bin/activate استخدام python أيضًا (استخدام شائع لـ venv، لكن المثال الرسمي لم يتّبع هذه الخطوة).
❌ إصدار بايثون أقل من 3.10
يتطلب الـ SDK الرسمي بايثون 3.10 أو أحدث. تحقق بـ python3 --version؛ إذا كان الإصدار أقدم، فقم أولًا بترقية بايثون، أو أعد إنشاء venv باستخدام مفسّر 3.10 أو أحدث.
❌ نجح التشغيل لكن القيم لا تطابق 0.67 / 0.99
هذا ليس عطلًا — يقول المسؤول بوضوح إن نتائج المثال تتغير مع إصدار Jev. تحقق من صحة البنية: السطر الأول أحد billing / technical / sales، والسطر الثاني رقم من 0–2، والسطر الثالث رقم من 0–1. إذا كانت البنية صحيحة فالتشغيل ناجح.
❌ عدّلت المثال فلم يعمل، ولا أعرف أي تعديل أفسده
عُد إلى خط الأساس: شغّل المثال الرسمي كما هو أولًا، ثم عدّل خطوة خطوة صغيرة — غيّر أولًا نص state، ثم الأسئلة، وأخيرًا نوع السؤال، وشغّل بعد كل تعديل. إذا علقت فعلًا، فدرس استكشاف أخطاء البدء يشرح كل خطأ على حدة.
حيل متقدمة (اختياري)
نسختان من العميل: متزامنة وغير متزامنة. يوفر الـ SDK كلاً من TypeSafeClient (متزامن، وهو المستخدم في هذا الدرس) وAsyncTypeSafeClient (غير متزامن)، بنفس أسماء الواجهات (system_one)؛ بدّل إلى النسخة غير المتزامنة في سيناريوهات التزامن العالي.
للـ SDK مكونات إضافية اختيارية. يمكن عند التثبيت تضمين extras: http2 يفعّل دعم HTTP/2، وpil لإرسال صور Pillow، وzstd لضغط جسم الطلب على بايثون 3.13 والإصدارات الأقدم. الاستخدامات المتعلقة بالصور موجودة في درس Box والصور.
لا تريد استخدام بايثون؟ طريقة استخدام SDK الخاص بـ JavaScript / TypeScript والاتصال المباشر بالـ API عبر curl موجودة كلها في درس طرق التثبيت البديلة.
خلاصة الدرس
✅ اكتمل تثبيت typesafe-sdk: باستخدام venv + pip، مثبَّت في .venv الخاص بالمشروع، مع Python 3.10+.
✅ نجح أول طلب: تذكرة واحدة، ثلاثة أسئلة، استجابة واحدة — technical / 0.67 / 0.99.
✅ أصبحت تعرف كيف تقرأ الاستجابة: الإجابات مخزنة حسب معرّف السؤال في choices / scores / nouls، والاحتمالات و confidence موجودة أيضًا.
مراجعة حقول الإعدادات الأساسية:
| الحقل | القيمة الموصى بها | الشرح |
|---|---|---|
| اسم الحزمة | typesafe-sdk | اسم التثبيت عبر pip؛ أما اسم import فهو typesafe_sdk |
model | jev-latest | اسم بديل، يشير حاليًا إلى Jev 1.14؛ وعند عدم تحديده يكون هذا أيضًا هو الافتراضي في SDK |
state | سلسلة نصية / كائن JSON / مصفوفة نصوص | استخدمنا في هذا الدرس سلسلة نصية لتذكرة واحدة |
questions | {ID: Choice/Score/Noul(...)} | معرّفات تختارها بنفسك؛ تُسترجع الإجابات حسب المعرّف من choices / scores / nouls |
| متغير البيئة | TYPESAFE_API_KEY | يقرأه SDK تلقائيًا، فلا تكتب المفتاح في الكود |
استعراض الدرس التالي
Python ليست المسار الوحيد: طرق التثبيت البديلة: uv و npm والاتصال المباشر بـ API عبر curl.
ستتعلم:
- تثبيت نفس SDK باستخدام uv بأمرين أو ثلاثة أوامر
- تشغيل نفس المثال باستخدام
@typesafe-ai/sdkعلى Node.js 20+ - الاتصال المباشر بـ API باستخدام curl 7.76+، ومعرفة شكل JSON الخام
- اختيار المسار المناسب حسب وضع مشروعك