Thinking budget schema — Kiln Documentation

Canonical fragments for thinking-budget request overrides, server defaults, effective resolution, terminal outcomes, complete records, and partial recent-request records. The token and decode-time dimensions resolve independently.

Schema identity

Property	Value
Title	Kiln thinking-budget contract v1
`$id`	`https://ericflo.github.io/kiln/contracts/thinking-budget-v1.schema.json`
Dialect	`https://json-schema.org/draft/2020-12/schema`
Root type	`any`
Root object	open or unspecified

Root fields

This schema node has no named object fields.

Definitions

limitOverrideOne present request override. Property absence means inherit; null means explicitly unlimited; a non-negative integer is a finite limit, including zero.0 fields

Type: null | integer.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": "null",
      "description": "Explicitly remove the inherited finite limit for this dimension."
    },
    {
      "type": "integer",
      "minimum": 0,
      "description": "Finite limit. Zero starts reasoning-block closure at the first decode candidate."
    }
  ]
}

sourceClosed provenance vocabulary for one independently resolved token or time dimension. An `_unlimited` suffix means that surface explicitly removed an inherited limit.0 fields

Type: string. Constraints: enum "unlimited", "server_default", "request", "request_unlimited", "suite", "suite_unlimited", "run_override", "run_override_unlimited", "example", "example_unlimited", "unknown".

triggerBoundary that made Kiln force the reasoning close sequence: the thinking-token limit, decode-time limit, or remaining completion-token capacity.0 fields

Type: string. Constraints: enum "tokens", "time", "max_tokens".

requestThinking-budget properties embedded in a chat or batch request. Other request properties are permitted because this definition describes only the budget fragment.2 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`thinking_budget_tokens`	no	`limitOverride`	-	Maximum generated thinking tokens before Kiln closes an open reasoning block. Omit to inherit the server token default.
`thinking_budget_ms`	no	`limitOverride`	-	Maximum decode time in milliseconds, starting at the first decode candidate and excluding queue and prefill. Omit to inherit the server time default.

serverDefaultsResolved server-wide defaults. Null means the dimension is unlimited; a non-negative integer is finite, including zero.2 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`default_thinking_budget_tokens`	yes	`null \| integer`	-	Default thinking-token limit inherited by requests that omit `thinking_budget_tokens`.
`default_thinking_budget_ms`	yes	`null \| integer`	-	Default decode-time limit inherited by requests that omit `thinking_budget_ms`.

effectiveIndependently resolved token and time dimensions before runtime applicability or outcome is known. `configured` is true exactly when at least one finite maximum is present.5 fields

Type: object.

Field	Required	Type	Constraints and default	Description
`configured`	yes	`boolean`	-	Whether at least one of `max_tokens` or `max_time_ms` is finite.
`max_tokens`	no	`integer`	minimum 0	Effective finite thinking-token limit. Absence means this dimension is unlimited.
`max_time_ms`	no	`integer`	minimum 0	Effective finite decode-time limit in milliseconds. Absence means this dimension is unlimited.
`tokens_source`	yes	`source`	-	Surface that supplied the finite token limit or explicit/inherited unlimited state.
`time_source`	yes	`source`	-	Surface that supplied the finite time limit or explicit/inherited unlimited state.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "if": {
        "properties": {
          "configured": {
            "const": true
          }
        },
        "required": [
          "configured"
        ]
      },
      "then": {
        "anyOf": [
          {
            "required": [
              "max_tokens"
            ]
          },
          {
            "required": [
              "max_time_ms"
            ]
          }
        ]
      },
      "else": {
        "not": {
          "anyOf": [
            {
              "required": [
                "max_tokens"
              ]
            },
            {
              "required": [
                "max_time_ms"
              ]
            }
          ]
        }
      }
    },
    {
      "if": {
        "required": [
          "max_tokens"
        ]
      },
      "then": {
        "properties": {
          "tokens_source": {
            "enum": [
              "server_default",
              "request",
              "suite",
              "run_override",
              "example",
              "unknown"
            ]
          }
        }
      },
      "else": {
        "properties": {
          "tokens_source": {
            "enum": [
              "unlimited",
              "request_unlimited",
              "suite_unlimited",
              "run_override_unlimited",
              "example_unlimited",
              "unknown"
            ]
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "max_time_ms"
        ]
      },
      "then": {
        "properties": {
          "time_source": {
            "enum": [
              "server_default",
              "request",
              "suite",
              "run_override",
              "example",
              "unknown"
            ]
          }
        }
      },
      "else": {
        "properties": {
          "time_source": {
            "enum": [
              "unlimited",
              "request_unlimited",
              "suite_unlimited",
              "run_override_unlimited",
              "example_unlimited",
              "unknown"
            ]
          }
        }
      }
    }
  ]
}

