{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://quantdiff.com/schema/quantdiff.schema.json",
  "title": "QuantDiff database",
  "description": "QuantDiff data model. Three collections: models (the full-precision base model), quants (one downloadable file/format of a model), runs (one benchmark run of one quant on one machine, including its results). Every record carries `example`: true for placeholder/seed rows that are NOT real measurements.",
  "type": "object",
  "required": [
    "schema_version",
    "models",
    "quants",
    "runs"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "1.0"
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "models": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/model"
      }
    },
    "quants": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/quant"
      }
    },
    "runs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/run"
      }
    }
  },
  "$defs": {
    "model": {
      "type": "object",
      "required": [
        "id",
        "name",
        "family",
        "params_b",
        "base_repo",
        "reference_dtype",
        "example"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9.-]*$",
          "description": "URL slug, e.g. qwen3-14b"
        },
        "name": {
          "type": "string",
          "description": "Display name, e.g. Qwen3 14B"
        },
        "family": {
          "type": "string"
        },
        "params_b": {
          "type": "number",
          "maximum": 34,
          "description": "Total parameters in billions (scope: <= ~32B)"
        },
        "active_params_b": {
          "type": [
            "number",
            "null"
          ],
          "description": "For MoE models"
        },
        "base_repo": {
          "type": "string",
          "description": "HF repo of the full-precision model, e.g. Qwen/Qwen3-14B"
        },
        "reference_dtype": {
          "type": "string",
          "enum": [
            "BF16",
            "F16",
            "F32"
          ]
        },
        "reference_gguf": {
          "type": [
            "string",
            "null"
          ],
          "description": "HF repo/file of the BF16 GGUF used to produce reference logits"
        },
        "license": {
          "type": "string"
        },
        "context_length": {
          "type": "integer"
        },
        "kv_bytes_per_token": {
          "type": "integer",
          "description": "Approx f16 KV-cache bytes per token, used for the VRAM-fit estimate"
        },
        "description": {
          "type": "string"
        },
        "example": {
          "type": "boolean"
        }
      }
    },
    "quant": {
      "type": "object",
      "required": [
        "id",
        "model_id",
        "publisher",
        "repo",
        "filename",
        "format",
        "quant_type",
        "size_bytes",
        "example"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "<model_id>--<publisher>--<quant_type>"
        },
        "model_id": {
          "type": "string"
        },
        "publisher": {
          "type": "string",
          "description": "HF user/org, e.g. unsloth, bartowski, mradermacher"
        },
        "repo": {
          "type": "string",
          "description": "HF repo id"
        },
        "filename": {
          "type": "string",
          "description": "File in repo (first shard if split)"
        },
        "revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "HF commit sha the file was downloaded at"
        },
        "sha256": {
          "type": [
            "string",
            "null"
          ]
        },
        "format": {
          "type": "string",
          "enum": [
            "GGUF",
            "EXL2",
            "EXL3",
            "AWQ",
            "GPTQ",
            "MLX"
          ]
        },
        "quant_type": {
          "type": "string",
          "description": "e.g. Q4_K_M, IQ4_XS, UD-Q4_K_XL"
        },
        "imatrix": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "size_bytes": {
          "type": "integer"
        },
        "bpw": {
          "type": [
            "number",
            "null"
          ],
          "description": "Effective bits per weight = size_bytes*8/params"
        },
        "example": {
          "type": "boolean"
        }
      }
    },
    "run": {
      "type": "object",
      "required": [
        "id",
        "quant_id",
        "started_at",
        "machine",
        "placement",
        "settings",
        "results",
        "example"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "<UTC yyyymmddThhmmss>_<quant_id>"
        },
        "quant_id": {
          "type": "string"
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "partial",
            "failed"
          ]
        },
        "machine": {
          "type": "object",
          "required": [
            "name",
            "gpu",
            "vram_gb",
            "ram_gb",
            "cpu",
            "os"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "gpu": {
              "type": "string"
            },
            "vram_gb": {
              "type": "number"
            },
            "ram_gb": {
              "type": "number"
            },
            "cpu": {
              "type": "string"
            },
            "os": {
              "type": "string"
            },
            "driver": {
              "type": [
                "string",
                "null"
              ]
            },
            "cuda": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "software": {
          "type": "object",
          "properties": {
            "llama_cpp_build": {
              "type": [
                "string",
                "null"
              ],
              "description": "e.g. b6500 (commit abc1234)"
            },
            "lm_eval_version": {
              "type": [
                "string",
                "null"
              ]
            },
            "harness_version": {
              "type": [
                "string",
                "null"
              ]
            },
            "python": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "placement": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "full_gpu",
            "gpu_ram_split",
            null
          ],
          "description": "full_gpu = all layers offloaded (-ngl 999). gpu_ram_split = some layers/experts on CPU+RAM."
        },
        "settings": {
          "type": "object",
          "description": "Exact settings used, copied verbatim into the run record.",
          "properties": {
            "ngl": {
              "type": "integer"
            },
            "ctx": {
              "type": "integer"
            },
            "batch": {
              "type": "integer"
            },
            "ubatch": {
              "type": "integer"
            },
            "threads": {
              "type": "integer"
            },
            "flash_attn": {
              "type": "boolean"
            },
            "cache_type_k": {
              "type": "string"
            },
            "cache_type_v": {
              "type": "string"
            },
            "seed": {
              "type": "integer"
            },
            "temperature": {
              "type": "number"
            },
            "kld_corpus": {
              "type": "string"
            },
            "kld_corpus_sha256": {
              "type": "string"
            },
            "kld_chunks": {
              "type": "integer"
            },
            "toolcall_set": {
              "type": "string"
            },
            "toolcall_set_sha256": {
              "type": "string"
            },
            "tasks": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "task_limit": {
              "type": "integer"
            },
            "commands": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Exact command lines executed"
            }
          }
        },
        "results": {
          "type": "object",
          "properties": {
            "kld": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "mean": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "median": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "p99": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "max": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "same_top_pct": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "% of tokens where quant top-1 == reference top-1"
                },
                "ppl": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "ppl_ref": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "delta_p_rms": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            },
            "toolcall": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "score": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "0-100, % of cases passed"
                },
                "passed": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "total": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "by_category": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object"
                  }
                }
              }
            },
            "tasks": {
              "type": [
                "object",
                "null"
              ],
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "metric": {
                    "type": "string"
                  },
                  "value": {
                    "type": "number"
                  },
                  "stderr": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "n": {
                    "type": "integer"
                  }
                }
              }
            },
            "speed": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "pp_tps": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "llama-bench prompt processing tokens/s (pp512)"
                },
                "tg_tps": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "llama-bench generation tokens/s (tg128)"
                },
                "pp_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "tg_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            },
            "vram_peak_gb": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "logs": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "name -> relative path/URL of raw log"
        },
        "notes": {
          "type": "string"
        },
        "example": {
          "type": "boolean"
        }
      }
    }
  }
}