Amend README.md to reflect shift of companion application (#64)
build and deploy Speckle functions / publish-automate-function-version (push) Has been cancelled

* Improves rule number handling

Adds a fallback mechanism for retrieving rule numbers.

This ensures the system can handle cases where the primary
"Rule Number" field is missing or empty, defaulting to "Rule #"
to maintain data integrity.
Also corrects some docstring formatting.

* Improves rule processing efficiency

Avoids unnecessary rule processing by checking rule severity against the minimum configured severity level. Also ensures that results are only attached to failed objects if they exist and meet the minimum severity criteria. Addresses a potential issue where rules with no "Report Severity" column could cause errors, by considering an alternative "Severity" column.

* Adds Python compatibility inspection

Ensures that the project is compatible with Python 3 by adding a compatibility inspection setting.

This will help to identify and address any potential compatibility issues early on.

* Updates integration test URL and severity.

Updates the default URL used in the integration test to a new speckle model checker endpoint.

Changes the minimum severity level from warning to info, increasing the detail of reported results.

* Updates Model Checker documentation

Updates the documentation to reflect the shift from a spreadsheet-based rule definition to the new Model Checker Application.

Explains how to access the application, create rules, and configure automations.

Also introduces the alternative TSV file format for programmatically generating rules or version controlling rules.
This commit is contained in:
Jonathon Broughton
2025-05-12 17:12:45 +01:00
committed by GitHub
parent 129132dd3a
commit 0019667302
+39 -30
View File
@@ -1,14 +1,13 @@
# Speckle Checker # Model Checker
Speckle Checker is an Automate function that validates Speckle objects against configurable rules defined in a Model Checker is an Automate function that validates Speckle objects against configurable rules. This approach provides
spreadsheet. This approach provides a flexible way to implement quality checks without coding, making it accessible to a flexible way to implement quality checks and maintain consistent standards across projects.
all team members.
## Overview ## Overview
The Checker function allows you to: The Model Checker allows you to:
- Define validation rules in a spreadsheet - Define validation rules for your objects
- Configure severity levels for issues - Configure severity levels for issues
- Check properties across different types of objects - Check properties across different types of objects
- Generate reports of validation results - Generate reports of validation results
@@ -16,39 +15,35 @@ The Checker function allows you to:
## Getting Started ## Getting Started
### 1. Prepare Your Rule Spreadsheet ### 1. Access the Model Checker Application
1. Access 1. Go to the [Model Checker Application](https://model-checker.speckle.systems)
the [template spreadsheet](https://docs.google.com/spreadsheets/d/1eB0RVuOXdjLyn4_GAPSahV05p1lqfSGQbH8WWijnkkA/edit?gid=0#gid=0) 2. Sign in with your Speckle account
2. Use the Speckle menu to launch the Speckle sidebar and make a copy. 3. Create and manage your validation rules through the intuitive web interface
3. Define your rules using the format explained below
4. Publish your rules by clicking "Publish Rules". Copy the resultant URL.
### 2. Create an Automation ### 2. Create an Automation
1. Go to your workspace project in [Speckle](https://app.speckle.systems/) 1. Go to your workspace project in [Speckle](https://app.speckle.systems/)
2. Create a new Automation 2. Create a new Automation
3. Select the Checker function 3. Select the Model Checker function
4. Configure the function: 4. Configure the function:
- Paste your published rules URL
- Set minimum severity level to report - Set minimum severity level to report
- Configure other options as needed - Configure other options as needed
5. Save and run your automation 5. Save and run your automation
## Rule Definition Format ## Rule Definition Format
Rules are defined in a spreadsheet with the following columns: Rules are defined with the following components:
| Rule Number | Logic | Property Name | Predicate | Value | Message | Report Severity | | Logic | Property Name | Predicate | Value | Message | Report Severity |
|-------------|-------|---------------|--------------|-----------|----------------------|-----------------| |-------|---------------|--------------|-----------|----------------------|-----------------|
| 1 | WHERE | category | matches | Walls | Wall thickness check | ERROR | | WHERE | category | matches | Walls | Wall thickness check | ERROR |
| 1 | AND | Width | greater than | 200 | | | | CHECK | Width | greater than | 200 | | |
| 2 | WHERE | category | matches | Columns | Column height check | WARNING | | WHERE | category | matches | Columns | Column height check | WARNING |
| 2 | AND | height | in range | 2500,4000 | | | | AND | height | in range | 2500,4000 | | |
### Column Explanation ### Component Explanation
- **Rule Number**: Groups conditions that belong to the same rule
- **Logic**: Defines how conditions are combined (WHERE, AND, CHECK) - **Logic**: Defines how conditions are combined (WHERE, AND, CHECK)
- **Property Name**: The object property or parameter to check - **Property Name**: The object property or parameter to check
- **Predicate**: Comparison operation (equals, greater than, etc.) - **Predicate**: Comparison operation (equals, greater than, etc.)
@@ -84,7 +79,7 @@ are reported as issues.
## Working with Object Properties ## Working with Object Properties
The Checker understands properties in Speckle objects regardless of schema: The Model Checker understands properties in Speckle objects regardless of schema:
- Direct properties: `category`, `name`, `id` - Direct properties: `category`, `name`, `id`
- Nested properties: `parameters.WIDTH.value` - Nested properties: `parameters.WIDTH.value`
@@ -95,27 +90,41 @@ The Checker understands properties in Speckle objects regardless of schema:
### Wall Thickness Check ### Wall Thickness Check
``` ```
Rule 1: WHERE category equals "Walls" AND width less than "200" Rule: WHERE category equals "Walls" AND width less than "200"
Message: "Wall too thin - minimum thickness is 200mm" Message: "Walls must have width of at least 200."
Severity: ERROR Severity: ERROR
``` ```
### Door Naming Convention ### Door Naming Convention
``` ```
Rule 2: WHERE category equals "Doors" AND name is not like "^D\d{3}$" Rule: WHERE category equals "Doors" AND name is not like "^D\d{3}$"
Message: "Door name must follow pattern D followed by 3 digits" Message: "All doors must have a name that follows the format "D" followed by three digits."
Severity: WARNING Severity: WARNING
``` ```
### Structural Column Height Range ### Structural Column Height Range
``` ```
Rule 3: WHERE category equals "Columns" AND is_structural is true AND height not in range "2400,4000" Rule: WHERE category equals "Columns" AND is_structural is true AND height not in range "2400,4000"
Message: "Structural column height outside acceptable range (2400-4000mm)" Message: "Structural columns must have a height between 2400 and 4000."
Severity: ERROR Severity: ERROR
``` ```
## Support ## Support
For issues or questions, please let us know on the [Speckle Community Forum](https://speckle.community/). For issues or questions, please let us know on the [Speckle Community Forum](https://speckle.community/).
### Alternative: TSV File Format
While the Model Checker Application is the recommended way to create and manage rules, you can also create compatible
TSV (Tab-Separated Values) files manually. This can be useful for:
- Programmatically generating rules
- Version controlling rules in a text format
- Integrating with existing workflows
- Creating rules in bulk
The TSV file should follow the same structure as shown in the table above, with columns separated by tabs. The file will
then need to be hosted somewhere and served with MIME-type of `text/tab-separated-values` and the URL used in the
automation configuration.