Skip to main content
Releases of kardinal-ai. For changes to the API itself, see the API changelog.
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.
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.
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.
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.
  • 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.
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.
  • The skill that kardinal init writes points to the Integration paths 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.
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 and parcel express case studies, as typed objects to adapt to your data.
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:
  • 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.
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.