# Jev Structured Decision

> Common

Submit one Jev structured-decision request. `model` is the platform model name
(e.g. `jev-1.13.0`) used for routing. `state` is the content to analyze; `questions` is the set of
questions. Each question returns a structured answer keyed by `type`, in a single
non-streaming response.

## Endpoint

`POST https://api.modelverse.cn/v1/systemone`

## Request Body

## Responses

- **200** — Jev native structured decision result (with an injected `u_trace_id` for platform-side lookup).
- **default** — Error response (gateway-side param/auth error or upstream non-200).

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse Jev Structured Decision API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse **TypeSafe Jev (System One structured\ndecision model)**. Unified endpoint `POST /v1/systemone`; the `model` field in the body selects\nthe provider. All other fields\nare Jev's native parameters, forwarded and returned as-is without normalization. The response is\nnon-streaming JSON.\n\nJev is not a chat model: you give it a `state` (the text/structured data to analyze) and a set of\n`questions` (each declaring `type`/`instructions`/`criteria`), and it returns a type-safe\nstructured answer per question (`noul` probability, `choice` selection, `score` level) — no free text.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "System One",
      "description": "TypeSafe Jev structured decisions."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/systemone": {
      "post": {
        "tags": [
          "System One"
        ],
        "operationId": "createSystemOneDecision",
        "summary": "Jev Structured Decision",
        "description": "Submit one Jev structured-decision request. `model` is the platform model name\n(e.g. `jev-1.13.0`) used for routing. `state` is the content to analyze; `questions` is the set of\nquestions. Each question returns a structured answer keyed by `type`, in a single\nnon-streaming response.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemOneRequest"
              },
              "examples": {
                "customerTicket": {
                  "summary": "Three judgments over one support ticket",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "I was charged twice for my annual plan this morning. Please refund one of the charges today.",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "Is the customer asking for money back?"
                      },
                      "queue": {
                        "type": "choice",
                        "instructions": "Which queue should handle this?",
                        "criteria": {
                          "billing": "Billing department",
                          "technical": "Technical support",
                          "sales": "Sales team"
                        }
                      },
                      "urgency": {
                        "type": "score",
                        "instructions": "How urgent is this issue?",
                        "criteria": [
                          "Can wait a week",
                          "Should be handled this week",
                          "Needs a reply today"
                        ]
                      }
                    }
                  }
                },
                "noulOnly": {
                  "summary": "A single noul judgment (whether a refund is requested)",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "I was charged twice for my annual plan this morning. Please refund one of the charges today.",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "Is the customer asking for money back?"
                      }
                    }
                  }
                },
                "choiceOnly": {
                  "summary": "A single choice judgment (which queue to route to)",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "I was charged twice for my annual plan this morning. Please refund one of the charges today.",
                    "questions": {
                      "queue": {
                        "type": "choice",
                        "instructions": "Which queue should handle this?",
                        "criteria": {
                          "billing": "Billing department",
                          "technical": "Technical support",
                          "sales": "Sales team"
                        }
                      }
                    }
                  }
                },
                "scoreOnly": {
                  "summary": "A single score judgment (how urgent the issue is)",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "I was charged twice for my annual plan this morning. Please refund one of the charges today.",
                    "questions": {
                      "urgency": {
                        "type": "score",
                        "instructions": "How urgent is this issue?",
                        "criteria": [
                          "Can wait a week",
                          "Should be handled this week",
                          "Needs a reply today"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Jev native structured decision result (with an injected `u_trace_id` for platform-side lookup).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneResponse"
                },
                "examples": {
                  "decision": {
                    "summary": "Structured answers for three questions plus usage",
                    "value": {
                      "id": "gen-dec-1789895482-0mFbIsogyPVPcm4CVgIe",
                      "model": "typesafe/jev-1.13-20260917",
                      "provider": "TypeSafe",
                      "answers": {
                        "wants_refund": {
                          "type": "noul",
                          "noul": 0.99
                        },
                        "queue": {
                          "type": "choice",
                          "choice": "billing",
                          "confidence": 1,
                          "probabilities": {
                            "sales": 0,
                            "billing": 1,
                            "technical": 0
                          }
                        },
                        "urgency": {
                          "type": "score",
                          "score": 2,
                          "confidence": 1,
                          "legend": {
                            "0": "Can wait a week",
                            "1": "Should be handled this week",
                            "2": "Needs a reply today"
                          },
                          "probabilities": {
                            "0": 0,
                            "1": 0,
                            "2": 1
                          }
                        }
                      },
                      "usage": {
                        "input_tokens": 388,
                        "output_tokens": 59,
                        "cost": 0.000016296
                      },
                      "u_trace_id": "3f6a1c9e-...-platform-trace"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response (gateway-side param/auth error or upstream non-200).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/SystemOneError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Platform-issued API key, passed via `Authorization: Bearer <API Key>`."
      }
    },
    "schemas": {
      "SystemOneRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "state",
          "questions"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Platform model name (e.g. `jev-1.13.0`) used for routing.",
            "examples": [
              "jev-1.13.0"
            ]
          },
          "state": {
            "description": "Content to analyze; a string, JSON object, or array.",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              },
              {
                "type": "array",
                "items": {},
                "title": "array"
              }
            ]
          },
          "questions": {
            "type": "object",
            "description": "Set of questions; key is the question ID, value is the question object.",
            "additionalProperties": {
              "$ref": "#/components/schemas/Question"
            }
          }
        }
      },
      "Question": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "instructions"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "noul",
              "choice",
              "score"
            ],
            "description": "Question type:\n- `noul`: returns a 0–1 probability; `criteria` optional (`{true, false}` descriptions).\n- `choice`: pick one of several options; `criteria` required, an option-name→description map (up to 255 options).\n- `score`: graded scoring; `criteria` required, an ordered array of level descriptions (low to high).\n"
          },
          "instructions": {
            "type": "string",
            "description": "What this question should evaluate."
          },
          "criteria": {
            "description": "Judging criteria, shaped by `type`: `choice` is an object (option name→description), `score` is a\nstring array (ordered levels), `noul` may be an object (`true`/`false` semantics) or omitted.\n",
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "title": "object"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "title": "array"
              }
            ]
          }
        }
      },
      "SystemOneResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "description": "Upstream decision ID (`gen-dec-` prefix), usable for lookup."
          },
          "model": {
            "type": "string",
            "description": "The exact upstream model version that answered."
          },
          "provider": {
            "type": "string",
            "description": "Upstream provider, fixed to `TypeSafe`."
          },
          "answers": {
            "type": "object",
            "description": "Structured answer per question, keyed the same as the request `questions`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/Answer"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "u_trace_id": {
            "type": "string",
            "description": "Platform-injected trace ID, present only in the response returned to the client, for platform-side trace lookup."
          }
        }
      },
      "Answer": {
        "description": "Structured answer; fields depend on `type` (`noul` / `choice` / `score`).",
        "oneOf": [
          {
            "$ref": "#/components/schemas/NoulAnswer"
          },
          {
            "$ref": "#/components/schemas/ChoiceAnswer"
          },
          {
            "$ref": "#/components/schemas/ScoreAnswer"
          }
        ]
      },
      "NoulAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "noul"
          },
          "noul": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "A 0–1 probability signal (no separate confidence field; the probability is the signal)."
          }
        }
      },
      "ChoiceAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "choice"
          },
          "choice": {
            "type": "string",
            "description": "The selected option name (a key from the request `criteria`)."
          },
          "confidence": {
            "type": "number",
            "description": "Confidence."
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Probability distribution across options."
          }
        }
      },
      "ScoreAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "score"
          },
          "score": {
            "type": "integer",
            "description": "The selected level index (0-based, matching the request `criteria` array)."
          },
          "confidence": {
            "type": "number",
            "description": "Confidence."
          },
          "legend": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Map of level index → level description."
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Probability distribution across levels."
          }
        }
      },
      "Usage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "Input token count."
          },
          "output_tokens": {
            "type": "integer",
            "description": "Output token count."
          },
          "cost": {
            "type": "number",
            "description": "Upstream-side cost (informational only; platform billing uses its own price table)."
          }
        }
      },
      "SystemOneErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/SystemOneError"
          }
        }
      },
      "SystemOneError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error description."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "Request ID, for feedback or troubleshooting."
          }
        }
      }
    },
    "examples": {
      "SystemOneError": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "Error description",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<request ID, for feedback or troubleshooting>"
          }
        }
      }
    }
  }
}
```