DriverModelSchema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/okareo/main/json-schema/okareo-driver-model-schema-schema.json",
  "title": "DriverModelSchema",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/okareo-openapi.json#/components/schemas/DriverModelSchema",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Id",
      "description": "ID of the driver model"
    },
    "name": {
      "type": "string",
      "title": "Name",
      "description": "Name of the driver model"
    },
    "temperature": {
      "type": "number",
      "title": "Temperature",
      "description": "Temperature of the driver model"
    },
    "model_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model Id",
      "description": "Model ID of the driver model"
    },
    "prompt_template": {
      "type": "string",
      "title": "Prompt Template",
      "description": "Prompt template for the driver model"
    },
    "voice_instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Voice Instructions",
      "description": "Voice instructions for the driver model"
    },
    "voice_profile": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Voice Profile",
      "description": "Voice profile for the driver model. Select from the following list of options: neutral, happy, excited, content, curious, calm, confident, surprised, confused, sad, disappointed, bored, frustrated, angry, agitated, anxious, scared, sarcastic."
    },
    "voice": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Voice",
      "description": "Voice setting for the driver model. Use GET /v0/voices to retrieve available voice options."
    },
    "voice_tone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Voice Tone",
      "description": "Driver's emotion/tone passed to Cartesia (a canonical tone token, e.g. 'happy', 'frustrated'). Definitive source of the driver's emotion. If omitted but voice_profile is set, it is derived from the profile."
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Language",
      "description": "Language code in BCP-47 format (e.g., 'en-US', 'es-MX', 'ja', 'fr-CA'). For voice targets, improves STT accuracy by constraining language model. If not specified, defaults to 'multi' for automatic language detection."
    },
    "project_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Project Id",
      "description": "ID for project"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tags",
      "description": "Tags are strings that can be used to filter drivers in the Okareo app. Omit to leave existing tags unchanged; send an empty list to clear them."
    },
    "steps": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DriverStepSchema"
          },
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Steps",
      "description": "Scripted Driver: an ordered list of steps ({message}, {dtmf}, {end_conversation}), or one {scenario_input.<column>} reference that resolves to that list per scenario row. end_conversation must be last. When set, prompt_template is not used and no Driver LLM runs."
    }
  },
  "type": "object",
  "required": [
    "name",
    "temperature",
    "prompt_template"
  ],
  "$defs": {
    "DriverStepSchema": {
      "properties": {
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Message",
          "description": "Words the Driver says, verbatim."
        },
        "dtmf": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dtmf",
          "description": "Keys the Driver presses (0-9, A-D, *, #, w); voice only."
        },
        "silence": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Silence",
          "description": "true: the Driver says nothing this turn and listens for the Target's next segment; voice only."
        },
        "end_conversation": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "End Conversation",
          "description": "Closing words; the Driver says them and ends the call."
        },
        "reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reason",
          "description": "Why the script ended the call (with end_conversation only)."
        },
        "turn": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Turn",
          "description": "Reserved; rejected today."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "DriverStepSchema",
      "description": "One scripted step: exactly one of message / dtmf / end_conversation (checked by the\nsteps validator), with an optional reason on end_conversation. Unknown keys are a 422."
    }
  }
}