PlannerTurn

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kdpcoloringbook-com/json-schema/kdpcoloringbook-com-planner-turn-schema.json",
  "title": "PlannerTurn",
  "description": "One assistant turn. ``kind`` discriminates the shape:\n\n- ``question``: render ``message`` + ``options`` (chips) and/or a free-text box.\n- ``plan``: render ``message`` + ``summary`` bullets + the 3 invented\n  ``style_candidates`` (rendered against one shared ``sample_scene`` so the user\n  can compare looks and pick one), plus Approve / give-feedback CTAs (``config``\n  is hidden state).",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kdpcoloringbook-com-openapi.json#/components/schemas/PlannerTurn",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "question",
        "plan"
      ],
      "title": "Kind"
    },
    "message": {
      "type": "string",
      "maxLength": 2000,
      "title": "Message"
    },
    "options": {
      "items": {
        "$ref": "#/$defs/PlannerOption"
      },
      "type": "array",
      "title": "Options"
    },
    "multi_select": {
      "type": "boolean",
      "title": "Multi Select",
      "default": false
    },
    "allow_free_text": {
      "type": "boolean",
      "title": "Allow Free Text",
      "default": true
    },
    "collected": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Collected"
    },
    "summary": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Summary"
    },
    "config": {
      "anyOf": [
        {
          "$ref": "#/$defs/BookPlanConfig"
        },
        {
          "type": "null"
        }
      ]
    },
    "style_candidates": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/StyleCandidate"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Style Candidates"
    },
    "sample_scene": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sample Scene"
    },
    "distribution": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DistributionRange"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Distribution"
    },
    "handled_requests": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Handled Requests"
    },
    "help_topic": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Help Topic"
    }
  },
  "type": "object",
  "required": [
    "kind",
    "message"
  ],
  "$defs": {
    "BookLength": {
      "type": "string",
      "enum": [
        "test",
        "short",
        "medium",
        "long"
      ],
      "title": "BookLength"
    },
    "BookPlanConfig": {
      "properties": {
        "theme": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "title": "Theme"
        },
        "length": {
          "$ref": "#/$defs/BookLength",
          "default": "short"
        },
        "pages": {
          "type": "integer",
          "maximum": 60.0,
          "minimum": 3.0,
          "title": "Pages",
          "default": 25
        },
        "distribution_type": {
          "type": "string",
          "enum": [
            "progressive",
            "bold_and_easy",
            "cute_and_cozy"
          ],
          "title": "Distribution Type",
          "default": "progressive"
        },
        "character_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Character Count"
        },
        "language": {
          "type": "string",
          "enum": [
            "en",
            "es",
            "de",
            "fr",
            "it",
            "pt"
          ],
          "title": "Language",
          "default": "en"
        },
        "style_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Style Id"
        },
        "style_description": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000
            },
            {
              "type": "null"
            }
          ],
          "title": "Style Description"
        },
        "allow_text": {
          "type": "boolean",
          "title": "Allow Text",
          "default": false
        },
        "user_rules": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 1000
            },
            {
              "type": "null"
            }
          ],
          "title": "User Rules"
        }
      },
      "type": "object",
      "required": [
        "theme"
      ],
      "title": "BookPlanConfig",
      "description": "The book the agent proposes — a superset compatible with GenerateRequest.\n\nOn approval the FE forwards this straight to POST /api/generate. ``pages`` is\nthe authoritative page count (the user picks it explicitly); ``length`` is only\na coarse label (the nearest LENGTH bucket) and is not used to derive pages."
    },
    "DistributionRange": {
      "properties": {
        "start_page": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Start Page"
        },
        "end_page": {
          "type": "integer",
          "minimum": 1.0,
          "title": "End Page"
        },
        "theme": {
          "type": "string",
          "maxLength": 120,
          "minLength": 1,
          "title": "Theme"
        },
        "description": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 600
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        }
      },
      "type": "object",
      "required": [
        "start_page",
        "end_page",
        "theme"
      ],
      "title": "DistributionRange",
      "description": "One contiguous section of the book's page plan.\n\nShared contract with the frontend: ranges are contiguous and cover pages\n``1..config.pages`` exactly. ``theme`` is a short user-facing label (in the\nuser's language); ``description`` is an optional English brief that is fed\nto the page-prompt generator."
    },
    "PlannerOption": {
      "properties": {
        "label": {
          "type": "string",
          "title": "Label"
        },
        "value": {
          "type": "string",
          "title": "Value"
        },
        "emoji": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Emoji"
        }
      },
      "type": "object",
      "required": [
        "label",
        "value"
      ],
      "title": "PlannerOption",
      "description": "A selectable chip for a multiple-choice question turn."
    },
    "StyleCandidate": {
      "properties": {
        "key": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Key"
        },
        "name": {
          "type": "string",
          "maxLength": 120,
          "minLength": 1,
          "title": "Name"
        },
        "description": {
          "type": "string",
          "maxLength": 2000,
          "minLength": 1,
          "title": "Description"
        },
        "name_local": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 120
            },
            {
              "type": "null"
            }
          ],
          "title": "Name Local"
        },
        "description_local": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 2000
            },
            {
              "type": "null"
            }
          ],
          "title": "Description Local"
        }
      },
      "type": "object",
      "required": [
        "name",
        "description"
      ],
      "title": "StyleCandidate",
      "description": "An AI-invented visual style for a planned book.\n\nThe planner model proposes these on a plan turn; it omits ``key`` and the\nserver slugifies ``name`` into a unique, stable key (see book_planner).\n\n``name``/``description`` stay in technical English (they feed the image\nmodel); ``name_local``/``description_local`` carry the same text translated\nto the user's chat language for display only."
    }
  }
}