{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ai.upstation.io/actions/design.schema.json",
  "title": "UpStation design file",
  "description": "One file moves through the ai.upstation.io actions: Size -> Network -> Rack & power -> Estimate -> Proposal. Each action reads it and fills its own section; stop after any step and the file is still useful. Every product line cites a catalog id and its https://ai.upstation.io/p/<id> page. Money is USD at the catalog's published price basis, numbers not strings. Reference implementation and checker: the filled examples at /actions/examples/.",
  "type": "object",
  "required": ["design_id", "created", "prices_as_of", "label", "requirements"],
  "properties": {
    "design_id": {"type": "string", "pattern": "^UPS-DSN-[0-9]{8}-[ABCDEFGHJKMNPQRSTUVWXYZ23456789]{4}$", "description": "UPS-DSN- + today YYYYMMDD + - + 4 random characters from ABCDEFGHJKMNPQRSTUVWXYZ23456789. Same ID on every artifact."},
    "created": {"type": "string", "format": "date"},
    "prices_as_of": {"type": "string", "format": "date", "description": "as_of in https://ai.upstation.io/catalog.json"},
    "label": {"const": "Budgetary design and estimate — not a quote"},
    "title": {"type": "string"},
    "summary": {"type": "string", "description": "2-3 sentences: what was designed and why, in the buyer's terms"},
    "customer": {
      "type": "object",
      "description": "The person you are working with and their company. All optional; never block on these. The proposal is written for them to take inside their company.",
      "properties": {
        "company": {"type": "string"}, "champion": {"type": "string", "description": "name or role of the person you are working with"}, "title": {"type": "string"},
        "email": {"type": "string"}, "decision_makers": {"type": "array", "items": {"type": "string"}},
        "criteria": {"type": "array", "items": {"type": "string"}, "description": "what the decision will be judged on, in their words"},
        "deadline": {"type": "string"}, "ship_to": {"type": "string"}
      }
    },
    "requirements": {
      "type": "object",
      "description": "Inputs. Values you chose rather than the user carry ' (proposed)' in prose fields and are listed in assumptions.",
      "properties": {
        "workload": {"enum": ["training", "fine-tuning", "inference", "hpc", "storage", "vdi", "rendering"]},
        "gpus": {"type": "integer", "minimum": 0},
        "parallelism": {"enum": ["single-gpu", "multi-gpu", "multi-node"], "description": "decides HGX vs PCIe (sizing.device_class.test)"},
        "gpu_product": {"type": "string", "description": "catalog id if the user picked one"},
        "storage": {
          "type": "object",
          "properties": {
            "media": {"enum": ["nvme", "hdd"]}, "usable_tb": {"type": "number"}, "dataset_tb": {"type": "number"},
            "feed_gbs_per_gpu": {"type": "number", "description": "sizing.storage.read_gbs_per_gpu"},
            "checkpoint_params_b": {"type": "number"}, "checkpoint_pause_s": {"type": "number"}, "checkpoints_kept": {"type": "integer"},
            "protection": {"type": "string", "description": "a key of sizing.storage.protection_efficiency, e.g. replica_3, ec_4+2, raid6_10+2"}
          }
        },
        "services_nodes": {"type": "integer", "minimum": 0, "description": "optional CPU nodes for cluster services; 0 or absent = none. Settle it with the buyer for HGX clusters"},
        "front_end": {"enum": ["10G", "25G", "100G", "200G"]},
        "rack_kw": {"type": "number", "default": 40},
        "location": {"enum": ["MT", "TX", "OR", "PA", "CA"], "description": "power.colo_locations key"},
        "internet": {"type": "string"},
        "timeline": {"type": "string"}, "budget": {"type": "string"}
      }
    },
    "size": {
      "type": "object",
      "description": "Action 1, Size. Rules: https://ai.upstation.io/sizing",
      "required": ["nodes", "gpus", "steps"],
      "properties": {
        "gpu_class": {"enum": ["hgx", "pcie", null]}, "gpu_product_id": {"type": ["string", "null"]},
        "nodes": {"type": "integer"}, "gpus": {"type": "integer"},
        "storage": {"type": "object", "properties": {"product_id": {"type": "string"}, "nodes": {"type": "integer"}, "protection": {"type": "string"}, "need_tb": {"type": "number"}, "plannable_tb": {"type": "number"}, "read_gbs": {"type": "number"}, "write_gbs": {"type": "number"}}},
        "services": {"type": "object", "description": "optional cluster-services CPU nodes (provisioning, scheduler, monitoring); only when the buyer wants them", "properties": {"product_id": {"type": "string"}, "nodes": {"type": "integer"}}},
        "steps": {"type": "array", "items": {"type": "string"}, "description": "one sentence per decision, arithmetic shown"},
        "assumptions": {"type": "array", "items": {"type": "string"}}
      }
    },
    "network": {
      "type": "object",
      "description": "Action 2, Network topology. Method: /actions/network/SKILL.md",
      "properties": {
        "fabrics": {"type": "array", "items": {"type": "object", "required": ["role", "speed", "switch_id", "ports_used", "ports_total"], "properties": {
          "role": {"enum": ["gpu_fabric", "storage", "front_end", "oob"]}, "speed": {"type": "string"}, "switch_id": {"type": "string"},
          "leaves": {"type": "integer"}, "spines": {"type": "integer"}, "rails_per_leaf": {"type": ["integer", "null"], "description": "rails sharing one leaf in a small rail-optimized fat-tree (k × nodes ≤ R/2)"}, "oversubscription": {"type": "string"},
          "ports_used": {"type": "integer"}, "ports_total": {"type": "integer"}}}},
        "lines": {"type": "array", "description": "switches, NIC options and links with unit price and qty", "items": {"type": "object"}},
        "mermaid": {"type": "string", "description": "flowchart TB source of the topology"},
        "port_map": {"type": "array", "description": "one row per connection; rows sharing a cable_id are breakout lanes. Method: /actions/network/SKILL.md", "items": {"type": "object", "required": ["cable_id", "fabric", "a", "a_port", "b", "b_port", "cable"], "properties": {
          "cable_id": {"type": "string", "pattern": "^C[0-9]{4,}$"}, "fabric": {"enum": ["gpu_fabric", "storage", "front_end", "oob"]}, "a": {"type": "string"}, "a_port": {"type": "string"},
          "b": {"type": "string"}, "b_port": {"type": "string"}, "cable": {"type": "string"}, "link": {"type": "string", "description": "which network line this cable is counted in"}}}},
        "steps": {"type": "array", "items": {"type": "string"}}, "assumptions": {"type": "array", "items": {"type": "string"}}
      }
    },
    "racks": {
      "type": "object",
      "description": "Action 3, Rack elevation & power. Method: /actions/rack/SKILL.md",
      "properties": {
        "rack_kw": {"type": "number"}, "usable_u": {"type": "integer"}, "provision_kw": {"type": "number"},
        "racks": {"type": "array", "items": {"type": "object", "required": ["name", "devices", "u_used", "kw", "circuit", "circuit_pairs"], "properties": {
          "name": {"type": "string"}, "u_used": {"type": "integer"}, "kw": {"type": "number"},
          "circuit": {"type": "string"}, "circuit_rated_kw": {"type": "number"}, "circuit_pairs": {"type": "integer"},
          "devices": {"type": "array", "items": {"type": "object", "required": ["product_id", "u", "ru", "kw", "role"], "properties": {
            "role": {"enum": ["gpu_node", "storage_node", "services_node", "gpu_fabric", "front_end", "oob"]}, "product_id": {"type": "string"},
            "name": {"type": "string", "description": "gpu-01, stor-01, svc-01, gpu-sw-1, leaf-01, spine-01, fe-1a, oob-1; same names as the port map"},
            "label": {"type": "string"}, "u": {"type": "integer", "description": "lowest U occupied, 1 = bottom"}, "ru": {"type": "integer"}, "kw": {"type": "number"}, "psu": {"type": "integer"}}}},
          "feed_load_pct": {"type": "number", "description": "rack kW ÷ (circuit_pairs × circuit_rated_kw) × 100"}, "outlets_per_feed": {"type": "integer", "description": "power cords per feed: half of each device's supplies, rounded up"}}}},
        "colo_options": {"type": "array", "description": "every power.colo_locations entry priced for this design", "items": {"type": "object", "properties": {"key": {"type": "string"}, "location": {"type": "string"}, "rate_usd_per_kw_month": {"type": "number"}, "usd_per_month": {"type": "number"}, "term_months": {"type": "integer"}, "term_total": {"type": "number"}, "sales_tax": {"type": ["string", "null"]}, "property_tax": {"type": ["string", "null"]}}}},
        "colo": {"type": "object", "properties": {"location": {"type": "string"}, "rate_usd_per_kw_month": {"type": "number"}, "term_months": {"type": "integer"}, "usd_per_month": {"type": "number"}}},
        "steps": {"type": "array", "items": {"type": "string"}}
      }
    },
    "estimate": {
      "type": "object",
      "description": "Action 4, Estimate. Rules: /actions/estimate/SKILL.md",
      "required": ["lines", "capex"],
      "properties": {
        "lines": {"type": "array", "items": {"type": "object", "required": ["section", "item", "unit", "qty", "extended", "url"], "properties": {
          "section": {"type": "string"}, "product_id": {"type": ["string", "null"]}, "item": {"type": "string"}, "url": {"type": "string"},
          "unit": {"type": "number"}, "qty": {"type": "integer"}, "extended": {"type": "number", "description": "unit × qty"},
          "basis": {"type": "string"}, "approx": {"type": "boolean"}, "lead_time": {"type": ["string", "null"]}, "lead_weeks": {"type": ["integer", "null"]}}}},
        "capex": {"type": "number", "description": "sum of extended"}, "opex_per_month": {"type": "number"}, "year_one": {"type": "number", "description": "capex + 12 × opex"},
        "tco_3y": {"type": "number", "description": "capex + 36 × opex"}, "tco_5y": {"type": "number", "description": "capex + 60 × opex"},
        "longest_lead_weeks": {"type": ["integer", "null"]}, "lead_driver": {"type": ["string", "null"]},
        "excluded": {"type": "array", "items": {"type": "string"}}
      }
    },
    "proposal": {"type": "object", "description": "Action 5, Proposal (to come): written for the champion to take inside their company."},
    "assumptions": {"type": "array", "items": {"type": "string"}},
    "next_step": {"type": "string"}
  }
}
