Metadata-Version: 2.4
Name: up-kairos
Version: 0.1.0
Summary: Kairos, a temporal and numeric PDDL planner, as an engine of the Unified Planning Framework
Author-email: Francisco Martín Rico <fmrico@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/PlanSys2/up-kairos
Project-URL: Kairos, https://github.com/PlanSys2/kairos
Keywords: planning,pddl,unified-planning,aiplan4eu,temporal planning,robotics
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: unified-planning>=1.3
Requires-Dist: kairos-planner>=1.0.3
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# up-kairos

[Kairos](https://github.com/PlanSys2/kairos), a temporal and numeric PDDL planner, as an engine
of the [Unified Planning Framework](https://github.com/aiplan4eu/unified-planning) (UPF).

Kairos plans in the same process (no files, no subprocess), anytime, and proves when no plan
exists. Every plan is validated before it is returned.

```bash
pip install up-kairos
```

```python
import up_kairos
from unified_planning.shortcuts import OneshotPlanner

up_kairos.register()  # until UPF lists Kairos among its engines

with OneshotPlanner(name="kairos") as planner:
    result = planner.solve(problem, timeout=10)
    print(result.status, result.plan)
```

## Operation modes

| UPF | Kairos |
|---|---|
| `OneshotPlanner` | a plan; with a quality metric and a timeout, the best within it |
| `AnytimePlanner` | each better plan as it comes (increasing quality), then the best |
| `PlanValidator` | Kairos' validator: VAL's semantics, numeric, temporal, PDDL3 |
| `Replanner` | through UPF's meta engine: `Replanner(problem, name="replanner[kairos]")` |

Results:

- `SOLVED_OPTIMALLY` when Kairos proves the plan optimal for the problem's metric.
- `UNSOLVABLE_PROVEN` when it proves there is no plan: the search space runs out, the timed
  literals take what the goal needs too soon, or there is no plan even without durations.
- `UNSOLVABLE_INCOMPLETELY` when the engines that apply ran out of states without being
  complete for the task.
- `TIMEOUT`, `MEMOUT`, `UNSUPPORTED_PROBLEM`.

Kairos' diagnostics, including why there is no plan, are in `result.log_messages`. Its
statistics are in `result.metrics`: expanded nodes, states, plans and peak memory.

## Problems

Kairos plans with:

- **Classical planning**, with negative, disjunctive, existential and universal conditions and
  conditional effects.
- **Numeric planning**, linear or not, with bounded numeric fluents and undefined values.
- **Object fluents.**
- **Temporal planning**, with required concurrency, timed effects (timed initial literals and
  fluents), duration inequalities and durations that read fluents.
- **Continuous effects, processes and events** (PDDL+).
- **Trajectory constraints and state invariants.**
- **Quality metrics**: action costs, plan length, makespan, final value, and oversubscription.

It plans 52 of the 66 example problems of UPF 1.3. The rest are hierarchical, scheduling,
integer or boolean parameters, intermediate conditions, timed goals and undefined booleans.

Notes:

- **Writing for Kairos.** Some things go beyond what UPF's PDDL writer writes, so this engine
  writes them itself:
  - object fluents, as PDDL 3.1;
  - oversubscription, as goal preferences and a metric of the gain lost;
  - bounded fluents, as state invariants.
- **One instance at a time.** A durative action does not overlap itself, as in POPF:
  `SELF_OVERLAPPING` is not declared.
- **Simultaneous happenings follow PDDL 2.1 and VAL.** Happenings that interfere need epsilon
  between them (`problem.epsilon`, 0.001 by default). Kairos' plans keep that separation.
- **PDDL+ plans and their end.** A PDDL+ plan ends when the goal is checked, after letting
  processes and events act. UPF's plans have no end time, so it comes in
  `result.metrics["kairos_plan_end"]`, and `PlanValidator` answers `UNKNOWN` for PDDL+.

## Options

`OneshotPlanner(name="kairos", params={...})`:

- `anytime`
- `timeout`: the default when the call gives none.
- `threads`
- `memory_limit_mb`
- `engine`: `"auto"`, `"m1"`, `"m2"` or `"m3"`.
- `search`
- `seed`
- `stop_after_no_improvement`
- `target_cost`

## License

Apache-2.0.
