Прямой Jev API принимает state, model и карту typed questions через POST /v1/systemone. Ключ хранится на сервере, а ответ проверяется до бизнес-действия.
От состояния до готового JSON
Соберите запрос для OpenRouter или прямого TypeSafe API. Код создаётся в браузере и никуда не отправляется.
Для Choice и Noul: ключ | описание. Для Score: один уровень на строку.
Используется OpenRouter Decisions API, а не chat/completions. Ключ подставляется только на сервере.
Что потребуется
Нужен ключ TypeSafe AI, серверное окружение и один проверяемый сценарий. Не помещайте секрет в клиентский JavaScript и не начинайте с необратимого действия.
- переменная TYPESAFE_API_KEY на сервере
- версионный ID или алиас модели
- описание state
- карта вопросов с устойчивыми ID
- обработка 401, 422, 429 и 529
Структура запроса
State содержит данные, questions — карту независимых решений, model выбирает модель. ID вопроса возвращается как ID ответа, но сам по себе не участвует в inference.
{
"state": { "message": "С меня списали оплату дважды" },
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Какая команда должна обработать message?",
"criteria": {
"billing": "Платежи и возвраты",
"technical": "Ошибки продукта",
"other": null
}
}
}
}State и questions
State может быть строкой, объектом или массивом текстовых значений. Передавайте только факты, необходимые для решения. В структурированном state ссылайтесь на поля явно: message, ticket.messages[0].text или order.charges.
Instructions формулирует полное суждение. Criteria расширяет смысл вариантов или уровней. Не рассчитывайте, что короткий ID вопроса заменит понятную инструкцию.
Choice, Score и Noul
Choice принимает до 255 вариантов. Score принимает от 2 до 10 упорядоченных уровней. Noul оценивает вероятность «да» и может иметь описания true и false.
Noul не возвращает отдельный confidence: само значение около 0,5 означает неопределённость. Choice и Score возвращают probabilities и агрегированный confidence.
Ответ и confidence
Ответ содержит фактический versioned model, карту answers и usage. Проверяйте тип ответа и наличие ожидаемых полей runtime-схемой.
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.88, "technical": 0.12, "other": 0 },
"confidence": 0.81
}
},
"usage": { "input_tokens": 318, "output_tokens": 34 }
}Пример curl
Прямой endpoint отличается от OpenAI-совместимого chat/completions. Он принимает нативную карту вопросов.
curl https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonTypeScript и Python
Официальные SDK добавляют типы, повторные попытки и обработку ошибок. Даже с SDK полезно держать тонкую доменную обёртку, которая задаёт таймаут, порог и резервное поведение.
// TypeScript
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const result = await client.systemOne({
state,
questions: { department: choice({ instructions, criteria }) }
});
# Python
from typesafe_sdk import Choice, TypeSafeClient
with TypeSafeClient() as client:
result = client.system_one(state, {
"department": Choice(instructions=instructions, criteria=criteria)
})Ошибки и повторные вызовы
401 означает проблему с ключом, 422 — ошибку структуры запроса, 429 — превышение лимита, 529 — временную перегрузку. Повторять следует 429 и 529 с экспоненциальной задержкой; 401 и 422 нужно исправлять.
Не повторяйте тот же запрос только потому, что содержательный ответ вам не понравился. Сначала исправьте вопрос, критерии или state.
Готовые рецепты
Типовой production-путь: нормализовать вход, отфильтровать лишнее, вызвать Jev, проверить схему, применить порог, затем выполнить разрешённое действие.
- поддержка: Choice отдела плюс Score срочности
- RAG: Score релевантности каждого фрагмента
- агент: Choice инструмента с вариантом ask_user
- guardrail: Noul риска плюс Score серьёзности
- неопределённый ответ: человек или reasoning-модель