CaSkade Planner - Capability-based Process Planning using SMT

CaSkade-Planner is an automated planning approach to derive process sequences that consist of provided capabilities for one or more required capabilities. It makes use of the CaSk ontology. There are different ways to install and use this tool:

1. Install and run locally
2. Run as a docker container
3. Integrate into your own Python scripts

You can find detailed instructions to every option in the sections below.

Local Installation

Make sure that you have Poetry installed. Clone this repository, open a terminal inside the repo's root folder and install everything using poetry install. Afterwards you can use CaSkade-Planner according to the instructions below.

CLI

CaSkade-Planner provides a command-line interface with two main commands. You can always open the help with the --help option.

Plan from local ontology file

To plan from a local ontology file, use: poetry run caskade-planner-cli plan-from-file

``` Arguments: ONTOLOGYFILE Path to your ontology that is used for generating the planning problem [required] REQUIREDCAPABILITY_IRI IRI of the required capability to plan for [required]

Options: -mh, --max-happenings INTEGER Maximum number of happenings to consider [default: 20] -problem, --problem-file TEXT Path to where the generated problem will be stored -model, --model-file TEXT Path to where the model file will be stored after solving -plan, --plan-file TEXT Path to where the plan file will be stored after solving and transformation --help Show this message and exit. ```

Example: bash poetry run caskade-planner-cli plan-from-file my-ontology.ttl http://example.org/capabilities#RequiredCapability1

Plan from SPARQL endpoint

To plan directly from a SPARQL endpoint, use: poetry run caskade-planner-cli plan-from-endpoint

``` Arguments: ENDPOINTURL URL of the SPARQL endpoint [required] REQUIREDCAPABILITY_IRI IRI of the required capability to plan for [required]

Options: -mh, --max-happenings INTEGER Maximum number of happenings to consider [default: 20] -problem, --problem-file TEXT Path to where the generated problem will be stored -model, --model-file TEXT Path to where the model file will be stored after solving -plan, --plan-file TEXT Path to where the plan file will be stored after solving and transformation --help Show this message and exit. ```

Example: bash poetry run caskade-planner-cli plan-from-endpoint http://localhost:7200/repositories/test-repo http://example.org/capabilities#RequiredCapability1

The plan-from-endpoint command outputs the result as JSON to stdout, making it easy to integrate with other tools.

REST-API

If you want to use CaSkade-Planner as a standalone planning service to be used by other software components, you can integrate it as a REST API. After cloning and installing the project, start the REST API by calling poetry run caskade-planner-api. The planning API runs on port 5000.

Endpoints

• GET /ping - Health check endpoint (returns 204 No Content)
• POST /plan - Main planning endpoint

Planning Request

Send an HTTP POST request to <API-Address>:5000/plan with a JSON body:

