Kairos (καιρός)

A modern temporal and numeric PDDL planner in C++20, usable as a library and as an executable.

Kairos aims to be a reference PDDL planner: broad language coverage, efficient on large problems, robust, and easy to embed. It is developed within the PlanSys2 organization and will become a planner for PlanSys2, but it does not depend on ROS.

How it compares: on classical, numeric, temporal and robotics benchmarks, and on PlanSys2 problems scaled up to thousands of objects, Kairos solves more problems than LAMA, the winners of the IPC 2023 classical and numeric tracks, OPTIC, TFD, POPF, ENHSP and the other planners it was measured against, under the same limits, and as many or more of them within 100 ms and 1 s. Results and method in docs/benchmark.md; which PDDL features each planner handles in docs/pddl-support.md.

Why another planner?

The planners that cover most of PDDL 2.1 (POPF, OPTIC, TFD, LPG) are no longer maintained, are hard to build, and were not designed to be used as libraries: global state, no cancellation, plans returned through stdout. The actively developed ones cover only part of the language (numeric but not temporal, or temporal without temporal heuristics). Very few optimize metrics that combine time and numeric fluents.

Kairos is written from scratch to close that gap.

Goals

• Coverage. PDDL 2.1 level 3 (durative actions, required concurrency, numeric fluents), PDDL 2.2 (derived predicates, timed initial literals), full ADL also inside durative actions, and general metrics. PDDL 3 constraints and preferences and object fluents. Later: PDDL+.
• Efficiency. A fast engine for temporally simple problems (action compression plus rescheduling) and a complete one for required concurrency (snap actions with partial-order states and an incremental STN), chosen automatically by analyzing the task.
• Anytime. Get the first valid plan as soon as possible, keep searching in the background, and receive each better plan through a callback.
• Modest hardware. Plan on the robot’s own computer (Raspberry Pi, Jetson): memory has a budget by default, and Kairos degrades gracefully instead of failing when it gets close.
• Robustness. Precise error messages with file, line and column; no crash on malformed input; cancellable; deterministic with a fixed seed.
• Easy to use. A small C++ API without global state, a command-line tool, PDDL validation without planning, and human-readable debug output per planner stage.
• Measured. A reproducible benchmark against the existing planners on IPC domains and on scaled-up PlanSys2 problems, with every plan checked by an independent validator.

Usage

#include <kairos/kairos.hpp>

// From files...
auto domain = kairos::load_domain("domain.pddl");
auto problem = kairos::load_problem("problem.pddl", *domain);
// ...or from strings already in memory
auto domain2 = kairos::parse_domain(domain_text);
auto problem2 = kairos::parse_problem(problem_text, *domain2);
// (on failure, ok() is false and diagnostics() say what and where)

kairos::Planner planner;

// In the calling thread: the best plan within the timeout
kairos::SolveOptions options;
options.timeout = std::chrono::seconds(10);
kairos::SolveResult result = planner.solve(*problem, options);
if (result.status == kairos::Status::Solved) {
  std::cout << kairos::to_string(*result.plan, kairos::PlanFormat::Ipc);
}

// Anytime, in its own thread: first plan as soon as possible, better ones through the callback
kairos::SearchOptions anytime;
anytime.timeout = std::chrono::seconds(60);
kairos::Search search = planner.start(*problem, anytime,
  [](const kairos::PlanUpdate & update) {
    // update.plan (validated, with its cost), update.index, update.elapsed
  });
auto first = search.wait_first(std::chrono::seconds(5));
kairos::SolveResult best = search.wait();  // or search.stop(); destroying it stops it too

result.status tells what happened (Solved, Unsolvable (proved), NoPlanFound (no proof), Timeout, Cancelled, OutOfMemory, Unsupported, InvalidInput, GroundingTooLarge), result.stop_reason why a

File truncated at 100 lines see the full file

Changelog for package kairos

1.0.4 (2026-10-18)

