Jev-Python-Guide

Installation

Das Paket heißt typesafe-sdk auf PyPI und braucht Python 3.10 oder neuer. Der Quellcode liegt auf github.com/typesafe-ai/typesafe-sdk-python.

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

Schlüssel und Base URL konfigurieren

Das SDK liest zwei Umgebungsvariablen. TYPESAFE_API_KEY nimmt einen Schlüssel aus Ihrem jev-api.org-Dashboard — TypeSafe-Console-Schlüssel funktionieren hier nicht — und TYPESAFE_BASE_URL muss https://jev-api.org sein, damit Requests den TypeSafe-kompatiblen Endpoint /v1/systemone statt api.typesafe.ai erreichen.

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

Alternativ direkt übergeben: TypeSafeClient(api_key=..., base_url="https://jev-api.org"). Das Standardmodell ist jev-latest; überschreiben Sie es mit TYPESAFE_DEFAULT_MODEL oder dem model-Argument. Der Standard-Timeout beträgt 10 Sekunden.

Erster Aufruf: Noul, Choice und Score

client.system_one nimmt einen state — String, Objekt oder Array — und eine questions-Map aus den Klassen Noul, Choice und Score. Der Aufruf unten kommt innerhalb der dokumentierten Latenzbandbreite von 70 bis 500 ms zurück und verbraucht auf dieser Site 1 Credit.

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

Antworten lesen

Die Antwort bietet typisierte Ansichten: response.nouls, response.choices und response.scores, indiziert über Ihre Fragen-IDs. Eine Noul-Antwort trägt .noul, die Ja-Wahrscheinlichkeit zwischen 0 und 1. Eine Choice-Antwort trägt .choice, .probabilities und .confidence. Eine Score-Antwort trägt einen gebrochenen .score plus .legend, .probabilities und .confidence.

Nutzen Sie confidence als Übergabesignal. Ist es niedrig oder liegen zwei Optionen nah beieinander, geben Sie den Fall an einen Menschen oder stellen Sie eine engere Folgefrage, statt den Schwellenwert blind zu senken. Das rohe Antwortobjekt pro Frage lesen Sie über response.answers["id"].

Async-Client

AsyncTypeSafeClient hat dieselbe Schnittstelle mit awaitbaren Aufrufen — nützlich in FastAPI-Endpunkten oder Workern, die mehrere States parallel abarbeiten.

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"])

Ohne SDK: reines requests

Wenn Sie die Abhängigkeit nicht wollen, senden Sie den JSON-Body selbst. Der einfache Endpoint dieser Site, /api/v1/decisions, akzeptiert dieselbe state+questions-Form mit dem Modell jev-1.13 und etwas engeren Limits (1 bis 6 Fragen, 2 bis 8 Choice-Optionen).

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"])

Fehler und Timeouts

jev-api.org liefert JSON-Fehler mit einem detail-Feld. Die Codes, die Sie sehen werden:

• 401 — fehlender oder abgelehnter API-Schlüssel. Prüfen Sie den Authorization: Bearer-Header und ob der Schlüssel von dieser Site stammt.
• 402 — der Schlüssel ist gültig, aber das Guthaben reicht nicht. Laden Sie Credits auf der Preisseite auf.
• 422 — der Body hat die Validierung nicht bestanden oder das Modell hat ihn abgelehnt (etwa über den 64k/32k-Token-Limits). Die Meldung nennt das Feld.
• 429 — Rate-Limit. Kurz zurückfallen und erneut versuchen.
• 502 — der Entscheidungsdienst hat keine Antworten geliefert. Kein Credit wird verbraucht.

FAQ