The explanation endpoint provides detailed insights into your solution, including constraint violations and alternative assignment options.
Enable Explanation
Add the explanation option to your request:
{
"employees": [
{
"name": "Alice",
"skills": [{ "name": "bar" }]
},
{
"name": "Bob",
"skills": [{ "name": "kitchen" }]
}
],
"shifts": [
{
"name": "shift-1",
"from": "2024-03-06T08:00:00",
"to": "2024-03-06T17:00:00",
"skills": [{ "name": "bar" }],
"min": 1,
"max": 1
}
],
"options": {
"explanation": {
"enabled": true
}
}
}
Solution Response
The solver assigns shift-1 to Alice since she has the required bar skill:
{
"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": "Alice"
}
]
}
Explanation Response
Request the explanation from /v2/fill/explanation/{jobId}:
{
"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"
}
]
}
Individual constraint violations contributing to the score
Aggregated constraints that could not be fully satisfied
Alternative Assignments
When explanation is enabled, the solver evaluates all possible employee-shift combinations:
{
"alternatives": {
"shift-1": [
{
"shift": "shift-1",
"employee": "Alice",
"score": {
"hardScore": 0,
"mediumScore": 0,
"softScore": -1,
"feasible": true
},
"violations": [
{
"constraint": "Employee Skill Level Match Soft",
"score": "-1soft"
}
]
},
{
"shift": "shift-1",
"employee": "Bob",
"score": {
"hardScore": -1,
"mediumScore": 0,
"softScore": -1,
"feasible": false
},
"violations": [
{
"constraint": "Employee Skill Match",
"score": "-1hard"
},
{
"constraint": "Employee Skill Match Soft",
"score": "-1soft"
}
]
}
]
}
}
The alternatives show that assigning Bob would violate a hard constraint (skill mismatch), explaining why Alice was chosen.
Explanation Options
options.explanation.enabled
Enable post-processing to generate alternatives for each assignment
options.explanation.filterHardConstraints
Exclude alternatives that violate hard constraints from the response
Use Cases
| Scenario | How Explanation Helps |
|---|
| Debugging | Identify why a solution is infeasible |
| User transparency | Show managers why specific assignments were made |
| What-if analysis | Evaluate impact of assigning different employees |
| Constraint tuning | Understand which constraints drive the solution |
Use filterHardConstraints: true to only see viable alternatives, reducing response size for large problems.
