lexpedite / blawx

A user-friendly web-based tool for Rules as Code.

Blawx

A user-friendly web-based tool for Rules as Code written by Jason Morris of Lexpedite Legal Technologies Ltd..

Blocks + law = Blawx

Demonstration Video

Click on the thumbnail below for a recent video demonstration of how Blawx is used.

Overview

What is "Rules as Code"?

Rules as Code is the idea that if you write rules in a programming language at the same time you write them in a natural language, you end up with better rules, and you make it easier for people to automate implementations of those rules.

I believe:

1. The best tools for doing knowledge representation of laws are declarative logic programming languages.
2. Rules as Code requires tools that make it easy for non-programmers to do legal knowledge representation.
3. Tools for Rules as Code must be accessible, and transparent, which means they need to be open source.

What is Blawx?

Blawx is an open source, user-friendly, web-based declarative logic knowledge representation tool designed specifically for encoding, testing and using rules.

It is implemented as a set of applications.

It provides:

• a web server that stores your Blawx encodings and gives access to them and the reasoner over a RESTful API, based on Django
• a visual development environment based on Google's Blockly to write, edit, and test your encodings
• a reasoner based on SWI-Prolog and s(CASP) that will answer questions and explain the answers

Why Should I Use Blawx?

• Open Source
• Easy to Learn
• Designed Specifically for Rules as Code
• Publish Code as an API
• Explainability
• Hypothetical reasoning
• User-friendly Scenario Explorer

Blawx is the only open source Rules as Code programming environment with a user-friendly scenario explorer, explanations for answers, and hypothetical reasoning.

How Can I Try It?

The easiest way to try Blawx is to go to dev.blawx.com. I try to keep a recent version running there for people to play with.

How do I Install It Myself?

If you would like to try running Blawx locally, install docker for your platform, and then run

docker run lexpedite/blawx

