Skip to content

इंस्टॉल के वैकल्पिक तरीके: uv, npm और curl से API को सीधे कनेक्ट करना ​

पिछले पाठ में venv + pip से मुख्य रास्ता पूरा किया, लेकिन TypeSafe SDK इंस्टॉल का एक ही रास्ता नहीं है: आधिकारिक क्विक स्टार्ट में uv, JavaScript / TypeScript SDK और Bash सीधे कनेक्शन — तीनों वैकल्पिक तरीके एक साथ दिए गए हैं। इस पाठ में तीनों को एक बार चलाएँगे — 8 मिनट बाद, अपने प्रोजेक्ट के हिसाब से एक चुनकर इस्तेमाल करें।

सीखने के बाद आप क्या कर सकते हैं ​

  • uv से दो कमांड में TypeSafe SDK इंस्टॉल करना, और डिपेंडेंसी को uv.lock में लॉक करना
  • npm से Jev JavaScript SDK (@typesafe-ai/sdk) इंस्टॉल करना, और पिछले पाठ वाला वही टिकट-तीन-सवाल उदाहरण चलाना
  • वही कोड TypeScript में सीधे चलाना (Node.js 22.18+)
  • curl 7.76+ से TypeSafe API को सीधे कॉल करना, और एक पूरी लाइन का रॉ JSON रिस्पॉन्स देखना
  • तीनों रास्तों की अपनी-अपनी वर्ज़न शर्तें बता सकना, और अपने प्रोजेक्ट के लिए उपयुक्त रास्ता चुन सकना

आपकी मौजूदा दिक्कत ​

  • प्रोजेक्ट पहले से uv पर है, वापस venv + pip पर जाना पीछे की ओर कदम जैसा है
  • हमारा टेक स्टैक पूरी तरह Node / TypeScript है, एक API कॉल के लिए पूरा Python एनवायरनमेंट सेट करने के लायक नहीं
  • अभी तय नहीं किया कि कौन सा SDK लेना है, पहले curl से देखना चाहते हैं कि API वास्तव में क्या लौटाता है, फिर हाथ आज़माना

यह तरीका कब इस्तेमाल करें ​

जब आपको चाहिए:

  • uv-प्रबंधित Python प्रोजेक्ट में Jev जोड़ना
  • Node.js, फ्रंटएंड या TypeScript प्रोजेक्ट में Jev कॉल करना
  • किसी भी भाषा से सीधे HTTP कॉल (पहले नतीजा जाँचना, या आपकी भाषा का आधिकारिक SDK न होना)

और नहीं चाहते:

  • मैन्युअली python3 -m venv फिर pip install
  • एक curl रिक्वेस्ट के लिए पूरा SDK इंस्टॉल करना

🎒 शुरू करने से पहले की तैयारी ​

  • पूरा किया इंस्टॉल और पहला रिक्वेस्ट — यह पाठ उसी route_ticket.py उदाहरण को दोबारा इस्तेमाल करेगा
  • एनवायरनमेंट वेरिएबल में Key मौजूद है: टर्मिनल में echo $TYPESAFE_API_KEY से प्रिंट हो जाता है (न हो तो लौटें रजिस्ट्रेशन और API Key)
  • जिस रास्ते पर जाना है उसके हिसाब से तैयार रखें: Python 3.10+ (uv रास्ता), Node.js 22+ (npm रास्ता), curl 7.76+ (curl रास्ता)
  • कमांड लाइन Bash है (macOS / Linux / Windows WSL — आधिकारिक क्विक स्टार्ट के कमांड इसी एनवायरनमेंट के हिसाब से लिखे गए हैं)

मुख्य विचार ​

आधिकारिक क्विक स्टार्ट के "कोड लिखकर पहला रिक्वेस्ट भेजें" खंड में चार टैब हैं: Python, JavaScript, TypeScript, Bash। पिछले पाठ में Python का venv + pip रास्ता चला, इस पाठ में बाकी सभी पूरे करेंगे।

तीनों वैकल्पिक रास्तों की तुलना:

