Skip to main content
A path is a reading order for one task. It lists the steps of the task in the order you do them. Each step links the section to read, and nothing more.

Integrate route optimization into an existing application with an SDK

Use this path when you add Kardinal to an application that already exists. You use the Python SDK or the TypeScript SDK. The steps are in four stages.

Stage 1: before you write code

  1. Read the checklist Start here if you’re an AI agent. Start with the “At a glance” table. Then read rule 1, rule 2, rule 3, rule 5, rule 6, and rule 9.
  2. Use the Requirements briefing checklist. Ask the user every question at once. Include the question about where the sandbox and production keys are. Then wait for the answers before you write the code that builds the plan. In the meantime, you can write the rest, such as reading the key, submitting the plan, and the screens. Don’t turn on an option such as lateDeparture or withTraffic, and don’t add breaks, unless the data or the user asks for it. If the user can’t answer now, leave each unanswered option unset, and make it a setting the operator can fill in. The operator is the company whose tours your app plans. Then list these settings for the user. The working time window (workingTimeWindow) is required, so it can’t stay unset. Read it from the operator’s data, such as each driver’s shift, or from a setting the operator fills in. Never write it as a constant in your code. If nobody can answer during your session, give that setting a starting value so the app can plan. Keep it in the settings, not in the code, and list it for the user as your assumption.
  3. Find the closest case study, for example Cold-chain last-mile. Use it as a starting point. Don’t copy it as a model. Its settings, such as withTraffic, its working hours and its breaks, belong to that example’s client. Keep one in your code only when the user confirms it. The SDK returns it as a typed plan: examples.cold_chain_plan() in Python, and examples.coldChainPlan() in TypeScript.

Stage 2: write the plan

  1. Follow the Quickstart. Then read Loading an existing JSON payload and Validating locally before you spend credits. In Python, build the plan with PlanCreate.model_validate_json. In TypeScript, build it with parsePlanCreate. Run kardinal init in your project. The kardinal command needs an extra install. In Python, install "kardinal-ai[cli]". In TypeScript, also install commander. See Installing the command-line tool. It writes a skill that tells your coding assistant how to use the SDK.
  2. Read these sections only when the question comes up.

Stage 3: follow the optimization from a web backend

  1. Check the API key when your application starts. Call whoami, then compare the agency it returns with the one in your configuration. A sandbox key and a production key look alike. Read Checking the key at startup.
  2. Read Waiting in a web backend or serverless function. Submit the plan, then store its id. Read the state later. Never call wait inside an HTTP request.
  3. Keep the warnings that submit, update, and replace return, for example next to the plan id. A later get doesn’t return them. Show them in your application to the person who submitted the plan, for example the planner. The API returns a warning when it changes part of your plan, for example when you ask for a longer maxOptimizationDuration than your limit allows. The sandbox also returns warnings that production doesn’t, for example when it forces straight-line (crow-fly) distances. These warnings aren’t errors. Build the message for the planner from properties.path and the value stored at that path, not from message or details. The SDKs also write each kind of warning in your logs. Read Warnings on successful calls.
  4. Keep the id of the plan you submit for each day. When the planner runs that day again, for example with other settings, call replace on that id. Don’t call submit again. A new plan bills every stop again. The same plan, with the same stops, isn’t billed again within 24 hours of its creation. Read Replacing a plan from your own data and How credits work.

Stage 4: test, then go to production

  1. Read Differences between sandbox and production. The sandbox limits the optimization time. Wait about one minute at most, as rule 9 says.
  2. Read Sizing maxOptimizationDuration for a large problem before you run a large plan.
  3. Read How credits work. Tell the user before you run a plan in production.
When you read a solution, use Reading the result. It shows how to list the stops of each tour, with their times. It also shows how to find the stops that the engine could not plan.