Documentation

Facts, Rules and Questions

The vast majority of the encoding that you do in Blawx will be done setting out Facts, Rules, and Questions. They are the starting points for the encoding process.

When you encode laws, you will do it by setting out facts and rules. Then, when you want to use the laws you have encoded, you will use questions.

Facts

A “Fact” in Blawx represents a thing that is known with certainty. If you have a fact, you need to put it in a Fact block, which looks like this:

fact

So for example, let’s say we have some code that represents the idea that Socrates is a human being. That would be placed in a Fact block.

socrates_human

As you will see in the documentation around Categories, you may also make statements about Categories of objects, like saying “A dog is an animal.” These are also treated as facts because they are a thing that is known with certainty.

A fact block can hold as many unrelated facts as you would like. And you can have as many different fact blocks in your workspace as is useful.

socrates and dog

It can be helpful to create separate Fact blocks for pieces of information that you will be working with at the same time, so that when you are not using them you can Collapse the fact block and leave your workspace a little easier to read. See the documentation on the Blawx User Interface for details on collapsing and expanding blocks.

If you ask Blawx whether or not something is true that you have stated as a Fact, the answer is always yes, without further explanation. Facts explain themselves. In fact, you can imagine a Blawx explanation as saying "because you told me so as a fact", after any line of an explanation that doesn't have further explanations.

Typically facts are used at two different stages of the encoding process. First, they are used to set out the terms of the conversation (e.g. “Human is a Category”, “Mortal is a Category”). Then fact blocks take a back seat while rules are written using those terms (e.g. “We know a thing is a mortal if we know that thing is a human.”). Then we come back to using fact blocks to describe a specific fact scenario that we want to ask questions about (e.g. “Socrates is a Human”). Then we use queries to ask questions (e.g. “Is Socrates a Mortal?”).

It can be helpful to separate facts that are always true in the ruleset from facts that are only true in the specific scenario being tested, and multiple fact blocks can be used for that purpose.

Note that when you use your encoding over the Web API, this second type of fact, the case-specific kind, is provided by the user in the request that is sent to Blawx. Your deployed code should not have testing facts inside it, because the user's data will add to them, not replace them.

Rules Rules are the most important part of encoding in Blawx. They are where you describe the simple logical building blocks that Blawx can combine in complicated ways to generate new insights. That is why the technology that Blawx implements is often referred to as “rules-based artificial intelligence”.

A rule has two parts. The first part is one or more statements that can be proved true by the rule, called the “conclusions.” The second part is the “conditions” that must be met for the conclusion to be proved true.

rule

A rule block has one slot for the conclusions, one slot for the conditions.

A rule with no conclusions should be a Question or a Constraint, and a rule with no conditions should be a Fact, so a rule block needs both statement connections filled to work properly.

A Note

on If/Then Some people might express rules as if conditions then conclusions. \ We prefer to avoid the words “if” and “then” to describe rules, because people who are familiar with imperative programming languages (which is most of the programming languages out there) will have in their minds a different meaning for “if” and “then.”

In imperative programming, if conditions then conclusions means “if right now the conditions are true, then next the computer should do conclusions.”

Blawx is a declarative logic programming tool, not an imperative one. Which means that the rule if conditions then conclusions means “if conditions are true, then conclusions are also true.”

When using Blawx, remember that you are not describing what steps the computer should follow. You are describing what is known (the fact, or the conclusion for rules), and when it is known (always for facts, when the conditions are true for rules).

Questions

Once you have encoded rules and described relevant facts, you will want to ask a question. That is what the question block is for.

There are two kinds of questions… yes/no questions, and search questions.

Yes/No Questions

A question that does not include variables is a “yes/no” question. An example is “Is Socrates Mortal?”

is socrates mortal

This question will be answered by the Blawx reasoner with either the bare statement "socrates is mortal", or “No”.

Search Question

A question that includes variables is a “search” question. Blawx attempts to find any objects that it can place in all the variables used so that the all of the statements will be true. If it can’t find any, it will respond “No.” If it can find any examples, it will provide each combination of objects that made the statements true, and each reason for each combination of objects.

So the question “is Socrates Mortal” above, which is a “yes or no” question, can be changed into a search by replacing “Socrates” with a variable. We will name the variable “Who”, because it reads better, but the name is unimportant, as long as you use the same variable name everywhere that it is important the rule is referring to the same object.

