Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.
docs: document System One API (#18702)
Parth Sareen1abe35e6e6e7
diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdxindex 0b42a6b30..2d7a73d4b 100644--- a/docs/api/introduction.mdx+++ b/docs/api/introduction.mdx@@ -22,7 +22,7 @@ The Anthropic client appends `/v1/messages` to its base URL.Cloud requests need an API key. Local requests do not. To use cloud models through your local server, [sign in to Ollama](/api/authentication#signing-in).-Creating or deleting models requires a local Ollama server. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility).+Creating or deleting models requires a local Ollama server. [System One](/capabilities/decision) also requires a local server and is not yet available on Ollama Cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility).## Ollama API examplediff --git a/docs/capabilities/decision.mdx b/docs/capabilities/decision.mdxnew file mode 100644index 000000000..5ba05daf2--- /dev/null+++ b/docs/capabilities/decision.mdx@@ -0,0 +1,113 @@+---+title: Decision+description: Classify text, estimate yes/no probabilities, and score ordered criteria.+---++<Note>+Currently available locally in Ollama.+</Note>++Use System One to classify text, answer yes/no questions, or score text against a rubric.++## Setup++Start [Ollama](/quickstart) v0.35.0 or later, then download [Nimble](https://ollama.com/library/nimble):++```shell setup.sh+ollama pull nimble+```++Local requests do not need an API key.++## Choose a label++Put your input in `state` and describe the possible answers in `criteria`:++```shell choice.sh+curl http://localhost:11434/v1/systemone \+ -H 'Content-Type: application/json' \+ -d '{+ "model": "nimble",+ "state": "Our checkout has returned 500 errors since 9am.",+ "questions": {+ "label": {+ "type": "choice",+ "instructions": "Which label fits this ticket?",+ "criteria": {+ "billing": "Payments and refunds",+ "bug": "Software errors",+ "account": "Login and account access"+ }+ }+ }+ }'+```++Example response:++```json+{+ "model": "nimble",+ "answers": {+ "label": {+ "type": "choice",+ "choice": "bug",+ "probabilities": {"billing": 0.0125, "bug": 0.9781, "account": 0.0093},+ "confidence": 0.8906+ }+ },+ "usage": {"input_tokens": 174, "output_tokens": 1}+}+```++## Question types++| Type | Criteria | Result |+| --- | --- | --- |+| `choice` | 2–26 named options with descriptions | The most likely option and each option's probability |+| `noul` | Descriptions for `"false"` and `"true"` | The probability of `true`, from 0 to 1 |+| `score` | 2–26 descriptions, ordered from lowest to highest | The probability-weighted average of the zero-based levels |++For the urgency criteria below:++```text+score = 0 × P(Routine) + 1 × P(Soon) + 2 × P(Immediate)+```++For `choice` and `score`, `confidence` measures how strongly the model favors one answer over the others, from 0 to 1. A higher value does not guarantee the answer is correct.++## Ask multiple questions++Combine question types in one request. Here, both questions use the same ticket:++```shell multiple.sh+curl http://localhost:11434/v1/systemone \+ -H 'Content-Type: application/json' \+ -d '{+ "model": "nimble",+ "state": {"ticket": "I was charged twice. Please refund the extra payment."},+ "questions": {+ "refund": {+ "type": "noul",+ "instructions": "Is the customer requesting a refund?",+ "criteria": {+ "false": "No refund is requested",+ "true": "The customer requests a refund"+ }+ },+ "urgency": {+ "type": "score",+ "instructions": "How urgently does this ticket need a response?",+ "criteria": [+ "Routine: no time pressure",+ "Soon: a customer is inconvenienced",+ "Immediate: a critical service is unavailable"+ ]+ }+ }+ }'+```++This returns a refund probability of `0.9989` and an urgency score of `0.8308` on the 0–2 scale (rounded). Results can vary with the model and configuration.++See the [API reference](/api/systemone) for request fields, limits, errors, and token usage.diff --git a/docs/docs.json b/docs/docs.jsonindex 1f7524517..44a655bcd 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -128,6 +128,7 @@"/capabilities/streaming","/capabilities/thinking","/capabilities/structured-outputs",+ "/capabilities/decision","/capabilities/vision","/capabilities/embeddings","/capabilities/tool-calling",@@ -249,6 +250,7 @@"POST /api/generate","POST /api/chat","POST /api/embed",+ "POST /v1/systemone","GET /api/tags","GET /api/ps","POST /api/show",diff --git a/docs/openapi.yaml b/docs/openapi.yamlindex e79419e1f..655d1ec5b 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -828,6 +828,189 @@ components:items:$ref: "#/components/schemas/TokenLogprob"description: Most likely tokens and their log probabilities at this position+ SystemOneContent:+ description: A nonempty string, or an object or array serialized as JSON text. Not interpreted as chat messages or multimodal input.+ oneOf:+ - type: string+ pattern: '\S'+ - type: object+ additionalProperties: true+ - type: array+ items: {}+ SystemOneChoiceQuestion:+ title: Choice+ type: object+ required: [type, instructions, criteria]+ properties:+ type:+ type: string+ enum: [choice]+ instructions:+ $ref: "#/components/schemas/SystemOneContent"+ criteria:+ type: object+ description: Option keys mapped to descriptions. A null description uses the key itself. Keys must not be blank; ties select the first option in request order.+ minProperties: 2+ maxProperties: 26+ propertyNames:+ pattern: '\S'+ additionalProperties:+ type: [string, "null"]+ SystemOneNoulQuestion:+ title: Noul+ type: object+ required: [type, instructions]+ properties:+ type:+ type: string+ enum: [noul]+ instructions:+ $ref: "#/components/schemas/SystemOneContent"+ criteria:+ type: object+ description: Optional descriptions for the two outcomes. Omitted entries use No and Yes.+ properties:+ "false":+ type: string+ default: "No"+ "true":+ type: string+ default: "Yes"+ additionalProperties: false+ SystemOneScoreQuestion:+ title: Score+ type: object+ required: [type, instructions, criteria]+ properties:+ type:+ type: string+ enum: [score]+ instructions:+ $ref: "#/components/schemas/SystemOneContent"+ criteria:+ type: array+ description: Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1.+ minItems: 2+ maxItems: 26+ items:+ type: string+ SystemOneRequest:+ type: object+ required: [model, state, questions]+ properties:+ model:+ type: string+ pattern: '\S'+ description: Local model trained for System One, such as nimble. Requires compatible GGUF weights and a scoring-capable runner; cloud and MLX/Safetensors models are not supported.+ state:+ $ref: "#/components/schemas/SystemOneContent"+ questions:+ type: object+ description: Named questions about the shared state. Each is scored separately against the full state and question schema; answers are not passed to later questions.+ minProperties: 1+ maxProperties: 64+ propertyNames:+ pattern: '\S'+ additionalProperties:+ oneOf:+ - $ref: "#/components/schemas/SystemOneChoiceQuestion"+ - $ref: "#/components/schemas/SystemOneNoulQuestion"+ - $ref: "#/components/schemas/SystemOneScoreQuestion"+ keep_alive:+ oneOf:+ - type: string+ - type: number+ description: How long to keep the model loaded after the request, as a duration string (such as 5m) or seconds. Zero unloads after the request; a negative value keeps it loaded. Defaults to the server's keep-alive setting (5m unless configured otherwise).+ SystemOneProbabilities:+ type: object+ description: Probabilities normalized over the supplied candidates, summing to 1 subject to floating-point precision.+ additionalProperties:+ type: number+ minimum: 0+ maximum: 1+ SystemOneConfidence:+ type: number+ minimum: 0+ maximum: 1+ description: Distribution concentration, calculated as 1 - H(p) / ln(N), where H(p) is entropy and N is the candidate count. Zero means uniform probabilities; values near 1 mean one candidate dominates. Not calibrated correctness.+ SystemOneChoiceAnswer:+ title: Choice+ type: object+ required: [type, choice, probabilities, confidence]+ properties:+ type:+ type: string+ enum: [choice]+ choice:+ type: string+ description: Option key with the highest probability. Ties select the first option in request order.+ probabilities:+ $ref: "#/components/schemas/SystemOneProbabilities"+ confidence:+ $ref: "#/components/schemas/SystemOneConfidence"+ SystemOneNoulAnswer:+ title: Noul+ type: object+ required: [type, noul]+ properties:+ type:+ type: string+ enum: [noul]+ noul:+ type: number+ minimum: 0+ maximum: 1+ description: Probability of true among the false and true candidates. This is a number, not a Boolean.+ SystemOneScoreAnswer:+ title: Score+ type: object+ required: [type, score, legend, probabilities, confidence]+ properties:+ type:+ type: string+ enum: [score]+ score:+ type: number+ minimum: 0+ maximum: 25+ description: Probability-weighted average of the zero-based criterion indices, from 0 to the number of criteria minus 1. Not rounded to a level or normalized to 0–1.+ legend:+ type: object+ description: Zero-based indices as string keys mapped to the criterion descriptions.+ additionalProperties:+ type: string+ probabilities:+ $ref: "#/components/schemas/SystemOneProbabilities"+ description: Probabilities keyed by zero-based criterion indices as strings.+ confidence:+ $ref: "#/components/schemas/SystemOneConfidence"+ SystemOneResponse:+ type: object+ required: [model, answers, usage]+ properties:+ model:+ type: string+ description: Model name from the request.+ answers:+ type: object+ description: Answers keyed by the question names in the request.+ additionalProperties:+ oneOf:+ - $ref: "#/components/schemas/SystemOneChoiceAnswer"+ - $ref: "#/components/schemas/SystemOneNoulAnswer"+ - $ref: "#/components/schemas/SystemOneScoreAnswer"+ usage:+ type: object+ required: [input_tokens, output_tokens]+ properties:+ input_tokens:+ type: integer+ minimum: 0+ description: Sum of full rendered prompt lengths across all questions, including repeated shared context even when cached.+ output_tokens:+ type: integer+ minimum: 0+ description: Tokens generated internally for scoring, including prefix preparation and retries. May exceed the question count; not the length of the JSON response.ErrorResponse:type: objectproperties:@@ -835,6 +1018,109 @@ components:type: stringdescription: Error message describing what went wrongpaths:+ /v1/systemone:+ post:+ summary: Answer typed questions+ description: |+ Answer choice, yes/no, and scoring questions with a local System One model. Requires Ollama v0.35.0 or later. See the [decision guide](/capabilities/decision) for examples.+ operationId: systemone+ x-mint:+ href: /api/systemone+ metadata:+ title: System One+ sidebarTitle: System One+ content: |+ <Note>+ Currently available locally in Ollama.+ </Note>++ - Returns one JSON response; streaming, images, tools, and generation controls are not supported.+ - Requests must fit within 64 KiB. Each rendered prompt must fit the loaded context window with two token positions left for scoring. Input is never truncated.+ x-codeSamples:+ - lang: bash+ label: Choose a label+ source: |+ curl http://localhost:11434/v1/systemone \+ -H 'Content-Type: application/json' \+ -d '{+ "model": "nimble",+ "state": "Our checkout has returned 500 errors since 9am.",+ "questions": {+ "label": {+ "type": "choice",+ "instructions": "Which label fits this ticket?",+ "criteria": {+ "billing": "Payments and refunds",+ "bug": "Software errors",+ "account": "Login and account access"+ }+ }+ }+ }'+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SystemOneRequest"+ example:+ model: nimble+ state: Our checkout has returned 500 errors since 9am.+ questions:+ label:+ type: choice+ instructions: Which label fits this ticket?+ criteria:+ billing: Payments and refunds+ bug: Software errors+ account: Login and account access+ responses:+ "200":+ description: Answers and token usage for all questions. Example probabilities and confidence are rounded to four decimal places; results and usage can vary with the model and server configuration.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/SystemOneResponse"+ example:+ model: nimble+ answers:+ label:+ type: choice+ choice: bug+ probabilities:+ billing: 0.0125+ bug: 0.9781+ account: 0.0093+ confidence: 0.8906+ usage:+ input_tokens: 174+ output_tokens: 1+ "400":+ description: Invalid request, unsupported model or runner, or a rendered prompt that exceeds the loaded context. Cloud models are rejected.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ErrorResponse"+ "404":+ description: Local model not found. Download the model before making a request.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ErrorResponse"+ "413":+ description: Request body exceeds 64 KiB.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ErrorResponse"+ example:+ error: request body must not exceed 64 KiB+ "500":+ description: Model loading, rendering, or scoring failed.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ErrorResponse"/api/generate:post:summary: Generate a response