{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://xevyo.local/spec/turn_plan.schema.json", "title": "xevyo-01 turn plan", "description": "One plan per chat turn. Canonical form lists keys in this order and OMITS every field that holds its default, so a typical plan is short. Decision fields describe what the message needs whatever tools are offered; only `tools` depends on the offered set. Conditional rules (e.g. doc_format only with a document, edit only with an image to edit) are checked after decoding, not here, so this file stays usable for guided decoding.", "type": "object", "additionalProperties": false, "required": [ "schema_version" ], "properties": { "schema_version": { "description": "Plan format version. Always xv01.1.", "const": "xv01.1" }, "safety_concern": { "description": "A concern the planner raises. Code takes the higher of this and its own safety screen and never lowers its own. Rank: none < medication_risk < possible_emergency < possible_crisis. Default none.", "enum": [ "none", "medication_risk", "possible_emergency", "possible_crisis" ], "default": "none" }, "image": { "description": "What to do with images this turn. Omitted = action none.", "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "description": "generate a new picture, edit the attached or remembered one, analyze the attached one, or none.", "enum": [ "none", "generate", "edit", "analyze" ] }, "prompt": { "description": "generate only: the visual scene in English, 10-40 words, no words meant to appear as text.", "type": "string", "minLength": 1, "maxLength": 400 }, "visible_text": { "description": "generate only: the exact words to show, one short line, only words the user gave; empty string for no text.", "type": "string", "maxLength": 200 }, "instruction": { "description": "edit only: the change as a short English command.", "type": "string", "minLength": 1, "maxLength": 300 } } }, "request_kind": { "description": "chat = answer in the reply; document = make a file with doc-gen. Default chat.", "enum": [ "chat", "document" ], "default": "chat" }, "doc_format": { "description": "Only with request_kind document: pptx decks, xlsx spreadsheets/data tables, docx when Word is named, pdf otherwise.", "enum": [ "pdf", "docx", "xlsx", "pptx", null ], "default": null }, "clarify": { "description": "A question to ask back instead of answering. Omitted = none.", "type": [ "string", "null" ], "minLength": 3, "maxLength": 300, "default": null }, "standalone_question": { "description": "The message restated so it needs no history, or the question left after a memory command. Omitted when the message already stands alone.", "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "default": null }, "needs_search": { "description": "Answering correctly needs live web data. Default false.", "type": "boolean", "default": false }, "search_queries": { "description": "With needs_search only: 1-3 standalone search phrases, the question itself first. Keep 'near me' as typed; code adds the saved place.", "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "minLength": 3, "maxLength": 300 } }, "data_tool": { "description": "A calculator or food-database question. Default none.", "enum": [ "none", "calc", "bmi", "dose", "barcode", "usda", "food" ], "default": "none" }, "drug": { "description": "A medication question and the medicines it names. Omitted = not a medication question.", "type": [ "object", "null" ], "additionalProperties": false, "required": [ "names" ], "properties": { "names": { "description": "Medicine names as the user wrote them, lowercased, known or not; not vitamins or supplements.", "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "minLength": 2, "maxLength": 60 } }, "wants_research": { "description": "The user also asked for studies or evidence. Default false.", "type": "boolean", "default": false } }, "default": null }, "memory": { "description": "An explicit memory request. Omitted = action none.", "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "description": "remember a fact, forget one (or everything), recall what is stored, or none.", "enum": [ "none", "remember", "forget", "recall" ] }, "memory_type": { "description": "remember only: the category of the fact (order: allergy > medication > medical_condition > preference > fact; location for a move; vital for a body measurement).", "enum": [ "allergy", "medication", "medical_condition", "preference", "fact", "location", "vital" ] }, "content": { "description": "remember: the fact in profile style ('Is vegetarian' -> 'Vegetarian', 'Takes metformin'); forget: what to forget, '*' for everything.", "type": "string", "minLength": 1, "maxLength": 300 } } }, "domain": { "description": "What kind of turn this is. Default general.", "enum": [ "general", "medical", "coding", "personal_memory", "prompt_authoring" ], "default": "general" }, "depth": { "description": "How much work the answer needs. With needs_tools it maps losslessly to tier/strategy: quick=T1, normal=T2 or T3, deep=T4, research=T5. Default normal.", "enum": [ "quick", "normal", "deep", "research" ], "default": "normal" }, "needs_tools": { "description": "The turn needs the agent path (tools, memory rules, medical rules), not the tool-less fast path. Default false.", "type": "boolean", "default": false }, "tools": { "description": "Ordered tool calls code should run for this turn, chosen ONLY from the offered tools. Web search, drug_lookup, generate_image and memory writes are never listed: needs_search, drug, image and memory drive them. Default empty.", "type": "array", "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "arguments" ], "properties": { "name": { "description": "A tool name from tools.json that was offered this turn.", "enum": [ "fetch_page", "kb_retrieve", "code_agent", "check_drug_interactions", "calculate_bmi", "calculate_dosage", "calculate", "open_food_facts", "usda_food_search", "open_fda", "dsld_lookup", "pharmgkb_lookup", "google_trends_search", "semantic_scholar_search", "openaq_air_quality", "google_calendar_list_events", "google_calendar_create_event", "google_calendar_delete_event", "google_calendar_list_calendars", "google_health_read", "google_health_list_data_sources", "handoff_to" ] }, "arguments": { "description": "Arguments by parameter name; validated per tool against tools.json. A string argument may be exactly $MESSAGE to mean the user's message as typed.", "type": "object", "additionalProperties": { "type": [ "string", "number", "integer", "boolean" ] } } } }, "default": [] }, "directives": { "description": "Per-turn prompt directives by id, from the planner-selectable part of directives.json, in catalogue order. Default empty.", "type": "array", "uniqueItems": true, "maxItems": 6, "items": { "enum": [ "safety.medication", "safety.undiagnosed_pain", "context.unseen_reference", "memory.self_fact", "style.statement_only", "style.casual", "style.followup", "lang.hinglish", "lang.hinglish_english", "lang.devanagari" ] }, "default": [] } } }