Sliding Work Sharing

Sliding Work Sharing (SWS) Management Component of the AI4Work Project.

The aim of this software is to support dynamic work sharing between human and machine (especially AI/robots). It can provide decision support regarding the appropriate degree of machine autonomy and the required degree of human involvement, depending on the respective work situation.

---

How to Build and Run the Application

1. Prerequisites

To build and run the Sliding Work Sharing, the following software is required:

Docker: Docker Desktop or Docker Engine (https://www.docker.com/get-started/)

2. Pull the SWS Docker image

Open a terminal and pull the Docker image using the following command:

docker pull ghcr.io/ai4work-project/sliding-work-sharing:1.1.0

3. Start the Application (using the Default Configuration for Testing)

Run the following command to start the application using the built container image:

docker run --rm -p 8080:8080 ghcr.io/ai4work-project/sliding-work-sharing:1.1.0

The application will start and listen on port 8080 by default.

4. How to Test the Application

You can test the application using the curl command (or using any other HTTP/REST client of your choice):

Example Request

Execute the following curl command in your terminal to request a "sliding decision" via a POST request to the /sliding-decision endpoint:

curl --request POST \
  --url http://localhost:8080/sliding-decision \
  --header "Content-Type: application/json" \
  --data '{
    "decisionStatus": "Sliding Decision Request",
    "slidingDecisionInputParameters": {
      "numberOfTrucksInQueue": 7,
      "positionOfTruckToBePrioritized": 5,
      "materialUrgency":30,
      "operationalWorkload":80
    }
  }'

Example Response

The application will respond with a JSON string similar to the following:

{
  "decisionStatus": "Sliding Decision Response",
  "slidingDecisionOutputParameters": {
    "suggestedApproach": {
      "slidingDecision": "informHuman",
      "description": "Human has to be informed about AI's rescheduling"
    }
  },
  "decisionExplanation": {
    "...": "..."
  }
}

Please Note: The decisionExplanation is not shown here for the sake of brevity. An example is described here.

---

How to apply the SWS to your own application scenario

To apply SWS to your own application scenario, you need to do the following:

1. create your custom .fcl file, which defines your own input parameters, output parameter(s) and decision rules
2. create your custom .yml configuration file
3. prepare the configuration directory
4. run the software and mount your configuration directory inside the container

Each step is explained in detail in the following.

1. Create your custom .fcl file

• fcl (fuzzy control language) is used to define input parameters, output parameter(s) and decision rules.
• our suggestion would be to take one of the existing .fcl files as template and adjust it to your scenario
• existing example .fcl files can be found at src/main/resources/rules

Note: The SWS application can return multiple output parameters. In your custom .fcl file, you can define several decision outputs, and each one will appear as a separate parameter in the response JSON. The agriculture scenario includes an example for this feature, please have a look at:

• The description of the agriculture scenario
• The .fcl file for the agriculture scenario

2. Create your custom .yml configuration file

Our suggestion would be to take an existing application-{existing-configuration}.yml configuration file as template and adjust it. Existing examples can be found at src/main/resources.

Please note:

• the configuration parameter fclRulesFilePath inside the .yml file must point to the location of your .fcl inside the Docker container, not the path on the host machine. Therefore, it should start with the folder name /config/, which corresponds to the directory that will later be mounted inside the Docker container. For example:

  application-scenario-config:
    fclRulesFilePath: /config/your-scenario.fcl
    decisionResultsDescription:
      # Add your scenario-specific decision result descriptions here.
      [...]

• the textual description of the decision results should fit to your scenario

• rename your file, replacing {existing-configuration} with a name representing your custom scenario

3. Prepare the configuration directory

Create a directory on your host machine containing both your custom .fcl file and your custom .yml configuration file.

For example:

<YOUR_CONFIG_DIRECTORY_ON_THE_HOST_MACHINE>/
├── your-scenario.fcl
└── application-{your-configuration-name}.yml

4. Run the application with your custom configuration

Use the following instructions to mount your config directory inside the Docker container and start the application. After startup, you can test your custom scenario, as explained in the part about testing the application. Please do not forget to adjust the input parameters to fit to your own scenario.

Linux or macOS

