Merge remote-tracking branch 'origin/tviehmann/extensions'

Author: TarikViehmann

.cmakelint.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2024-2025 Carologistics
+# Copyright (c) 2024-2026 Carologistics
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

.pre-commit-config.yaml

@@ -151,7 +151,8 @@ repos:
         entry: ament_cpplint
         language: system
         stages: [manual]
-        exclude: /templates/
+        pass_filenames: true
+        exclude: 'jinja'
 
       # -------------------------------
       # Python Linters
@@ -188,3 +189,5 @@ repos:
         language: system
         files: \.(launch|xml)$
         stages: [manual]
+
+exclude: (^extensions/pddl/cx_z3_vendor/|^extensions/pddl/cx_up_nextflap/)

clips_executive/cx_docs/conf.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2024-2025 Carologistics
+# Copyright (c) 2024-2026 Carologistics
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -33,7 +33,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 ros_distro = os.getenv('ROS_DISTRO', 'humble')  # Default to 'humble' if ROS_DISTRO is not set
 
-extensions = ['sphinx.ext.extlinks', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.extlinks', 'sphinx.ext.todo', 'sphinx_copybutton']
 local = True
 
 

clips_executive/cx_docs/extensions/PDDL.rst

@@ -0,0 +1,47 @@
+PDDL Integration for CLIPS
+==========================
+
+This extension provides an implementation for using PDDL alongside CLIPS.
+
+If you need one of the following features, you may find this useful:
+
+- A structured model of action and change to progress the CLIPS fact base according to a robots actions
+- Unified sanity checks to ensure actions can only be executed if conditions are currently met according to the fact base
+- Automated planning to reach complex objectives by means of computing and executing plans consisting of individual robot actions
+
+Background: PDDL
+++++++++++++++++
+
+The Planning Domain Definition Language (PDDL) is the de facto standard language for expressing planning problems in artificial intelligence.
+A PDDL problem consists of
+
+ - a domain description, which defines the available objects, predicates, actions and their preconditions and effects,
+ - a problem description, which specifies the initial state and desired goals.
+
+Given such a description, a PDDL planner computes a sequence of actions (a plan) that transforms the initial state into one that satisfies the goal conditions.
+
+An example PDDL problem can be found `here <pddl/domain.html>`_.
+
+
+Overview
+++++++++
+
+This extension leverages the `Unified Planning Framework (UPF)`_, which supports a wide range of PDDL standards.
+UPF is wrapped and exposed as a ROS node, hence interfacing is done via the regular |CX| plugins.
+
+In order to reduce the manual overhead, an optional CLIPS abstraction layer is provided, which takes care of the ROS communication.
+
+Additionally, this extension contain the `NEXTFLAP planner`_, which can handle both classical and temporal PDDL variants.
+This planner requires the `z3 constraint solver`_, which is also provided.
+
+Content
++++++++
+
+.. toctree::
+   :maxdepth: 2
+
+   pddl/usage.rst
+   pddl/pddl_clips.rst
+   pddl/domain.rst
+   pddl/raw_tutorial.rst
+   pddl/structured_tutorial.rst

clips_executive/cx_docs/extensions/index.rst

@@ -0,0 +1,10 @@
+.. _extensions:
+
+Extensions
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   PDDL.rst
+   reinforcement_learning.rst

clips_executive/cx_docs/extensions/pddl/PDDL.rst

@@ -0,0 +1,102 @@
+PDDL Domain and Problem File Example
+####################################
+
+This is how a PDDL domain file looks like:
+
+.. code-block:: pddl
+
+  (define (domain blocksworld)
+      (:types
+          block - object
+      )
+
+
+      (:predicates
+          (on ?x - block ?y - block) ; object ?x is on ?object ?y
+          (on-table ?x - block) ; ?x is directly on the table
+          (clear ?x - block) ; ?x has nothing on it
+          (arm-empty) ; robot isn't holding anything
+          (holding ?x - block)) ; robot is holding ?x
+
+      (:durative-action pick-up
+          :parameters (?ob - block)
+          :duration (= ?duration 10)
+          :condition
+              (and
+                  (at start (clear ?ob))
+                  (at start (on-table ?ob))
+                  (at start (arm-empty)))
+          :effect
+              (and
+                  (at end (not (on-table ?ob)))
+                  (at end (not (clear ?ob)))
+                  (at end (not (arm-empty)))
+                  (at end (holding ?ob))))
+
+      (:durative-action put-down
+          :parameters (?ob - block)
+          :duration (= ?duration 10)
+          :condition (at start (holding ?ob))
+          :effect
+              (and
+                  (at end (not (holding ?ob)))
+                  (at end (clear ?ob))
+                  (at end (arm-empty))
+                  (at end (on-table ?ob)))
+      )
+
+      (:durative-action stack
+          :parameters (?ob1 - block ?ob2 - block)
+          :duration (= ?duration 10)
+          :condition (and (at start (holding ?ob1)) (at start (clear ?ob2)))
+          :effect
+              (and
+                  (at end (not (holding ?ob1)))
+                  (at end (not (clear ?ob2)))
+                  (at end (clear ?ob1))
+                  (at end (arm-empty))
+                  (at end (on ?ob1 ?ob2)))
+      )
+
+      (:durative-action unstack
+          :parameters (?ob1 - block ?ob2 - block)
+          :duration (= ?duration 10)
+          :condition
+              (and
+                  (at start (on ?ob1 ?ob2))
+                  (at start (clear ?ob1))
+                  (at start (arm-empty)))
+          :effect
+              (and
+                  (at end (holding ?ob1))
+                  (at end (clear ?ob2))
+                  (at end (not (clear ?ob1)))
+                  (at end (not (arm-empty)))
+                  (at end (not (on ?ob1 ?ob2))))
+      )
+  )
+
+This is how a matching PDDL problem file would look like:
+
+.. code-block:: pddl
+
+  (define (problem blocksworld-problem)
+      (:domain blocksworld)
+
+      (:objects A B C - block)
+
+      (:init
+          (arm-empty)
+          (on-table A)
+          (on B A)
+          (on C B)
+          (clear C)
+      )
+
+      (:goal
+          (and
+              (on A B)
+              (on B C)
+          )
+      )
+  )