> ## 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.

# Explainable AI

> Understand optimization decisions with detailed constraint analysis and alternative evaluations

## Overview

Explainable AI provides transparency into how Solvice's optimization solvers make decisions. This feature enables you to understand not just what solution the solver produced, but why specific assignments were made and what alternatives were considered.

<Info>
  Currently available for the **FILL API** and **VRP API** in beta.
</Info>

## Key Benefits

### Transparency

Understand the reasoning behind every optimization decision, from resource assignments to route planning. The solver reveals which constraints influenced each choice and how different factors were weighted.

### Debugging

Quickly identify issues with solution parameters by examining constraint violations and their impact. This insight helps you fine-tune your optimization requests for better results.

### Trust

Build confidence in automated decisions by seeing the full evaluation of alternatives. Users can verify that the solver considered their operational constraints appropriately.

## How It Works

The explainable AI feature extends the optimization process with a **Hyper-local Discovery** phase after finding the best solution. During this phase, the solver:

1. Evaluates all possible alternative assignments for each decision
2. Calculates scores for each alternative based on constraint violations
3. Ranks alternatives to show why the chosen solution performs best
4. Provides detailed constraint analysis for each option

<Warning>
  The explanation phase evaluates n^n alternatives (where n is the number of possible assignments), making it computationally intensive. Only enable this feature when you need detailed explanations.
</Warning>

## API Implementation

### FILL API

Enable explanations in your shift scheduling requests to understand employee assignments.

<CodeGroup>
  ```json Request theme={null}
  {
    "shifts": [...],
    "employees": [...],
    "options": {
      "explanation": {
        "enabled": true
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "solution": {...},
    "explanation": {
      "shiftAlternatives": [
        {
          "shiftId": "shift-123",
          "currentAssignment": "employee-456",
          "alternatives": [
            {
              "employeeId": "employee-789",
              "score": 85.2,
              "violations": [
                {
                  "constraint": "SKILL_MISMATCH",
                  "severity": "SOFT",
                  "penalty": 10
                }
              ]
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

<Frame>
  <img src="https://i.imgur.com/hnEZIad.gif" alt="Interactive visualization showing alternative employee assignments for shifts with constraint violations" />
</Frame>

### VRP API

Analyze routing decisions to understand job assignments and sequencing choices.

<CodeGroup>
  ```json Request theme={null}
  {
    "jobs": [...],
    "resources": [...],
    "options": {
      "explanation": {
        "enabled": true
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "solution": {...},
    "explanation": {
      "jobAlternatives": [
        {
          "jobId": "job-123",
          "currentResource": "vehicle-456",
          "currentPosition": 3,
          "alternatives": [
            {
              "resourceId": "vehicle-789",
              "position": 2,
              "score": 92.5,
              "violations": [
                {
                  "constraint": "TIME_WINDOW",
                  "severity": "HARD",
                  "detail": "Arrival at 14:30, window closes at 14:00"
                }
              ]
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

## Common Use Cases

### Why wasn't my preferred assignment used?

The explanation reveals all constraint violations that would occur with your preferred assignment, ranked by severity:

```json theme={null}
{
  "preferredAssignment": {
    "violations": [
      {
        "constraint": "MAX_HOURS_EXCEEDED",
        "severity": "HARD",
        "detail": "Would result in 45 hours, maximum is 40"
      },
      {
        "constraint": "SKILL_REQUIREMENT",
        "severity": "HARD", 
        "detail": "Employee lacks required certification"
      }
    ],
    "totalPenalty": 1000
  }
}
```

### Why is a task unassigned?

For unassigned items, the explanation shows why no feasible assignment exists:

```json theme={null}
{
  "unassignedReason": {
    "job": "job-999",
    "attempts": [
      {
        "resource": "vehicle-1",
        "violation": "CAPACITY_EXCEEDED"
      },
      {
        "resource": "vehicle-2", 
        "violation": "TIME_WINDOW_CONFLICT"
      }
    ]
  }
}
```

## Performance Considerations

<Tabs>
  <Tab title="Best Practices">
    * Enable explanations only when needed
    * Limit explanation requests to specific problematic solutions
    * Use smaller problem instances when debugging
    * Cache explanation results for repeated queries
  </Tab>

  <Tab title="Performance Impact">
    | Problem Size | Base Solve Time | With Explanation |
    | ------------ | --------------- | ---------------- |
    | 10 jobs      | 0.5s            | 1.5s             |
    | 50 jobs      | 2s              | 15s              |
    | 100 jobs     | 5s              | 60s              |
    | 500 jobs     | 30s             | 10+ minutes      |
  </Tab>
</Tabs>

## API References

<CardGroup cols={2}>
  <Card title="FILL API Explanation" icon="users" href="/guides/fill/examples/explain">
    Detailed reference for shift scheduling explanations
  </Card>

  <Card title="VRP API Explanation" icon="route" href="/guides/vrp/features/explain">
    Vehicle routing explanation examples and usage
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Enable explanations">
    Add `explanation.enabled: true` to your API request options
  </Step>

  <Step title="Analyze results">
    Review the constraint violations and alternative scores in the response
  </Step>

  <Step title="Refine constraints">
    Adjust your request parameters based on the insights gained
  </Step>
</Steps>

<Note>
  The explainable AI feature continues to evolve. Contact support for access to advanced explanation capabilities or to provide feedback on your use cases.
</Note>