docker run --rm \
  -p 8080:8080 \
  --mount type=bind,source="<PATH_TO_YOUR_CONFIG_DIRECTORY_ON_THE_HOST_MACHINE>",target=/config,readonly \
  ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 \
  --spring.config.location=file:/config/application-{your-configuration-name}.yml

Replace:

• <PATH_TO_YOUR_CONFIG_DIRECTORY_ON_THE_HOST_MACHINE> with the absolute path to the directory containing your YAML and FCL files.
• {your-configuration} with the name of your custom scenario.

For example:

docker run --rm \
  -p 8080:8080 \
  --mount type=bind,source="/home/user/sws-config",target=/config,readonly \
  ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 \
  --spring.config.location=file:/config/application-sws-scenario.yml

Windows PowerShell

docker run --rm `
  -p 8080:8080 `
  --mount type=bind,source="<PATH_TO_YOUR_CONFIG_DIRECTORY_ON_THE_HOST_MACHINE>",target=/config,readonly `
  ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 `
  --spring.config.location=file:/config/application-{your-configuration-name}.yml

Replace:

• <PATH_TO_YOUR_CONFIG_DIRECTORY_ON_THE_HOST_MACHINE> with the absolute path to the directory containing your YAML and FCL files.
• {your-configuration-name} with the name of your custom scenario.

For example:

docker run --rm `
  -p 8080:8080 `
  --mount type=bind,source="C:\Users\YourName\sws-config",target=/config,readonly `
  ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 `
  --spring.config.location=file:/config/application-sws-scenario.yml

---

Demonstration Scenarios

To make this software useful for application in different domains, it can be configured via application-scenario-specific rules. This is explained in the following, based on simplified example scenarios from the AI4Work project's pilot domains:

1. Logistics Scenario
2. Agriculture Scenario
3. Construction Scenario

---

Logistics Scenario

This example scenario is from the logistics domain:

• imagine a queue of trucks that deliver material to a warehouse
• usually the sequence of trucks is "first come, first served"
• an exception to the previous rule is that a truck should be prioritized if
  • the stock of some material is getting low
  • a truck is delivering that very same material

The SWS management decides in how far a human should be involved in the decision. This decision depends on:

• the number of trucks in the queue
• the position of the truck in the queue
• the urgency of the material that is being delivered by the truck
• the current workload of the warehouse

Example Rules

• if the queue is short and the truck is near its front, it can be automatically prioritized
• if the queue is long and the truck is near its end, a human needs to be involved in the decision

To explore the example rules in detail, please refer to the FCL file located here.

How to Run and Test the Scenario

To start the application and run the logistics scenario, use the following command:

docker run --rm -p 8080:8080 ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 --spring.profiles.active=logistics

Example Request

Execute the following curl command in your terminal to request a "sliding decision" via a POST request to the /sliding-decision endpoint:

curl --request POST \
  --url http://localhost:8080/sliding-decision \
  --header "Content-Type: application/json" \
  --data '{
    "decisionStatus": "Sliding Decision Request",
    "slidingDecisionInputParameters": {
      "numberOfTrucksInQueue": 7,
      "positionOfTruckToBePrioritized": 5,
      "materialUrgency":30,
      "operationalWorkload":80
    }
  }'

To test the implemented rules, you can pass different inputs to the application and observe the outcomes. Just modify the values for the slidingDecisionInputParameters as follows:

• numberOfTrucksInQueue: Total number of trucks in the queue (0-20 trucks)
• positionOfTruckToBePrioritized: Position of the truck number that needs to be prioritization (0-20)
• materialUrgency: Urgency of the need for the material that is being delivered by the truck (0%-100%)
• operationalWorkload: Current workload of the warehouse (0%-100%)

Example Response

The application will respond with a JSON string similar to the following:

{
  "decisionStatus": "Sliding Decision Response",
  "slidingDecisionOutputParameters": {
    "suggestedApproach": {
      "slidingDecision": "informHuman",
      "description": "Human has to be informed about AI's rescheduling"
    }
  },
  "decisionExplanation": {
    "...": "..."
  }
}

Please Note: The decisionExplanation is not shown here for the sake of brevity. An example is described here.

