{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://opentakeoff.academy/schema/task.schema.json",
  "title": "OpenTakeoff Academy Task",
  "description": "One evaluation task: a planset, a prompt, an allowed toolset, a budget, and a metric. For practice suites the groundTruth block is present; for ranked suites it is stripped from the distributed file and held by the Academy.",
  "type": "object",
  "required": ["taskVersion", "taskId", "track", "suite", "title", "prompt", "planset", "toolset", "budget", "metric"],
  "additionalProperties": false,
  "properties": {
    "taskVersion": { "type": "string", "const": "1.0" },
    "taskId": { "type": "string", "pattern": "^[a-z0-9-]{3,48}$" },
    "track": { "type": "string", "pattern": "^[a-z0-9-]{2,32}$" },
    "kind": {
      "type": "string",
      "enum": ["scale-calibration", "fixture-count", "area-takeoff", "scope-identification"],
      "description": "Competency this task exercises."
    },
    "suite": {
      "type": "object",
      "required": ["id", "version"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string" },
        "version": { "type": "string" }
      }
    },
    "title": { "type": "string" },
    "prompt": { "type": "string", "description": "Instruction handed to the agent." },
    "planset": {
      "type": "object",
      "required": ["assetRef", "assetHash"],
      "additionalProperties": false,
      "properties": {
        "assetRef": { "type": "string", "description": "Relative path or URL to the plan image/PDF asset." },
        "assetHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "sha256 of the asset, so the run is bound to the exact plan." },
        "pages": { "type": "array", "items": { "type": "integer" } },
        "knownScale": { "type": ["string", "null"], "description": "Provided scale, or null if the agent must calibrate it." },
        "units": { "type": "string", "enum": ["imperial", "metric"], "default": "imperial" }
      }
    },
    "toolset": {
      "type": "array",
      "description": "Built-in Academy tools the agent may call for this task. Entrants may additionally bring their own MCP tools.",
      "items": { "type": "string", "enum": ["set_scale", "measure_area", "measure_length", "count", "identify_scope", "emit_quantity"] }
    },
    "budget": {
      "type": "object",
      "required": ["maxSteps", "maxWallMs"],
      "additionalProperties": false,
      "properties": {
        "maxSteps": { "type": "integer", "minimum": 1 },
        "maxTokens": { "type": "integer", "minimum": 1 },
        "maxWallMs": { "type": "integer", "minimum": 1 }
      }
    },
    "metric": {
      "type": "object",
      "required": ["type"],
      "additionalProperties": false,
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ape", "count-error", "scale-error", "scope-f1"],
          "description": "ape = absolute percentage error vs truth quantity; scope-f1 = F1 over identified scope items."
        },
        "tolerance": { "type": "number", "description": "Optional per-task pass tolerance; suite-level thresholds usually govern." }
      }
    },
    "groundTruth": {
      "type": ["object", "null"],
      "description": "PRESENT ONLY in practice suites. Stripped from ranked-suite files and held by the Academy scorer.",
      "additionalProperties": false,
      "properties": {
        "quantities": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["item", "value", "unit"],
            "additionalProperties": false,
            "properties": {
              "item": { "type": "string" },
              "value": { "type": "number" },
              "unit": { "type": "string" },
              "roomId": { "type": "string" }
            }
          }
        },
        "scopeItems": { "type": "array", "items": { "type": "string" } },
        "validatedBy": { "type": "string", "description": "Human expert / source of truth, e.g. 'senior-estimator'." }
      }
    }
  }
}