{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nexusquantum-legal/json-schema/nexusquantum-legal-llm-provider-schema.json",
  "title": "LlmProvider",
  "description": "Firm BYO-LLM configuration (your own LLM engine, firm-level). NON-SECRET projection: the credential (`api_key` / `aws.secretAccessKey`) is WRITE-ONLY and NEVER appears here — only `key_fingerprint` is exposed (non-secret). Once `enabled`, the engine applies to ALL of the firm's generative flows (analyze included).",
  "x-generated": "2026-11-19",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nexusquantum-legal-openapi.json#/components/schemas/LlmProvider",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "label": {
      "type": "string",
      "maxLength": 120,
      "description": "Human-readable name, unique within the firm."
    },
    "kind": {
      "type": "string",
      "enum": [
        "openai_compatible",
        "anthropic",
        "bedrock"
      ],
      "description": "Adapter family."
    },
    "base_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Endpoint (openai_compatible: required; anthropic: optional; bedrock: null, derived from region). Validated against SSRF."
    },
    "model_default": {
      "type": "string",
      "description": "Default model."
    },
    "model_map": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Role→model map (e.g. { \"A\": \"claude-opus-4-8\", \"B\": \"gpt-4o\" }). No silent defaults: each node uses exactly the declared model (or `model_default` when the role is not mapped). Recommendation (not a default): Node A → `claude-fable-5` · Node B → `claude-opus-4-8` · Node C → `claude-opus-4-8` or another equally strong reasoning model; any model of the 3 kinds works in any node. `B` ≠ `A` is recommended to preserve the independence of the audit."
    },
    "key_fingerprint": {
      "type": [
        "string",
        "null"
      ],
      "description": "NON-secret, NON-reversible fingerprint of the credential (hash, e.g. `sha256:a1b2c3d4e5f6`; older rows may show the legacy format `sk-p…a1b2`). The ONLY representation of the key that leaves the API."
    },
    "extra_headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Optional extra headers for the provider."
    },
    "routing_policy": {
      "type": "string",
      "enum": [
        "own_only",
        "own_then_platform"
      ],
      "description": "own_then_platform leaves the platform chain as a fallback if your provider fails recoverably."
    },
    "role": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "A",
        "B",
        "C"
      ],
      "description": "Node this engine is assigned to: 'A' (primary analysis), 'B' (adversarial audit) or 'C' (adversarial counterparty). Omit or null = the firm's DEFAULT engine, which serves every node and role (consulta, chat, draft…). Precedence: node engine → default engine → (when the policy forbids platform) Node A engine → platform. Allows a DIFFERENT engine per node: B and C should not share a model with A, or the cross-audit loses its value."
    },
    "billing_mode": {
      "type": "string",
      "description": "Billing mode (default platform)."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether it is active for routing firm traffic."
    },
    "last_verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Last successful /test health check."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "secret_at_rest": {
      "type": "string",
      "enum": [
        "encrypted_aes_256_gcm",
        "plaintext"
      ],
      "description": "Creation response only: at-rest encryption status of the credential."
    }
  }
}