रास्ताक्या इंस्टॉल होता हैवर्ज़न ज़रूरतकिसके लिए उपयुक्त
uvtypesafe-sdk (pip वाला ही पैकेज)Python 3.10+, uv इंस्टॉल होना चाहिएuv पहले से इस्तेमाल करने / करना चाहने वाले Python प्रोजेक्ट
npm@typesafe-ai/sdkNode.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 पर डिफ़ॉल्ट रूप से एक्सपोनेंशियल बैकऑफ़ से रिट्राईखुद लिखें (आधिकारिक errors पेज एक्सपोनेंशियल बैकऑफ़ साफ़ माँगता है)
भेजने-पाने का फ़ॉर्मैटस्टेटस + सवाल क्लास में रैप करके, जवाब ID से लेता हैखुद JSON बनाएँ, खुद JSON पार्स करें

मेरे साथ करें ​

तीनों रास्ते एक-दूसरे से स्वतंत्र हैं, अपनी भाषा के हिसाब से कोई एक चुनकर चलें (तुलना ऊपर तालिका में); चरणों के नंबर लगातार हैं, क्रॉस-रेफ़रेंस में सुविधा के लिए।

चरण 1: uv से TypeSafe SDK इंस्टॉल पूरा करना ​

क्यों: uv आधिकारिक quick start में pip के साथ समानांतर इंस्टॉल विधि है, दो कमांड से प्रोजेक्ट बनाना + SDK इंस्टॉल करना, और यह क्रॉस-प्लेटफ़ॉर्म लॉक फ़ाइल uv.lock भी अपने आप बना देता है।

पहले जाँच लें कि uv मौजूद है या नहीं:

bash
uv --version

अगर इंस्टॉल नहीं है, तो आधिकारिक इंस्टॉल स्क्रिप्ट का उपयोग करें (macOS / Linux):

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

SDK इंस्टॉल करें। प्रोजेक्ट डायरेक्टरी में निष्पादित करें:

bash
uv init --bare
uv add typesafe-sdk

आपको यह दिखना चाहिए: दोनों में कोई त्रुटि नहीं; दूसरी का आउटपुट Installed 14 packages जैसा होगा, सूची में एक पंक्ति typesafe-sdk==0.7.5 होगी (संस्करण संख्या आपके इंस्टॉल के समय के अनुसार)। डायरेक्टरी में .venv/ और uv.lock जुड़ गए, pyproject.toml के dependencies में "typesafe-sdk>=0.7.5" जुड़ गया।

  • प्रोजेक्ट डायरेक्टरी में .venv/ और uv.lock दिखाई देते हैं

पिछले पाठ का उदाहरण चलाएँ——किसी भी एनवायरनमेंट को सक्रिय करने की ज़रूरत नहीं:

bash
uv run route_ticket.py

आपको यह दिखना चाहिए: पिछले पाठ जैसी हूबहू तीन पंक्तियाँ:

text
technical
0.67
0.99

route_ticket.py वही पिछले पाठ वाला आधिकारिक उदाहरण है, जस का तस कॉपी कर लाएँ (कोड इंस्टॉल और पहला अनुरोध में)।

uv मार्ग के तीन विवरण (uv आधिकारिक दस्तावेज़ के अनुसार):

विवरणव्याख्या
uv init --bareकेवल pyproject.toml बनाता है, src डायरेक्टरी, README और git नहीं बनाता——तेज़ शुरुआत के लिए पर्याप्त
.venvuv वर्चुअल एनवायरनमेंट को pyproject.toml के बगल में प्रबंधित करता है; uv run इसे लॉक फ़ाइल के साथ सिंक रखना अपने आप सुनिश्चित करता है। सीधे .venv/bin/python route_ticket.py से भी चला सकते हैं
uv.lockसटीक संस्करण लॉक करता है, आधिकारिक सलाह है कि इसे वर्ज़न कंट्रोल में रखें, दूसरी मशीन पर भी एक ही डिपेंडेंसी सेट को फिर से बनाया जा सकता है

चरण 2: npm से Jev JavaScript SDK इंस्टॉल करें और उदाहरण चलाएँ ​

क्यों: JavaScript / TypeScript SDK दो आधिकारिक क्लाइंट SDK में से एक है, Python SDK की तरह ही「state + questions」लेखन शैली उपयोग करता है, और उत्तर के प्रकार प्रश्न की परिभाषा से अपने आप अनुमानित हो जाते हैं।