Blawx will then be available at (http://localhost:8000)[http://localhost:8000].

Check out INSTALL.md for more details.

How Can I Learn More?

Extensive documentation is available from inside the application by clicking "Help" in the left navigation menu. You can also view the documentation on the live demo site.

Is this software production ready?

No. Blawx is functional, but it is not production-quality software. It is intended for educational and experimental purposes.

Contributions

If you have issues or concerns with the package, please open an Issue in the GitHub Repository. Contributions to the code and documentation are welcome. Please contribute responsibly.

blawx's Issues

unexpected answer to queries using data blocks

Above block generates a "no" and also search results.

Generated Blocks Do Not Update When Their Source is Updated

If you declare an attribute as having a type, the next time you open the Known Attributes section of the toolbox you will receive a block with the new datatype. But any blocks already in the workspace are not updated with the new datatype.

This is problematic, because there is nothing stopping you from having the same attribute name in two different categories, which means that we probably can't solve this problem until the attributes are identified by their category.

Stop using Sleep() in reasoner.php

Reasoner.php is using sleep() commands in order to wait for Flora-2 to be finished processing commands. Whether that will work is dependent on the length of the code and the speed and availability of the processor on which Flora-2 is running.

We could make the requests asynchronous, or re-implement the reasoner in python with Pyxf, and poll whether Flora-2 is finished, or implement something similar in PHP.

Disallow multiple queries in a workspace

If a workspace contains multiple queries, it's not clear which of them the reasoner is supposed to run, and if more than one, in what order.

Temporarily, this could be resolved by setting the maximum number of query blocks to one.

Add Date/Time/Duration Data Types

Flora-2 supports Date, DateTime, Time, and Duration datatypes.

Would require datatype selectors for each, and value-setting blocks for each.

Overridden Answers are Still Returned

If you use an override block to say that one rule overrides another rule, and the override is triggered, both the original and the new result are reported as true.

This is likely because Flora-2 requires you to specify that answers "oppose" one another with \opposes statements that are not currently being generated.

Need to think about whether to add \opposes to the existing block or create a new block for it.

Save Workspace doesn't work in Windows Edge

Improve Date and Time Field Interface

https://www.npmjs.com/package/@blockly/field-date

Provides a simple calendar interface, but there is no equivalent time field. Might need to write one.

database error at blawx.com

I went to blawx.com to look for documentation but the site showed only the text "Error establishing a database connection".

Generate custom object declaration blocks based on declared categories

Right now, in order to say "Jason is a Person" you have to say "Person is a Category", "Jason is an Object", and "Jason is a Person." The middle step is pointless and slows you down.

When you create a category, it should generate the category selection block, but it should also generate an object declaration block for that category in the Objects drawer of the toolbox.

So you would say "person is a category", and then you would go to the objects drawer and find "_____ is a Person" as one of the options, and fill in "Jason".

The risk is that it will be used mutliple times with regard to the same symbol, which is risky because of the risk of typos, so we should also make it so that you can't have two object declarations with the same value for the name.

It may also make sense to get rid of the generic "Object" declaration entirely, and force people to choose a declared category whenever creating an object.

Add tests for reasoner

New Version of FLora-2

There is a new RC for Flora2.1, which includes useful date and time calculations. Need to confirm that the existing code works properly with the new RC in dev.

Implication Operator has meaningless options

Right now the comparison operator includes --> and <--> which have no meaning.

Reasoner Crashes if not provided data

In the dev branch, If there is no data parameter in the API call, the reasoner calls the json to flora-2 translator anyway, which crashes when it tries to open a empty or non-existent file.

Add well-formedness checking

Using techniques similar to https://google.github.io/blockly-samples/plugins/disable-top-blocks/test/, I could check to see if the code is well-formed before allowing the user to send it to the reasoner, or highlight blocks that are not well-formed in real time in the interface.

Any orphaned blocks make the workspace not well-formed, and any value or statement connections that are empty would be not well-formed.

Assignment operator not accepting non-values

Assignment operators should be able to process a value, or the result of a statement that generates a value. Right now only values work.

Missing calculation operator

Dockerfile: Add COPY commands to avoid having to clone blawx twice

The Dockerfile currently clones blawx inside the Docker container. Instead, we want to make it so users can first git clone https://github.com/Blawx/blawx.git and run docker build -t blawx . without the Dockerfile telling Docker to git clone blawx inside the container. Instead, the Dockerfile should use COPY to copy the cloned blawx repo into the container.

Docassemble module for integrating with Blawx

Add tests for Code Generation

Remove unnecessary files from docker container

The container is unnecessarily cloning thee blawx repo to get access to the source files for the documentation. Dockerfile should copy them in instead.

New Blockly Release

Just need to confirm that the system has not been broken by any of the changes in the new quarterly release of Blockly.

installation on MacOS

Is it possible to install Blawx on MacOS? http://app.blawx.com/blawx.html site cannot be reached for live app.

Report compilation warnings and errors in the user interface

Can be done by parsing output from Flora-2 in reasoner.py and including the results in the output JSON, then optionally displaying those results in the user interface. May want to create a configuration for whether you want to display warnings.

Dockerize the Development Environment

It would be great if we could dockerize the app for the purpose of fcilitating development and deployment.

Eventually, it should be structured with more than one container, to allow each to grow as required. But for now, if we could just get the single-machine installation process streamlined that would be a big win.

Python3 Not Included in Docker Container

Reasoner.php is expecting Python3 to be installed on the machine. API data features will be failing right now in docker installations as a result.

Probably just something that needs to be added to the dockerfile.

Add Constraints

I need a constraint block, and it needs to be able to accept comparators and equations over numbers only. That is going to require changing how comparators and non-identity operators are in the same block, right now. Might need to move the comparator operators to math, but check to see if they work on anything else.

Need to clean up installation process

Had a bunch of problems trying to install Flora-2 on Ubuntu in windows. Need to go back through the installation process step by step and make sure everything works.

Aggregate functions not working properly

Permission Problem requires running Flora-2 as root

When running the reasoner with test data to see if it is connecting to Flora-2 properly, it is crashing.

Add Days Between Method

A method for calculating the number of calendar days between two dates or date times.

Raw \true and \false values being displayed in reasoner interface.

Since fixing #8, raw \true and \false values are appearing in the reasoner. Need to get rid of those to make it look pretty.

Add Attribution Blocks with Cardinality

Cardinality for an attribute is how many values that attribute can have. One way to do this would be to create a set of 4 (or 5) different attribute declarations:

• up to X
• at least X
• between X and Y
• exactly X
• optionally, any number, which is duplicative of zero or more.

Add search capabilities to workspace

https://www.npmjs.com/package/@blockly/plugin-workspace-search

Adding include block and not providing name breaks workspace.

Queries Fail if Not at the Bottom of the Workspace

The above query fails if the order of the blocks is reversed.

Errors in reasoner.php under WSL2

The installation process has been updated to adjust for some of the changes caused by WSL2 and Ubuntu 20.04 running in Windows 10. However, the current installation process results in PHP errors being thrown from reasoner.php.

It is likely that the cause is a permission problem, or changes in where files are located on the new system.

Feedback when running code without query is unclear

The interface should probably notice, and advise the user that it won't do anything.

Import blocks don't chain

If you import a file with an import statement in it, the "inside" import statement doesn't work.

Add package.json for npm dependency management

We should add a package.json to the repository for npm dependency management. This will help optimize Docker builds so npm install blockly xmlhttprequest can be replaced with npm install.

npm install will look at package.json to determine if any packages have been updated and only install/updated the dependencies if so.

I'm definitely not an expert with npm dependencies, so please feel free to correct me here if I'm wrong anywhere.

(self-assigning this @Gauntlet173!)

npm init reference: https://docs.npmjs.com/cli/init

Import Block Definitions from .json

Right now the block definitions are duplicated in the interface code in blawx_blocks.js and in decode.js.
Decode.js should just be importing blawx_blocks.js, or something.

Revise update.sh to rebuild docker container

npm warnings in docker container build process

npm WARN deprecated [email protected]: request-promise-native has been deprecated because it extends the now deprecated request package, see https://github.com/request/request/issues/3142
npm WARN deprecated [email protected]: request has been deprecated, see https://github.com/request/request/issues/3142
npm WARN deprecated [email protected]: this library is no longer supported

Installation was in Gauntlet173/date branch, but likely exists in all of them

Allow Long Search Results

Currently anything past 1k of data is cut off.

Boolean Data Values Inconsistent

Flora-2 uses \true as a boolean truth value, but Blawx is using true, which is an object named "true" in Flora-2. This is probably going to cause problems.

Add Rule Meta-Data

Facts and rules can have IDs, tags, defeasibility (strict, or defeasible), and arbitrary additional meta data. It would make sense to include 'link' and 'description' as basic meta-data elements for explainability.

The design challenge is to add these capabilities to both blocks without making them huge, and ugly.

In the best-case scenario there would be a mutator with the ability to specify which meta-data elements should be included.

As a first step, we might have two versions of the fact and rule blocks. One with meta-data, one without.

Remove Calculation Operator

For now, we are working on a naive implementation of the \is operator from Flora-2 to allow for mathematical calculations.

At some point, it would be preferrable to get rid of it by having math blocks de-nest, and turn into a chain of linked statements with randomly generated silent variable names.

For example, (4-2)+(7*8) would be interpreted as
?_x \is ?_a + ?_b, ?_a \is 4-2, ?_b \is 7*8, and then ?_x would be used in the place of the statement. Scoping the extra lines of code is going to be complicated, but it's feasible. So this is a wish-list item.

Add toType methods for datatypes

Currently, the value blocks allow you to type in things like dates and times, but you cannot use the value of other variables in order to generate them. We could allow that by including a toType method block for each of the types.

Comparison Operator May Be Missing Options

It currently does not have a unity operator, numerical equality operator, or the inequality operator from Flora-2, among others that may be less important. Numerical equality may not be important in the absence of different numerical types, I'm not sure.

Redesign results interface as modal

https://www.npmjs.com/package/@blockly/plugin-modal

Provides a library for displaying messages to the user in a modal window.