outcomeCompletion-specific terminal state after the budget controller ran. Natural closure has `triggered=false` and no `trigger`.5 fields

Type: object. Constraints: closed object.

Field	Required	Type	Constraints and default	Description
`triggered`	yes	`boolean`	-	Whether Kiln forced the close sequence because a finite or completion-capacity boundary was reached.
`trigger`	no	`trigger`	-	Boundary that forced closure. Present exactly when `triggered` is true.
`closed`	yes	`boolean`	-	Whether the tokenizer's complete reasoning close sequence entered model history.
`thinking_tokens`	yes	`integer`	minimum 0	Thinking tokens produced before closure or before the request ended.
`thinking_time_ms`	yes	`integer`	minimum 0	Decode time from the first candidate to closure or request end, in milliseconds.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "if": {
        "properties": {
          "triggered": {
            "const": true
          }
        }
      },
      "then": {
        "required": [
          "trigger"
        ]
      },
      "else": {
        "not": {
          "required": [
            "trigger"
          ]
        }
      }
    }
  ]
}

recordComplete effective configuration, applicability, and optional flat terminal outcome written by current chat, streaming, batch, and eval surfaces.0 fields

Type: effective & object & any & any.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "$ref": "#/$defs/effective"
    },
    {
      "type": "object",
      "required": [
        "applied",
        "triggered"
      ],
      "properties": {
        "applied": {
          "type": "boolean",
          "description": "Whether the request began in reasoning with a configured finite limit and the controller ran."
        },
        "triggered": {
          "type": "boolean",
          "description": "Whether a finite or completion-capacity boundary forced closure. False also covers inert and natural-close records."
        },
        "trigger": {
          "$ref": "#/$defs/trigger",
          "description": "Boundary that forced closure. Absent when no forced closure occurred."
        },
        "closed": {
          "type": "boolean",
          "description": "Whether the complete reasoning close sequence entered model history."
        },
        "thinking_tokens": {
          "type": "integer",
          "minimum": 0,
          "description": "Thinking tokens observed before closure or request end."
        },
        "thinking_time_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Decode time observed from the first candidate to closure or request end, in milliseconds."
        }
      }
    },
    {
      "if": {
        "properties": {
          "applied": {
            "const": true
          }
        },
        "required": [
          "applied"
        ]
      },
      "then": {
        "properties": {
          "configured": {
            "const": true
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "closed"
        ]
      },
      "then": {
        "required": [
          "thinking_tokens",
          "thinking_time_ms"
        ],
        "if": {
          "properties": {
            "triggered": {
              "const": true
            }
          }
        },
        "then": {
          "required": [
            "trigger"
          ]
        },
        "else": {
          "not": {
            "required": [
              "trigger"
            ]
          }
        }
      },
      "else": {
        "properties": {
          "triggered": {
            "const": false
          }
        },
        "not": {
          "anyOf": [
            {
              "required": [
                "trigger"
              ]
            },
            {
              "required": [
                "thinking_tokens"
              ]
            },
            {
              "required": [
                "thinking_time_ms"
              ]
            }
          ]
        }
      }
    }
  ]
}

recentRecordRecent-request form of the effective record. `applied` and outcome fields may be absent when failure occurred before applicability or terminal state was known.0 fields

Type: effective & object.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "allOf": [
    {
      "$ref": "#/$defs/effective"
    },
    {
      "type": "object",
      "properties": {
        "applied": {
          "type": "boolean",
          "description": "Whether the configured controller applied. Absence means applicability was not established."
        },
        "triggered": {
          "type": "boolean",
          "description": "Whether a known terminal outcome forced closure."
        },
        "trigger": {
          "$ref": "#/$defs/trigger",
          "description": "Known boundary that forced closure."
        },
        "closed": {
          "type": "boolean",
          "description": "Whether the complete reasoning close sequence is known to have entered model history."
        },
        "thinking_tokens": {
          "type": "integer",
          "minimum": 0,
          "description": "Known thinking-token count at closure or request end."
        },
        "thinking_time_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Known decode time from first candidate to closure or request end, in milliseconds."
        }
      }
    }
  ]
}