Jev Python Rehberi

Kurulum

PyPI'daki paket adı typesafe-sdk'dır ve Python 3.10 veya üzeri gerekir. Kaynak github.com/typesafe-ai/typesafe-sdk-python adresindedir.

pip install typesafe-sdk
# or: uv add typesafe-sdk
# requires Python 3.10+

Anahtarı ve base URL'yi ayarlama

SDK iki ortam değişkeni okur. TYPESAFE_API_KEY, jev-api.org panonuzdan bir anahtar alır — TypeSafe konsol anahtarları burada çalışmaz — ve TYPESAFE_BASE_URL, isteklerin api.typesafe.ai yerine TypeSafe uyumlu /v1/systemone endpoint'ine ulaşması için https://jev-api.org olmalıdır.

# .env — a key from your jev-api.org dashboard
TYPESAFE_API_KEY=jeva_...
TYPESAFE_BASE_URL=https://jev-api.org

Doğrudan da geçirebilirsiniz: TypeSafeClient(api_key=..., base_url="https://jev-api.org"). Varsayılan model jev-latest; TYPESAFE_DEFAULT_MODEL veya model argümanıyla değiştirin. Varsayılan zaman aşımı 10 saniyedir.

İlk çağrı: Noul, Choice ve Score

client.system_one bir state — string, nesne veya dizi — ve Noul, Choice, Score sınıflarıyla kurulmuş bir questions haritası alır. Aşağıdaki çağrı, modelin belgelenen 70–500 ms gecikme bandında döner ve bu sitede 1 kredi kullanır.

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:  # reads TYPESAFE_API_KEY and TYPESAFE_BASE_URL
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={
            "billing": Noul(instructions="Is this ticket about billing?"),
            "tone": Choice(
                instructions="What is the customer's tone?",
                criteria={"calm": None, "frustrated": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["can wait", "this week", "today"],
            ),
        },
    )

print(response.nouls["billing"].noul)      # 0.0 .. 1.0
print(response.choices["tone"].choice)     # winning option
print(response.scores["urgency"].score)    # fractional level

Cevapları okuma

Yanıt nesnesi tiplendirilmiş görünümler sunar: response.nouls, response.choices ve response.scores, soru id'lerinizle indekslenir. Noul cevabı .noul taşır — 0 ile 1 arasında evet olasılığı. Choice cevabı .choice, .probabilities ve .confidence taşır. Score cevabı seviyeler arasına düşebilen kesirli .score ile .legend, .probabilities ve .confidence taşır.

confidence'ı devir sinyali olarak kullanın. Düşükse veya iki seçenek yakınsa, eşiği körü körüne düşürmek yerine vakayı bir kişiye verin veya daha dar bir takip sorusu sorun. Ham soru nesnesini response.answers["id"] ile de okuyabilirsiniz.

Async istemci

AsyncTypeSafeClient aynı arayüzü await edilebilir çağrılarla sunar — FastAPI endpoint'leri içinde veya birden çok state'i paralel açan worker'larda kullanışlıdır.

from typesafe_sdk import AsyncTypeSafeClient, Noul

async with AsyncTypeSafeClient() as client:
    response = await client.system_one(
        state="I was charged twice for my subscription.",
        questions={"refund": Noul(instructions="Is the customer asking for money back?")},
    )
    print(response.answers["refund"])

SDK'sız: sade requests

Bağımlılık istemiyorsanız JSON gövdesini kendiniz POST edin. Bu sitenin basit endpoint'i /api/v1/decisions, jev-1.13 modeliyle aynı state+questions biçimini kabul eder ve limitler biraz daha sıkıdır (1–6 soru, 2–8 Choice seçeneği).

import os
import requests

res = requests.post(
    "https://jev-api.org/api/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['JEV_API_KEY']}"},
    json={
        "model": "jev-1.13",
        "state": "I was charged twice for my subscription.",
        "questions": {
            "refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}
        },
    },
    timeout=30,
)
print(res.json()["answers"]["refund"])

Hatalar ve zaman aşımları

jev-api.org, detail alanı içeren JSON hataları döndürür. Göreceğiniz kodlar:

• 401 — API anahtarı eksik veya reddedildi. Authorization: Bearer başlığını ve anahtarın bu siteden geldiğini kontrol edin.
• 402 — anahtar geçerli ama bakiye çağrıyı karşılamıyor. Fiyat sayfasından kredi ekleyin.
• 422 — gövde doğrulamayı geçemedi veya model reddetti (ör. 64k/32k token limitleri aşıldı). Mesaj alanı belirtir.
• 429 — hız limiti. Geri çekilip yeniden deneyin.
• 502 — karar servisi cevap döndürmedi. Kredi kullanılmaz.

SSS