Схема решения

JSON-документ, стоящий за каждым решением, — принимаемое состояние, вопросы, на которые оно отвечает, композиты, политики, выбирающие действие, настройки выполнения и назначения.

Решение определяется одним JSON-документом — схемой решения. Редактор и визуальный конструктор редактируют её за вас (правая панель показывает её в разделе Схема решения), CLI создаёт заготовку и валидирует её офлайн, а каждая опубликованная версия хранит её полный снимок.

Схема не зависит от движка: в ней нет ничего специфичного для Jev или любого другого движка.

Полный пример

Это шаблон Квалификация лидов в том виде, в каком он хранится, со всеми заполненными значениями по умолчанию:

decision.json
{
  "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"
  }
}

Поля верхнего уровня

ПолеТипОбязательноОписание
stateSchemaobjectДаВходные данные, которые принимает решение, — см. Схема state.
questionsarrayДаОт 1 до 64 вопросов — см. Вопросы.
compositesarrayНетДо 20 взвешенных комбинаций ответов. По умолчанию [] — см. Композиты.
policiesarrayНетДо 50 правил, оцениваемых по порядку. По умолчанию [] — см. Политики и действия.
contextstringНетДо 8 000 символов бизнес-контекста, отправляемого с каждым state, — см. Контекст.
settingsobjectНетДвижок, хранение, бюджет времени, fallback-действие и поведение при ошибке движка — см. Настройки решения.
destinationsarrayНетДо 20 назначений — что происходит после решения, для каждого варианта, уровня, порога или итогового действия. По умолчанию [] — см. Назначения.

Ключи

Поля state, ключи вопросов, ключи композитов и значения вариантов choice подчиняются одному правилу, потому что становятся JSON-ключами и значениями в ответе API:

  • snake_case: начинаются со строчной буквы, далее строчные буквы, цифры или _;
  • не более 48 символов (шаблон ^[a-z][a-z0-9_]{0,47}$);
  • уникальность: ключи вопросов и композитов — в пределах решения, ключи полей — в пределах state, значения вариантов — в пределах вопроса.

Схема state

State — это то, что ваше приложение отправляет в теле запроса как { "state": … }. Выберите один из трёх видов — те же три формы, которые Jev оценивает нативно:

ВидЧто отправлятьПодходит для
objectJSON-объект с типизированными полямибольшинства решений: именованные поля чётко разделяют части входных данных
textнепустую строкуодного сообщения, комментария или отрывка
listнепустой массив строк или объектоврасшифровки чата, пакета записей

Объектный state

{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }

fields содержит до 50 определений полей:

СвойствоТипПо умолчаниюОписание
keystring—JSON-ключ в state.
typestring—Один из string, number, integer, boolean, array, object — или файл: image, audio, file (см. Входные данные).
requiredbooleanfalseОтклонять state без этого поля.
descriptionstring—До 255 символов. Документирует поле в контракте API, который показывает редактор.

Как state проверяется перед запуском движка:

  • state должен быть JSON-объектом (не массивом, не строкой и не null);
  • поле required должно присутствовать и не быть null; необязательное поле может отсутствовать или быть null;
  • типы строгие: number — любое конечное число, integer — целое число, object — ненулевой объект, не являющийся массивом; "500" — это не number; image, audio и file принимают URL data:, URL https:// или { "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?"]
objectJSON-объектом (не 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 появляется, только если у решения они есть.

На этой странице