who is morta

If you ask this question of the Reasoner, the answer back will be:

socrates
is a mortal, because
socrates is a person

Remember that a question requires all of its blocks connected by the And connectors to be true at the same time in order to find any answers. So make sure you are only asking one question at a time.

Declarations in Facts and Rule Conclusions

vs Rule Conditions and Queries Declaration blocks for objects and categories have the usual meaning when used in a fact or the conclusions of a Rule block. But they have a different meaning when they are included in the conditions of a Rule block, or in a query.

A declaration causes the object, category, or attribute to exist when used inside a fact block or the conclusions of a rule. Inside a condition block, they test whether or not those declarations have been made somewhere else.

So this rule says “we know fruit is a Category if plants are living things.” This rule has the effect of creating a category when its conditions are met.

conclude fruit

However, in the next rule, the same Category declaration block “Fruit is a Category” does not create the category fruit, but instead asks whether the category has been created.

query fruit

If the category Fruit has not been defined anywhere (in a fact, or the conclusion of a Rule that had true conditions), then the answer to the query “is Fruit a category” will be no.

This can be confusing, because Blawx still creates a “Known Category”, “Known Object” or “Known Attribute” block in the toolbox regardless of where the relevant block is used. So you may have a Category selector block called “Fruit” while in the code the category fruit does not exist.

So it is important to remember the effect of declaration blocks in different locations:

In Facts and Rule Conclusions, a new object or new category block or new attribute block means “this thing exists”. In Rules Conditions and Queries, a declaration block means “does this thing exist?” - model: blawx.docpage pk: guide/interface fields: title: User Interface Tour content: # Blawx User Interface Tour

Workspace Components

In Blawx you encode laws by sticking puzzle pieces together on a table. The table is called your “workspace”. The place you grab the puzzle pieces from is called the “toolbox.”

In the picture below, the area on the left is the toolbox, and the area on the right is the workspace.

workspace

The toolbox is made up of categories. When you click on a category name, the blocks available in that category are displayed. If the category has sub-categories, a black triangle appears before the name of the category.

Usually, most of the blocks in a category will match the highlight colour on the left side of the category.

At the top of the workspace is a resizeable, transparent area that shows the results received from the Blawx reasoner.

response area

Blocks

The individual puzzle pieces that you use to encode laws are called “Blocks”, or “Blawx”. Blocks can include information that you can’t change, like the words “is an Object” in the Object Declaration block shown below, and they can include information that you can change, like the word “rock” in the image below.

Fields

text field

Information that you can change in a block is called a field. The field above is a text field that allows you to type information into it. There are also fields for numbers, which is a text field that you can only type numbers into.

number field

And there are dropdown fields, that allow you to choose one of several options. One example is the true/false block.

dropdown field

Connectors

There are two kinds of connectors on the blocks in in Blawx (say that 5 times fast!): “insert” connectors, and “and” connectors. Each has a positive and negative version.

The positive “insert” connector looks like the sticky-outie part of a puzzle piece and sticks out of the left side of the block.

positive insert connector

Th negative insert connector looks like a “hole” where the positive insert connector would fit. Most of these locations show up as a missing puzzle piece inside a larger block.

negative insert connector

The size of the hole doesn’t matter, and will expand to fit whatever block connects to it.

Add part for when

Connectors DO Fit

When Insert Connectors “Don’t Fit”

Blawx tries to help make sure that you don’t stick things where they don’t belong. So as an example, if you try to stick a number where Blawx is expecting a string, the blocks won’t “fit properly.” Just like when you’re doing a jigsaw puzzle and you’re trying to stick two pieces together that don’t belong together… it just doesn’t quite work.

If you’re trying to insert a block and it “won’t fit”, you are probably trying to insert a block that is of the wrong datatype.

Whenever you use an insert connector, it has the same meaning as “filling in the blank”. Most blocks will not work if any of their negative insert connectors are empty. If there’s a blank, you need to fill it.

And Connectors

The “And” connectors, are shown as a divot on the top of a block and a bump on the bottom of a block.

Blocks with “and” connectors can be stacked with each other vertically. When you stack two things vertically using the “and” connector, that is treated as a statement that they both must be true. You can stack as many statements as you need in this way.

