Documentation Index
Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
Use this file to discover all available pages before exploring further.
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.