• The validator with epsilon 0 (ValidateOptions::epsilon, kairos validate --epsilon 0): no separation, so a happening may read what another at the same instant writes (conditions read the state before, effects apply together), as UPF validates problems without an epsilon. Writes that disagree are still interference.
• Contributors: Francisco Martín Rico

1.0.3 (2026-10-18)

• Python: pip install kairos-planner (wheels for Linux x86-64 and arm64): parse, check, plan (blocking, in the background or as an iterator of better plans) and validate, with the diagnostics; planning releases the GIL and Ctrl-C stops it. The wheel has the kairos command too.
• A search stopped by the caller while the steps of time were still searching after M3 ran out of states is cancelled, not "no plan found".
• The static libkairos is position independent (it links into shared objects).
• The goal holds after the last timed initial literal too, as VAL and the validator check it: M3 took a goal state as a plan before later literals, and every plan it found could fail validation (an internal error). A goal state of M3 with timed literals counts once its plan is valid; the search goes on otherwise.
• Reads the PDDL that UPF's writer gives: several constraints in :constraints without and, and timed initial fluents as (at t (assign (f) v)) (with a warning).
• Python: SearchOptions given to solve (what SolveOptions has).
• Contributors: Francisco Martín Rico

1.0.2 (2026-10-18)

• Proofs that a temporal task has no plan: the timed initial literals take away what the goal needs too soon (from the initial state, ignoring deletes, with the shortest durations), or the task without durations nor times has no path to the goal (when M3 runs out of states).
• Steps of time: the time is kept only with timed initial literals, until the last one, and epsilon passes only right after a happening; tiny tasks that ran to the timeout end in ms.
• With several threads, the phases for when there is no plan stop once another finds one.
• M3 out of states while the steps of time run out of time is a timeout, not "no plan found".
• The deadlines of M3 no longer take durations that change as bounds, nor over all conditions an action's start gives itself as needed before it.
• Contributors: Francisco Martín Rico

1.0.1 (2026-10-17)

• Builds on Ubuntu 22.04 and ROS 2 Humble: CMake 3.22 is enough (nothing needed 3.24), and the CI builds the Humble packages as the buildfarm does.
• The style test is disabled, with a warning, when uncrustify is older than its configuration (0.78).
• Why there is no plan: an unreachable goal is now traced to the static fact that is really missing (the initial facts that grounding leaves out of the task count as reachable).
• Contributors: Francisco Martín Rico

1.0.0 (2026-10-14)

• PDDL+: processes, events, global constraints and continuous effects (linear and non-linear), planned in steps of time and validated in continuous time.
• Durations between their bounds and non-linear numeric conditions in the heuristics.
• Planning without grounding: a lifted engine for tasks with millions of ground actions.
• Status NoPlanFound (exit code 14): Unsolvable now needs a proof.
• A bank of benchmarks per PDDL feature (https://github.com/PlanSys2/kairos-benchmarks), and the bugs it found fixed: object fluents without a value, timed initial fluents in M2 and M3, required concurrency between two variables, deadlines with derived atoms, waits longer than 2000 s, incremental goals that must break a goal true from the start.
• Every PDDL feature that kairos --features lists is fully supported.
• Without a plan, a note says why and which option could change it (orchestrator.why).
• Builds as a ROS 2 package for Jazzy, Kilted and Lyrical on every buildfarm target (Ubuntu amd64 and arm64, RHEL 9 and 10, Fedora): no <format> (GCC 11), no whole-archive linking (CMake 3.28), the library in lib under /opt/ros and the command with a relative RUNPATH; the tests follow BUILD_TESTING. A CI job builds the packages as the buildfarm.
• The library's SONAME is libkairos.so.1: the ABI is stable within a major version.
• Contributors: Francisco Martín Rico

0.5.0 (2026-10-13)

• Ahead of LAMA and of the winners of the IPC 2023 on classical planning.
• PDDL3 preferences and trajectory constraints; changing object

File truncated at 100 lines see the full file