Some blocks have “internal” and connectors, when they expect to contain other blocks. A block usually won’t work properly if it has any internal "and" connectors that are left empty.

In any stack of blocks, the bottom block will always have an external "and" connector with nothing attached. That's fine.

Keeping Connected: Outer Blocks

For your encoding to work, all of the blocks need to be connected to an outer block that has no empty connectors. The outer blocks are facts, rules, constraints, assumptions, and queries, and look like this:

outer blocks

The Facts, Assumption, Constraint, and Query blocks have only one internal And connector. The Rule query has two. All of them must be connected to a stack of blocks to work properly. And all blocks with connectors must be attached to (or attached to something that is attached to) an outer block with no empty connectors.

So if you have blocks hanging around with empty negative and connectors, that won’t work. But if you put them inside an outer block, it will.

So you have well formed code if there are only full outer blocks, and blocks with no empty connections (except for the last "and" in a stack) in the workspace.

Navigating

the Blawx User Interface

Scrolling

The size of the workspace increases as necessary for however many blocks you add to it. If you can’t see all the blocks on the workspace, you can scroll around the workspace using the vertical and horizontal scroll bars.

workspace

You can also scroll the workspace by dragging any empty part of the workspace.

Dragging Blocks

You drag blocks from the toolbox to the workspace in order to add them to your code, and you drag them around the workspace in order to connect them to one another.

Dragging a block in a vertical stack will drag that block and any blocks that are connected below it, but not blocks above it or blocks containing it.

Dragging a block will drag blocks contained in it.

Because of the different ways in which dragging behaves, it’s important to know which block is currently selected. For that reason, the currently selected block is highlighted with an orange boundary.

block highlighting

Block Context Menu

If you right-click on a block in the workspace you will get a context menu.

context menu

Duplicate

The Duplicate menu option will make a copy of the block you have selected (and any blocks that are contained in it, but not any blocks it is vertically stacked with), and put it on the workspace.

Comments

Adding a comment opens a bubble that you can type extra information into. That information has no effect on the meaning of the blocks, it is just to allow you to add more useful information to the workspace.

Comments are typically used by software developers to explain what a piece of code is supposed to do, and why it is built the way it is, so that if anyone else (or the same person, but after a long period of time) needs to make adjustments later, they can get up to speed more quickly.

That is a very good idea. When encoding legislation, until we add more specific features for it, the comments are also a good place to include information about the source for the rule.

When a block already has a comment, the context menu will allow you to delete it instead. When a block has a comment, that comment can be hidden or shown by clicking on the blue question mark icon that appears on the top left of the block.

commment

Collapsing

Collapsing a block reduces it to one line high, and makes the right side of the block look “torn” to show that it is a collapsed block.

collapsed

In a collapsed block the context menu will allow you to expand it to its normal size again.

Collapsing blocks can be very helpful when you are dealing with a lot of complicated outer blocks at the same time.

Note that when a block is collapsed you cannot see whether it has a comment.

Disabling

A disabled block will change in colour to a cross-hatch pattern. Disabled blocks remain on the workspace, but they do not mean anything. So it does not matter whether a disabled block has unfilled connectors.

disabled

Disabling a block disables that block and any blocks it contains.

For a disabled block, the context menu will allow you to enable it again.

Deleting

Deleting a block removes a block and any blocks it contains from the workspace. If you delete a block in a vertical stack, the blocks above and below will become vertically connected with each other.

The context menu will tell you how many blocks you are about to delete, as shown here:

context menu delete

Block-Specific Help

If there is a help page for the specific kind of block you are using, the Help item in the context menu will take you to that help page. If there isn’t, it will be disabled.

The help context menu is also the only item that is available when you right click on a block in the toolbox.

context menu toolbox

Workspace Context Menu

There is also a context menu that you can access by right-clicking on an empty part of the workspace.

workspace context menu

Undo and Redo

If you make a mistake, you can use the Undo and Redo commands in the workspace context menu to get things back to how they were before the mistake.

Clean Up Blocks

Cleaning up blocks will cause all the blocks in the workspace to be organized in a single vertical column along the left side of the workspace. This can be useful if your workspace has gotten out of control.

Collapse and Expand Blocks

Collapsing and expanding blocks from the workspace context menu does it to all the blocks in the workspace.

Delete All