json { "mode": "file" | "sparql-endpoint", "requiredCapabilityIri": "<IRI of the required capability>", "maxHappenings": 5, // optional, defaults to 5 "endpointUrl": "<SPARQL endpoint URL>" // only for mode="sparql-endpoint" }

For mode="file", you need to upload the ontology file as multipart/form-data with the key "ontology-file".

Response Format

Both CLI and REST API return results in JSON format:

json { "timeCreated": "2024-01-01T12:00:00Z", "resultType": "sat" | "unsat", "plan": { // only if resultType="sat" "plan_steps": [...], "plan_length": 5, "total_duration": 120 }, "unsatCore": [...] // only if resultType="unsat" }

Docker

CaSkade-Planner is available as a Docker image on Docker Hub at aljoshakoecher/caskade-planner. The image supports multiple modes of operation through a flexible entrypoint system.

Quick Start

Pull the latest image:

bash docker pull aljoshakoecher/caskade-planner:latest

Run REST API:

bash docker run -p 5000:5000 aljoshakoecher/caskade-planner:latest rest

Run CLI commands:

```bash

Plan from file

docker run -it --rm -v "$(pwd):/data" \ aljoshakoecher/caskade-planner:latest \ plan-from-file /data/my-ontology.ttl http://example.org/capabilities#RequiredCapability1

Plan from endpoint

docker run -it --rm \ aljoshakoecher/caskade-planner:latest \ plan-from-endpoint http://host.docker.internal:7200/repositories/test-repo http://example.org/capabilities#RequiredCapability1 ```

Available Commands

The Docker image supports the following commands through its entrypoint:

rest - Start REST API Server

bash docker run -p 5000:5000 aljoshakoecher/caskade-planner:latest rest Starts the REST API server on port 5000. The API will be accessible at http://localhost:5000.

plan-from-file - Direct File Planning

bash docker run -it --rm -v "$(pwd):/data" \ aljoshakoecher/caskade-planner:latest \ plan-from-file /data/ontology.ttl http://capability.iri [OPTIONS]

Available options: - --max-happenings INTEGER (default: 20) - --problem-file TEXT - --model-file TEXT - --plan-file TEXT

plan-from-endpoint - Direct Endpoint Planning

bash docker run -it --rm \ aljoshakoecher/caskade-planner:latest \ plan-from-endpoint http://endpoint-url http://capability.iri [OPTIONS]

cli - Full CLI Access

bash docker run -it --rm -v "$(pwd):/data" \ aljoshakoecher/caskade-planner:latest \ cli plan-from-file /data/ontology.ttl http://capability.iri

bash - Interactive Shell

bash docker run -it --rm -v "$(pwd):/data" \ aljoshakoecher/caskade-planner:latest bash

Legacy Commands (Still Supported)

For backward compatibility, the original commands still work:

```bash

Original CLI usage

docker run -it --rm -v "$(pwd):/data" \ aljoshakoecher/caskade-planner:latest \ caskade-planner-cli plan-from-file /data/my-ontology.ttl http://example.org/capabilities#RequiredCapability1 ```

Docker Compose Integration

For integration into larger systems, you can use Docker Compose:

yaml version: '3.8' services: caskade-planner: image: aljoshakoecher/caskade-planner:latest ports: - "5000:5000" volumes: - ./data:/data # Default command starts REST API # Override with: command: ["plan-from-file", "/data/ontology.ttl", "http://cap.iri"]

Notes

• File Access: Mount your local directory with -v "$(pwd):/data" to access local ontology files from within the container
• Network Access: Use host.docker.internal instead of localhost to access services on your host machine from within the container
• Data Persistence: Results can be saved to mounted volumes using the file output options
• Health Checks: The REST API includes a health check endpoint at /ping for monitoring

Python Integration

If you want to integrate CaSkade-Planner directly into your Python scripts, you can use it as a library.

Installation

Using pip: bash pip install caskade-planner

Using Poetry: bash poetry add caskade-planner

Basic Usage

```python from smtplanning.smt.casktosmt import CaskadePlanner from smtplanning.planning_result import PlanningResultType

Create planner instance with required capability

planner = CaskadePlanner("http://example.org/capabilities#RequiredCapability1")

Option 1: Load ontology from file

planner.withfilequery_handler("my-ontology.ttl")

Option 2: Use SPARQL endpoint

planner.withendpointquery_handler("localhost:7200/repositories/test-repo")

Run planning

result = planner.casktosmt(max_happenings=20)

Process results

if result.resulttype == PlanningResultType.SAT: print(f"Plan found with {result.plan.planlength} steps") for step in result.plan.plansteps: print(f"Step {step.stepnumber}:") for cap in step.capabilityappearances: print(f" - {cap.capabilityiri}") else: print("No plan found") ```

Advanced Usage

```python

Save intermediate files for debugging

result = planner.casktosmt( maxhappenings=20, problemlocation="problem.smt", # Save SMT problem modellocation="model.json", # Save Z3 model planlocation="plan.json" # Save structured plan )

Convert result to JSON

import json resultjson = result.tojson() print(json.dumps(result_json, indent=2)) ```