{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nexusquantum-legal/json-schema/nexusquantum-legal-llm-provider-suitability-report-schema.json",
  "title": "LlmProviderSuitabilityReport",
  "description": "SUITABILITY report of the BYO engine for legal work (goes BEYOND the connectivity health check in `/test`). Runs the model against an ADVERSARIAL legal mini-goldset (ES∪EN) and scores it with Nexus's OWN citation verification engine (meaning vetoes + citation extraction): it judges the model with the same wall that protects the client. A weak model NEVER produces a false-verified (verification runs over the output whatever the engine); this measures the QUALITY that a bad model degrades. Citation fabrication is disqualifying (rating `fail`).",
  "x-generated": "2026-11-19",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nexusquantum-legal-openapi.json#/components/schemas/LlmProviderSuitabilityReport",
  "type": "object",
  "properties": {
    "rating": {
      "type": "string",
      "enum": [
        "pass",
        "warn",
        "fail"
      ],
      "description": "Overall suitability verdict. READ `assessed` FIRST: with `assessed: false` this verdict is the non-certifying value of a CLOSED enum, not a measurement of your model."
    },
    "score": {
      "type": "integer",
      "description": "Score 0-100 (weighted sum of the dimensions) OVER THE MEASURED PART: the real ceiling is `100 x scoreCoverage`, not 100. Whatever could not be measured adds 0 — it is never credited as a pass. `score: 0` with `scoreCoverage: 0` means \"nothing was measured\", NOT \"measured and scored zero\"."
    },
    "model": {
      "type": "string",
      "description": "Model evaluated."
    },
    "dimensions": {
      "type": "object",
      "description": "Per dimension `{ pass, total, ok, unusable? }`: anti_fabrication, faithfulness, instruction_following, reliability. `total` is the MEASURED denominator (probes that produced usable output); `unusable` counts the probes discarded for lack of it, so `total + unusable` = probes launched. `ok: true` requires the dimension to have been measured AND fully passed — a dimension with `total: 0` is `ok: false`, since absence of evidence never certifies."
    },
    "reliability": {
      "type": "object",
      "description": "`{ calls, errors, errorRate, p95LatencyMs, unusable? }` over the goldset calls (captures the down/unstable-engine failure class). `errors` = transport failures; `unusable` = calls that yielded no usable output (a SUPERSET of `errors`: it also counts 200s answered with empty content)."
    },
    "recommendation": {
      "type": "string",
      "description": "Plain-language verdict + recommended action. When no quality dimension could be measured it carries the English `assessedNote` instead of a verdict on the model."
    },
    "probes": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per-probe detail (id, dimension, lang, ok, pass, note, evaluable?). `evaluable: false` = the engine produced no usable output for that probe, so it was NOT scored: the accompanying `pass: false` is filler, it means \"not measured\", not \"measured and failed\"."
    },
    "assessed": {
      "type": "boolean",
      "description": "ADDITIVE and optional. `false` = the report is NOT a complete measurement: at least one probe (or a whole dimension) could not be scored because your engine returned no usable output. An engine that answers nothing does not score low — IT DOES NOT SCORE: without this field a mute engine collected the full 40% of `anti_fabrication` (\"it fabricated no citation\" — it wrote no word at all) and the 15% of `reliability`, and came out rated as usable. It is a new optional FIELD on purpose, never a new value inside the closed `rating` enum, so integrators that `switch` on rating do not break."
    },
    "assessedCode": {
      "type": "string",
      "enum": [
        "ENGINE_NO_RESPONSE",
        "ENGINE_EMPTY_OUTPUT",
        "PARTIAL_COVERAGE"
      ],
      "description": "Stable machine code, present only when `assessed: false`. `ENGINE_NO_RESPONSE` = your engine did not answer (credentials, balance/quota, reachability). `ENGINE_EMPTY_OUTPUT` = it answered with no content (model id, output token budget, content filter). `PARTIAL_COVERAGE` = some probes were not scored."
    },
    "assessedNote": {
      "type": "string",
      "description": "Human-readable explanation (English, prefixed with `assessedCode`), present only when `assessed: false`."
    },
    "scoreCoverage": {
      "type": "number",
      "description": "0..1 — share of the total weight that COULD be measured. `score` is out of `100 x scoreCoverage`. A value below 1 means part of the report is a gap, not a result."
    },
    "unmeasured": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Dimensions with NO evaluable probe: they were not measured at all, neither well nor badly. Absent when everything was measured."
    }
  }
}