Merge pull request #499 from Lexpedite/arity_3plus

Arity 3plus

CHANGELOG.md

@@ -7,6 +7,28 @@ As of v0.2-alpha, this project is attempting to adhere to [Semantic Versioning](
 While alpha, however, any version may include breaking changes that may not be specifically noted as such,
 and breaking changes will not necessarily result in changes to the main version number.
 
+## [v1.6.1-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.6.1-alpha) 2023-04-27
+
+This release adds to the representational power of Blawx by adding "relationships", which are
+a statement that is true (or not) about 3 or more objects or values.
+
+### Added
+* Relationship Declaration Block
+* Relationship Selector Blocks
+* Known Relationship Drawer
+* Associated documentation
+
+### Changed
+* `/onto` endpoint returns information about relationships in addition to categories and attributes
+* the JSON format accepted by the `test` and `interview` endpoints now accepts relationships in addition to categories and attributes
+* The response from the ontology endpoint is now shown in the "devel" tab of the scenario editor.
+* Scenario Editor has been modified to support relationships.
+* Rock Paper Scissors example was updated to use relationships for throws instead of attributes.
+* Associated documentation
+
+### Fixed
+* Problems with natural language generation for non-boolean attributes in test editor explanations
+
 ## [v1.6.0-alpha](https://github.com/Lexpedite/blawx/releases/tag/v1.6.0-alpha) 2023-04-11
 
 **This release is NOT backward compatible.**

blawx/fixtures/docs/blocks/categories/new_relationship.yaml

@@ -0,0 +1,35 @@
+- model: blawx.docpage
+  pk: blocks/new_relationship
+  fields:
+    title: New Relationship Block
+    content: |
+      # New Relationship Block
+
+      ![New Relationship Block](/static/blawx/docs/images/blocks/new_relationship.png)
+
+      ## Where Is It?
+
+      The new relationship block is found in the Categories drawer of the Blawx toolbox.
+
+      ## What Does It Do?
+
+      The new relationship block is used to create a new relationship between 3 or more objects and values.
+
+      ## Technical Details
+
+      The new relationship block is a statement, and can be stacked with other statements.
+
+      The new relationship block accepts the name of the relationship. To be valid, the name of the relationship must begin with a lower-case letter and not
+      include any spaces.
+
+      It also accepts the number of objects and values that will be related to one another in this relationship, which
+      is a number between 3 and 10.
+
+      For each object or value, it accepts a type, which is selected from a dropdown that shows the available data types and the known categories.
+
+      Before, between, and after each object or value, it accepts the text that should be used to generate the relationship selector blocks, and used in
+      explanations.
+
+      ## Tips
+
+      Names of relationships should be unique, but can safely overlap with other relationship that have a different number of objects and values.

blawx/fixtures/docs/blocks/categories/relationship_selector.yaml

@@ -0,0 +1,26 @@
+- model: blawx.docpage
+  pk: blocks/relationship_selector
+  fields:
+    title: Relationship Selector Block
+    content: |
+      # Relationship Selector Block
+
+      ![Relationship Selector Block](/static/blawx/docs/images/blocks/relationship_selector.png)
+
+      ## Where Is It?
+
+      The relationship selector block is located in the Known Relationships drawer of the Blawx toolbox.
+
+      ## What Does It Do?
+
+      The relationship selector block is used to set or test a value for a relationship between 3 or more objects and values.
+
+      ## Technical Details
+
+      The relationship selector block's appearance is determined by the new relationship block that defines it.
+
+      It has between 3 and 10 internal connectors for objects and values. If a connector is for a data type, it will only
+      accept values of that type and variables. If a connector is for a category, it will accept objects and variables.
+
+      ## Tips
+

blawx/fixtures/docs/components/web-api.yaml

@@ -60,10 +60,20 @@
       "AttributeNLG" is a list of dictionaries, each of which has the keys "Attribute", "Order", "Prefix", "Infix" and "Postfix", describing the details provided in an attribute declaration block.
       Order will be either "vo" or "ov", indicating the order in which the object and the value appear in the natural language expression.
 
+      "Relationships" is a list of dictionaries, each of which has the key "Relationship", and between 3 and 10 keys "ParameterN" where N is replaced with the number of the parameter. The "Relationship"
+      is the name of the relationship. Inside each "ParameterN" key is the data type or category for that parameter in the relationship. The available types are the same as for attributes.
+
+      "RelationshipNLG" is a list of dictionaries, each of which has the keys "Relationship", "Postfix", and between 3 and 10 "PrefixN" keys where N is replaced with the number of the parameter. The
+      relationship key is the name of the relationship, the PrefixN keys hold text that should appear before each of the parameters in the relationship, and the Postfix key holds text that should appear
+      after all parameters.
+
       "Objects" is a list of dictionaries, each with the keys "Category" and "Object", describing the category and the name of the object in that category.
 
       "Values" is a list of dictionaries, each with the keys "Object", "Attribute", and "Value", describing a known value for that object and attribute.
 
+      "Relations" is a list of dictionaries, each with the keys "Relationship", and a set of 3 to 10 keys named "ParameterN" where N is replaced with the number of the parameter, describing a known
+      statement for that relationship.
+
       The ontology endpoint is intended to be used at the start of an interaction between Blawx and another application, to provide the other application with information about what data structure is
       used in the encoding, and to provide hints about how to collect items into that data structure.
 
@@ -82,9 +92,10 @@
       * A 'from_ontology' key, the value of which is a `true` or `false` value. This is used to note which facts were already present in the code and were not provided by the user. Data provided by a user application
         should always set the 'from_ontology' value to `false`.
       * A 'type' key, the values of which can be the strings 'true','false', or 'unknown'.
-      * Either a 'category' or 'attribute' key, where the value is the name of the category or attribute about which a statement is being made.
-      * An 'object' key, the value of which is either the name of an object as a string, or a variable definition (described below).
+      * Either a 'category', 'attribute', or 'relationship' key, where the value is the name of the category or attribute or relationship about which a statement is being made.
+      * For categories and attributes only, an 'object' key, the value of which is either the name of an object as a string, or a variable definition (described below).
       * In the case of non-boolean attributes, a 'value' key, the value of which is the particular value being provided, or a variable definition (described below).
+      * For relationships, a set of between 3 and 10 "parameterN" keys where N is replaced with the parameter number, setting out the value or variable definition for each.
 
       Dates, datetimes, times, and durations are provided as strings in ISO8601 format. Numbers and booleans are provided in the standard JSON format.
       ```
@@ -112,7 +123,13 @@
             'attribute': 'duration',
             'object': 'bob',
             'value': 'P1Y5MT5H30S'
-          }
+          },
+          { 'from_ontology': flase,
+            'type': 'true',
+            'relationship': 'trio',
+            'parameter1': 'bob',
+            'parameter2': 'jane',
+            'parameter3': 'terry'}
         ]
       }
       ```
@@ -146,10 +163,10 @@
         ]
       }
       ```
-      
+      Variable names are not case sensitive. The variable "one" and "One" will be treated as though they are identical.
+
       Additional examples can be obtained by using the Scenario Editor to run a test, and then looking at the "Devel" tab, which will show the JSON
       package that was delivered to the interview endpoint, and the response.
-
       
       The output from the interview endpoint is a JSON dictionary with keys "Answers", "Relevant Statements", and "Transcript".
 

blawx/fixtures/docs/features/categories.yaml

@@ -1,15 +1,13 @@
 - model: blawx.docpage
   pk: features/categories
   fields:
-    title: Categories, Objects, and Attributes
+    title: Categories, Attributes, Relationships
     content: |
-      # Categories, Objects, and Attributes
+      # Categories, Attributes, and Relationships
 
-      Categories, Objects, and
-      Attributes are how Blawx organizes what it knows about the world.
+      Categories, Attributes, and Relationships are how Blawx organizes what it knows about the world.
 
-      A Category
-      is a type of object. For example, "Car."
+      A Category is a type of object. For example, "Car."
 
       A Category has Attributes,
       which are names for things that you can know about things in that Category.
@@ -26,9 +24,9 @@
       The information that you put into
       an object's attribute has to be of
       the correct type. You can't put a number
-      if the attribute is supposed to hold a true or false value, and vice-versa.
+      if the attribute is supposed to hold a date value, and vice-versa.
 
-      An easy way
+            An easy way
       to think of a Category is as a description of a blank form. The form might have
       a name, like “Application for a Permit”. That is like the Category name. A form
       will also have fields that can be filled in, like “Applicant’s Name". Those are
@@ -40,11 +38,13 @@
       of an object. Some fields on the form are for checkmarks, others numbers,
       and others dates. Those are like the types of the category attributes.
 
-      An
-      attribute can hold either a basic data type, or objects in a category.
+      A Relationship is a thing that is true about a combination of 3 or more objects and values.
+      For example, you might want to record information about where cars placed in races, and you
+      could create a relationship between a car (a category), a race (another category), and a number indicating the finishing position.
 
-      The
-      basic data types are numbers, true or false values, dates, and durations.
+      An attribute or a relationship can hold either a basic data type, or objects in a category.
+
+      The basic data types are numbers, true or false values, dates, times, datetimes, durations, and lists.
 
       Not only can you use your Categories as a type, but you
       can use your category
@@ -242,4 +242,18 @@
       and the way that you say it is false is by surrounding it with a "it is false that" negation block.
 
       So when you create a "True / False" attribute, it has only an "object" field, and you only need to customize the text
-      that appears before and after the name of the object.
+      that appears before and after the name of the object.
+
+      ## Relationships
+
+      You can create a relationship by using the new relationship block. You need to give it a name, which
+      must be lower case and not have spaces. You also need to give it a number of objects or values that will
+      be related to one another. Note that if what you are looking for is a relationship between 2 objects,
+      you should use an Attribute instead.
+
+      ![New Relationship Block](/static/blawx/docs/images/blocks/new_relationship.png)
+
+      Once you have chosen the name and the number of objects or values, you will be able to choose a type for
+      each of the elements, choosing between the available data types and the known categories. You can also
+      provide the text that should appear before, between, and after all of the elements. This text will be used
+      to build the relationship selector block, and will be used in explanations.