Jev и Python — гайд

Установка

Пакет называется typesafe-sdk в PyPI и требует Python 3.10 или новее. Исходники — на github.com/typesafe-ai/typesafe-sdk-python.

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

Настройка ключа и base URL

SDK читает две переменные окружения. В TYPESAFE_API_KEY укажите ключ из дашборда jev-api.org — ключи консоли TypeSafe здесь не работают, — а TYPESAFE_BASE_URL должен быть https://jev-api.org, чтобы запросы шли на TypeSafe-совместимый /v1/systemone вместо api.typesafe.ai.

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

Можно передать их напрямую: TypeSafeClient(api_key=..., base_url="https://jev-api.org"). Модель по умолчанию — jev-latest; переопределяется через TYPESAFE_DEFAULT_MODEL или аргумент model. Таймаут по умолчанию — 10 секунд.

Первый вызов: Noul, Choice и Score

client.system_one принимает state — строку, объект или массив — и карту questions, собранную из классов Noul, Choice и Score. Вызов ниже возвращается в заявленной полосе задержки 70–500 мс и тратит 1 кредит на этом сайте.

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

Чтение ответов

Ответ предлагает типизированные представления: response.nouls, response.choices и response.scores, индексированные вашими id вопросов. Ответ Noul несёт .noul — вероятность «да» от 0 до 1. Ответ Choice несёт .choice, .probabilities и .confidence. Ответ Score несёт дробный .score плюс .legend, .probabilities и .confidence.

Используйте confidence как сигнал передачи. Когда он низкий или два варианта близки, отдайте случай человеку или задайте более узкий уточняющий вопрос вместо слепого понижения порога. Сырой объект ответа по вопросу доступен через response.answers["id"].

Асинхронный клиент

AsyncTypeSafeClient имеет тот же интерфейс с awaitable-вызовами — удобно внутри эндпоинтов FastAPI или воркеров, обрабатывающих несколько состояний параллельно.

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: чистый requests

Если зависимость не нужна, отправьте JSON-тело сами. Простой эндпоинт сайта /api/v1/decisions принимает ту же форму state+questions с моделью jev-1.13 и чуть более строгими лимитами (от 1 до 6 вопросов, от 2 до 8 вариантов Choice).

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

Ошибки и таймауты

jev-api.org возвращает JSON-ошибки с полем detail. Коды, которые вы увидите:

• 401 — ключ отсутствует или отклонён. Проверьте заголовок Authorization: Bearer и что ключ выдан этим сайтом.
• 402 — ключ валиден, но баланса не хватает на вызов. Пополните кредиты на странице цен.
• 422 — тело не прошло валидацию или модель его отклонила (например, превышены лимиты 64k/32k токенов). Сообщение называет поле.
• 429 — превышен лимит запросов. Отступите и повторите.
• 502 — сервис решений не вернул ответы. Кредит не тратится.

Частые вопросы