sentinel-gate/inference_contract/schema_sentinel_v1.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://huggingface.co/flowxai/sentinel-gate/inference_contract/schema_sentinel_v1.json",
  "title": "FlowX Sentinel Gate output (schema_sentinel_v1)",
  "description": "The single JSON object the Sentinel Gate emits for one regulated-decision case. The gate decides ESCALATE (route to a human) vs DECIDE (safe to automate). When action=ESCALATE, escalation_category is one of six ids and a category-specific block is present; when action=DECIDE, escalation_category is null. Prompt version sentinel_sys_v1. Note: additionalProperties is intentionally true because the category-specific block key varies by category (policy_violations, missing_preconditions, boundary_analysis, confidence_factors, conflicting_signals, external_dependency) and DECIDE cases carry decision/rationale keys.",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "action",
    "escalation_category",
    "confidence_score",
    "audit_trail"
  ],
  "properties": {
    "action": {
      "type": "string",
      "description": "The gate decision. ESCALATE routes the case to a human; DECIDE marks it safe to automate. This is the field to gate on (perfect on the held-out set).",
      "enum": ["ESCALATE", "DECIDE"]
    },
    "escalation_category": {
      "description": "The human-routing label for an escalation, or null when action=DECIDE. A secondary routing hint (~0.61 accuracy on true-escalate), not the gate.",
      "type": ["string", "null"],
      "enum": [
        "MISSING_REQUIRED_DOCUMENTATION",
        "POLICY_VIOLATION",
        "BOUNDARY_CONDITION",
        "INSUFFICIENT_CONFIDENCE",
        "CONFLICTING_SIGNALS",
        "EXTERNAL_DEPENDENCY",
        null
      ]
    },
    "confidence_score": {
      "type": "number",
      "description": "Calibrated confidence in the decision, 0.0-1.0. For ESCALATE this is typically the confidence that the case is safe to automate (low), so a low score supports escalation; for DECIDE it is the confidence in the auto-decision (high).",
      "minimum": 0.0,
      "maximum": 1.0
    },
    "confidence_reasoning": {
      "type": "string",
      "description": "One to three sentences explaining the confidence_score and why the case was escalated or auto-decided."
    },
    "human_action_required": {
      "type": "string",
      "description": "For ESCALATE: the concrete next step a human owner must take (who does what). For DECIDE: the string \"NONE\"."
    },
    "audit_trail": {
      "type": "array",
      "description": "Ordered, append-only log of the reasoning steps and policy gates evaluated, for compliance review.",
      "items": { "type": "string" },
      "minItems": 1
    },
    "policy_violations": {
      "type": "object",
      "description": "Category-specific block for POLICY_VIOLATION. Keyed by violation id; each entry names the policy, regulation, restriction, and consequence.",
      "additionalProperties": true
    },
    "missing_preconditions": {
      "type": "object",
      "description": "Category-specific block for MISSING_REQUIRED_DOCUMENTATION. Keyed by the missing precondition; each entry names required_by, regulation, severity, and reason.",
      "additionalProperties": true
    },
    "boundary_analysis": {
      "type": "object",
      "description": "Category-specific block for BOUNDARY_CONDITION. Names the policy_threshold, the shipment/case value, distance_from_threshold, and an assessment of the edge case.",
      "additionalProperties": true
    },
    "confidence_factors": {
      "type": "object",
      "description": "Category-specific block for INSUFFICIENT_CONFIDENCE. Lists ambiguous_signals and why_uncertain.",
      "additionalProperties": true
    },
    "conflicting_signals": {
      "type": "array",
      "description": "Category-specific block for CONFLICTING_SIGNALS. The competing sources/values that disagree.",
      "items": { "type": "object", "additionalProperties": true }
    },
    "external_dependency": {
      "type": "object",
      "description": "Category-specific block for EXTERNAL_DEPENDENCY. Names what the decision is awaiting and the blocking_gate.",
      "additionalProperties": true
    },
    "escalation_path": {
      "type": "string",
      "description": "Optional routing hint naming the specialist queue or workflow that should own the escalation."
    },
    "policy_gates_passed": {
      "type": "array",
      "description": "Optional list of policy gates that were checked and passed before the decision (present on some ESCALATE edge cases and on DECIDE cases).",
      "items": { "type": "string" }
    },
    "decision": {
      "type": "string",
      "description": "For DECIDE cases: the automated outcome selected (e.g. ROUTE_APPROVED)."
    },
    "selected_route": {
      "type": "string",
      "description": "For DECIDE cases where a route/option is chosen: the selected option."
    },
    "rationale": {
      "type": "string",
      "description": "For DECIDE cases: the plain rationale for auto-deciding (some records use confidence_reasoning for this)."
    }
  },
  "allOf": [
    {
      "if": { "properties": { "action": { "const": "DECIDE" } } },
      "then": { "properties": { "escalation_category": { "type": "null" } } }
    },
    {
      "if": { "properties": { "action": { "const": "ESCALATE" } } },
      "then": {
        "properties": {
          "escalation_category": {
            "type": "string",
            "enum": [
              "MISSING_REQUIRED_DOCUMENTATION",
              "POLICY_VIOLATION",
              "BOUNDARY_CONDITION",
              "INSUFFICIENT_CONFIDENCE",
              "CONFLICTING_SIGNALS",
              "EXTERNAL_DEPENDENCY"
            ]
          }
        }
      }
    }
  ]
}