طرق التثبيت البديلة: uv و npm و الاتصال المباشر بواجهة API عبر curl
في الدرس السابق سلكنا المسار الرئيسي باستخدام venv + pip، لكن تثبيت TypeSafe SDK لا يقتصر على مسار واحد: البداية السريعة الرسمية تقدم ثلاث طرق بديلة في آنٍ واحد: uv، و JavaScript / TypeScript SDK، والاتصال المباشر عبر Bash. في هذا الدرس سنمر بالطرق الثلاث — بعد 8 دقائق، اختر واحدة منها حسب مشروعك.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- إكمال تثبيت TypeSafe SDK بأمرين من uv، وقفل التبعيات داخل
uv.lock - تثبيت Jev JavaScript SDK عبر npm (
@typesafe-ai/sdk)، وتشغيل نفس مثال الأسئلة الثلاثة عن التذكرة من الدرس السابق بنجاح - تشغيل نفس الشيفرة مباشرة بـ TypeScript (Node.js 22.18+)
- الاتصال المباشر بواجهة TypeSafe API باستخدام curl 7.76+، ورؤية استجابة JSON خام في سطر واحد كامل
- ذكر متطلبات الإصدارات لكل من المسارات الثلاثة، واختيار المسار المناسب لمشروعك
المأزق الذي أنت فيه الآن
- المشروع يستخدم uv بالفعل، والعودة إلى venv + pip أشبه بالسير إلى الخلف
- مكدسنا التقني كله Node / TypeScript، وإعداد بيئة Python كاملة من أجل استدعاء API واحد لا يستحق
- لم نقرر بعد أي SDK نستخدم، ونريد أولًا استخدام curl لرؤية ما تعيده واجهة API فعلًا قبل البدء
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- إضافة Jev إلى مشروع Python يديره uv
- استدعاء Jev من مشروع Node.js أو الواجهة الأمامية أو TypeScript
- إجراء استدعاء HTTP مباشر بأي لغة (للتحقق من النتيجة أولًا، أو عندما لا توفر الجهة الرسمية SDK للغتك)
ولا تريد:
- تشغيل
python3 -m venvيدويًا ثمpip install - تثبيت SDK كاملًا من أجل طلب curl واحد
🎒 الاستعدادات قبل البدء
- أنجزت درس التثبيت وأول طلب — هذا الدرس سيعيد استخدام نفس مثال
route_ticket.py - لديك Key في متغيرات البيئة: تنفيذ
echo $TYPESAFE_API_KEYفي الطرفية يطبعها (إن لم يكن لديك، فارجع إلى التسجيل ومفتاح API) - جهّز حسب المسار الذي ستسلكه: Python 3.10+ (مسار uv)، Node.js 22+ (مسار npm)، curl 7.76+ (مسار curl)
- سطر الأوامر يستخدم Bash (macOS / Linux / Windows WSL — أوامر البداية السريعة الرسمية مكتوبة لهذه البيئة)
الفكرة الأساسية
يعرض قسم «اكتب الشيفرة وأرسل أول طلب» في البداية السريعة الرسمية أربع علامات تبويب: Python و JavaScript و TypeScript و Bash. الدرس السابق سلك مسار Python عبر venv + pip، وهذا الدرس يكمل المسارات المتبقية.
مقارنة بين المسارات البديلة الثلاثة:
| المسار | ما الذي يُثبِّت | متطلبات الإصدار | لمن يناسب |
|---|---|---|---|
| uv | typesafe-sdk (نفس الحزمة المتاحة عبر pip) | Python 3.10+، مع ضرورة تثبيت uv | مشاريع Python التي تستخدم uv بالفعل أو تريد استخدامه |
| npm | @typesafe-ai/sdk | Node.js 22+ (تشغيل TS مباشرة 22.18+) | مشاريع Node والواجهات الأمامية و TypeScript |
| curl | لا يثبِّت شيئًا | curl 7.76+ | أي لغة؛ للتحقق السريع من استجابة API |
المسارات الثلاثة تستدعي نفس نقطة النهاية: POST https://api.typesafe.ai/v1/systemone، والمصادقة في جميعها هي Authorization: Bearer <Key>. الاختلاف الوحيد في «من يغلّف HTTP نيابةً عنك».
يقوم SDK بثلاثة أمور نيابةً عنك، وعند الاتصال المباشر عليك القيام بها بنفسك:
| الأمر | ما يفعله SDK | عند الاتصال المباشر عبر curl |
|---|---|---|
| المصادقة | يقرأ TYPESAFE_API_KEY تلقائيًا | يبني ترويسة الطلب -H "Authorization: Bearer $TYPESAFE_API_KEY" كتابتها يدويًا |
| إعادة المحاولة عند تحديد المعدل | 429 / 529 إعادة محاولة افتراضية بتراجع أُسّي | تكتبها بنفسك (صفحة الأخطاء الرسمية تشترط صراحةً التراجع الأُسّي) |
| صيغة الإرسال والاستقبال | الحالة والأسئلة مغلفة بفئات، والإجابات تُجلب حسب ID | تبني JSON بنفسك وتحلل JSON بنفسك |
اتبع خطواتي
المسارات الثلاثة مستقلة عن بعضها، فاختر واحدًا حسب لغتك (راجع الجدول أعلاه للمقارنة)؛ أرقام الخطوات متسلسلة لتسهيل الإحالات المتبادلة.
الخطوة 1: إكمال تثبيت TypeSafe SDK باستخدام uv
لماذا: uv هو طريقة تثبيت مذكورة في البدء السريع الرسمي جنبًا إلى جنب مع pip، حيث تنشئ الأمران مشروعًا وتثبّتان SDK، كما يُولَّد تلقائيًا ملف قفل متوافق مع جميع المنصات uv.lock.
تحقق أولًا مما إذا كان uv مثبتًا:
uv --versionإذا لم يكن مثبتًا، استخدم سكربت التثبيت الرسمي (macOS / Linux):
curl -LsSf https://astral.sh/uv/install.sh | shثبّت SDK. نفّذ في دليل المشروع:
uv init --bare
uv add typesafe-sdkيجب أن ترى: عدم ظهور أي خطأ في كلا الأمرين؛ يُخرج الأمر الثاني شيئًا مشابهًا لـ Installed 14 packages، مع سطر في القائمة مثل typesafe-sdk==0.7.5 (رقم الإصدار يعتمد على وقت تثبيتك). ظهر في الدليل كلٌّ من .venv/ و uv.lock، وأُضيف "typesafe-sdk>=0.7.5" إلى dependencies في pyproject.toml.
- ظهر في دليل المشروع كلٌّ من
.venv/وuv.lock
شغّل مثال الدرس السابق — دون الحاجة إلى تفعيل أي بيئة:
uv run route_ticket.pyيجب أن ترى: الأسطر الثلاثة نفسها تمامًا كما في الدرس السابق:
technical
0.67
0.99route_ticket.py هو نفسه المثال الرسمي من الدرس السابق، انسخه كما هو (الكود في التثبيت وأول طلب).
ثلاثة تفاصيل حول مسار uv (استنادًا إلى وثائق uv الرسمية):
| التفصيل | الشرح |
|---|---|
uv init --bare | يُنشئ pyproject.toml فقط، دون إنشاء دليل src أو README أو git — يكفي للبدء السريع |
.venv | يدير uv البيئة الافتراضية بجانب pyproject.toml؛ ويضمن uv run تلقائيًا بقائها متزامنة مع ملف القفل. يمكن أيضًا استخدام .venv/bin/python route_ticket.py مباشرة |
uv.lock | يثبّت الإصدارات الدقيقة، وتوصي الوثائق الرسمية بإدراجه في نظام التحكم بالإصدارات، ما يتيح إعادة إنتاج المجموعة نفسها من التبعيات على جهاز آخر |
الخطوة 2: تثبيت Jev JavaScript SDK عبر npm وتشغيل المثال بنجاح
لماذا: يُعد JavaScript / TypeScript SDK أحد اثنين من عملاء SDK الرسميين، ويستخدم أسلوب «state + questions» نفسه المستخدم في Python SDK، كما يمكن استنتاج أنواع الإجابات تلقائيًا من تعريف الأسئلة.
تحقق أولًا من إصدار Node — هناك فخ يسهل الوقوع فيه هنا:
node --versionتذكر تبويب JavaScript في البدء السريع الرسمي «Node.js 20 or later»، لكن ذلك كان معيار الإصدار القديم: صفحة وثائق SDK وسجل التغييرات يذكران Node.js 22 or newer (تغييرات جذرية بدءًا من الإصدار v0.7.0)، وحقل engines في حزمة npm هو >=22 أيضًا. اعتمد على 22+ (التفاصيل في تنبيه المخاطر أدناه).
ثبّت SDK:
npm install @typesafe-ai/sdk
npm pkg set type=moduleيضع الأمر الثاني علامة على المشروع كوحدة ES module — يستخدم المثال الرسمي صيغة import، وبدون هذا الإعداد سيظهر خطأ عند تحميل Node.
يجب أن ترى: يُخرج الأمر الأول added 1 package؛ ظهر في الدليل كلٌّ من node_modules/ و package.json و package-lock.json. يوجد في package.json القيمة "@typesafe-ai/sdk": "^0.7.0"، وبعد تنفيذ الأمر الثاني تظهر أيضًا "type": "module".
أنشئ باستخدام محرر النصوص ملف route_ticket.js، والصق فيه المثال الرسمي:
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
const 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.";
const client = new TypeSafeClient({ defaultModel: "jev-latest" }); // Reads TYPESAFE_API_KEY.
const response = await client.systemOne({
state: ticket,
questions: {
department: choice("Which team should handle this", {
billing: "Payment or subscription issues",
technical: "Bugs or integration problems",
sales: "Pricing or account questions",
}),
frustration: score("How frustrated the customer appears", [
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
]),
is_urgent: noul("The message conveys urgency or time-sensitivity"),
},
});
console.log(response.answers.department.choice);
console.log(response.answers.frustration.score);
console.log(response.answers.is_urgent.noul);شغّله:
node route_ticket.jsيجب أن ترى: ثلاثة أسطر من المخرجات، متوافقة مع مسار Python:
technical
0.67
0.99node route_ticket.jsطبعtechnical/0.67/0.99
التشغيل المباشر بـ TypeScript (اختياري)
الكود نفسه، احفظه كما هو باسم route_ticket.ts (المحتوى مطابق تمامًا لـ route_ticket.js)، ثم مباشرة:
node route_ticket.tsيجب أن ترى: أسطر المخرجات الثلاثة نفسها. يتطلب هذا Node.js 22.18 أو أحدث (يدعم تشغيل TypeScript مباشرة)؛ كما يستنتج SDK نوع الإجابة من تعريف أسئلتك — نوع response.answers.department.choice هو "billing" | "technical" | "sales"، والإكمال التلقائي في المحرر متاح فورًا.
الخطوة 3: الاتصال المباشر بواجهة TypeSafe API باستخدام curl
لماذا: مثال Bash في البدء السريع الرسمي هو ببساطة «طلب HTTP كامل بدون SDK». يمكن لأي لغة قادرة على إرسال HTTP (Go أو Java أو Rust...) استدعاء Jev بنفس هذا الهيكل؛ كما أنه مناسب للتحقق من استجابة الواجهة أولًا قبل تقرير تثبيت SDK.
أنشئ باستخدام محرر النصوص ملف route_ticket.sh، والصق فيه المثال الرسمي:
#!/usr/bin/env bash
set -euo pipefail
: "${TYPESAFE_API_KEY:?Set TYPESAFE_API_KEY first.}"
curl --fail-with-body --silent --show-error \
https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"state": "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.",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated the customer appears",
"criteria": [
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language"
]
},
"is_urgent": {
"type": "noul",
"instructions": "The message conveys urgency or time-sensitivity"
}
}
}
JSONشغّله:
bash route_ticket.shيجب أن ترى: سطر واحد كامل من JSON خام — بخلاف القيم الثلاث التي يطبعها مسار SDK، هذه هي الاستجابة الكاملة، وتتضمن confidence و probabilities لكل إجابة، بالإضافة إلى قياس usage. النموذج الكامل بعد التنسيق موجود في قسم «فهم الاستجابة الكاملة» في الدرس السابق، ولن نكرر معاني الحقول: التثبيت وأول طلب.
عند عدم تعيين المفتاح، يوقف السكربت الطلب محليًا أولًا: route_ticket.sh: line 3: TYPESAFE_API_KEY: Set TYPESAFE_API_KEY first. — هذا هو دور سطر الحماية في السطر رقم 3 في البداية، لتجنب إرسال مفتاح فارغ إلى الخادم دون فائدة.
bash route_ticket.shطبع سطرًا كاملًا من JSON يحتوي على"answers"
تنبيهان لمسار curl:
| البند | الشرح |
|---|---|
--fail-with-body | يتطلب curl 7.76+: عند حدوث خطأ HTTP يكون رمز الخروج غير 0، لكنه يطبع متن الاستجابة مع ذلك، ما يسهّل معرفة موضع الخطأ |
429 / 529 | في حل الاتصال المباشر عليك كتابة إعادة المحاولة مع التراجع الأسي بنفسك (SDK يتضمنها افتراضيًا)؛ عند الاستلام ألقِ نظرة على متن الاستجابة، وخذ قسطًا من الراحة ثم أعد الإرسال |
نقطة تحقق ✅
- مسار uv: العناصر الثلاثة
.venv/وuv.lockوpyproject.tomlموجودة جميعها، وuv run route_ticket.pyيُخرج ثلاثة أسطر من الإجابات - مسار npm: يوجد في
package.jsonكلٌّ من"@typesafe-ai/sdk"و"type": "module" - مسار curl:
bash route_ticket.shيُخرج سطرًا كاملًا من JSON يحتوي علىanswers - أعرف أن المسارات الثلاثة تستدعي نقطة النهاية نفسها:
POST /v1/systemone - أعرف الحد الأدنى للإصدارات: Python 3.10+ / Node 22+ (تشغيل TS المباشر 22.18+) / curl 7.76+
تنبيهات المخاطر
❌ npm pkg set type=module يعرض npm error code ENOENT
الظاهرة: تشغيل npm pkg set type=module مباشرة في دليل فارغ يعرض Could not read package.json ... no such file or directory.
السبب: npm pkg set هو أمر «لتعديل package.json»، وعندما لا يوجد هذا الملف في الدليل فلن ينشئه لك (تم التحقق فعليًا على npm 10.9.7).
الطريقة الصحيحة: اتبع الترتيب الرسمي — أولًا npm install @typesafe-ai/sdk (سيولّد npm تلقائيًا package.json)، ثم npm pkg set type=module.
❌ node يُظهر Warning: Failed to load the ES module
الظاهرة: عند تشغيل node route_ticket.js، يظهر الخطأ Failed to load the ES module: route_ticket.js. Make sure to set "type": "module" in the nearest package.json file or use the .mjs extension.
السبب: المشروع لم يُوسم كـ ES module (أو تم ضبطه على commonjs)، بينما المثال الرسمي يستخدم صيغة import.
الطريقة الصحيحة: npm pkg set type=module؛ أو اتبعًا لتلميح الخطأ، غيّر امتداد الملف إلى .mjs.
❌ حضّرت البيئة وفق «Node 20+» لكنك ثبّتت إصدار SDK جديدًا يتطلب 22+
السبب: صفحة البدء السريع الرسمية تقول في تبويب JavaScript «Node.js 20 or later»، لكن أحدث إصدار للـ SDK على npm حاليًا (0.7.0) engines هو node >=22، وسجل التغييرات في الإصدار v0.7.0 يوضح أيضًا أنه تغيير كاسر «require Node.js 22 or newer». أما تاريخيًا فالإصداران 0.5.7 / 0.6.0 كانا يدعمان 20+ — فجملة البدء السريع تلك تعود إلى الإصدارات القديمة.
الطريقة الصحيحة: تحقق أولًا بـ node --version، وإن لم يكن كافيًا لـ 22 فقم بترقية Node، أو تحول إلى مسار uv أو curl في هذا الدرس.
❌ بعد uv add لا يزال python route_ticket.py يظهر ModuleNotFoundError
السبب: python الموجود في النظام ليس البيئة التي يديرها uv، فالـ SDK مثبت في .venv الخاص بالمشروع.
الطريقة الصحيحة: اتبع المثال الرسمي واستخدم دائمًا uv run route_ticket.py (فهو يتأكد أولًا من مزامنة .venv مع ملف القفل)؛ أو حدد صراحةً .venv/bin/python route_ticket.py.
نصائح متقدمة (اختياري)
يدير الـ SDK الضغط نيابةً عنك أيضًا. يستخدم Python SDK افتراضيًا ضغط zstd لجسم الطلب بدءًا من الإصدار v0.7.5؛ بينما يضغط JavaScript SDK تلقائيًا أجسام الطلبات الأكبر من 1 KiB على Node 22.15+، ولإيقاف ذلك مرّر compression: false. أما Python 3.13 والإصدارات الأقدم فتتطلب إضافة extras صراحةً: uv add "typesafe-sdk[zstd]" (وهناك أيضًا extras إضافيان هما http2 وpil).
اللغات التي لا يوجد لها SDK رسمي. Go وJava وRust…… فقط أرسل POST /v1/systemone وفق بنية الخطوة 3، وتعريفات حقول state / questions / answers موجودة في مرجع API السريع.
قبل دفع الحل المباشر إلى الإنتاج. ضمّن إعادة المحاولة بالتراجع الأُسّي لـ 429 / 529 في عميل HTTP الخاص بك — هذا مطلب صريح من صفحة errors الرسمية لمستخدمي الاتصال المباشر، أما مسار SDK فلا يلزمه ذلك.
خلاصة هذا الدرس
✅ مسار uv: uv init --bare + uv add typesafe-sdk، أمران فقط لتثبيت SDK الخاص بـ TypeSafe، ثم uv run للتشغيل مباشرةً.
✅ مسار npm: npm install @typesafe-ai/sdk + npm pkg set type=module، تشغيل نفس المثال في JavaScript وTypeScript (تشغيل مباشر على 22.18+).
✅ مسار curl: --fail-with-body للاتصال المباشر بـ API، ورؤية JSON الخام الكامل مع confidence وprobabilities.
مراجعة حقول الإعداد الأساسية:
| الحقل | القيمة الموصى بها | الشرح |
|---|---|---|
| اسم حزمة Python | typesafe-sdk | نفس الحزمة لـ pip / uv؛uv add typesafe-sdk |
| اسم حزمة JS | @typesafe-ai/sdk | التثبيت عبر npm؛ بدءًا من v0.7.0 يتطلب Node 22+ |
| ES module | type=module | أمثلة JS / TS الرسمية تستخدم import، ويجب ضبطه |
| نقطة النهاية | POST https://api.typesafe.ai/v1/systemone | مشتركة بين المسارات الثلاثة |
| المصادقة | Authorization: Bearer <Key> | يضيفها الـ SDK تلقائيًا؛ وcurl يستخدم $TYPESAFE_API_KEY |
| متغير البيئة | TYPESAFE_API_KEY | مشترك بين المسارات الثلاثة، ولا تُكتب المفتاح في الكود |
استعراض الدرس التالي
بعد إتمام المسارات الثلاثة يتبقى خطوة أخيرة كشبكة أمان: ماذا تفعل إذا فشل التثبيت أو التشغيل: استكشاف أخطاء البداية.
ستتعلم:
- باستخدام 3 أوامر، تحديد في أقل من 60 ثانية أي حلقة هي المشكلة: البيئة أم المفتاح أم الشبكة
400/401/413/422/429— ماذا يعني كل رمز حالة وكيفية التعامل معه- أي الأخطاء يعيد الـ SDK محاولتها تلقائيًا (
429/529)، وكيف تكتبها بنفسك عند الاتصال المباشر - عند الإبلاغ عن خطأ، كيف ترفق
request_idوأصغر كود لإعادة الإنتاج عند طرح السؤال