Схема решения
JSON-документ, стоящий за каждым решением, — принимаемое состояние, вопросы, на которые оно отвечает, композиты, политики, выбирающие действие, настройки выполнения и назначения.
Решение определяется одним JSON-документом — схемой решения. Редактор и визуальный конструктор редактируют её за вас (правая панель показывает её в разделе Схема решения), CLI создаёт заготовку и валидирует её офлайн, а каждая опубликованная версия хранит её полный снимок.
Схема не зависит от движка: в ней нет ничего специфичного для Jev или любого другого движка.
Полный пример
Это шаблон Квалификация лидов в том виде, в каком он хранится, со всеми заполненными значениями по умолчанию:
{
"stateSchema": {
"kind": "object",
"fields": [
{ "key": "message", "type": "string", "required": true, "description": "Inbound lead message" },
{ "key": "company_size", "type": "number", "required": false, "description": "Employee count" },
{ "key": "source", "type": "string", "required": false, "description": "website, referral, ads…" }
]
},
"questions": [
{
"key": "purchase_intent",
"type": "probability",
"instructions": "Does this lead have real intent to buy in the next 30 days?",
"criteria": {
"yes": "asks for pricing, a demo, a quote or a start date",
"no": "just browsing, student, vendor or spam"
}
},
{
"key": "priority",
"type": "score",
"instructions": "How urgent is it to answer this lead?",
"scale": ["low", "medium", "high", "critical"]
},
{
"key": "route",
"type": "choice",
"instructions": "Which team should receive this lead?",
"options": [
{ "value": "sales", "description": "high intent, ready to talk to sales" },
{ "value": "sdr", "description": "some intent, needs qualification" },
{ "value": "nurture", "description": "early stage, send content" },
{ "value": "spam", "description": "spam, vendor pitch or irrelevant" },
{ "value": "other", "description": "none of the options above" }
]
}
],
"composites": [
{
"key": "lead_score",
"description": "0–1 ranking: intent counts double, priority adds, spam-like routes don't count",
"terms": [
{ "question": "purchase_intent", "weight": 2 },
{ "question": "priority", "weight": 1 },
{ "question": "route", "option": "sales", "weight": 1 }
]
}
],
"policies": [
{ "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" },
{ "field": "purchase_intent", "on": "confidence", "operator": "lt", "value": 0.6, "action": "escalate" }
],
"settings": {
"storeInput": true,
"storeOutput": true,
"timeoutMs": 5000,
"fallbackAction": "escalate",
"onEngineError": "error"
}
}Поля верхнего уровня
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
stateSchema | object | Да | Входные данные, которые принимает решение, — см. Схема state. |
questions | array | Да | От 1 до 64 вопросов — см. Вопросы. |
composites | array | Нет | До 20 взвешенных комбинаций ответов. По умолчанию [] — см. Композиты. |
policies | array | Нет | До 50 правил, оцениваемых по порядку. По умолчанию [] — см. Политики и действия. |
context | string | Нет | До 8 000 символов бизнес-контекста, отправляемого с каждым state, — см. Контекст. |
settings | object | Нет | Движок, хранение, бюджет времени, fallback-действие и поведение при ошибке движка — см. Настройки решения. |
destinations | array | Нет | До 20 назначений — что происходит после решения, для каждого варианта, уровня, порога или итогового действия. По умолчанию [] — см. Назначения. |
Ключи
Поля state, ключи вопросов, ключи композитов и значения вариантов choice подчиняются одному правилу, потому что становятся JSON-ключами и значениями в ответе API:
- snake_case: начинаются со строчной буквы, далее строчные буквы, цифры или
_; - не более 48 символов (шаблон
^[a-z][a-z0-9_]{0,47}$); - уникальность: ключи вопросов и композитов — в пределах решения, ключи полей — в пределах state, значения вариантов — в пределах вопроса.
Схема state
State — это то, что ваше приложение отправляет в теле запроса как { "state": … }. Выберите один из трёх видов — те же три формы, которые Jev оценивает нативно:
| Вид | Что отправлять | Подходит для |
|---|---|---|
object | JSON-объект с типизированными полями | большинства решений: именованные поля чётко разделяют части входных данных |
text | непустую строку | одного сообщения, комментария или отрывка |
list | непустой массив строк или объектов | расшифровки чата, пакета записей |
Объектный state
{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }fields содержит до 50 определений полей:
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
key | string | — | JSON-ключ в state. |
type | string | — | Один из string, number, integer, boolean, array, object — или файл: image, audio, file (см. Входные данные). |
required | boolean | false | Отклонять state без этого поля. |
description | string | — | До 255 символов. Документирует поле в контракте API, который показывает редактор. |
Как state проверяется перед запуском движка:
- state должен быть JSON-объектом (не массивом, не строкой и не
null); - поле
requiredдолжно присутствовать и не бытьnull; необязательное поле может отсутствовать или бытьnull; - типы строгие:
number— любое конечное число,integer— целое число,object— ненулевой объект, не являющийся массивом;"500"— это неnumber;image,audioиfileпринимают URLdata:, URLhttps://или{ "data" | "url", "filename" }; - необъявленные поля принимаются и передаются движку, поэтому можно отправлять дополнительный контекст, не меняя схему;
- сообщается о первом поле с ошибкой, например
422 INVALID_STATEс"Field company_size must be a number.".
Описания полей — это документация
Движок получает ключи и значения вашего state, context решения и вопросы — но не описания полей. Давайте движку то, что ему нужно, через описательные имена полей, context и точные инструкции и ссылайтесь в инструкциях на поля по имени: "Does `message` ask for a demo?".
Текстовый state
{ "kind": "text" }State должен быть непустой строкой: { "state": "Congratulations! You won a $1000 gift card…" }. Движок получает саму строку.
State-список
{ "kind": "list", "items": "string" }State должен быть непустым массивом длиной до 500 элементов. items задаёт, чем является каждый элемент:
items | Каждый элемент должен быть | Пример state |
|---|---|---|
string (по умолчанию) | строкой | ["Hi!", "My card was charged twice.", "Can you refund one?"] |
object | JSON-объектом (не null и не массивом) | [{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }] |
Движок получает сам массив. Ошибки называют проблему: "Field state must be a non-empty array.", "Field state has too many items (612, max 500)." или "Item 2 of state must be an object.".
Список — это один state: на каждый вопрос отвечают про список целиком — «просит ли этот разговор о возврате?», — а не по разу на элемент. Чтобы классифицировать элементы независимо, отправляйте по одному решению на элемент или используйте объектный state вроде { "messages": [ … ] } с одним вопросом на позицию ("Is `messages[2]` a complaint?").
Ограничения размера
Сериализованный state должен укладываться в 128 KB и примерно в 32 000 токенов (оценка: символы ÷ 4) — не считая файлов, у которых свои ограничения (20 MB каждый; их текст обрезается до нужного размера — см. Входные данные).
У Jev также есть бюджет токенов на весь вызов: около 32 000 токенов на state плюс самый длинный вопрос и 64 000 токенов на state плюс все вопросы. Dcision проверяет оба до вызова движка; state сверх лимитов завершается ошибкой 422 INVALID_STATE с сообщением, указывающим, какой лимит превышен, — например "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." См. Ограничения.
Контекст
context — это произвольный текст до 8 000 символов, отправляемый с каждым state под зарезервированным ключом decision_context, — например "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." Описывайте бизнес, а не ожидаемый ответ.
Как его получает движок:
| Вид state | Что оценивает движок, когда задан context |
|---|---|
object | ваш объект плюс поле decision_context |
text, list | { "decision_context": "<context>", "input": <your state> } |
Без context движок получает ваш state без изменений.
decision_context зарезервирован: когда у решения есть context, он заменяет поле decision_context, которое ваше приложение отправляет в объектном state. Любое другое поле — включая поле с именем context — передаётся как есть.
Структурированные записи
Инструкции, описания вариантов choice, уровни score и критерии probability принимают не только текст, но и JSON-объекты или массивы — Jev нативно читает структуру. Используйте это, чтобы размечать части длинного вопроса, передавать вспомогательные данные или давать каждому варианту рубрику. См. Структурированные инструкции и критерии.
Валидация
Везде действуют одни и те же правила:
-
Редактор — валидирует по мере ввода, показывает каждую проблему со ссылкой К ошибке и автоматически сохраняет только корректные черновики.
-
API — сохранение или публикация некорректной схемы завершается ошибкой
422 INVALID_SCHEMA;detailsперечисляет каждую проблему с её путём:{ "error": { "code": "INVALID_SCHEMA", "message": "The decision schema is invalid.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w", "details": [ { "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }, { "path": "policies.1.field", "message": "Unknown question \"intent\"." }, { "path": "composites.0.terms.2.option", "message": "Pick the option whose probability counts." } ] } } -
CLI —
dcision validate decision.jsonпроверяет файл офлайн, аdcision check-stateпроверяет state по нему.
Правила валидации со временем могут становиться строже — например, начиная с v0.3 значения правил проверяются на соответствие вариантам, уровням и диапазонам, с которыми они сравниваются ("Use a number between 0 and 1 (e.g. 0.7, not 70)."). Более строгие правила применяются при сохранении или публикации; уже опубликованные версии продолжают работать без изменений, поэтому ужесточённое правило никогда не превращает работающий эндпоинт в ошибку.
Контракт API
Представление Контракт API в редакторе показывает, на что могут полагаться клиенты решения: state в виде JSON Schema, форму ответа на каждый вопрос и композиты.
{
"name": "lead-qualification",
"state": {
"type": "object",
"required": ["message"],
"properties": {
"message": { "type": "string", "description": "Inbound lead message" },
"company_size": { "type": "number", "description": "Employee count" },
"source": { "type": "string", "description": "website, referral, ads…" }
}
},
"questions": {
"purchase_intent": { "type": "probability", "range": [0, 1] },
"priority": { "type": "score", "scale": ["low", "medium", "high", "critical"] },
"route": { "type": "choice", "options": ["sales", "sdr", "nurture", "spam", "other"] }
},
"composites": {
"lead_score": { "type": "number" }
}
}Текстовый state отображается как { "type": "string" }, а state-список — как { "type": "array", "items": { "type": "string" } } (или "object"). Шкалы score перечисляют метки уровней, в том числе для структурированных уровней. composites появляется, только если у решения они есть.
Быстрый старт
Зарегистрируйтесь, создайте решение из шаблона, протестируйте его в Playground, опубликуйте и вызовите через cURL, JavaScript или Python — примерно за пять минут.
Входные данные — текст, JSON, изображения, аудио, документы
Что может читать решение — текст, структурированный JSON, изображения, голосовые сообщения и документы (PDF, Word, Excel, PowerPoint, CSV и другие) — и как каждый из них попадает в Jev, Laya или OpenAI Decisions.