पहले Node संस्करण जाँचें——यहाँ एक आसानी से फँसने वाला गड्ढा है:

bash
node --version

आधिकारिक quick start के JavaScript टैब में लिखा है「Node.js 20 or later」, लेकिन वह पुराने संस्करण की बात थी: SDK दस्तावेज़ पृष्ठ और चेंजलॉग दोनों Node.js 22 or newer लिखते हैं (v0.7.0 से शुरू ब्रेकिंग बदलाव), npm पैकेज का engines फ़ील्ड भी >=22 है। 22+ को मानक मानें (विवरण नीचे गड्ढा चेतावनी में)।

SDK इंस्टॉल करें:

bash
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 नई फ़ाइल बनाएँ, आधिकारिक उदाहरण पेस्ट करें:

javascript
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);

इसे चलाएँ:

bash
node route_ticket.js

आपको यह दिखना चाहिए: तीन पंक्तियों का आउटपुट, Python मार्ग के अनुरूप:

text
technical
0.67
0.99
  • node route_ticket.js ने technical / 0.67 / 0.99 प्रिंट किया

TypeScript से सीधे चलाएँ (वैकल्पिक) ​

वही कोड, जस का तस route_ticket.ts के रूप में सेव करें (सामग्री route_ticket.js से पूरी तरह समान), और सीधे:

bash
node route_ticket.ts

आपको यह दिखना चाहिए: वही तीन पंक्तियों का आउटपुट। इसके लिए Node.js 22.18 या अधिक चाहिए (TypeScript को सीधे चलाने का समर्थन); और SDK आपकी प्रश्न परिभाषा से उत्तर के प्रकार अनुमानित करेगा——response.answers.department.choice का प्रकार "billing" | "technical" | "sales" ही है, एडिटर में ऑटो-कंप्लीशन सीधे उपयोग करने योग्य है।

चरण 3: curl से सीधे TypeSafe API से जुड़ें ​

क्यों: आधिकारिक quick start का Bash उदाहरण ही「SDK के बिना पूरा HTTP अनुरोध」है। कोई भी HTTP भेजने में सक्षम भाषा (Go, Java, Rust……) इसी संरचना से Jev को कॉल कर सकती है; और SDK इंस्टॉल करने का निर्णय लेने से पहले API प्रतिक्रिया जाँचने के लिए भी उपयुक्त है।

एडिटर से route_ticket.sh नई फ़ाइल बनाएँ, आधिकारिक उदाहरण पेस्ट करें:

bash
#!/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
bash route_ticket.sh

आपको यह दिखना चाहिए: पूरी एक पंक्ति कच्चा JSON——SDK मार्ग से प्रिंट हुए तीन मानों से भिन्न, यह पूर्ण प्रतिक्रिया है, जिसमें प्रत्येक उत्तर का confidence और probabilities, तथा usage मीटरिंग शामिल है। फ़ॉर्मैट किया हुआ पूर्ण नमूना पिछले पाठ के「पूर्ण प्रतिक्रिया समझें」में है, फ़ील्ड के अर्थ दोबारा नहीं दिए जाते: इंस्टॉल और पहला अनुरोध।

Key सेट न होने पर स्क्रिप्ट पहले ही स्थानीय स्तर पर रोक देगी: route_ticket.sh: line 3: TYPESAFE_API_KEY: Set TYPESAFE_API_KEY first.——यही शुरुआत की 3वीं पंक्ति वाले उस गार्ड का काम है, ताकि खाली Key बेकार में सर्वर को न भेजा जाए।

  • bash route_ticket.sh ने पूरी एक पंक्ति JSON प्रिंट किया, जिसमें "answers" है

curl मार्ग के दो अनुस्मारक:

मदव्याख्या
--fail-with-bodycurl 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+ मांगता है ​

