# Laya Structured Decision

> Common

Submit one Laya structured-decision request. `model` is the platform model name (`laya`, or
a specific checkpoint — `laya-english` / `laya-multilingual` / `laya-typed-decisions`) 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** — Laya structured decision result (`x_`-prefixed fields are extensions).
- **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 Laya Structured Decision API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse **Laya (System One structured decision\nmodel)**. Unified endpoint `POST /v1/systemone`; the `model` field in the body selects the\nprovider (`laya` or a specific `laya-*` checkpoint). Request fields match the Jev protocol;\nthe response follows the System One protocol, with Laya extensions carried under `x_`-prefixed\nfields. The response is non-streaming JSON.\n\nLaya is not a chat model: you give it a `state` (the text/structured data to analyze) and a set\nof `questions` (each declaring `type`/`instructions`/`criteria`), and in a single forward pass it\nreturns a type-safe structured answer per question (`noul` probability, `choice` selection,\n`score` level) — no free text.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "System One",
      "description": "Laya structured decisions."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/systemone": {
      "post": {
        "tags": [
          "System One"
        ],
        "operationId": "createLayaSystemOneDecision",
        "summary": "Laya Structured Decision",
        "description": "Submit one Laya structured-decision request. `model` is the platform model name (`laya`, or\na specific checkpoint — `laya-english` / `laya-multilingual` / `laya-typed-decisions`) used\nfor routing. `state` is the content to analyze; `questions` is the set of questions. Each\nquestion returns a structured answer keyed by `type`, in a single non-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 (auto-routed to the multilingual checkpoint)",
                  "value": {
                    "model": "laya",
                    "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": "laya",
                    "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": "laya",
                    "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": "laya",
                    "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"
                        ]
                      }
                    }
                  }
                },
                "structuredStateEnglish": {
                  "summary": "state as a JSON object, an explicit English checkpoint, and a noul with true/false semantics",
                  "value": {
                    "model": "laya-english",
                    "state": {
                      "subject": "Server down",
                      "body": "prod API returns 500 since 9am"
                    },
                    "questions": {
                      "is_outage": {
                        "type": "noul",
                        "instructions": "Is this an outage?",
                        "criteria": {
                          "true": "service unavailable",
                          "false": "not an availability issue"
                        }
                      },
                      "severity": {
                        "type": "score",
                        "instructions": "How severe is this?",
                        "criteria": [
                          "low",
                          "medium",
                          "high"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Laya structured decision result (`x_`-prefixed fields are extensions).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneResponse"
                },
                "examples": {
                  "decision": {
                    "summary": "Structured answers for three questions plus usage (real response)",
                    "value": {
                      "id": "gen-dec-1789972637-oljFHZz1M-dMxKNtCqDb",
                      "model": "laya-multilingual",
                      "provider": "Laya",
                      "answers": {
                        "wants_refund": {
                          "type": "noul",
                          "noul": 0.9943,
                          "x_confidence": 0.9943,
                          "x_act_probability": 1
                        },
                        "queue": {
                          "type": "choice",
                          "choice": "billing",
                          "confidence": 0.9782,
                          "probabilities": {
                            "billing": 0.9965,
                            "technical": 0.0002,
                            "sales": 0.0033
                          },
                          "x_act_probability": 1
                        },
                        "urgency": {
                          "type": "score",
                          "score": 2,
                          "confidence": 0.5997,
                          "legend": {
                            "0": "Can wait a week",
                            "1": "Should be handled this week",
                            "2": "Needs a reply today"
                          },
                          "probabilities": {
                            "0": 0.0166,
                            "1": 0.1152,
                            "2": 0.8682
                          },
                          "x_expected_score": 1.8516,
                          "x_argmax_score": 2,
                          "x_act_probability": 1
                        }
                      },
                      "usage": {
                        "input_tokens": 171,
                        "output_tokens": 0,
                        "cost": 0
                      },
                      "u_trace_id": "41c727bf-0f68-438b-b9e9-c60236b54291",
                      "x_routing": {
                        "requested_model": "laya",
                        "checkpoint": "multilingual",
                        "reason": "non-Latin script (han, 100% of letters); the English checkpoint cannot read it",
                        "workflow": null
                      },
                      "x_latency_ms": 230,
                      "x_request_id": "req-b8689788276345ca"
                    }
                  }
                }
              }
            }
          },
          "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"
                  },
                  "modelNotFound": {
                    "$ref": "#/components/examples/ModelNotFound"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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",
            "enum": [
              "laya",
              "laya-english",
              "laya-multilingual",
              "laya-typed-decisions"
            ],
            "description": "Platform model name used for routing. `laya` auto-selects a checkpoint based on the\nlanguage/script of `state` (recommended); `laya-english` is English-only (512-token\ncontext); `laya-multilingual` covers 100+ languages including Chinese (1024 tokens);\n`laya-typed-decisions` runs a typed-decisions workflow (1024 tokens). Case-insensitive.\n",
            "examples": [
              "laya"
            ]
          },
          "state": {
            "description": "Content to analyze; a string, JSON object, or array. Objects/arrays are serialized to JSON text before being fed to the model; content beyond the context length is truncated from the right.",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              },
              {
                "type": "array",
                "items": {},
                "title": "array"
              }
            ]
          },
          "questions": {
            "type": "object",
            "minProperties": 1,
            "description": "Set of questions; key is the question ID, value is the question object. All questions are answered in parallel in a single forward pass — batch them into one request when possible.",
            "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}` semantic descriptions).\n- `choice`: pick one of several options; `criteria` required, an option-name→description map.\n  The protocol allows up to 255 options; Laya is limited by a 192-token option budget, so in\n  practice ~20–60 options, beyond which it returns `criteria_too_long`.\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 (only the `true`/`false` keys are allowed)\nor omitted. Non-string description values are serialized to JSON.\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": "Decision ID (`gen-dec-` prefix)."
          },
          "model": {
            "type": "string",
            "enum": [
              "laya-english",
              "laya-multilingual",
              "laya-typed-decisions"
            ],
            "description": "The checkpoint that actually answered."
          },
          "provider": {
            "type": "string",
            "const": "Laya",
            "description": "Upstream provider, fixed to `Laya`."
          },
          "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, for platform-side trace lookup."
          },
          "x_routing": {
            "$ref": "#/components/schemas/Routing"
          },
          "x_latency_ms": {
            "type": "integer",
            "description": "Extension: model inference latency in milliseconds."
          },
          "x_request_id": {
            "type": "string",
            "description": "Extension: server-side request ID, shared with the error response's `error.param`."
          }
        }
      },
      "Routing": {
        "type": "object",
        "description": "Extension: automatic routing decision.",
        "properties": {
          "requested_model": {
            "type": "string",
            "description": "The `model` value from the request."
          },
          "checkpoint": {
            "type": "string",
            "enum": [
              "english",
              "multilingual",
              "typed-decisions"
            ],
            "description": "The checkpoint actually selected."
          },
          "reason": {
            "type": "string",
            "description": "Routing reason, e.g. `non-Latin script (han, 100% of letters); the English checkpoint cannot read it`, `English Latin text`, `explicit model='multilingual'`."
          },
          "workflow": {
            "type": [
              "string",
              "null"
            ],
            "description": "The matched typed-decisions workflow name, or null if none matched."
          }
        }
      },
      "Answer": {
        "description": "Structured answer; fields depend on `type` (`noul` / `choice` / `score`). `x_`-prefixed fields are extensions.",
        "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)."
          },
          "x_confidence": {
            "type": "number",
            "description": "Extension: `max(noul, 1 - noul)`."
          },
          "x_act_probability": {
            "type": "number",
            "description": "Extension: the model's act-head output, currently always 1.0 — safe to ignore."
          }
        }
      },
      "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`, the highest-probability option)."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence: normalized entropy `1 - H(p)/log(k)` — 1 when the distribution is fully concentrated, 0 when uniform."
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Probability distribution across options (softmax, 4 decimal places)."
          },
          "x_act_probability": {
            "type": "number",
            "description": "Extension: currently always 1.0 — safe to ignore."
          }
        }
      },
      "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; the highest-probability level)."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence: normalized entropy `1 - H(p)/log(k)`."
          },
          "legend": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Map of level index → level description."
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Probability distribution across levels."
          },
          "x_expected_score": {
            "type": "number",
            "description": "Extension: expected level value `Σ i·p(i)`, a Laya-native output useful when a continuous score is needed."
          },
          "x_argmax_score": {
            "type": "integer",
            "description": "Extension: same value as `score`."
          },
          "x_act_probability": {
            "type": "number",
            "description": "Extension: currently always 1.0 — safe to ignore."
          }
        }
      },
      "Usage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "Input token count. Each question is a separate sequence, so `state` is counted once per question."
          },
          "output_tokens": {
            "type": "integer",
            "description": "Output token count, always 0 (not a generative model)."
          },
          "cost": {
            "type": "number",
            "description": "Upstream-side cost, always 0 (self-hosted); 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",
            "enum": [
              "invalid_request_error",
              "authentication_error",
              "server_error"
            ],
            "description": "Error type."
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_json",
              "missing_model",
              "model_not_found",
              "missing_state",
              "invalid_state",
              "invalid_questions",
              "invalid_question",
              "invalid_question_type",
              "missing_instructions",
              "invalid_criteria",
              "too_many_options",
              "criteria_too_long",
              "invalid_api_key",
              "model_loading",
              "gpu_oom",
              "internal_error"
            ],
            "description": "Machine-readable error code."
          },
          "param": {
            "type": "string",
            "description": "Request ID, for feedback or troubleshooting."
          }
        }
      }
    },
    "examples": {
      "SystemOneError": {
        "summary": "Standard JSON error response",
        "value": {
          "error": {
            "message": "question 'queue': choice `criteria` must be a non-empty object {option: description}",
            "type": "invalid_request_error",
            "code": "invalid_criteria",
            "param": "req-fac9605f69d745ce"
          }
        }
      },
      "ModelNotFound": {
        "summary": "model is not one of the laya family",
        "value": {
          "error": {
            "message": "unknown model 'jev-1.13.0'; supported: laya, laya-english, laya-multilingual, laya-typed-decisions",
            "type": "invalid_request_error",
            "code": "model_not_found",
            "param": "req-dd569f9b15c948ef"
          }
        }
      }
    }
  }
}
```