kardinal-ai. For changes to the API itself, see the API changelog.
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.This release doesn’t change the code you write.New
kardinal initwrites 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.mdfor Claude Code. See Project setup for AI coding assistants.
- The descriptions of the models follow the API reference.
sharedCapacitiesnow says what it really changes: how the engine treats apickupwith a negative quantity.Warningsays thatproperties.pathis 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 newPlanCreate, the input thatsubmit()takes. You don’t copyid,agencyId, orversion. See Replacing a plan from your own data.
submit(),update(), andreplace()log each kind of API warning on thekardinallogger, at theWARNINGlevel. Python prints these lines on stderr, with no logging setup. To silence them, writelogging.getLogger("kardinal").setLevel(logging.ERROR). A program should keep readingplan.warnings. See Warnings on successful calls.- The skill that
kardinal initwrites points to the Integration paths page first.
solutions.wait()right afterplans.start()now waits for the new run. Before, you could restart a plan that was still optimizing, andwait()returned after 10 seconds. It returned the previous run’s solution, withfinal_stateset tointerrupted.
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
.rootno longer exists on them.plan.id,stop.id,tour.resourceId,waypoint.stopId, andplan.tzarestr.tour.wayPointsis a list ofWayPointBegin,WayPointStop,WayPointBreak, andWayPointEnd, so writewaypoint.typeinstead ofwaypoint.root.type. A tour’s violations, the plan’s global constraints, and the solution’s global violations work the same way. Remove every.rootthat reads one of these values.==andstr()give the same results as before on ids. - 36 classes are removed from
kardinal.routing.models, because the value they wrapped is now a plainstr,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, andRegexIdValidationstay, as type aliases ofstror of a list of strings. CallingDurationorRegexIdValidationstill returns the plain string, without validating it, so code that used one to validate now passes silently. CallingIncompatibilityraisesTypeError: pass a plain list such as["a", "b"]instead. Validation happens when a model field is parsed.isinstance()with one of them raisesTypeError. Where you builtmodels.Capacities({...}), pass the dictionary itself, such ascapacities={"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 orformat()prints the same.plans.get_status()always returns aPlanState, never a plainstr, even for a state that this version of the SDK doesn’t know yet. An unknown state comes back as aPlanStatethat 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 orderstrategy, as the API reads and returns it. Writestrategy="lifo"instead ofremovalStrategy="lifo", which the API ignored, and readviolation.strategyinstead ofviolation.removalStrategyType. - The validation errors of an invalid stop keep their path under the
single,alternatives, or othertypeof the stop that you wrote, and none is reported for the other types.
plans.get_status() == "optimized"isTruewhen the plan is optimized. Before, the comparison could beFalse.json.dumpsaccepts an id, a version, or a state that you read from a plan or a solution.- A stop that you write without
stopKindno 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.
- 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 initwrites 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()andexamples.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
403error now raises a class that matches its cause. A revoked or regenerated key raisesKardinalAuthError, with.statusset to403. An archived plan that you update, stop, or restart withoutforceraisesKardinalValidationError, with no field path in.errors. A403stays aKardinalLimitErroronly when it carries a clue of a limit: plan size, quota, or credits. Any other403raises a new public class,KardinalForbiddenError. -
Code that catches
KardinalLimitErrorto handle a revoked key or an archived plan no longer catches them. CatchKardinalAuthErrororKardinalValidationErrorinstead. This code works in 1.0.0 and in 1.1.0: -
height,width, andlengthofVehicleProfileTruckare whole centimetres, typedint, so a type checker now flags afloat. A decimal value such as4.2is refused before sending, and building the profile raisespydantic.ValidationError. A decimal that you set on a profile after it is built isn’t checked, and the API refuses it with a400. Round after converting from metres, withround(width_m * 100), because2.55 * 100is254.99999999999997. If you set these dimensions with 1.0.0, check the values. A whole number in metres, such aslength=12, is read as 12 centimetres with no error. -
SolutionObjective.nameis a plain string..name.rootno longer exists, and==andstr()work as before. -
A
maxCumulatedCostconstraint withoutmaximumraisespydantic.ValidationErrorwhen you build the plan. The API already refused it with a400, so what changes is the moment and the class of the error.
solutions.get(),wait(), andget_objectives()no longer fail with a validation error on a plan that uses themaximizePrecedencesobjective.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.
- The descriptions of the models follow the current API specification.
- The PyPI “Documentation” link, the README, and the
.kardinal/SKILL.mdfile written bykardinal initpoint to the SDK pages. PyPI and the README link to this changelog. submit()sendsdisableGroupProximity: falsewhen the plan doesn’t set it, which is also the API’s default.
- Synchronous client for every endpoint of the Route Optimization API:
plans.submit,get,update,delete,list,iter_all,start,stop,get_status, andsolutions.get,get_objectives,wait. pydanticmodels 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_unknownto 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; any403raised asKardinalLimitError. - Automatic retries of reads,
update,delete,start, andstop;submitis never retried. - Optional
kardinalcommand-line tool (pip install "kardinal-ai[cli]"), with local plan validation. - Python 3.10 or later.