Depending on the input, the SWS may decide one of the following:

• autonomousReprioritization: "AI can reschedule without human involvement"
• informHuman: "Human has to be informed about AI's rescheduling"
• requireHumanApproval: "Human has to decide without AI support"

---

Agriculture Scenario

This example is from the agriculture domain:

• imagine workers who are manually harvesting produce and putting it into boxes
• whenever a box is full of produce, it has to be carried to a central collection point
• carrying the box can be done either by the workers themselves or by an AI-powered transport drone
• the transport drone has limited capacity, so it cannot transport all boxes for all workers

For each required transport of a harvest box, the SWS management decides if this transport should be done by the drone or by the worker, and in how far a human (either worker or supervisor) should be involved/informed. This decision depends on:

• the drone's battery level
• the availability of the drone
• the fatigue level of the worker
• the distance from the current location of the box to the central collection point

Example rules

• if distance from the current location is high and the drone is currently available, let the drone carry the box
• if distance from the current location is low and the drone is currently not available or fatigue level of worker is low, let the worker carry the box
• if drone battery level is low or fatigue level of worker is high, inform the supervisor about the situation

To explore the example rules in detail, please refer to the FCL file located here.

How to Run and Test the Scenario

To start the application and run the agriculture scenario, use the following command:

docker run --rm -p 8080:8080 ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 --spring.profiles.active=agriculture

Example Request

Execute the following curl command in your terminal to request a "sliding decision" via a POST request to the /sliding-decision endpoint:

curl --request POST \
  --url http://localhost:8080/sliding-decision \
  --header "Content-Type: application/json" \
  --data '{
    "decisionStatus": "Sliding Decision Request",
    "slidingDecisionInputParameters": {
      "distanceToCentralCollectionPoint": 250,
      "fatigueLevelOfWorker": 80,
      "droneBatteryLevel":80,
      "isDroneCurrentlyAvailable":1
    }
}'

To test the implemented rules, you can pass different inputs to the application and observe the outcomes. Just modify the values for the slidingDecisionInputParameters as follows:

• distanceToCentralCollectionPoint: The distance to the collection point, measured in meters (0-300 meters)
• fatigueLevelOfWorker: The current fatigue level of the worker, measured in percent (0%-100%)
• droneBatteryLevel: The current battery level of the drone, measured in percent (0%-100%)
• isDroneCurrentlyAvailable: Whether the drone is currently available (1 = yes, 0 = no)

Example Response

The application will respond with a JSON string similar to the following:

{
  "decisionStatus": "Sliding Decision Response",
  "slidingDecisionOutputParameters": {
    "suggestedApproach": {
      "slidingDecision": "droneShouldCarryTheBox",
      "description": "Let the drone carry the box"
    },
    "shouldSupervisorBeInformed": {
      "slidingDecision": "yes",
      "description": "Inform the supervisor"
    }
  },
  "decisionExplanation": {
    "...": "..."
  }
}

Please Note:

• This application scenario provides an example how the SWS can return multiple output parameters. In the .fcl file, several decision outputs can be defined, and each one will appear as a separate parameter in the response JSON.
• The decisionExplanation is not shown here for the sake of brevity. An example is described here.

Depending on the input parameters, the SWS may decide one of the following:

• droneShouldCarryTheBox: "Let the drone carry the box"
• letTheSupervisorDecide: "Let the supervisor decide"
• letTheWorkerDecide: "Let the worker decide"
• humanShouldCarryTheBox: "Let the worker carry the box"

---

Construction Scenario

This example scenario is from the construction domain:

• imagine a robot doing work on a construction site
• while moving, the robot detects an unexpected obstacle in its way (e.g. some construction materials that are stored there temporarily)
• depending on the situation, either of the following may now happen:
  • the robot may be able to autonomously circumnavigate the obstacle and continue its work
  • the robot may be blocked and thus unable to continue its work, so that it requires human support

The SWS management should support the decision if/when a human should be called to help the robot. This decision depends on:

• the time that the robot is already moving
• the battery status of the robot
• the number of humans currently present in the room

Example Rules

• if the robot battery status is low or the time the robot is already moving is long, ask for human help
• if the time robot is already moving is short and robot battery status is not low, let the robot continue trying

