API reference

Two endpoints, three question shapes

The service runs on your own host and decides locally. Below is the full request and response: every field, every question type, thresholds and error codes. Written from the service code rather than from intent.

Running it

The service is a single FastAPI application. Weights are read from a model directory given by an environment variable, falling back to the released weights next to the code.

pip install -r serve/requirements.txt
export RU_JEV_MODEL=/path/to/ru-jev
uvicorn serve.app:app --host 0.0.0.0 --port 8080

The device is chosen automatically: a GPU when one is present, otherwise the CPU. Temperature and context length are read from calibration.json in the model directory, so a request never has to set them.

Request

POST /v1/systemone

Field	What it means
`state`required	The text the decision is about. A string is taken as is. A list is joined with newlines, taking `text` from object items and `value` otherwise. Anything else is serialised to JSON.
`questions`required	An object whose key is your own question id and whose value describes the question. Ids come back unchanged in the response, which makes them convenient to dispatch on.
`model`optional	Model name, `ru-jev-latest` by default. The service echoes it back and switches nothing on it: the weights are fixed at startup.
`threshold`optional	Confidence threshold for the whole request, from 0 to 1. Answers below it are marked as withheld. Leave it out and nothing is withheld.

Question fields

Field	What it means
`type`required	One of `boolean`, `choice`, `score`. Anything else returns 400.
`criteria`	The options. The shape depends on the type and is described below. For `choice` and `score` it is required and cannot be empty.
`instructions`optional	A string placed before the text on its own line. Use it to say what is being judged when the same text is read from several angles.
`threshold`optional	Threshold for this question. Overrides the request-level one.

boolean question

Yes or no. criteria is optional: pass an object with true and false keys to name the two options in your own words. Without it the options are the Russian words for yes and no.

The wording of an option affects the result, because the model reads its text. Name options as ordinary words that describe the category.

"questions": {
  "tox": {
    "type": "boolean",
    "criteria": { "true": "токсичный", "false": "нормальный" }
  }
}

The response carries probability, the probability of the first option. Confidence is the distance from a half, that is the larger of p and 1 - p.

choice question

criteria is an object: the key comes back as the chosen option, the value is the text the model reads. Keys are for your code, values are for the model.

"questions": {
  "route": {
    "type": "choice",
    "criteria": {
      "billing": "оплата, счета и возвраты",
      "tech":    "техническая проблема",
      "sales":   "вопрос о покупке"
    }
  }
}

The response carries choice with the best key and probabilities over all keys. They sum to one: the model picks from what you gave it and cannot report that none of the options fit. When that outcome is possible, add an option for it.

score question

criteria is a list of levels in order, lowest first. The response carries score, the mean over the distribution and therefore a value between indices, and probabilities by level number.

"questions": {
  "ton": {
    "type": "score",
    "criteria": ["негативный", "нейтральный", "позитивный"]
  }
}

A score of 1.97 over three levels means the top level with little doubt. Confidence for the threshold is the probability of the single most likely level, not the nearness to the end of the scale.

Response

{
  "model": "ru-jev-latest",
  "answers": {
    "ton": {
      "type": "score",
      "score": 1.97,
      "probabilities": { "0": 0.008, "1": 0.009, "2": 0.982 }
    }
  },
  "usage": { "input_tokens": 14, "output_tokens": 0 },
  "providerMetadata": {
    "ru_jev": { "confidence": { "ton": 0.982 }, "review": [] }
  }
}

Field	What it means
`answers`	One answer per question, under the same id the request used.
`usage`	Token count of the input text. There are no output tokens: the model generates no text, so that figure is always zero.
`providerMetadata.ru_jev.confidence`	Confidence per question, from 0 to 1. This is the quantity the threshold is compared against.
`providerMetadata.ru_jev.review`	Ids whose answer the threshold withheld and which need a person. Empty when no threshold is set.

Threshold and abstain

A threshold is set for the whole request with threshold, or per question, and the question wins. Once a threshold is in play every answer carries abstain, and the ids of withheld answers are collected in review.

{
  "state": "Списали дважды за один заказ.",
  "threshold": 0.8,
  "questions": { "route": { "type": "choice", "criteria": { ... } } }
}

The higher the threshold, the less goes through without a person and the more accurate what does go through. That trade is measured and shown on the home page.

Health check

GET /health

Loads the model if it is not loaded yet and returns its parameters. Worth calling after startup so the first real request does not wait for the weights.

{
  "status": "ok",
  "model": "/opt/ru-jev",
  "device": "cpu",
  "max_len": 256,
  "temperature": 1.864
}

Errors

Code	What it means
`400`	The question type is not supported.
`400`	A `choice` question has no `criteria`, or an empty one.
`400`	A `score` question has `criteria` that is not a list, or is empty.
`422`	The body does not parse: `state` or `questions` missing, or wrong types.

The reason arrives in detail and names the question id.