explain-dataset-fsr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Model context: Field Service Routing (FSR)

## Terminology

| Generic term | FSR term |
|---|---|
| Work item / work unit | visit |
| Resource | vehicle |
| Resource sub-unit | vehicle shift (a vehicle can have multiple shifts) |
| Mandatory work | mandatory visit |
| Optional work | optional visit |
| Required capability | skill (`requiredSkills`) |
| Capacity constraint | shift time window (`maxEndTime`), max visits, max travel time |

## Model-specific configuration

Always set these before running any script.

```bash
MODEL=field-service-routing
MODEL_API_URL=https://app.timefold.ai/api/models/field-service-routing/v1
COLLECTION=/route-plans
OPENAPI_URL=https://app.timefold.ai/openapis/field-service-routing/v1
```

## Scripts

Scripts live in the sibling skill `explain-dataset-shared`, in its `scripts/` directory.
Anchor every path on this skill's own directory, not on the working directory. The working
directory is the user's project, and these skills are installed somewhere else.

In Claude Code, `${CLAUDE_SKILL_DIR}` is substituted with this skill's directory. If your agent
leaves the placeholder unresolved, replace it with the absolute directory that holds this
`SKILL.md`.

`$PY` is the Python runner that the shared skill's runtime check selects (`uv run`,
`python3`, or `python`). Run that check before the first script call.

The variables in the block below are placeholders. **Write their values out in every command you
run**, with the runner and the absolute script path in full, for example
`uv run /abs/path/to/explain-dataset-shared/scripts/summarize.py --model-api-url https://... --model ...`.
Each command starts a new shell, so a variable that an earlier command set is gone. And in zsh,
the default shell on macOS, `$PY` with the value `uv run` stays one word, so the command is not
found.

```bash
SKILL_DIR=${CLAUDE_SKILL_DIR}
SHARED=$SKILL_DIR/../explain-dataset-shared
SCRIPTS=$SHARED/scripts
PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT:-$SKILL_DIR/../..}

$PY $SCRIPTS/summarize.py             --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--tenant ID]
$PY $SCRIPTS/list_unassigned.py       --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--recommendations]
$PY $SCRIPTS/resource_metrics.py      --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--sort overtime|travel|visits|name]
$PY $SCRIPTS/work_details.py          --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --work-ids "visit-001"
$PY $SCRIPTS/work_details.py          --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --resource "VAN-12"
$PY $SCRIPTS/score_violations.py      --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--type hard|medium|soft]
$PY $SCRIPTS/score_justifications.py  --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--samples 3]
$PY $SCRIPTS/score_justifications.py  --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --resource "VAN-12"
```

`$SHARED` also carries the version stamp and, in a plugin install, `$PLUGIN_ROOT` carries the
plugin manifest. The report metadata needs both. Keep the two variables set.

## API

```
Base URL : https://app.timefold.ai/api/models/field-service-routing/v1
Auth     : X-API-KEY: {token}
Collection path: /route-plans
OpenAPI spec: https://app.timefold.ai/openapis/field-service-routing/v1
```

## Documentation

- User guide: https://docs.timefold.ai/field-service-routing/latest/
- Metrics and KPIs: https://docs.timefold.ai/field-service-routing/latest/metrics-and-optimization-goals

## FSR-specific notes

- **Unassigned visits** are in `modelOutput.unassignedVisits` (an explicit list of visit IDs),
  not inferred from a null field like in ESS.
- **Vehicles have shifts**: a vehicle wraps one or more `vehicleShift` objects that each have
  their own itinerary, time window, and metrics. Per-vehicle aggregate metrics are in
  `vehicle.metrics`; per-shift detail is in `vehicle.shifts[].metrics`.
- **Travel metrics** are a core KPI: total travel time, distance, average per visit, and time
  breakdowns (depot-to-first, between visits, last-to-depot).
- **SLA**: if `percentageVisitsInSla` / `absoluteVisitsInSla` are present, call them out.
  They directly measure service quality.
- **Mandatory vs optional is not a fixed tag or priority range.** By default, this is automatic
  and implicit: a visit is mandatory if its time window falls within the current planning
  window, and optional if its time window ends outside it. The `priority` field can override
  this default: built-in priorities `1`-`10` use the automatic `AUTO` behavior above
  (overridable dataset-wide via `defaultAssignmentType: MANDATORY`), `opt-1`-`opt-10` are
  always optional, and custom priority names can set an explicit `assignment` of `AUTO`,
  `MANDATORY`, or `OPTIONAL`. Read the dataset's own priority configuration rather than
  assuming a fixed threshold. See
  [Priority visits and optional visits](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/priority-visits-and-optional-visits).
- **`SOLVING_COMPLETED` is not a feasibility verdict.** It means the solver stopped. A completed
  plan with a negative hard score is infeasible.

## Hard constraints: the settings behind them

The shared skill tells you to trace every hard violation to the settings that cause it, and to
link each one. This table maps the FSR hard constraints that are hardest to trace to the input
field or configuration setting that switches them on.

| Constraint | Switched on by | Docs |
|---|---|---|
| Require visit dependency prerequisite assigned | `visits[].visitDependencies[].precedingVisit` on B. Penalizes B being assigned while A, its preceding visit, is unassigned | [Single visit dependency](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_single_visit_dependency) |
| Require visit dependency dependent assigned | A dependency whose assignment type is `DISALLOW_TO_BLOCK_FOLLOWING` (the default, also set dataset-wide by `defaultDependencyAssignmentType`) | [Assignment type](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_assignment_type) |
| Require visit dependency delay | `minDelayTo` / `maxDelayTo` on the dependency | [Dependency with delay](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_with_delay) |
| Require the same vehicle for dependent visit | `coordination: SAME_VEHICLE` on the dependency | [Coordination](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_with_coordination) |
| Require the same vehicle shift for dependent visit | `coordination: SAME_SHIFT`, **or any pooling type other than `ALLOW_POOLING_ALL`**, set on the dependency or inherited from `config.model.overrides.defaultDependencyPoolingType` | [Coordination](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_with_coordination), [Pooling type](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_pooling_type) |
| Require visit dependency pooling type | `poolingType` other than `ALLOW_POOLING_ALL`, on the dependency or from `defaultDependencyPoolingType` | [Pooling type](https://docs.timefold.ai/field-service-routing/latest/visit-service-constraints/visit-dependencies#_visit_dependency_pooling_type) |
| Keep a pinned visit's vehicle shift | `pinningRequested: true` on the visit, or `pin: true` on an itinerary item | [Pinning individual visits](https://docs.timefold.ai/field-service-routing/latest/real-time-planning/real-time-planning-pinning-visits#_pinning_individual_visits) |
| Keep a pinned visit's start service time | `pin: true` with `startServiceTime` on `vehicles[].shifts[].itinerary[]` | [Pinning individual visits](https://docs.timefold.ai/field-service-routing/latest/real-time-planning/real-time-planning-pinning-visits#_pinning_individual_visits) |

For a hard constraint that is not in this table, find its page in the

From TimefoldAI/skills, Apache-2.0.

More from TimefoldAI/skills