To explore the example rules in detail, please refer to the FCL file located here.

How to Run and Test the Scenario

To start the application and run the construction scenario, use the following command:

docker run --rm -p 8080:8080 ghcr.io/ai4work-project/sliding-work-sharing:1.1.0 --spring.profiles.active=construction

Example Request

Execute the following curl command in your terminal to request a "sliding decision" via a POST request to the /sliding-decision endpoint:

curl --request POST \
  --url http://localhost:8080/sliding-decision \
  --header "Content-Type: application/json" \
  --data '{
    "decisionStatus": "Sliding Decision Request",
    "slidingDecisionInputParameters": {
      "timeTheRobotIsAlreadyMoving": 4,
      "robotBatteryStatus": 65,
      "noOfHumansInTheRoom": 10
    }
  }'

To test the implemented rules, you can pass different inputs to the application and observe the outcomes. Just modify the values for the slidingDecisionInputParameters as follows:

• timeTheRobotIsAlreadyMoving: The time that the robot is already moving, measured in minutes (0-15 minutes); a higher time may indicate that the robot is blocked
• robotBatteryStatus: The battery status of the robot, measured in percent (0%-100%)
• noOfHumansInTheRoom: The number of humans currently present in the room (0-20 humans)

Example Response

The application will respond with a JSON string similar to the following:

{
  "decisionStatus": "Sliding Decision Response",
  "slidingDecisionOutputParameters": {
    "suggestedApproach": {
      "slidingDecision": "askForHumanHelp",
      "description": "Ask human for help"
    }
  },
  "decisionExplanation": {
    "...": "..."
  }
}

Please Note: The decisionExplanation is not shown here for the sake of brevity. An example is described here.

Depending on the input, the SWS may decide one of the following:

• letRobotContinue: "Let the robot continue trying"
• informHumanAboutSituation: "Inform human about the situation"
• askForHumanHelp: "Ask human for help"

---

How to Read the decisionExplanation

To make clear how the internal rule engine reached the "sliding decision", the response JSON contains the section decisionExplanation, subdivided into inputVariables, appliedRules and outputVariables. Each of those are described in the following based on examples.

Input Variables

{
  "decisionExplanation": {
    "inputVariables": {
      "numberOfTrucksInQueue": {
        "value": 7.0,
        "membershipValues": {
          "moderate": 1.0
        }
      },
      "...": "..."
    }
  }
}

• value: this is the original number provided as input in the Sliding Decision Request.
• membershipValues: this shows the "fuzzy categories" into which the input value fits. Each category is assigned a membership degree between 0 and 1. In the given example, the input value of 7.0 belongs to the moderate category with a membership degree of 1.0.

Applied Rules

This field lists the rules that were activated during the decision-making process.

{
  "appliedRules": [
    {
      "name": "1",
      "condition": "IF numberOfTrucksInQueue IS moderate",
      "consequence": "THEN [suggestedWorkSharingApproach IS autonomousReprioritization]",
      "weight": "1.0",
      "degreeOfSupport": "1.0"
    }
  ],
  "...": "..."
}

• name: an identifier for the rule
• condition: the part that decides if this rule should be activated, based on the input values' memberships in the fuzzy categories
• consequence: the outcome that the rule suggests (e.g., "[suggestedWorkSharingApproach IS autonomousReprioritization]")
• weight: is a pre-defined value, which defines the general "importance/impact" of this rule
• degreeOfSupport: the level of impact that this rule has on the final decision, calculated based on the fuzzy membership degrees of the input values

Output Variables

Shows the final outcome after evaluating all the activated rules.

{
  "outputVariables": {
    "suggestedWorkSharingApproach": {
      "value": 1.4977511244377752,
      "membershipValues": {
        "informHuman": 1.0
      }
    }
  }
}

• value: after combining all contributions from the fired rules, the fuzzy inference process computes a numerical value. In the given example, a value of approximately 1.497 is produced.
• membershipValues: this final output is then associated with a fuzzy category. In our example, 1.497 maps to "informHuman" with a membership degree of 1.0. This means that, after all rules are applied, the final decision is identified as that suggested work sharing approach.