Deleting blocks from the workspace context menu will delete all the blocks in the workspace, and has the same effect as using the Menu, Clear Workspace command.

Keyboard Shortcuts

CTRL-C will copy the currently selected block and any blocks that would move with it if you dragged it.

CTRL-V will pase the most recently copied blocks slightly below and to the right of where it was copied (which may not be where you are looking).

The Delete key will delete the currently selected block and any blocks it contains.

CTRL-Z will undo the most recent change to the workspace.

Trash Can

The trash can is located in the bottom right of the workspace, no matter where you scroll.

trash
can

Dragging a block to the trash can deletes it from the workspace.

Clicking on the trash can will open the trash can and allow you to drag blocks that were deleted back into the workspace.

open trash can

The Command Menu

Commands that you can run on an entire workspace are located at the top of the page.

menu

Clear Workspace

The Clear Workspace command will delete all of the blocks in the current workspace.

Import Workspace The Import Workspace command will let you choose a local .blawx file to open in the current workspace. The contents of the uploaded file will overwrite the contents of the workspace.

Export Workspace

The Export Workspace command will allow you to save the current workspace to a local .blawx file, so that it can be shared with someone using a different Blawx server.

Run Blawx Code The Run Blawx Code command sends the current workspace to the Blawx reasoner and displays the results in the output area. Note that the Rune Blawx Code command also saves the current workspace to the Blawx server.

Help The Help command brings you to the Blawx.com documentation, which... is what you're reading right now.

Save and Close

The Save and Close command saves the current workspace to the Blawx server, and returns to the Workspace view. - model: blawx.docpage pk: guide/logic fields: title: Logic Blocks content: # Logic Blocks

This page describes the basic logic blocks available in the Logic drawer of the Toolbox.

Negation

Blawx provides you with two different types of negation.

The first type of negation is a "known false” block. It looks like this:

not

The second type of negation is a "not" block. It looks like this:

naf not

It is very important to understand the difference between them.

Inside a Fact or a Rule Conclusion, a "known false" block tells Blawx that the included statement is known with certainty to be false. Inside a Question or a Rule Condition, it asks Blawx to check to see whether it is known with certainty that the statement is false.

A "not" block does require that a thing is certainly false, but if it is known false, the "not" block will succeed. But a "not" block will also succeed if there is only no facts or rules that can be used to derive that the statement is true.

"Not" blocks can't be used in facts, or the conclusions of rules. They are used in queries, and in the conditions of rules.

Let's imagine you want to ask if there are no dogs. You might (incorrectly) write this code:

wrong not any dogs

But this code will not work as expected. A "known false" only returns “true” if its contents are explicitly stated to be false. But if a fact stated (or a rule concluded) "it is known false that any is in the category Dog", that would mean “it is impossible for an object to be a dog.” That is probably not what you meant to check for.

You don't want to know if that statement is explicitly false. You want to know whether you can find a specific example in which it is true. Put another way, you don't want to ask "is it true that nothing can be a dog?", you want to ask

"do you know of any examples of dogs?" So the "not" version is what you need.

correct not any dogs

That version of the rule will work as expected.

Another way to think about the difference is to think of statements as having opposites. "Known false" checks to see if the opposite is true. "Not" checks to see if the opposite is true, or if the statement can't be proven.

In law, we are familiar with this distinction between the two different kinds of negation. In criminal trials, when a court decides that a person is "not guilty", they are using the "not". "Not guilty" means either the person is innocent (the opposite of guilty), or there was not sufficient proof to find them guilty.

As a general rule, you usually want to use "not" in questions and in rule conditions. "Known fasle" is the only thing that will work in rule conclusions and facts.

Comparison

comparison

The comparison operator has 6 different comparisons it can make between two values, or objects.

They are quite self-explanatory. The block will succeed if the two values provided satisfy the condition, which is one of:

  • "is the same value as"
  • "is a different value from"
  • "is less than" * "is greater than"
  • "is less than or the same value as"
  • "is greater than or the same value as"

There are a couple of things to note. First, it will only work if the values are ordered, like numbers, or dates. Second, it compares the values, but it does not know whether the values are coming from the same source.

If you want to know whether objects referred to by two variables are the same object (they are "identical"), then you don't want to compare their values, you want to check their identities. That is done using the object equivalence or object disequivalence blocks.