{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://blueprints.metrale.ai/schemas/kbp-graph.v2.json",
  "title": "kbp-graph/v2",
  "description": "kbp-graph/v1 plus the kernel math. What the store's architecture view renders (blueprint design §10): the circuit's nodes and edges joined with one plan arm (default decode:1), the resolved precision and the kernel set. Indices are the document's own (`order` is execution order); no coordinates are included, layout is the site's. `collapsed` holds one template per distinct layer structure plus the layer layout, so a 45-layer model renders as a few templates and a sequence. Shared definitions live in kbp-card.v1.json. v2 adds `explain`, the engine's kernel-math table (KERNEL_FAMILIES.toml `explain` and the engine's format semantics): one entry per kernel family a node names and per format an edge or weight names, so nodes refer to it by `family` and edges by `format`; and on every edge its width (`dim_value`), its bytes per token and its requantisation, if any.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "blueprint_id",
    "lineage",
    "revision",
    "exported_by",
    "arm",
    "layers",
    "nodes",
    "edges",
    "groups",
    "collapsed",
    "explain",
    "provenance"
  ],
  "properties": {
    "schema": {
      "const": "kbp-graph/v2"
    },
    "blueprint_id": {
      "type": "string",
      "pattern": "^(sha256|preview):[0-9a-f]{64}$"
    },
    "lineage": {
      "$ref": "kbp-card.v1.json#/$defs/sha256id"
    },
    "revision": {
      "type": "integer",
      "minimum": 0
    },
    "exported_by": {
      "$ref": "kbp-card.v1.json#/$defs/text"
    },
    "arm": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode",
        "rows",
        "digest"
      ],
      "properties": {
        "mode": {
          "enum": [
            "decode",
            "multi_seq",
            "verify",
            "draft",
            "verify_batch"
          ]
        },
        "rows": {
          "type": "integer",
          "minimum": 1
        },
        "digest": {
          "$ref": "kbp-card.v1.json#/$defs/hex64"
        }
      }
    },
    "layers": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "index",
          "kind",
          "template",
          "blocks"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "kind": {
            "$ref": "kbp-card.v1.json#/$defs/ident"
          },
          "template": {
            "$ref": "#/$defs/templateId"
          },
          "blocks": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/$defs/blockInst"
            }
          }
        }
      }
    },
    "nodes": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/node"
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "from",
          "to",
          "format",
          "rows",
          "dim",
          "fused",
          "dim_value",
          "bytes_per_token",
          "requant"
        ],
        "properties": {
          "id": {
            "$ref": "#/$defs/nodeId"
          },
          "from": {
            "type": "integer",
            "minimum": 0
          },
          "to": {
            "type": "integer",
            "minimum": 0
          },
          "format": {
            "$ref": "kbp-card.v1.json#/$defs/formatOrNull"
          },
          "rows": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 80
          },
          "dim": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "fused": {
            "type": "boolean"
          },
          "dim_value": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "bytes_per_token": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "requant": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "from",
                  "to",
                  "at"
                ],
                "properties": {
                  "from": {
                    "$ref": "kbp-card.v1.json#/$defs/format"
                  },
                  "to": {
                    "$ref": "kbp-card.v1.json#/$defs/format"
                  },
                  "at": {
                    "enum": [
                      "producer",
                      "reader"
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    },
    "groups": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "rule",
          "kernels",
          "where",
          "numerics",
          "compute",
          "nodes"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 0
          },
          "rule": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.:/-]+$",
            "maxLength": 160
          },
          "kernels": {
            "type": "array",
            "items": {
              "$ref": "kbp-card.v1.json#/$defs/kernelId"
            }
          },
          "where": {
            "$ref": "#/$defs/where"
          },
          "numerics": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "compute": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "$ref": "kbp-card.v1.json#/$defs/compute"
              }
            ]
          },
          "nodes": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    },
    "collapsed": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "prologue",
        "layout",
        "epilogue",
        "templates"
      ],
      "properties": {
        "prologue": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/templateId"
          }
        },
        "layout": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/templateId"
          }
        },
        "epilogue": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/templateId"
          }
        },
        "templates": {
          "type": "object",
          "minProperties": 1,
          "propertyNames": {
            "$ref": "#/$defs/templateId"
          },
          "additionalProperties": {
            "$ref": "#/$defs/template"
          }
        }
      }
    },
    "explain": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "families",
        "formats"
      ],
      "properties": {
        "families": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/familyMath"
          }
        },
        "formats": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/formatMath"
          }
        }
      }
    },
    "provenance": {
      "$ref": "kbp-card.v1.json#/$defs/provenance"
    }
  },
  "$defs": {
    "templateId": {
      "type": "string",
      "pattern": "^[a-z0-9_]+(\\+[a-z0-9_]+)*(~[0-9]+)?$",
      "maxLength": 80
    },
    "blockInst": {
      "type": "string",
      "pattern": "^(l[0-9]+\\.)?[a-z0-9_]+$",
      "maxLength": 60
    },
    "nodeId": {
      "type": "string",
      "pattern": "^(l[0-9]+\\.)?[a-z0-9_]+\\.[A-Za-z0-9_]+$",
      "maxLength": 120
    },
    "where": {
      "enum": [
        "device",
        "host",
        "novel"
      ]
    },
    "precision": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "weight",
        "activation",
        "output"
      ],
      "properties": {
        "weight": {
          "$ref": "kbp-card.v1.json#/$defs/formatOrNull"
        },
        "activation": {
          "$ref": "kbp-card.v1.json#/$defs/formatOrNull"
        },
        "output": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-z0-9_/]+(,[a-z0-9_/]+)*$",
          "maxLength": 120
        }
      }
    },
    "node": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "order",
        "layer",
        "block",
        "block_type",
        "kind",
        "op",
        "roles",
        "inserted",
        "precision",
        "steps",
        "group",
        "kernel",
        "family",
        "point",
        "compute",
        "numerics",
        "where",
        "state"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/nodeId"
        },
        "order": {
          "type": "integer",
          "minimum": 0
        },
        "layer": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "block": {
          "$ref": "#/$defs/blockInst"
        },
        "block_type": {
          "$ref": "kbp-card.v1.json#/$defs/ident"
        },
        "kind": {
          "$ref": "kbp-card.v1.json#/$defs/identOrNull"
        },
        "op": {
          "type": "string",
          "pattern": "^[a-z0-9_]+(:[a-z0-9_]+)?$",
          "maxLength": 80
        },
        "roles": {
          "type": "array",
          "items": {
            "$ref": "kbp-card.v1.json#/$defs/ident"
          }
        },
        "inserted": {
          "type": "boolean",
          "description": "a node the planner inserted (an activation quantize), not in the circuit"
        },
        "precision": {
          "$ref": "#/$defs/precision"
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          }
        },
        "group": {
          "type": "integer",
          "minimum": 0
        },
        "kernel": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "$ref": "kbp-card.v1.json#/$defs/kernelId"
            }
          ]
        },
        "family": {
          "$ref": "kbp-card.v1.json#/$defs/identOrNull"
        },
        "point": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "type": [
              "string",
              "integer",
              "boolean"
            ]
          }
        },
        "compute": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "$ref": "kbp-card.v1.json#/$defs/compute"
            }
          ]
        },
        "numerics": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "where": {
          "$ref": "#/$defs/where"
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-z0-9_]+:[a-z0-9_]+(,[a-z0-9_]+:[a-z0-9_]+)*$"
        }
      }
    },
    "template": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "blocks",
        "nodes",
        "edges",
        "ports",
        "instances"
      ],
      "properties": {
        "blocks": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "kbp-card.v1.json#/$defs/ident"
          }
        },
        "nodes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "op",
              "kind",
              "block_type",
              "precision",
              "kernel",
              "family",
              "compute",
              "where",
              "group",
              "inserted"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_]+\\.[A-Za-z0-9_]+$"
              },
              "op": {
                "type": "string",
                "pattern": "^[a-z0-9_]+(:[a-z0-9_]+)?$"
              },
              "kind": {
                "$ref": "kbp-card.v1.json#/$defs/identOrNull"
              },
              "block_type": {
                "$ref": "kbp-card.v1.json#/$defs/ident"
              },
              "precision": {
                "$ref": "#/$defs/precision"
              },
              "kernel": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "kbp-card.v1.json#/$defs/kernelId"
                  }
                ]
              },
              "family": {
                "$ref": "kbp-card.v1.json#/$defs/identOrNull"
              },
              "compute": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "kbp-card.v1.json#/$defs/compute"
                  }
                ]
              },
              "where": {
                "$ref": "#/$defs/where"
              },
              "group": {
                "type": "integer",
                "minimum": 0
              },
              "inserted": {
                "type": "boolean"
              }
            }
          }
        },
        "edges": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "from",
              "to",
              "format",
              "fused"
            ],
            "properties": {
              "from": {
                "type": "integer",
                "minimum": 0
              },
              "to": {
                "type": "integer",
                "minimum": 0
              },
              "format": {
                "$ref": "kbp-card.v1.json#/$defs/formatOrNull"
              },
              "fused": {
                "type": "boolean"
              }
            }
          }
        },
        "ports": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "in",
            "out"
          ],
          "properties": {
            "in": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0
              }
            },
            "out": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        },
        "instances": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "familyMath": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "description",
        "about",
        "numerics",
        "math"
      ],
      "properties": {
        "description": {
          "$ref": "kbp-card.v1.json#/$defs/text"
        },
        "about": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "numerics": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "math": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          }
        }
      }
    },
    "formatMath": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "title",
        "description",
        "math",
        "encode"
      ],
      "properties": {
        "title": {
          "$ref": "kbp-card.v1.json#/$defs/text"
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "math": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          }
        },
        "encode": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          ]
        }
      }
    }
  }
}