Skip to content

Knowledge Definition

Jump to bottom
Riccardo De Benedictis edited this page Oct 23, 2024 · 9 revisions

In order to operate effectively, CoCo requires specific information that defines the types of items it manages, the format of the data produced, the reactive rules that allow the system to respond to environmental changes, and the deliberative rules that enable CoCo to generate plans over time.

Types

The CoCo server allows for the definition of this knowledge through REST services. In particular, a POST request to the /type endpoint enables the creation of new item types. The body of the request should contain a JSON structure that includes the following information:

  • name: The name of the type.
  • description (optional): A description of the type.
  • static_properties (optional): Static properties that all instances of the type must have.
  • dynamic_properties (optional): Dynamic properties that can change and must also be defined for instances of the type.
  • parents (optional): Types from which the new type inherits properties.

For example, the following JSON body defines a new type called User:

{
  "name": "User",
  "description": "User type",
  "static_properties": {
    "name": { "type": "string" }
  },
  "dynamic_properties": {
    "age": { "type": "integer", "min": 0, "max": 120 }
  }
}

The server will create a new type according to the provided specifications and return a JSON response containing the description of the newly created type, including the ID assigned to it.

Retrieving Types

To retrieve all types, you can send a GET request to the /types endpoint. To retrieve a specific type, you can use the ID of the type in a GET request to /type/<id>, where <id> is the ID of the desired type. Alternatively, if you know the name of the type, you can retrieve it by sending a GET request to /type?name=<name>, where <name> is the name of the desired type. This flexibility in knowledge definition and retrieval allows CoCo to handle a wide variety of data models and system behaviors dynamically, making it highly adaptable for different application domains.

Properties

CoCo allows the definition of various property types to meet different modeling needs. For some properties, additional information can be specified, which can be useful for validating data formats (e.g., minimum and maximum values for an integer) or providing default values when none are supplied.

The available property types include:

  • boolean: A boolean data type that can take on the values true or false.
  • integer: A numerical data type for integers. You can specify a minimum (min) and maximum (max) value to constrain the range of allowed values.
  • float: A floating-point numerical data type. Similar to integers, you can specify a minimum (min) and maximum (max) value.
  • string: A text data type that can hold any sequence of characters.
  • symbol: A symbolic data type that can take on a predefined value (e.g., High, Medium, or Low). You can define an allowed set of values through the values field, which accepts an array of options. Additionally, using the multiple field (a boolean), you can indicate whether the property can hold multiple values simultaneously.
  • item: A data type that can reference an item defined in the CoCo environment. You can restrict the type of item allowed by specifying its type_id (the ID of the type). Similarly, the multiple field (a boolean) can indicate whether multiple values are allowed.
  • json: A complex data type that can hold a JSON object. You can enforce a specific data structure by providing a schema via the schema field.

Static and Dynamic Properties

There are two categories of properties in CoCo: static and dynamic.

Static properties: These are used to store information that does not change, or changes very rarely, over time. Examples of static properties include an individual's first and last name.

Dynamic properties: These are properties that can change over time. Changes to dynamic properties are stored in a database so that they can be retrieved and analyzed later. For example, you might visualize changes in dynamic properties over time using graphs or reports.

This flexible property system allows you to model diverse data structures and item behaviors within the CoCo environment, ensuring that you can manage both constant and evolving data with ease.

Items

Once types are defined, items can be created as instances of those types. To define an item, you will need the ID of the type and the values for its static properties. The CoCo server allows item creation through a POST request to the /item endpoint. The request body should contain a JSON structure that includes the type ID and the static properties of the new item.

For example, the following request creates a new user, assuming the ID of the previously defined User type is user_type_id:

{
  "type": "user_type_id",
  "properties": {
    "name": "Alice"
  }
}

Retrieving Items

You can retrieve all items by sending a GET request to the /items endpoint. Additionally, you can filter the retrieved items by specifying the type:

To filter by ID, use /items?type_id=<ID>, where <ID> is the type's ID. To filter by name, use /items?type_name=<name>, where <name> is the name of the type. For instance, a GET request to /items?type_name=User will return all instances of the User type.

This system allows for easy creation and retrieval of items based on their types, providing a flexible way to manage different entities within the CoCo environment.

Facts Representation

For each type, CoCo creates a fact in the form of (type id name description), which indicates the type's ID, name, and description. Additionally, inheritance relationships between types are modeled with facts like (is_a type_id parent_id), which specify a subtype and its parent type.

For each item, CoCo creates a fact in the form of (item id), representing the item's ID. There is also a set of facts (is_instance_of item_id type_id) that link each item to its corresponding type, showing the item ID and its type ID.

Properties Facts

The fact names for properties depend on the type of the item, the name of the property, and whether it is static or dynamic. For static properties, the fact is named <Type>_<Property>, while for dynamic properties, it is named <Type>_has_<Property>. Here:

<Type> is the name of the item type. <Property> is the name of the property. These facts include:

item_id: Indicates the ID of the item that has the property. A slot named after the property, indicating its value.

For dynamic properties, an additional timestamp slot records when the property was last updated.

For example, a fact like User_name could be used to store user names. The fact (User_name (item_id alice_id) (name "Alice")) indicates that the user with ID alice_id has the name "Alice".

Reactive Rules

Reactive rules in CoCo enable the system to respond to changes in the environment by triggering actions based on predefined conditions. These rules are essential for automating responses to events and ensuring that the system can adapt to dynamic situations.

Defining Reactive Rules

The CoCo server allows the definition of new reactive rules via POST requests to the /reactive_rules endpoint. The request body must contain a JSON structure that includes the rule's name and its definition written in the CLIPS language.

For example, the following request defines a rule that is triggered every time an rPPG sensor, associated with a kit and a user, produces new data:

{
  "name": "rppg_rule",
  "content":
  "(defrule rppg_rule
    (rPPG_has_HR (item_id ?rppg) (HR ?hr) (timestamp ?timestamp))
    (rPPG_has_BR (item_id ?rppg) (BR ?br) (timestamp ?timestamp))
    (rPPG_has_SpO2 (item_id ?rppg) (SpO2 ?spo2) (timestamp ?timestamp))
    (rPPG_has_user (item_id ?rppg) (user ?user))
    =>
    (add_data ?user (create$ HR BR SpO2) (create$ ?hr ?br ?spo2) ?timestamp))"
}

This rule listens for heart rate (HR), breathing rate (BR), and oxygen saturation (SpO2) data from an rPPG sensor, associates it with a user, and then adds the data to the user's record with a timestamp.

Extending CLIPS in CoCo

CoCo extends the CLIPS language by introducing custom functions that can be invoked from within the rules. These functions control the behavior of the framework, offering advanced capabilities to manage and manipulate data dynamically. Refer to the Reactive Rules documentation for more information.

Deliberative Rules

Deliberative rules in CoCo allow the system to generate activity plans aimed at achieving specific goals in the future. These rules take into account the potential interactions between the activities to foresee and avoid possible problems. CoCo organizes activities to prevent conflicts and ensure smooth execution.

Defining Deliberative Rules

The CoCo server enables users to define new deliberative rules via a POST request to the /deliberative_rules endpoint. The request body must be a JSON containing:

  • name: The name of the deliberative rule.
  • content: The rule definition written in the RiDDLe language.

Refer to the Deliberative Rules documentation for more information on how to define and use these rules.

Clone this wiki locally