> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you're integrating Kardinal into an application with an SDK, start with Integration paths: https://developers.kardinal.ai/getting-started/integration-paths.md. It lists the sections to read, in order. If you follow Integration paths, you don't need llms-full.txt or openapi.yaml. Each step links the section you need.

# Python SDK changelog

> Version history of the Kardinal Python SDK (kardinal-ai on PyPI): what each release adds or changes, and which version of the Route Optimization API it targets.

Releases of [`kardinal-ai`](https://pypi.org/project/kardinal-ai/). For changes to the API itself, see the [API changelog](https://developers.kardinal.ai/reference/changelog.md).

**2.2.1**

Released on 2026-11-16. The README says how to get an API key

This release doesn't change the code. The README, which is also the page on PyPI, now opens its Quickstart with how to get an API key and set `KARDINAL_API_KEY`.

**2.2.0**

Released on 2026-11-16. kardinal init also writes the skill for OpenAI Codex and Mistral Vibe

This release doesn't change the code you write.

**New**

* `kardinal init` writes the same skill to `.agents/skills/kardinal-python/SKILL.md`, where OpenAI Codex and Mistral Vibe load it. It still writes `.claude/skills/kardinal-python/SKILL.md` for Claude Code. See [Project setup for AI coding assistants](https://developers.kardinal.ai/sdks/cli.md#project-setup-for-ai-coding-assistants).

**Changes**

* The descriptions of the models follow the API reference. `sharedCapacities` now says what it really changes: how the engine treats a `pickup` with a negative quantity. `Warning` says that `properties.path` is stable.

**2.1.0**

Released on 2026-11-04. whoami() and plans.replace(), API warnings in the log, and wait() right after start()

This release doesn't change the code you write. Your program now shows the API's warnings on stderr: the second section says how to silence them.

**New**

* `Kardinal.whoami()` returns the host and the agency of your API key. Call it when your application starts, to check that the key belongs to the agency you expect. See [Checking the key at startup](https://developers.kardinal.ai/sdks/configuration.md#checking-the-key-at-startup).
* `plans.replace(plan_id, plan)` updates a plan from a new `PlanCreate`, the input that `submit()` takes. You don't copy `id`, `agencyId`, or `version`. See [Replacing a plan from your own data](https://developers.kardinal.ai/sdks/plan-lifecycle.md#replacing-a-plan-from-your-own-data).

**Changes**

* `submit()`, `update()`, and `replace()` log each kind of API warning on the `kardinal` logger, at the `WARNING` level. Python prints these lines on stderr, with no logging setup. To silence them, write `logging.getLogger("kardinal").setLevel(logging.ERROR)`. A program should keep reading `plan.warnings`. See [Warnings on successful calls](https://developers.kardinal.ai/sdks/errors-and-warnings.md#warnings-on-successful-calls).
* The skill that `kardinal init` writes points to the [Integration paths](https://developers.kardinal.ai/getting-started/integration-paths.md) page first.

**Fixes**

* `solutions.wait()` right after `plans.start()` now waits for the new run. Before, you could restart a plan that was still optimizing, and `wait()` returned after 10 seconds. It returned the previous run's solution, with `final_state` set to `interrupted`.

**2.0.0**

Released on 2026-11-04. Ids, versions, states, and waypoints are plain values, with no .root, and four fixes

This release changes behaviour in ways that can break existing code, so read the first section before you upgrade. To stay on 1.1.0 until you're ready, write `kardinal-ai<2` in your `requirements.txt` or `pyproject.toml` instead of a plain `kardinal-ai`. A one-off `pip install "kardinal-ai<2"` only changes the current environment.

**Changes that can affect your code**

* Ids, versions, states, and waypoints are plain values, so `.root` no longer exists on them. `plan.id`, `stop.id`, `tour.resourceId`, `waypoint.stopId`, and `plan.tz` are `str`. `tour.wayPoints` is a list of `WayPointBegin`, `WayPointStop`, `WayPointBreak`, and `WayPointEnd`, so write `waypoint.type` instead of `waypoint.root.type`. A tour's violations, the plan's global constraints, and the solution's global violations work the same way. Remove every `.root` that reads one of these values. `==` and `str()` give the same results as before on ids.
* 36 classes are removed from `kardinal.routing.models`, because the value they wrapped is now a plain `str`, `int`, list, or the model they wrapped: `AdditionalConstraints`, `AgencyId`, `Assignments`, `Break`, `Capacities`, `Constraints`, `CostsByCurrency`, `CostsByResourceTag`, `CountryCode`, `CountryCodes`, `DateTime`, `Direction`, `Direction1`, `ErrorProperties`, `GlobalConstraints`, `GlobalViolations`, `Kind`, `MaxGroupsByStopTag`, `Mode`, `Mode1`, `PlanObjectives`, `PlanVersion`, `Properties`, `RemovalStrategy`, `ShippedHazardousGoodModel`, `State`, `State2`, `Status`, `Status4`, `Stop`, `StopTagPair`, `TimeZone`, `TourViolation`, `UUIDModel`, `WayPoints`, `WaypointViolation`. `Duration`, `Incompatibility`, and `RegexIdValidation` stay, as type aliases of `str` or of a list of strings. Calling `Duration` or `RegexIdValidation` still returns the plain string, without validating it, so code that used one to validate now passes silently. Calling `Incompatibility` raises `TypeError`: pass a plain list such as `["a", "b"]` instead. Validation happens when a model field is parsed. `isinstance()` with one of them raises `TypeError`. Where you built `models.Capacities({...})`, pass the dictionary itself, such as `capacities={"weight": 200}`. This works in 1.1.0 too.
* `str()` of an enum value gives its value: `str(PlanState.optimized)` is `"optimized"`, and an f-string or `format()` prints the same.
* `plans.get_status()` always returns a `PlanState`, never a plain `str`, even for a state that this version of the SDK doesn't know yet. An unknown state comes back as a `PlanState` that equals its raw string. Compare it with a string or with the enum, as both work.
* A last-in-first-out constraint (`AdditionalConstraintRemovalStrategy`) and its violation (`RemovalStrategyViolation`) name the unloading order `strategy`, as the API reads and returns it. Write `strategy="lifo"` instead of `removalStrategy="lifo"`, which the API ignored, and read `violation.strategy` instead of `violation.removalStrategyType`.
* The validation errors of an invalid stop keep their path under the `single`, `alternatives`, or other `type` of the stop that you wrote, and none is reported for the other types.

**Fixes**

* `plans.get_status() == "optimized"` is `True` when the plan is optimized. Before, the comparison could be `False`.
* `json.dumps` accepts an id, a version, or a state that you read from a plan or a solution.
* A stop that you write without `stopKind` no longer logs a warning.
* A solution with a tour that breaks a last-in-first-out unloading order can be read. Before, reading it failed with a validation error.

**Other changes**

* The descriptions of the models follow the current API specification, such as the durations of tours and breaks and the rest between the days of a multi-day shift. This release targets API 1.0.2.
* The Python examples of the SDK pages and the guides are run in a test before each release, against a mocked API.
* `kardinal init` writes a skill that Claude Code loads, `.claude/skills/kardinal-python/SKILL.md`, instead of `.kardinal/SKILL.md`. It lists the pitfalls of an integration and links to the docs. Run it again at the root of your repository, and delete the old `.kardinal/SKILL.md`.
* `examples.cold_chain_plan()` and `examples.parcel_express_plan()` return the plans of the [cold-chain](https://developers.kardinal.ai/case-studies/cold-chain-last-mile.md) and [parcel express](https://developers.kardinal.ai/case-studies/parcel-express.md) case studies, as typed objects to adapt to your data.

**1.1.0**

Released on 2026-10-23. Each 403 error gets its own class, truck dimensions are whole centimetres, and two fixes

This release changes behaviour in ways that can break existing code, so read the first section before you upgrade. To stay on 1.0.0 until you're ready, write `kardinal-ai<1.1` in your `requirements.txt` or `pyproject.toml` instead of a plain `kardinal-ai`. A one-off `pip install "kardinal-ai<1.1"` only changes the current environment.

**Changes that can affect your code**

* A `403` error now raises a class that matches its cause. A revoked or regenerated key raises `KardinalAuthError`, with `.status` set to `403`. An archived plan that you update, stop, or restart without `force` raises `KardinalValidationError`, with no field path in `.errors`. A `403` stays a `KardinalLimitError` only when it carries a clue of a limit: plan size, quota, or credits. Any other `403` raises a new public class, `KardinalForbiddenError`.

* Code that catches `KardinalLimitError` to handle a revoked key or an archived plan no longer catches them. Catch `KardinalAuthError` or `KardinalValidationError` instead. This code works in 1.0.0 and in 1.1.0:

  ```python theme={null}
  try:
      k.routing.plans.update(plan)
  except KardinalError as e:
      if e.status == 403:
          ...  # read e.details and e.errors to tell the cases apart
      else:
          raise
  ```

* `height`, `width`, and `length` of `VehicleProfileTruck` are whole centimetres, typed `int`, so a type checker now flags a `float`. A decimal value such as `4.2` is refused before sending, and building the profile raises `pydantic.ValidationError`. A decimal that you set on a profile after it is built isn't checked, and the API refuses it with a `400`. Round after converting from metres, with `round(width_m * 100)`, because `2.55 * 100` is `254.99999999999997`. If you set these dimensions with 1.0.0, check the values. A whole number in metres, such as `length=12`, is read as 12 centimetres with no error.

* `SolutionObjective.name` is a plain string. `.name.root` no longer exists, and `==` and `str()` work as before.

* A `maxCumulatedCost` constraint without `maximum` raises `pydantic.ValidationError` when you build the plan. The API already refused it with a `400`, so what changes is the moment and the class of the error.

**Fixes**

* `solutions.get()`, `wait()`, and `get_objectives()` no longer fail with a validation error on a plan that uses the `maximizePrecedences` objective.
* `update()` sends back the fields that were read or set, not the SDK's defaults. Before, sending back an unchanged plan created outside the SDK created a new version and optimized the plan again, once per plan.

**Other changes**

* The descriptions of the models follow the current API specification.
* The PyPI "Documentation" link, the README, and the `.kardinal/SKILL.md` file written by `kardinal init` point to the SDK pages. PyPI and the README link to this changelog.
* `submit()` sends `disableGroupProximity: false` when the plan doesn't set it, which is also the API's default.

**1.0.0**

Released on 2026-10-12. First public release, targeting API 1.0.1

* Synchronous client for every endpoint of the Route Optimization API: `plans.submit`, `get`, `update`, `delete`, `list`, `iter_all`, `start`, `stop`, `get_status`, and `solutions.get`, `get_objectives`, `wait`.
* `pydantic` models generated from the API specification, with the API's field names and descriptions.
* Misspelled keys refused before sending (`UnknownFieldError`), with the closest real field name; `allow_unknown` to send a field the SDK doesn't know yet.
* `solutions.wait`, which follows a plan's optimization and returns its solution once it's over.
* Typed exceptions for every API error, with `.errors`, `.details`, and `.retryable`; any `403` raised as `KardinalLimitError`.
* Automatic retries of reads, `update`, `delete`, `start`, and `stop`; `submit` is never retried.
* Optional `kardinal` command-line tool (`pip install "kardinal-ai[cli]"`), with local plan validation.
* Python 3.10 or later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.