Explainable AI in Shift Filling

Explaining a solution from a solve, does not only require listing the constraint violations, but also providing a list of alternative employees for each shift FILL API: reference.
The explain endpoint provides the score and a break-down of all the constraints and their contribution to the score.
This information can be very useful to understand why a solution is unfeasible and what makes it unfeasible.
Additionally, it can provide an exhaustive list of alternative positions that can be used to understand why
a shift has been assigned in a certain way. For each shift it evaluates all its possible employees and provides a score for each alternative.

Example:
Let's take a simple request where we have two employees and one shift.

{
  "employees": [
    {
      "name": "employee 1",
      "skills": [
        {
          "name": "bar"
        }
      ]
    },
    {
      "name": "employee 2",
      "skills": [
        {
          "name": "kitchen"
        }
      ]
    }
  ],
  "shifts": [
    {
      "name": "shift 1",
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-06T17:00:00",
      "skills": [
        {
          "name": "bar"
        }
      ],
      "value": 1
    }
  ],
  "options": {
    "explanation": {
      "enabled": true
    }
  }
}

Our solver will quickly find a feasible solution where shift 1 is assigned to employee 1. The response will look like this:

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -1,
    "feasible": true
  },
  "assignments": [
    {
      "shift": "shift 1",
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-06T17:00:00",
      "skills": [
        "bar"
      ],
      "employee": "employee 1"
    }
  ]
}

The result of a request to the explain endpoint will be something like this

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -1,
    "feasible": true
  },
  "conflicts": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft"
    }
  ],
  "unresolved": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft"
    }
  ]
}

The response reports the score and the list of contributions of the various constraints.
The explanation can be extended to a list of alternative positions for each job in the request. By showing different what-if scenarios,
these alternatives can provide a better comprehension of the solution. To instruct the solver to compute the alternatives the option
options.explanation.enabled should be set to true like this:

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -1,
    "feasible": true
  },
  "conflicts": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft"
    }
  ],
  "unresolved": [
    {
      "constraint": "Employee Skill Level Match Soft",
      "score": "-1soft"
    }
  ],
  "alternatives": {
    "shift 1": [
      {
        "shift": "shift 1",
        "employee": "employee 1",
        "score": {
          "hardScore": 0,
          "mediumScore": 0,
          "softScore": -1,
          "feasible": true
        },
        "violations": [
          {
            "constraint": "Employee Skill Level Match Soft",
            "score": "-1soft"
          }
        ]
      },
      {
        "shift": "shift 1",
        "employee": "employee 2",
        "score": {
          "hardScore": -1,
          "mediumScore": 0,
          "softScore": -1,
          "feasible": false
        },
        "violations": [
          {
            "constraint": "Employee Skill Match",
            "score": "-1hard"
          },
          {
            "constraint": "Employee Skill Match Soft",
            "score": "-1soft"
          }
        ]
      }
    ]
  }
}

This option will trigger an additional stage at the end of the solve request (Hyper-local Discovery) where the solver will produce a list of alternative
positions for each job and add it to the explanation. Each alternative reports, the job subject of the scenario, its position in the scenario
and the annotated score.
Here is an example we see that the solver has evaluated two different scenarios for the assignment of shift 1 and has reported the score for each of them.
Assigning shift 1 to employee 1 has a soft score of -1 and no violations, while assigning it to employee 2 has a hard score of -1 and two violations.