कारण: आधिकारिक quick start पेज के JavaScript टैब में लिखा है "Node.js 20 or later", लेकिन SDK का वर्तमान npm नवीनतम संस्करण (0.7.0) का engines node >=22 है, और changelog में v0.7.0 स्पष्ट रूप से एक breaking change है "require Node.js 22 or newer"। ऐतिहासिक रूप से 0.5.7 / 0.6.0 ही 20+ का समर्थन करते थे—quick start का वह वाक्य पुराने संस्करणों के लिए है।

सही तरीका: पहले 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 v0.7.5 से डिफ़ॉल्ट रूप से zstd से रिक्वेस्ट बॉडी कंप्रेस करता है; JavaScript SDK Node 22.15+ पर 1 KiB से बड़ी रिक्वेस्ट बॉडी को अपने आप कंप्रेस करता है, इसे बंद करने के लिए compression: false पास करें। Python 3.13 और उससे पुराने संस्करणों में स्पष्ट रूप से extras जोड़ने होंगे: uv add "typesafe-sdk[zstd]" (साथ ही http2, pil दो अन्य extras भी हैं)।

वे भाषाएँ जिनका कोई आधिकारिक SDK नहीं है। Go, Java, Rust…… चरण 3 की संरचना के अनुसार POST /v1/systemone भेजें; state / questions / answers के फ़ील्ड परिभाषाएँ API क्विक रेफ़रेंस में देखें।

डायरेक्ट कनेक्शन विकल्प को प्रोडक्शन पर ले जाने से पहले। 429 / 529 के लिए एक्सपोनेंशियल बैकऑफ़ रिट्राई को अपने HTTP क्लाइंट में शामिल करें—यह आधिकारिक errors पेज की डायरेक्ट-कनेक्शन उपयोगकर्ताओं के लिए स्पष्ट आवश्यकता है; SDK मार्ग पर इसकी चिंता करने की ज़रूरत नहीं।

इस पाठ का सारांश ​

✅ uv मार्ग: uv init --bare + uv add typesafe-sdk, दो कमांड में TypeSafe SDK इंस्टॉल हो जाता है, uv run से सीधे चलाएँ।

✅ npm मार्ग: npm install @typesafe-ai/sdk + npm pkg set type=module, JavaScript और TypeScript (22.18+ पर सीधे चलता है) एक ही उदाहरण चला पाते हैं।

✅ curl मार्ग: --fail-with-body से सीधे API से जुड़ें, confidence और probabilities सहित पूरा रॉ JSON देखें।

मुख्य कॉन्फ़िगरेशन फ़ील्ड की समीक्षा:

फ़ील्डअनुशंसित मानविवरण
Python पैकेज नामtypesafe-sdkpip / uv एक ही पैकेज; uv add typesafe-sdk
JS पैकेज नाम@typesafe-ai/sdknpm से इंस्टॉल; v0.7.0 से Node 22+ आवश्यक
ES moduletype=moduleआधिकारिक JS / TS उदाहरण import का उपयोग करते हैं, सेट करना अनिवार्य है
एंडपॉइंटPOST https://api.typesafe.ai/v1/systemoneतीनों मार्गों में साझा
प्रमाणीकरणAuthorization: Bearer <Key>SDK अपने आप जोड़ता है; curl में $TYPESAFE_API_KEY
पर्यावरण चरTYPESAFE_API_KEYतीनों मार्गों में साझा, कोड में कुंजी न लिखें

अगले पाठ की झलक ​

तीनों मार्ग सफल होने के बाद भी अंतिम सुरक्षा-कवच बाकी है: इंस्टॉल न हो या चल न पाए तो क्या करें: शुरुआती समस्या-निवारण।

आप सीखेंगे:

  • 3 कमांडों से 60 सेकंड में पता लगाएँ कि परिवेश, Key, नेटवर्क में से कौन-सी कड़ी में समस्या है
  • 400 / 401 / 413 / 422 / 429 स्टेटस कोड क्रमशः क्या दर्शाते हैं, उनसे कैसे निपटें
  • कौन-सी त्रुटियों पर SDK अपने आप रिट्राई करता है (429 / 529), और डायरेक्ट कनेक्शन पर स्वयं कैसे लिखें
  • त्रुटि रिपोर्ट करते समय request_id और न्यूनतम पुनरुत्पादक कोड के साथ कैसे प्रश्न पूछें
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.