Merge pull request #62 from specklesystems/cdriesler-patch-1

Update main.yml

.github/workflows/main.yml

@@ -44,3 +44,4 @@ jobs:
           speckle_function_id: ${{ secrets.SPECKLE_FUNCTION_ID }}
           speckle_function_input_schema_file_path: ${{ env.FUNCTION_SCHEMA_FILE_NAME }}
           speckle_function_command: 'python -u main.py run'
+          speckle_function_recommended_memory_mi: 5000

DEVELOPER_README.md

@@ -1,56 +1,377 @@
-# Checker Function Development Guide
+# Checker Function Developer Guide
 
-## Setup
+This document provides technical details for developers working on the Speckle Checker Automate function.
 
-1. Install dependencies:
+## Project Overview
+
+The Checker function enables validation of Speckle objects against user-defined rules in a spreadsheet. It's designed to
+be flexible, supporting various object schemas including both v2 and v3 Speckle APIs.
+
+## Setup Development Environment
+
+### Prerequisites
+
+- Python 3.10+
+- Poetry for dependency management
+
+### Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   poetry install
+   ```
+3. Activate the virtual environment:
+   ```bash
+   poetry shell
+   ```
+
+### Test Automation Environment
+
+The project uses Speckle's [Test Automation feature](https://speckle.guide/automate/function-testing.html) to run
+integration tests against real Speckle data. This provides a sandboxed environment to validate the function's business
+logic without triggering actual automations.
+
+#### Setting Up a Test Automation
+
+1. Navigate to your Speckle project
+2. Go to the **Automations** tab
+3. Click **New Automation**
+4. Select **Create Test Automation** in the bottom left
+5. Follow the configuration steps
+
+Note: To create a test automation, you must:
+
+- Be an owner of the Speckle project
+- Have published this function to the Function Library
+- Have at least one release for the function
+
+#### Environment Configuration
+
+For local integration testing, create a `.env` file in the project root with these variables:
+
+```
+# Your Personal Access Token from Speckle
+SPECKLE_TOKEN=your_speckle_token
+
+# The Speckle server URL
+SPECKLE_SERVER_URL=https://app.speckle.systems
+
+# From the test automation URL: /projects/[project-id]/automations/[automation-id]
+SPECKLE_PROJECT_ID=your_project_id
+SPECKLE_AUTOMATION_ID=your_automation_id
+```
+
+This configuration allows the test suite to:
+
+1. Connect to your test automation via the Speckle API
+2. Run the function locally against real Speckle data
+3. Submit results to the test automation for validation
+
+For detailed instructions, refer to
+the [official documentation on function testing](https://speckle.guide/automate/function-testing.html#how-to-create-a-test-automation).
+
+#### Running Integration Tests
+
+With the `.env` file configured:
 
 ```bash
-poetry shell && poetry install
+# Run the integration tests
+pytest test_function.py
 ```
 
-2. Configure `.env`:
+The SDK utilities will automatically:
 
-```
-SPECKLE_TOKEN=your_speckle_token
-SPECKLE_SERVER_URL=app.speckle.systems
+- Connect to your test automation
+- Execute your function with the specified test data
+- Submit results back to Speckle
+
+Test results will be visible on the automation page in the Speckle UI.
+
+#### Unit Tests
+
+For unit tests that don't require a full Speckle connection, you can run:
+
+```bash
+# Run unit tests only
+pytest test_comparisons.py test_rule_processing.py
 ```
 
-Get test automation details from app.speckle.systems
+Note: The `.env` file should never be committed to version control (it's included in .gitignore)
 
 ## Project Structure
 
-- `function.py`: Main business logic
-- `rules.py`: Rule definitions and processing
-- `inputs.py`: Function input schema
-- `helpers.py`: Utility functions
-- `spreadsheet.py`: TSV handling
+```
+├── main.py                  # Entry point for Automate
+├── src/
+│   ├── function.py          # Main function logic
+│   ├── inputs.py            # Function input schema
+│   ├── helpers.py           # Utility functions
+│   ├── filters.py           # Object filtering functions
+│   ├── rules.py             # Rule definitions and property handling
+│   ├── predicates.py        # Predicate mapping for spreadsheet values
+│   ├── rule_processor.py    # Rule application and result handling
+│   └── spreadsheet.py       # TSV file parsing
+├── tests/
+│   ├── conftest.py          # Test fixtures
+│   ├── test_function.py     # Main function tests
+│   ├── test_comparisons.py  # Value comparison tests
+│   ├── test_parameters.py   # Parameter handling tests
+│   └── test_rule_processing.py  # Rule processing tests
+├── pyproject.toml           # Project dependencies
+└── poetry.lock              # Locked dependencies
+```
+
+## Core Components
+
+### 1. Function Execution Flow
+
+The main execution flow is defined in `function.py`:
+
+1. `automate_function()` receives context and inputs from Automate
+2. Retrieves Speckle objects via `automate_context.receive_version()`
+3. Flattens the object tree using `flatten_base()`
+4. Loads rules from the spreadsheet URL via `read_rules_from_spreadsheet()`
+5. Applies rules to objects using `apply_rules_to_objects()`
+6. Reports results via the Automate context
+
+### 2. Rule Processing
+
+Rules are processed through several stages:
+
+1. **Spreadsheet Parsing** (`spreadsheet.py`):
+    - Reads TSV data
+    - Groups rules by rule number
+    - Validates rule structure
+
+2. **Rule Application** (`rule_processor.py`):
+    - Processes rule logic (WHERE, AND, CHECK)
+    - Evaluates conditions against objects
+    - Attaches results to objects in Automate context
+
+3. **Property Rules** (`rules.py`):
+    - Handles property lookups in objects
+    - Implements comparison logic
+    - Supports both v2 and v3 Speckle schemas
+
+### 3. Property Access System
+
+The system uses a flexible property access mechanism that works with different Speckle schemas:
+
+- **V2 Schema**: Properties in `parameters` dictionary with internal definition names
+- **V3 Schema**: Properties in nested `properties.Parameters` structure
+
+The `PropertyRules` class provides methods to:
+
+- Find properties by path or name
+- Extract values with appropriate type conversion
+- Perform comparisons with tolerance and type handling
+
+## Test-Driven Development for Rules
+
+The test infrastructure is designed to support Test-Driven Development (TDD) when creating new rules or extending
+functionality. This approach is especially powerful for rule development as it allows you to verify behavior against
+known test objects.
+
+### Using Test Fixtures for Rule Development
+
+The `conftest.py` file contains test fixtures that provide sample Speckle objects for testing:
+
+```python
+@pytest.fixture
+def v2_wall():
+    """Creates a v2-style Speckle wall object"""
+    wall = Base()
+    wall.id = "cdb18060dc48281909e94f0f1d8d3cc0"
+    wall.type = "W30(Fc24)"
+    wall.units = "mm"
+    wall.family = "Basic Wall"
+    wall.height = 1400
+    wall.flipped = False
+    wall.category = "Walls"
+    # ... more properties
+
+    return wall
+
+
+@pytest.fixture
+def v3_wall():
+    """Creates a v3-style Speckle wall object"""
+    wall = Base()
+    wall.id = "46f06fef727d64a0bbcbd7ced51e0cd2"
+    wall.name = "Walls - W30(Fc24)"
+    wall.type = "W30(Fc24)"
+    wall.units = "mm"
+    wall.family = "Basic Wall"
+    # ... more properties
+
+    return wall
+```
+
+These fixtures create standardized test objects that represent different Speckle schema versions, allowing you to test
+rule behavior consistently.
+
+### TDD Workflow for New Rules
+
+When developing a new rule or predicate, follow this TDD approach:
+
+1. **Add test fixtures**: First, expand `conftest.py` with representative objects that your rule will process
+
+2. **Write tests first**: Create test cases in a test file (e.g., `test_my_rule.py`):
+   ```python
+   def test_new_wall_rule(v2_wall, v3_wall):
+       """Test a new rule that checks wall thickness requirements"""
+       # Test with v2 schema
+       assert PropertyRules.is_new_wall_check(v2_wall, "width", "300")
+       
+       # Test with v3 schema
+       assert PropertyRules.is_new_wall_check(v3_wall, "Width", "300")
+       
+       # Test failure case
+       v2_wall.parameters["WALL_ATTR_WIDTH_PARAM"].value = 200
+       assert not PropertyRules.is_new_wall_check(v2_wall, "width", "300")
+   ```
+
+3. **Implement the rule**: Add the new rule method to the `PropertyRules` class in `rules.py`:
+   ```python
+   @staticmethod
+   def is_new_wall_check(speckle_object: Base, parameter_name: str, expected_value: str) -> bool:
+       """Checks if a wall meets specific thickness requirements"""
+       parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
+       # Implement rule logic
+       return result
+   ```
+
+4. **Add to predicate mapping**: Register your new rule in `predicates.py`:
+   ```python
+   PREDICATE_METHOD_MAP = {
+       # Existing predicates...
+       "new_wall_check": PropertyRules.is_new_wall_check.__name__,
+   }
+   ```
+
+5. **Run tests to verify**:
+   ```bash
+   pytest test_my_rule.py -v
+   ```
+
+### Creating Comprehensive Test Objects
+
+For the most effective testing, your test objects in `conftest.py` should:
+
+1. **Include diverse objects**: Walls, columns, beams, etc.
+2. **Cover edge cases**: Null values, missing properties, special characters
+3. **Represent both schemas**: Include both v2 and v3 format objects
+4. **Include real-world examples**: Extract sample objects from actual projects
+
+You can extract real objects for testing using:
+
+```python
+# Example code to extract and save real objects for test fixtures
+from specklepy.api import operations
+from specklepy.api.client import SpeckleClient
+from specklepy.transports.server import ServerTransport
+
+client = SpeckleClient(host="app.speckle.systems")
+client.authenticate_with_token(token)
+
+transport = ServerTransport(client=client, stream_id="stream_id")
+obj = operations.receive("object_id", transport)
+
+# Print structure to help with fixture creation
+print(obj.get_member_names())
+print(obj.get_dynamic_member_names())
+```
+
+By following this TDD approach and maintaining comprehensive test fixtures, you can develop robust rules that work
+reliably across different object schemas and handle edge cases appropriately.
 
 ## Testing
 
+### Running Tests
+
 ```bash
-poetry run pytest
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_parameters.py
+
+# Run with coverage
+pytest --cov=src
 ```
 
-## Extending Rules
+### Test Data
 
-1. Add new predicate to `input_predicate_mapping` in `rules.py`
-2. Create corresponding method in `PropertyRules` class
-3. Update tests
+Test fixtures in `conftest.py` provide sample objects:
 
-## Building
+- `v2_wall`: Wall object in v2 schema
+- `v3_wall`: Wall object in v3 schema
 
-The function is packaged as a Docker container:
+### Manual Testing with Real Data
 
-```bash
-docker build -f ./Dockerfile -t checker .
-```
+For testing with real Speckle data:
 
-## Local Testing
+```python
+from specklepy.api import operations
+from specklepy.api.client import SpeckleClient
+from specklepy.api.credentials import get_account_from_token
+from specklepy.transports.server import ServerTransport
 
-```bash
-docker run --rm checker python -u main.py run [automation_data] [parameters] [token]
+client = SpeckleClient(host="app.speckle.systems")
+account = get_account_from_token(token, "app.speckle.systems")
+client.authenticate_with_account(account)
+
+transport = ServerTransport(client=client, stream_id="your_stream_id")
+commit = client.commit.get(stream_id="your_stream_id", commit_id="your_commit_id")
+obj = operations.receive(commit.referencedObject, transport)
 ```
 
 ## Deployment
 
-Create a GitHub release to trigger deployment to Speckle Automate.
+The function is deployed through GitHub Actions:
+
+1. Create a GitHub release to trigger the build workflow
+2. The workflow builds the necessary artifacts and pushes them to the Speckle Automate registry
+3. The function becomes available in the Speckle Automate UI
+
+## Performance Considerations
+
+- **Large Object Trees**: When processing large models, use aggressive filtering with WHERE clauses
+- **Rule Complexity**: Minimize the number of nested property lookups
+- **Memory Usage**: Be aware of object reference handling and avoid deep copies
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Rule not matching expected objects**:
+    - Check property paths for the specific object type
+    - Verify data types (strings vs. numbers)
+    - Enable debug logging
+
+2. **Slow performance**:
+    - Check for inefficient property lookups
+    - Add more specific WHERE filters to reduce object set
+
+3. **Docker build failures**:
+    - Check dependency compatibility
+    - Verify Python version requirements
+
+## Contributing
+
+1. Create a branch for your feature or fix
+2. Add tests for new functionality
+3. Update documentation
+4. Submit a pull request
+5. Ensure CI tests pass
+
+## Future Development
+
+Potential improvements:
+
+- Support for more complex rule logic (OR conditions)
+- UI-based rule editor
+- Result visualization tools
+- Performance optimizations for large models
+- Support for referencing other objects in rules

README.md

@@ -1,36 +1,121 @@
-# Public Function: Checker
+# Speckle Checker
 
-Validate Speckle objects against configurable rules using spreadsheet definitions.
+Speckle Checker is an Automate function that validates Speckle objects against configurable rules defined in a
+spreadsheet. This approach provides a flexible way to implement quality checks without coding, making it accessible to
+all team members.
 
-## Usage
+## Overview
 
-1. Access the template Google Sheet [link needed]
-2. Make a copy to your Google Drive using File > Make a copy
-3. Define your rules in your sheet
-4. Click "Speckle" menu > "Publish Rules" to get your TSV URL
-5. Create an Automation in Speckle Automate using the Checker function
-6. Paste your TSV URL into the function configuration
-7. Run your automation
+The Checker function allows you to:
 
-## Rule Types
+- Define validation rules in a spreadsheet
+- Configure severity levels for issues
+- Check properties across different types of objects
+- Generate reports of validation results
+- Apply consistent standards across projects
 
-- Property existence
-- Value matching
-- Numeric comparisons
-- Range checks
-- List membership
-- Pattern matching
-- Boolean checks
+## Getting Started
 
-## Severity Levels
+### 1. Prepare Your Rule Spreadsheet
 
-- WARNING: Issues that should be reviewed
-- ERROR: Critical issues requiring attention
+1. Access
+   the [template spreadsheet](https://docs.google.com/spreadsheets/d/1eB0RVuOXdjLyn4_GAPSahV05p1lqfSGQbH8WWijnkkA/edit?gid=0#gid=0)
+2. Use the Speckle menu to launch the Speckle sidebar and make a copy.
+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
+
+1. Go to your workspace project in [Speckle](https://app.speckle.systems/)
+2. Create a new Automation
+3. Select the Checker function
+4. Configure the function:
+    - Paste your published rules URL
+    - Set minimum severity level to report
+    - Configure other options as needed
+5. Save and run your automation
+
+## Rule Definition Format
+
+Rules are defined in a spreadsheet with the following columns:
+
+| Rule Number | Logic | Property Name | Predicate    | Value     | Message              | Report Severity |
+|-------------|-------|---------------|--------------|-----------|----------------------|-----------------|
+| 1           | WHERE | category      | matches      | Walls     | Wall thickness check | ERROR           |
+| 1           | AND   | Width         | greater than | 200       |                      |                 |
+| 2           | WHERE | category      | matches      | Columns   | Column height check  | WARNING         |
+| 2           | AND   | height        | in range     | 2500,4000 |                      |                 |
+
+### Column Explanation
+
+- **Rule Number**: Groups conditions that belong to the same rule
+- **Logic**: Defines how conditions are combined (WHERE, AND, CHECK)
+- **Property Name**: The object property or parameter to check
+- **Predicate**: Comparison operation (equals, greater than, etc.)
+- **Value**: Reference value for comparison
+- **Message**: Description shown in validation results
+- **Report Severity**: ERROR, WARNING, or INFO
+
+### Supported Predicates
+
+| Predicate        | Description                 | Example                               |
+|------------------|-----------------------------|---------------------------------------|
+| exists           | Checks if a property exists | `height` exists                       |
+| equal to         | Exact value match           | `width` equal to `300`                |
+| not equal to     | Value doesn't match         | `material` not equal to `Concrete`    |
+| greater than     | Value exceeds threshold     | `height` greater than `3000`          |
+| less than        | Value below threshold       | `thickness` less than `50`            |
+| in range         | Value within bounds         | `elevation` in range `0,10000`        |
+| in list          | Value in allowed set        | `type` in list `W1,W2,W3`             |
+| contains         | Property contains substring | `name` contains `Beam`                |
+| does not contain | Property doesn't contain    | `name` does not contain `temp`        |
+| is true          | Boolean property is true    | `is_structural` is true               |
+| is false         | Boolean property is false   | `is_placeholder` is false             |
+| is like          | Loose text matching         | `name` is like `Wall` matches `Walls` |
+
+## Rule Logic
+
+- **WHERE**: Filters objects to check (like SELECT WHERE in SQL)
+- **AND**: Additional filter conditions
+- **CHECK**: Final check condition (optional, defaults to last AND)
+
+Objects pass a rule when they match all conditions. Objects that match WHERE/AND filters but fail the CHECK condition
+are reported as issues.
+
+## Working with Object Properties
+
+The Checker understands properties in Speckle objects regardless of schema:
+
+- Direct properties: `category`, `name`, `id`
+- Nested properties: `parameters.WIDTH.value`
+- Revit parameters: Use parameter names like `Mark`, `Width`, `Assembly Code`
 
 ## Example Rules
 
-[Screenshot or example table to be added]
+### Wall Thickness Check
+
+```
+Rule 1: WHERE category equals "Walls" AND width less than "200"
+Message: "Wall too thin - minimum thickness is 200mm"
+Severity: ERROR
+```
+
+### Door Naming Convention
+
+```
+Rule 2: WHERE category equals "Doors" AND name is not like "^D\d{3}$"
+Message: "Door name must follow pattern D followed by 3 digits"
+Severity: WARNING
+```
+
+### Structural Column Height Range
+
+```
+Rule 3: 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)"
+Severity: ERROR
+```
 
 ## Support
 
-For issues or questions, please open a GitHub issue.
+For issues or questions, please let us know on the [Speckle Community Forum](https://speckle.community/).

src/function.py

@@ -1,7 +1,17 @@
-"""This is the main function that will be executed when the automation is triggered.
+"""This is the main entry point for the Speckle Automate function.
 
-It will receive the inputs from the user, and the context of the run.
-It will then apply the rules to the objects in the model, and report back the results.
+The Speckle Automate system works as follows:
+1. When a model is committed to Speckle, it triggers automations associated with the project
+2. For each automation, Speckle Automate prepares a runtime environment and context
+3. The automation context includes the model data and function inputs
+4. This function is executed to process the model and provide results
+5. Results are attached to objects in the model, creating an annotated view
+
+This function implements a configurable rule-based validation system that:
+- Reads validation rules from an external spreadsheet
+- Applies these rules to objects in the Speckle model
+- Reports validation results back to the Speckle platform
+- Provides an annotated view of the model showing validation issues
 """
 
 from speckle_automate import AutomationContext
@@ -19,38 +29,77 @@ def automate_function(
     automate_context: AutomationContext,
     function_inputs: FunctionInputs,
 ) -> None:
-    """This VERSION of the function will add a check for the new provide inputs.
+    """Main entry point for the Speckle Automate function.
+
+    This function is called by the Speckle Automate system when the automation is triggered.
+    It orchestrates the entire validation process:
+
+    1. Receiving and flattening the model data
+    2. Detecting the Speckle object schema version
+    3. Loading and grouping rules from the external spreadsheet
+    4. Applying rules to objects and collecting results
+    5. Reporting results back to the Speckle platform
 
     Args:
-        automate_context: A context helper object, that carries relevant information
-            about the runtime context of this function.
-            It gives access to the Speckle project data, that triggered this run.
-            It also has convenience methods attach result data to the Speckle model.
-        function_inputs: An instance object matching the defined schema.
+        automate_context: A context helper provided by Speckle Automate that:
+            - Provides access to the Speckle model data
+            - Handles result reporting and view management
+            - Manages run status (success, failure, exception)
+        function_inputs: User-provided inputs defined in the FunctionInputs schema,
+            particularly the URL to the rules spreadsheet
     """
-    # the context provides a convenient way, to receive the triggering VERSION
+    # -------------------------------------------------------------------------
+    # Step 1: Receive and process the model data
+    # -------------------------------------------------------------------------
+
+    # The AutomationContext provides a convenient way to access the model data
+    # that triggered this automation run
     version_root_object: Base = automate_context.receive_version()
 
-    # We can continue to work with a flattened list of objects.
+    # Flatten the object tree into a list of objects
+    # The Speckle object model is hierarchical, but for validation purposes,
+    # it's easier to work with a flat list of objects
     flat_list_of_objects = list(flatten_base(version_root_object))
 
-    # If it is a next_gen model, we can get the VERSION from the root object
-    # This function's rules don't make use of this check, but it is here for reference if you want to.
+    # -------------------------------------------------------------------------
+    # Step 2: Detect Speckle object schema version
+    # -------------------------------------------------------------------------
+
+    # The Speckle object schema has evolved over time
+    # In newer models, we can detect the version from the root object
+    # This version information helps our validation logic handle different schemas
     global VERSION
     VERSION = getattr(version_root_object, "version", 2)  # noqa: F841SION = getattr(version_root_object,"version", 2)  # noqa: F841  # noqa: F841
 
-    # Read and group rules
+    # In v2, parameters are stored in a 'parameters' dictionary on each object
+    # In v3, they are nested in 'properties.Parameters' with categorization
+    speckle_print(f"Detected Speckle object schema version: {VERSION}")
+
+    # -------------------------------------------------------------------------
+    # Step 3: Load and process rules from the spreadsheet
+    # -------------------------------------------------------------------------
+
+    # The rules are defined in an external spreadsheet (TSV format)
+    # This allows non-technical users to define and modify rules
+    # without changing the code
     grouped_rules, messages = read_rules_from_spreadsheet(function_inputs.spreadsheet_url)
 
-    # Handle any validation messages
+    # Handle any validation messages from rule processing
     for message in messages:
         speckle_print(message)  # or log them appropriately
 
+    # If rule processing failed, mark the run as failed and exit
     if grouped_rules is None:
         automate_context.mark_run_exception("Failed to process rules")
         return
 
-    # apply the rules to the objects
+    # -------------------------------------------------------------------------
+    # Step 4: Apply rules to objects and collect results
+    # -------------------------------------------------------------------------
+
+    # This is where the actual validation happens
+    # Each rule is applied to relevant objects, and results are collected
+    # Results are attached to objects in the model to create an annotated view
     apply_rules_to_objects(
         flat_list_of_objects,
         grouped_rules,
@@ -59,10 +108,16 @@ def automate_function(
         hide_skipped=function_inputs.hide_skipped,
     )
 
-    # set the automation context view, to the original model / VERSION view
+    # -------------------------------------------------------------------------
+    # Step 5: Finalize the automation run
+    # -------------------------------------------------------------------------
+
+    # Set the context view to the original model/version view
+    # This ensures that the results are displayed in the correct context
     automate_context.set_context_view()
 
-    # report success
+    # Mark the run as successful and provide a summary message
+    # This message will be displayed to the user in the Speckle UI
     automate_context.mark_run_success(
         f"Successfully applied {len(grouped_rules)} rules to {len(flat_list_of_objects)} version {VERSION} objects."
     )

src/rule_processor.py

@@ -1,4 +1,16 @@
-"""Module for processing rules against Speckle objects and updating the automate context with the results."""
+"""Module for processing rules against Speckle objects and updating the automate context with the results.
+
+This module implements the core rule processing logic that:
+1. Validates rule structure and logic
+2. Evaluates rule conditions against Speckle objects
+3. Separates filtering conditions and final check conditions
+4. Processes rule groups and tracks results
+5. Reports results back to the Speckle Automate context
+
+The rule processing follows a "filter then validate" approach:
+- Filter conditions (WHERE, AND) narrow down which objects to check
+- The final check condition (CHECK or last AND) determines pass/fail
+"""
 
 import json
 from enum import Enum
@@ -18,6 +30,11 @@ from src.rules import PropertyRules
 def validate_rule_structure(rule_group: pd.DataFrame) -> None:
     """Validates the structure and logic of a rule group.
 
+    This ensures the rule follows the proper format:
+    - First condition must be WHERE
+    - Following conditions can be AND
+    - Only one CHECK condition is allowed (and must be last)
+
     Args:
         rule_group: DataFrame containing the rule conditions
 
@@ -58,47 +75,61 @@ def validate_rule_structure(rule_group: pd.DataFrame) -> None:
 def evaluate_condition(
     speckle_object: Base, condition: pd.Series, rule_number: str | None = None, case_number: int | None = None
 ) -> bool:
-    """Given a Speckle object and a condition, evaluates the condition and returns a boolean value.
+    """Evaluates a single condition against a Speckle object.
 
-    A condition is a pandas Series object with the following keys:
-    - 'Property Name': The name of the property to evaluate.
-    - 'Predicate': The predicate to use for evaluation.
-    - 'Value': The value to compare against.
+    This function is the bridge between the rules defined in the spreadsheet
+    and the property checking methods in PropertyRules. It:
+    1. Extracts the property name, predicate, and value from the condition
+    2. Maps the predicate to the corresponding method in PropertyRules
+    3. Calls the method with the object, property name, and value
 
     Args:
-        rule_number (string): For information the rule number.
-        case_number (int): For information the rule clause number.
-        speckle_object (Base): The Speckle object to evaluate.
-        condition (pd.Series): The condition to evaluate.
+        speckle_object: The Speckle object to evaluate against
+        condition: A pandas Series containing the condition details
+            - 'Property Name': The name of the property to check
+            - 'Predicate': The comparison operation (like 'equals', 'greater than')
+            - 'Value': The value to compare against
+        rule_number: For tracking, the rule number being evaluated
+        case_number: For tracking, the condition number within the rule
 
     Returns:
-        bool: The result of the evaluation. True if the condition is met, False otherwise.
+        True if the condition is met, False otherwise
     """
     property_name = condition["Property Name"]
     predicate_key = condition["Predicate"]
     value = condition["Value"]
 
+    # Debugging info
     _ = rule_number
     _ = case_number
 
+    # Look up the method name in the predicate map
+    # This map connects spreadsheet predicates to PropertyRules methods
     if predicate_key in PREDICATE_METHOD_MAP:
         method_name = PREDICATE_METHOD_MAP[predicate_key]
         method = getattr(PropertyRules, method_name, None)
 
         if method:
+            # Call the method with the object, property name, and value
             return method(speckle_object, property_name, value)
 
     return False
 
 
 def get_filters_and_check(rule_group: pd.DataFrame) -> tuple[pd.DataFrame, pd.Series]:
-    """Separates rule conditions into filters and final check.
+    """Separates rule conditions into filtering conditions and the final check condition.
+
+    This function handles two rule formats:
+    1. Explicit format: WHERE + AND... + CHECK
+    2. Legacy format: WHERE + AND... (last AND is implicitly the check)
+
+    This separation enables the "filter then validate" approach.
 
     Args:
         rule_group: DataFrame containing rule conditions
 
     Returns:
-        Tuple containing filter conditions and final check condition
+        Tuple containing (filter_conditions, final_check_condition)
     """
     if rule_group.empty:
         return pd.DataFrame(), pd.Series()
@@ -135,16 +166,21 @@ def get_filters_and_check(rule_group: pd.DataFrame) -> tuple[pd.DataFrame, pd.Se
 def process_rule(
     speckle_objects: list[Base], rule_group: pd.DataFrame
 ) -> tuple[list[Any], list[Any]] | tuple[list[Base], list[Base]]:
-    """Processes a set of rules against Speckle objects, returning those that pass and fail.
+    """Processes a rule group against a list of Speckle objects.
 
-    The first rule is used as a filter ('WHERE'), and subsequent rules as conditions ('AND').
+    This function implements the "filter then validate" approach:
+    1. Apply filter conditions sequentially to narrow down objects
+    2. Apply the final check condition to determine pass/fail
+
+    This approach is efficient for large models as it reduces the number
+    of objects that need full validation.
 
     Args:
-        speckle_objects: List of Speckle objects to be processed.
-        rule_group: DataFrame defining the filter and conditions.
+        speckle_objects: List of Speckle objects to be processed
+        rule_group: DataFrame defining the filter and check conditions
 
     Returns:
-        A tuple of lists containing objects that passed and failed the rule.
+        A tuple of lists (pass_objects, fail_objects)
     """
     if not speckle_objects or rule_group.empty:
         return [], []
@@ -177,6 +213,7 @@ def process_rule(
             return [], []
 
     # For remaining objects, evaluate the final check
+    # This separates objects into pass/fail groups
     pass_objects = []
     fail_objects = []
 
@@ -198,14 +235,23 @@ def apply_rules_to_objects(
     minimum_severity: MinimumSeverity = MinimumSeverity.INFO,
     hide_skipped: bool = False,
 ) -> dict[str, tuple[list[Base], list[Base]]]:
-    """Applies defined rules to a list of objects and updates the automate context based on the results.
+    """Applies defined rules to a list of objects and updates the automate context with the results.
+
+    This is the main orchestration function that:
+    1. Processes each rule group against all objects
+    2. Filters results based on severity levels
+    3. Attaches results to objects in the Speckle Automate context
+    4. Reports skipped rules (where no objects matched filters)
 
     Args:
-        speckle_objects (List[Base]): The list of objects to which rules are applied.
-        grouped_rules (pd.DataFrameGroupBy): The DataFrame containing rule definitions.
-        automate_context (Any): Context manager for attaching rule results.
+        speckle_objects: The list of objects to which rules are applied
+        grouped_rules: The rules grouped by rule number
+        automate_context: Context manager for attaching results to objects
         minimum_severity: Minimum severity level to report
-        hide_skipped: Whether to hide skipped tests
+        hide_skipped: Whether to hide skipped rules in results
+
+    Returns:
+        Dictionary mapping rule IDs to (pass_objects, fail_objects) tuples
     """
     grouped_results = {}
     rules_processed = 0
@@ -249,7 +295,13 @@ def apply_rules_to_objects(
 
 
 class SeverityLevel(Enum):
-    """Enum for severity levels."""
+    """Enumeration for severity levels of rule results.
+
+    These severity levels determine how rule failures are displayed:
+    - INFO: Informational, no action required
+    - WARNING: Potential issue that should be reviewed
+    - ERROR: Critical issue requiring attention
+    """
 
     INFO = "Info"
     WARNING = "Warning"
@@ -257,13 +309,19 @@ class SeverityLevel(Enum):
 
 
 def get_severity(rule_info: pd.Series) -> SeverityLevel:
-    """Convert a string severity level to the corresponding SeverityLevel enum.
+    """Convert a string severity level from the spreadsheet to the corresponding SeverityLevel enum.
 
-    This function normalizes input strings (because processing user entered dead is hard), handling:
+    This function normalizes user input with robust handling for:
     - Case insensitivity (e.g., "info", "WARNING" → "Info", "Warning")
     - Shorthand mappings (e.g., "WARN" → "Warning")
-    - Stripping whitespace
-    - Defaults to SeverityLevel.ERROR if the input is invalid
+    - Whitespace handling
+    - Default fallback to ERROR for invalid input
+
+    Args:
+        rule_info: Series containing rule information with 'Report Severity' key
+
+    Returns:
+        Appropriate SeverityLevel enum value
     """
     severity = rule_info.get("Report Severity")  # Extract severity from input data
 
@@ -291,15 +349,18 @@ def get_severity(rule_info: pd.Series) -> SeverityLevel:
 def get_metadata(
     rule_id: str, rule_info: pd.Series, passed: bool, speckle_objects: list[Base]
 ) -> dict[str, str | int | Any]:
-    """Function that generates metadata with severity validation and ensures JSON serializability.
+    """Generates structured metadata for rule results.
 
-    Reasoning is that non-valid metadata fails inside the Automate context. So let's ensure it's valid.
+    This metadata is attached to objects in the Speckle platform and is:
+    1. Validated for JSON serializability
+    2. Structured for consistent representation
+    3. Includes key information about the rule and results
 
     Args:
         rule_id: Identifier for the rule
         rule_info: Series containing rule information
         passed: Boolean indicating if the rule passed
-        speckle_objects: List of Speckle objects
+        speckle_objects: List of Speckle objects affected
 
     Returns:
         Dictionary containing metadata if valid JSON serializable, empty dict otherwise
@@ -330,14 +391,19 @@ def attach_results(
     context: AutomationContext,
     passed: bool,
 ) -> None:
-    """Attaches the results of a rule to the objects in the context.
+    """Attaches rule results to objects in the Speckle Automate context.
+
+    This function is the interface to the Speckle platform for reporting results:
+    - For failing objects, attaches results with appropriate severity levels
+    - For passing objects, attaches informational results
+    - Includes structured metadata for consistent reporting
 
     Args:
-        speckle_objects (List[Base]): The list of objects to which the rule was applied.
-        rule_info (pd.Series): The information about the rule.
-        rule_id (str): The ID of the rule.
-        context (AutomationContext): The context manager for attaching results.
-        passed (bool): Whether the rule passed or failed.
+        speckle_objects: The list of objects affected by the rule
+        rule_info: Information about the rule
+        rule_id: Identifier for the rule
+        context: The Speckle Automate context for result attachment
+        passed: Whether the objects passed the rule
     """
     if not speckle_objects:
         return
@@ -372,7 +438,16 @@ def attach_results(
 
 
 def format_message(rule_info):
-    """Format the message for the rule."""
+    """Format the message for the rule result.
+
+    Handles cases where the message might be None or NaN.
+
+    Args:
+        rule_info: Series containing rule information with 'Message' key
+
+    Returns:
+        Formatted message string
+    """
     message = (
         str(rule_info["Message"])
         if rule_info["Message"] is not None and not pd.isna(rule_info["Message"])

src/rules.py

@@ -1,4 +1,15 @@
-"""A collection of rules for processing Speckle objects and their properties."""
+"""A collection of rules for processing Speckle objects and their properties.
+
+This module provides essential utilities for:
+1. Accessing and comparing properties across different Speckle object versions (v2/v3)
+2. Handling nested property paths with a flexible search mechanism
+3. Converting between different value types (strings, booleans, numbers)
+4. Implementing various comparison predicates for validation rules
+
+The core challenge addressed by this module is the evolving schema of Speckle objects.
+In v2, parameters were stored directly in a 'parameters' dictionary, while in v3,
+they are nested within a more complex 'properties.Parameters' structure with categories.
+"""
 
 import math
 import re
@@ -11,13 +22,30 @@ PRIMITIVE_TYPES = (bool, int, float, str, type(None))
 
 
 class Rules:
-    """A collection of rules for processing properties in Speckle objects."""
+    """A collection of rules for processing properties in Speckle objects.
+
+    This class provides utilities for working with displayable objects
+    in the Speckle ecosystem.
+    """
 
     @staticmethod
     def try_get_display_value(
         speckle_object: Base,
     ) -> list[Base] | None:
-        """Try fetching the display value from a Speckle object."""
+        """Try fetching the display value from a Speckle object.
+
+        Speckle objects might store display geometry in various ways:
+        - 'displayValue' (newer versions)
+        - '@displayValue' (older versions)
+
+        This method handles both cases transparently.
+
+        Args:
+            speckle_object: The Speckle object to extract display value from
+
+        Returns:
+            List of Base objects representing display geometry, or None if not found
+        """
         raw_display_value = getattr(speckle_object, "displayValue", None) or getattr(
             speckle_object, "@displayValue", None
         )
@@ -34,7 +62,21 @@ class Rules:
 
     @staticmethod
     def is_displayable_object(speckle_object: Base) -> bool:
-        """Determines if a given Speckle object is displayable."""
+        """Determines if a given Speckle object is displayable.
+
+        A Speckle object is considered displayable if:
+        1. It has an ID and displayable geometry, OR
+        2. It has a definition with an ID and displayable geometry
+           (typically for instanced objects)
+
+        This is useful for filtering out non-visible/utility objects.
+
+        Args:
+            speckle_object: The Speckle object to check
+
+        Returns:
+            True if the object is displayable, False otherwise
+        """
         display_values = Rules.try_get_display_value(speckle_object)
         if display_values and getattr(speckle_object, "id", None) is not None:
             return True
@@ -49,7 +91,17 @@ class Rules:
 
     @staticmethod
     def get_displayable_objects(flat_list_of_objects: list[Base]) -> list[Base]:
-        """Filters a list of Speckle objects to only include displayable objects."""
+        """Filters a list of Speckle objects to only include displayable objects.
+
+        This is useful when processing a flattened object tree but only wanting
+        to work with objects that have visual representation.
+
+        Args:
+            flat_list_of_objects: A list of Speckle objects to filter
+
+        Returns:
+            A filtered list containing only displayable objects with IDs
+        """
         return [
             speckle_object
             for speckle_object in flat_list_of_objects
@@ -58,19 +110,30 @@ class Rules:
 
 
 class PropertyRules:
-    """A collection of rules for processing parameters in Speckle objects."""
+    """A collection of rules for processing parameters in Speckle objects.
+
+    This class provides the core functionality for:
+    - Locating properties in complex object hierarchies
+    - Converting between different value types
+    - Comparing values with appropriate type handling
+    - Implementing various comparison predicates for validation rules
+
+    It's designed to work with both Speckle v2 and v3 object schemas.
+    """
 
     @staticmethod
     def is_parameter_value_not_containing(speckle_object: Base, parameter_name: str, substring: str) -> bool:
         """Checks if parameter value does not contain the given substring.
 
+        This is the logical inverse of is_parameter_value_containing.
+
         Args:
-            speckle_object: The Speckle object to check
-            parameter_name: Name of the parameter to check
-            substring: The substring to look for
+           speckle_object: The Speckle object to check
+           parameter_name: Name of the parameter to check
+           substring: The substring to look for
 
         Returns:
-            bool: True if the parameter value does not contain the substring
+           True if the parameter value does not contain the substring
         """
         # Invert the result of contains check
         return not PropertyRules.is_parameter_value_containing(speckle_object, parameter_name, substring)
@@ -79,13 +142,16 @@ class PropertyRules:
     def is_parameter_value_containing(speckle_object: Base, parameter_name: str, substring: str) -> bool:
         """Checks if parameter value contains the given substring.
 
+        Case-insensitive substring matching for parameters.
+        If the parameter doesn't exist, returns False.
+
         Args:
             speckle_object: The Speckle object to check
             parameter_name: Name of the parameter to check
             substring: The substring to look for
 
         Returns:
-            bool: True if the parameter value contains the substring
+            True if the parameter value contains the substring
         """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         if parameter_value is None:
@@ -102,14 +168,41 @@ class PropertyRules:
 
     @staticmethod
     def normalize_path(path: str) -> str:
-        """Remove technical path prefixes like 'properties' and 'parameters'."""
+        """Remove technical path prefixes like 'properties' and 'parameters'.
+
+        This helps make property paths version-agnostic by focusing on the
+        meaningful parts of the path rather than the container structure.
+
+        Examples:
+        - 'properties.Parameters.Type Parameters.Construction.Width' becomes 'Type Parameters.Construction.Width'
+        - 'parameters.WALL_ATTR_WIDTH_PARAM' becomes 'WALL_ATTR_WIDTH_PARAM'
+
+        Args:
+            path: The parameter path to normalize
+
+        Returns:
+            A normalized path with technical prefixes removed
+        """
         parts = path.split(".")
         filtered = [p for p in parts if p.lower() not in ("properties", "parameters")]
         return ".".join(filtered)
 
     @staticmethod
     def convert_revit_boolean(value: Any) -> Any:
-        """Convert Revit-style Yes/No strings to boolean values."""
+        """Convert Revit-style Yes/No strings to boolean values.
+
+        Revit and some other BIM applications use "Yes"/"No" strings
+        instead of boolean values. This function converts them:
+        - "Yes" → True
+        - "No" → False
+        - Other values remain unchanged
+
+        Args:
+            value: The value to potentially convert
+
+        Returns:
+            Converted boolean if applicable, otherwise original value
+        """
         # Handle None case
         if value is None:
             return None
@@ -131,7 +224,20 @@ class PropertyRules:
 
     @staticmethod
     def get_obj_value(obj: Any, get_raw: bool = False) -> Any:
-        """Extract appropriate value from an object, handling special cases."""
+        """Extract appropriate value from an object, handling special cases.
+
+        This function handles the various ways values might be stored:
+        - In v2 Parameter objects (with .value property)
+        - In v3 dictionary structures (with 'value' key)
+        - As primitive values directly
+
+        Args:
+            obj: The object to extract value from
+            get_raw: If True, return the object itself without extracting value
+
+        Returns:
+            The extracted value, possibly with Yes/No conversion
+        """
         if get_raw:
             return obj
 
@@ -155,7 +261,19 @@ class PropertyRules:
 
     @staticmethod
     def search_obj(obj: Any, parts: list[str]) -> tuple[bool, Any]:
-        """Recursively search an object following a path."""
+        """Recursively search an object following a path.
+
+        This is a key part of the property access mechanism, allowing
+        navigation through nested object structures using dot notation.
+        The search is case-insensitive to handle inconsistencies.
+
+        Args:
+            obj: The object to search within
+            parts: List of path components to follow
+
+        Returns:
+            Tuple of (found: bool, value: Any)
+        """
         if not parts:
             return True, obj
 
@@ -184,6 +302,14 @@ class PropertyRules:
     def find_property(root: Any, search_path: str, get_raw: bool = False) -> tuple[bool, Any]:
         """Find a property by searching through nested objects.
 
+        This method implements a flexible property search that:
+        1. First attempts a direct path match
+        2. Then recursively searches through nested object structures
+        3. Uses cycle detection to prevent infinite recursion
+
+        The approach handles both v2 and v3 Speckle object schemas and
+        supports fuzzy property matching by normalizing paths.
+
         Args:
             root: The root object to search
             search_path: Path to the property to find
@@ -241,7 +367,17 @@ class PropertyRules:
 
     @staticmethod
     def has_parameter(speckle_object: Base, parameter_name: str, *_args, **_kwargs) -> bool:
-        """Check if a parameter exists in the Speckle object."""
+        """Check if a parameter exists in the Speckle object.
+
+        This method is version-agnostic and works with both v2 and v3 objects.
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to look for
+
+        Returns:
+            True if parameter exists, False otherwise
+        """
         found, _ = PropertyRules.find_property(speckle_object, parameter_name)
         return found
 
@@ -252,29 +388,58 @@ class PropertyRules:
         default_value: Any = None,
         get_raw: bool = False,
     ) -> Any:
-        """Get a parameter value from the Speckle object using strict path matching.
+        """Get a parameter value from the Speckle object using path matching.
+
+        This is the core property access method that:
+        1. Handles both v2 and v3 object structures
+        2. Supports direct and nested property paths
+        3. Applies appropriate value extraction and conversion
 
         Args:
             speckle_object: The Speckle object to search
-            parameter_name: Exact parameter path to find
+            parameter_name: Parameter path to find
             default_value: Value to return if parameter not found
             get_raw: Whether to return raw values without conversion
 
         Returns:
-            The parameter value if found using exact path matching, otherwise default_value
+            The parameter value if found, otherwise default_value
         """
         found, value = PropertyRules.find_property(speckle_object, parameter_name, get_raw)
         return value if found else default_value
 
     @staticmethod
     def is_parameter_value(speckle_object: Base, parameter_name: str, value_to_match: Any) -> bool:
-        """Checks if the value of the specified parameter matches the given value."""
+        """Checks if the value of the specified parameter matches the given value.
+
+        This is a basic equality check that leverages the parameter access system.
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+            value_to_match: The value to compare against
+
+        Returns:
+            True if values match, False otherwise
+        """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         return parameter_value == value_to_match
 
     @staticmethod
     def parse_number_from_string(input_string: str):
-        """Attempts to parse a number from a string."""
+        """Attempts to parse a number from a string.
+
+        First tries to parse as integer, then as float if that fails.
+        Raises ValueError if the string is not a valid number.
+
+        Args:
+            input_string: The string to parse
+
+        Returns:
+            int or float value
+
+        Raises:
+            ValueError: If the string is not a valid number
+        """
         try:
             return int(input_string)
         except ValueError:
@@ -287,8 +452,19 @@ class PropertyRules:
     def is_parameter_value_greater_than(speckle_object: Base, parameter_name: str, threshold: str) -> bool:
         """Checks if parameter value is greater than threshold.
 
+        This implements the 'greater than' predicate for numeric comparisons.
+
         Note: From a UX perspective, if someone writes 'height greater than 2401',
-        they mean "flag an error if height <= 2401". So we flip the comparison.
+        they mean "flag an error if height <= 2401". So we implement the check to match
+        that intuitive interpretation.
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+            threshold: The threshold value as a string
+
+        Returns:
+            True if parameter value > threshold, False otherwise
         """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         if parameter_value is None:
@@ -303,8 +479,19 @@ class PropertyRules:
     def is_parameter_value_less_than(speckle_object: Base, parameter_name: str, threshold: str) -> bool:
         """Checks if parameter value is less than threshold.
 
+        This implements the 'less than' predicate for numeric comparisons.
+
         Note: From a UX perspective, if someone writes 'height less than 2401',
-        they mean "flag an error if height >= 2401". So we flip the comparison.
+        they mean "flag an error if height >= 2401". So we implement the check to match
+        that intuitive interpretation.
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+            threshold: The threshold value as a string
+
+        Returns:
+            True if parameter value < threshold, False otherwise
         """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         if parameter_value is None:
@@ -318,10 +505,21 @@ class PropertyRules:
 
     @staticmethod
     def is_parameter_value_in_range(speckle_object: Base, parameter_name: str, value_range: str) -> bool:
-        """Checks if parameter value falls outside specified range.
+        """Checks if parameter value falls within specified range.
+
+        This implements the 'in range' predicate for numeric comparisons.
+        The range is specified as "min,max" and is inclusive.
 
         Note: From a UX perspective, if someone writes 'height in range 2401,3000',
         they mean "flag an error if height < 2401 or height > 3000".
+
+        Args:
+           speckle_object: The Speckle object to check
+           parameter_name: The parameter name/path to check
+           value_range: Range specification as "min,max"
+
+        Returns:
+           True if min <= parameter value <= max, False otherwise
         """
         min_value, max_value = value_range.split(",")
         min_value = PropertyRules.parse_number_from_string(min_value)
@@ -345,7 +543,22 @@ class PropertyRules:
         fuzzy: bool = False,
         threshold: float = 0.8,
     ) -> bool:
-        """Checks if parameter value matches pattern."""
+        """Checks if parameter value matches pattern.
+
+        This implements the 'is like' predicate with two modes:
+        1. Regular expression matching (fuzzy=False)
+        2. Levenshtein distance-based fuzzy matching (fuzzy=True)
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+            pattern: Regex pattern or string to match
+            fuzzy: Whether to use fuzzy matching
+            threshold: Similarity threshold for fuzzy matching (0.0-1.0)
+
+        Returns:
+            True if the parameter value matches the pattern, False otherwise
+        """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         if parameter_value is None:
             return False
@@ -358,7 +571,20 @@ class PropertyRules:
 
     @staticmethod
     def is_parameter_value_in_list(speckle_object: Base, parameter_name: str, value_list: list[Any] | str) -> bool:
-        """Checks if parameter value is in list."""
+        """Checks if parameter value is in list.
+
+        This implements the 'in list' predicate, supporting both:
+        1. Python lists
+        2. Comma-separated string lists
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+            value_list: List of values or comma-separated string
+
+        Returns:
+            True if parameter value is in the list, False otherwise
+        """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
 
         if isinstance(value_list, str):
@@ -373,7 +599,19 @@ class PropertyRules:
 
     @staticmethod
     def check_boolean_value(value: Any, values_to_match: tuple[str, ...]) -> bool:
-        """Check if a value matches any target value in expected format."""
+        """Check if a value matches any target value in expected format.
+
+        This is a helper for boolean parameter checking that handles:
+        - Boolean literals (True/False)
+        - String representations ("yes", "true", "1", etc.)
+
+        Args:
+            value: The value to check
+            values_to_match: Tuple of string values representing the target state
+
+        Returns:
+            True if value matches any target value, False otherwise
+        """
         if isinstance(value, bool):
             return value is (True if "true" in values_to_match else False)
 
@@ -384,35 +622,103 @@ class PropertyRules:
 
     @staticmethod
     def is_parameter_value_true(speckle_object: Base, parameter_name: str) -> bool:
-        """Check if parameter value represents true."""
+        """Check if parameter value represents true.
+
+        This implements the 'is true' predicate, handling various
+        representations of true values ("yes", "true", "1").
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+
+        Returns:
+            True if parameter value represents true, False otherwise
+        """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         return PropertyRules.check_boolean_value(parameter_value, ("yes", "true", "1"))
 
     @staticmethod
     def is_parameter_value_false(speckle_object: Base, parameter_name: str) -> bool:
-        """Check if parameter value represents false."""
+        """Check if parameter value represents false.
+
+        This implements the 'is false' predicate, handling various
+        representations of false values ("no", "false", "0").
+
+        Args:
+            speckle_object: The Speckle object to check
+            parameter_name: The parameter name/path to check
+
+        Returns:
+            True if parameter value represents false, False otherwise
+        """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         return PropertyRules.check_boolean_value(parameter_value, ("no", "false", "0"))
 
     @staticmethod
     def has_category(speckle_object: Base) -> bool:
-        """Check if object has category."""
+        """Check if object has category.
+
+        This is a convenience method specifically for checking
+        the existence of the 'category' property.
+
+        Args:
+            speckle_object: The Speckle object to check
+
+        Returns:
+            True if object has a category property, False otherwise
+        """
         return PropertyRules.has_parameter(speckle_object, "category")
 
     @staticmethod
     def is_category(speckle_object: Base, category_input: str) -> bool:
-        """Check if object matches category."""
+        """Check if object matches category.
+
+        This is a convenience method for filtering objects by category,
+        which is a common operation in Speckle.
+
+        Args:
+            speckle_object: The Speckle object to check
+            category_input: The category value to match
+
+        Returns:
+            True if object's category matches input, False otherwise
+        """
         category_value = PropertyRules.get_parameter_value(speckle_object, "category")
         return category_value == category_input
 
     @staticmethod
     def get_category_value(speckle_object: Base) -> str:
-        """Get object's category value."""
+        """Get object's category value.
+
+        This is a convenience method for retrieving an object's category.
+
+        Args:
+            speckle_object: The Speckle object to get category from
+
+        Returns:
+            The category value as a string
+        """
         return PropertyRules.get_parameter_value(speckle_object, "category")
 
     @staticmethod
     def try_boolean_comparison(value1: Any, value2: Any, allow_yes_no: bool) -> tuple[bool, bool]:
-        """Attempts to compare two values as booleans."""
+        """Attempts to compare two values as booleans.
+
+        This handles various boolean representations:
+        - Boolean literals (True/False)
+        - String representations ("true"/"false")
+        - Revit-style "Yes"/"No" strings (if allow_yes_no=True)
+
+        Args:
+            value1: First value to compare
+            value2: Second value to compare
+            allow_yes_no: Whether to convert Yes/No strings to booleans
+
+        Returns:
+            Tuple of (can_compare: bool, result: bool) where:
+            - can_compare indicates if both values could be interpreted as booleans
+            - result is the comparison result if can_compare is True
+        """
 
         def strict_convert_boolean(value: Any) -> Any:
             """Convert 'True'/'False' strings to booleans, and use `convert_revit_boolean` for Yes/No."""
@@ -451,15 +757,25 @@ class PropertyRules:
     ) -> bool:
         """Core logic for comparing two values with type handling and tolerance.
 
+        This is the comprehensive value comparison function that:
+        1. Tries boolean comparison first
+        2. Handles numeric string conversion
+        3. Implements case sensitivity options for strings
+        4. Uses tolerance-based floating point comparison
+        5. Falls back to regular equality
+
+        This function is used by multiple predicates.
+
         Args:
             value1: First value to compare
             value2: Second value to compare
             case_sensitive: Whether to perform case-sensitive string comparison
             tolerance: Tolerance for floating point comparisons
-            allow_yes_no_bools: Whether to convert Yes/No strings to booleans when comparing with boolean values
+            allow_yes_no_bools: Whether to convert Yes/No strings to booleans
             use_exact: Whether to use exact equality for numeric comparisons
+
         Returns:
-            bool: True if values are considered equal, False otherwise
+            True if values are considered equal, False otherwise
         """
         # Try boolean comparison first
         can_compare, result = PropertyRules.try_boolean_comparison(value1, value2, allow_yes_no_bools)
@@ -502,15 +818,20 @@ class PropertyRules:
     ) -> bool:
         """Compares a parameter value from a Speckle object with the provided value.
 
+        This implements the 'equal to' predicate with flexible comparison rules:
+        - Case insensitivity option for strings
+        - Tolerance-based comparison for floating point numbers
+        - Type conversion for common scenarios (numeric strings, Yes/No)
+
         Args:
-            speckle_object (Base): The Speckle object containing the parameter
-            parameter_name (str): Name of the parameter to compare
-            value_to_match: The value to compare against (float, string, int, etc.)
-            case_sensitive (bool): Whether to perform case-sensitive comparison for strings
-            tolerance (float): Tolerance for floating point comparisons
+            speckle_object: The Speckle object containing the parameter
+            parameter_name: Name of the parameter to compare
+            value_to_match: The value to compare against
+            case_sensitive: Whether to perform case-sensitive comparison for strings
+            tolerance: Tolerance for floating point comparisons
 
         Returns:
-            bool: True if values are considered equal, False otherwise
+            True if values are considered equal, False otherwise
         """
         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
         if parameter_value is None:

src/rules_old.py

@@ -1,756 +0,0 @@
-# import re
-# from typing import Any
-#
-# from Levenshtein import ratio
-# from specklepy.objects.base import Base
-#
-# from src.helpers import get_item, has_item, speckle_print
-# from src.inputs import PropertyMatchMode
-
-# We're going to define a set of rules that will allow us to filter and
-# process parameters in our Speckle objects. These rules will be encapsulated
-# in a class called `ParameterRules`.
-
-
-# class Rules:
-#     """A collection of rules for processing properties in Speckle objects.
-#
-#     Simple rules can be straightforwardly implemented as static methods that
-#     return boolean value to be used either as a filter or a condition.
-#     These can then be abstracted into returning lambda functions that  we can
-#     use in our main processing logic. By encapsulating these rules, we can easily
-#     extend or modify them in the future.
-#     """
-#
-#     @staticmethod
-#     def try_get_display_value(
-#         speckle_object: Base,
-#     ) -> list[Base] | None:
-#         """Try fetching the display value from a Speckle object.
-#
-#         This method encapsulates the logic for attempting to retrieve the display value from a
-#         Speckle object. It returns a list containing the display values if found,
-#         otherwise it returns None.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to extract the display value from.
-#
-#         Returns:
-#             Optional[List[Base]]: A list containing the display values.
-#                                   If no display value is found, returns None.
-#         """
-#         # Attempt to get the display value from the speckle_object
-#         raw_display_value = getattr(speckle_object, "displayValue", None) or getattr(
-#             speckle_object, "@displayValue", None
-#         )
-#
-#         # If no display value found, return None
-#         if raw_display_value is None:
-#             return None
-#
-#         # If display value found, filter out non-Base objects
-#         display_values = [value for value in raw_display_value if isinstance(value, Base)]
-#
-#         # If no valid display values found, return None
-#         if not display_values:
-#             return None
-#
-#         return display_values
-#
-#     @staticmethod
-#     def is_displayable_object(speckle_object: Base) -> bool:
-#         """Determines if a given Speckle object is displayable.
-#
-#         This method encapsulates the logic for determining if a Speckle object is displayable.
-#         It checks if the speckle_object has a display value and returns True if it does, otherwise it returns False.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#
-#         Returns:
-#             bool: True if the object has a display value, False otherwise.
-#         """
-#         # Check for direct displayable state using try_get_display_value
-#         display_values = Rules.try_get_display_value(speckle_object)
-#         if display_values and getattr(speckle_object, "id", None) is not None:
-#             return True
-#
-#         # Check for displayable state via definition, using try_get_display_value on the definition object
-#         definition = getattr(speckle_object, "definition", None)
-#         if definition:
-#             definition_display_values = Rules.try_get_display_value(definition)
-#             if definition_display_values and getattr(definition, "id", None) is not None:
-#                 return True
-#
-#         return False
-#
-#     @staticmethod
-#     def get_displayable_objects(flat_list_of_objects: list[Base]) -> list[Base]:
-#         """Filters a list of Speckle objects to only include displayable objects.
-#
-#         This function takes a list of Speckle objects and filters out the objects that are displayable.
-#         It returns a list containing only the displayable objects.
-#
-#         Args:
-#             flat_list_of_objects (List[Base]): The list of Speckle objects to filter.
-#         """
-#         return [
-#             speckle_object
-#             for speckle_object in flat_list_of_objects
-#             if Rules.is_displayable_object(speckle_object) and getattr(speckle_object, "id", None)
-#         ]
-#
-#
-# class PropertyRules:
-#     """A collection of rules for processing Revit parameters in Speckle objects."""
-#
-#     @staticmethod
-#     def has_parameter(speckle_object: Base, parameter_name: str, *_args, **_kwargs) -> bool:
-#         """Checks if the speckle_object has a parameter with the given name."""
-#         found, _ = ParameterSearch.lookup_parameter(speckle_object, parameter_name)
-#         return found
-#
-#     @staticmethod
-#     def get_parameter_value(
-#         speckle_object: Base,
-#         parameter_name: str,
-#         match_mode: PropertyMatchMode = PropertyMatchMode.MIXED,
-#         default_value: Any = None,
-#     ) -> Any:
-#         """Gets the value of a parameter if it exists."""
-#         found, value = ParameterSearch.lookup_parameter(speckle_object, parameter_name, match_mode)
-#         return value if found else default_value
-#
-#     @staticmethod
-#     def is_v3(speckle_object: Base) -> bool:
-#         """Determines if a Speckle object uses v3 parameter structure.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check
-#
-#         Returns:
-#             bool: True if object uses v3 structure, False otherwise
-#         """
-#         properties = get_item(speckle_object, "properties")
-#         return bool(properties and has_item(properties, "Parameters"))
-#
-#     # @staticmethod
-#     # def has_parameter(speckle_object: Base, parameter_name: str, *_args, **_kwargs) -> bool:
-#     #     """Checks if the speckle_object has a Revit parameter with the given name.
-#     #
-#     #     First checks direct properties, then determines if it's a v2 or v3 object structure
-#     #     and searches in the appropriate parameter hierarchy.
-#     #
-#     #     Args:
-#     #         speckle_object (Base): The Speckle object to check.
-#     #         parameter_name (str): The name of the parameter to check for.
-#     #         *_args: Extra positional arguments which are ignored.
-#     #         **_kwargs: Extra keyword arguments which are ignored.
-#     #
-#     #     Returns:
-#     #         bool: True if the object has the parameter, False otherwise.
-#     #     """
-#     #     # Check direct property first regardless of version
-#     #     if has_item(speckle_object, parameter_name):
-#     #         return True
-#     #
-#     #     if PropertyRules.is_v3(speckle_object):
-#     #         properties = get_item(speckle_object, "properties")
-#     #         parameters = get_item(properties, "Parameters")
-#     #         if parameters:
-#     #
-#     #             def search_v3_params(params: dict, search_name: str) -> bool:
-#     #                 for key, value in params.items():
-#     #                     if isinstance(value, dict):
-#     #                         # Check direct name match
-#     #                         if key.lower() == search_name.lower():
-#     #                             return True
-#     #                         # Check nested parameters
-#     #                         if search_v3_params(value, search_name):
-#     #                             return True
-#     #                 return False
-#     #
-#     #             return search_v3_params(parameters, parameter_name)
-#     #     else:
-#     #         # Handle v2 structure
-#     #         parameters = get_item(speckle_object, "parameters")
-#     #         if not parameters:
-#     #             return False
-#     #
-#     #         # Check direct parameter name match
-#     #         if has_item(parameters, parameter_name):
-#     #             return True
-#     #
-#     #         # Check nested parameters with name property
-#     #         def check_nested_name(value: Any) -> bool:
-#     #             if isinstance(value, dict):
-#     #                 return get_item(value, "name") == parameter_name
-#     #             return get_item(value, "name") == parameter_name if hasattr(value, "name") else False
-#     #
-#     #         return any(check_nested_name(param_value) for param_value in parameters.values() if param_value is not None)
-#     #
-#     #     return False
-#     #
-#     # @staticmethod
-#     # def get_parameter_value(
-#     #     speckle_object: Base,
-#     #     parameter_name: str,
-#     #     match_mode: PropertyMatchMode = PropertyMatchMode.MIXED,
-#     #     default_value: Any = None,
-#     # ) -> Any | None:
-#     #     """Retrieves the value of the specified parameter from the speckle_object.
-#     #
-#     #     First checks direct properties, then determines if it's a v2 or v3 object structure
-#     #     and retrieves from the appropriate parameter hierarchy.
-#     #
-#     #     Args:
-#     #             speckle_object (Base): The Speckle object to retrieve the parameter value from.
-#     #         parameter_name (str): The name of the parameter to retrieve the value for.
-#     #         match_mode (PropertyMatchMode): The matching mode to use for parameter lookup
-#     #         default_value: The default value to return if parameter not found.
-#     #
-#     #     Returns:
-#     #         The value of the parameter if found, else default_value.
-#     #     """
-#     #     # Check direct property first regardless of version
-#     #     if has_item(speckle_object, parameter_name):
-#     #         value = get_item(speckle_object, parameter_name)
-#     #         return value if value is not None else default_value
-#     #
-#     #     if PropertyRules.is_v3(speckle_object):
-#     #         return PropertyRules.get_v3_parameter(speckle_object, parameter_name, match_mode, default_value)
-#     #     else:
-#     #         return PropertyRules.get_v2_parameter(speckle_object, parameter_name, match_mode, default_value)
-#
-#     # @staticmethod
-#     # def get_v2_parameter(obj: Base, name: str, mode: PropertyMatchMode, default: Any) -> Any:
-#     #     """Get parameter value from v2 Speckle object structure.
-#     #
-#     #     Args:
-#     #         obj: Speckle object to get parameter from
-#     #         name: Parameter name to retrieve
-#     #         mode: Match mode for parameter lookup
-#     #         default: Default value if parameter not found
-#     #
-#     #     Returns:
-#     #         Parameter value if found, else default
-#     #     """
-#     #     parameters = get_item(obj, "parameters")
-#     #     if not parameters:
-#     #         return default
-#     #
-#     #     if mode == PropertyMatchMode.STRICT:
-#     #         return PropertyRules.strict_parameter_lookup(name, parameters, default)
-#     #
-#     #     def search_params(param_dict: dict, search_name: str, fuzzy: bool) -> Any:
-#     #         for key, value in param_dict.items():
-#     #             key_match = (key.lower() == search_name.lower()) or (fuzzy and search_name.lower() in key.lower())
-#     #             if key_match:
-#     #                 # Handle both direct values and nested parameter objects
-#     #                 return get_item(value, "value", value)
-#     #         return None
-#     #
-#     #     result = search_params(parameters, name, mode == PropertyMatchMode.FUZZY)
-#     #     return result if result is not None else default
-#     #
-#     # @staticmethod
-#     # def get_v3_parameter(obj: Base, name: str, mode: PropertyMatchMode, default: Any) -> Any:
-#     #     """Get parameter value from v3 Speckle object structure.
-#     #
-#     #     Args:
-#     #         obj: Speckle object to get parameter from
-#     #         name: Parameter name to retrieve
-#     #         mode: Match mode for parameter lookup
-#     #         default: Default value if parameter not found
-#     #
-#     #     Returns:
-#     #         Parameter value if found, else default
-#     #     """
-#     #     properties = get_item(obj, "properties")
-#     #     if not properties or not has_item(properties, "Parameters"):
-#     #         return default
-#     #
-#     #     parameters = get_item(properties, "Parameters")
-#     #     if not parameters:
-#     #         return default
-#     #
-#     #     if mode == PropertyMatchMode.STRICT:
-#     #         return PropertyRules.strict_parameter_lookup(name, parameters, default)
-#     #
-#     #     def search_nested(data: dict, search_name: str, fuzzy: bool) -> Any:
-#     #         for nested_key, value in data.items():
-#     #             if isinstance(value, dict):
-#     #                 key_match = (nested_key.lower() == search_name.lower()) or (
-#     #                     fuzzy and search_name.lower() in nested_key.lower()
-#     #                 )
-#     #
-#     #                 if key_match and has_item(value, "value"):
-#     #                     return get_item(value, "value")
-#     #
-#     #                 nested_result = search_nested(value, search_name, fuzzy)
-#     #                 if nested_result is not None:
-#     #                     return nested_result
-#     #         return None
-#     #
-#     #     result = search_nested(parameters, name, mode == PropertyMatchMode.FUZZY)
-#     #     return result if result is not None else default
-#     #
-#     # @staticmethod
-#     # def strict_parameter_lookup(name: str, parameters: dict, default: Any) -> Any:
-#     #     """Perform strict parameter lookup following exact path.
-#     #
-#     #     Args:
-#     #         name: Parameter path (dot separated)
-#     #         parameters: Parameters dictionary
-#     #         default: Default value if not found
-#     #
-#     #     Returns:
-#     #         Parameter value if found, else default
-#     #     """
-#     #     path_parts = name.split(".")
-#     #     current = parameters
-#     #
-#     #     for part in path_parts:
-#     #         if not current or not isinstance(current, dict):
-#     #             return default
-#     #
-#     #         # Find exact case-insensitive match
-#     #         key = next((k for k in current.keys() if k.lower() == part.lower()), None)
-#     #         if not key:
-#     #             return default
-#     #
-#     #         current = get_item(current, key)
-#     #
-#     #     # Handle both direct values and parameter objects
-#     #     if isinstance(current, dict):
-#     #         return get_item(current, "value", current)
-#     #     return current
-#
-#     @staticmethod
-#     def is_parameter_value(speckle_object: Base, parameter_name: str, value_to_match: Any) -> bool:
-#         """Checks if the value of the specified parameter matches the given value.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             value_to_match (Any): The value to match against.
-#
-#         Returns:
-#             bool: True if the parameter value matches the given value, False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         return parameter_value == value_to_match
-#
-#     @staticmethod
-#     def is_parameter_value_like(
-#         speckle_object: Base,
-#         parameter_name: str,
-#         pattern: str,
-#         fuzzy: bool = False,
-#         threshold: float = 0.8,
-#     ) -> bool:
-#         """Checks if the value of the specified parameter matches the given pattern.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             pattern (str): The pattern to match against.
-#             fuzzy (bool): If True, performs fuzzy matching using Levenshtein distance.
-#                           If False (default), performs exact pattern matching using regular expressions.
-#             threshold (float): The similarity threshold for fuzzy matching (default: 0.8).
-#                                Only applicable when fuzzy=True.
-#
-#         Returns:
-#             bool: True if the parameter value matches the pattern (exact or fuzzy), False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         if parameter_value is None:
-#             return False
-#
-#         if fuzzy:
-#             similarity = ratio(str(parameter_value), pattern)
-#             return similarity >= threshold
-#         else:
-#             return bool(re.match(pattern, str(parameter_value)))
-#
-#     @staticmethod
-#     def parse_number_from_string(input_string: str):
-#         """Attempts to parse an integer or float from a given string.
-#
-#         Args:
-#             input_string (str): The string containing the number to be parsed.
-#
-#         Returns:
-#             int or float: The parsed number, or raises ValueError if parsing is not possible.
-#         """
-#         try:
-#             # First try to convert it to an integer
-#             return int(input_string)
-#         except ValueError:
-#             # If it fails to convert to an integer, try to convert to a float
-#             try:
-#                 return float(input_string)
-#             except ValueError:
-#                 # Raise an error if neither conversion is possible
-#                 raise ValueError("Input string is not a valid integer or float")
-#
-#     @staticmethod
-#     def is_parameter_value_greater_than(speckle_object: Base, parameter_name: str, threshold: str) -> bool:
-#         """Checks if the value of the specified parameter is greater than the given threshold.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             threshold (Union[int, float]): The threshold value to compare against.
-#
-#         Returns:
-#             bool: True if the parameter value is greater than the threshold, False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         if parameter_value is None:
-#             return False
-#
-#         if not isinstance(parameter_value, int | float):
-#             raise ValueError(f"Parameter value must be a number, got {type(parameter_value)}")
-#         return parameter_value > PropertyRules.parse_number_from_string(threshold)
-#
-#     @staticmethod
-#     def is_parameter_value_less_than(speckle_object: Base, parameter_name: str, threshold: str) -> bool:
-#         """Checks if the value of the specified parameter is less than the given threshold.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             threshold (Union[int, float]): The threshold value to compare against.
-#
-#         Returns:
-#             bool: True if the parameter value is less than the threshold, False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         if parameter_value is None:
-#             return False
-#         if not isinstance(parameter_value, int | float):
-#             raise ValueError(f"Parameter value must be a number, got {type(parameter_value)}")
-#         return parameter_value < PropertyRules.parse_number_from_string(threshold)
-#
-#     @staticmethod
-#     def is_parameter_value_in_range(speckle_object: Base, parameter_name: str, value_range: str) -> bool:
-#         """Checks if the value of the specified parameter falls within the given range.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             value_range (str): The range to check against, in the format "min_value, max_value".
-#
-#         Returns:
-#             bool: True if the parameter value falls within the range (inclusive), False otherwise.
-#         """
-#         min_value, max_value = value_range.split(",")
-#         min_value = PropertyRules.parse_number_from_string(min_value)
-#         max_value = PropertyRules.parse_number_from_string(max_value)
-#
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         if parameter_value is None:
-#             return False
-#         if not isinstance(parameter_value, int | float):
-#             raise ValueError(f"Parameter value must be a number, got {type(parameter_value)}")
-#
-#         return min_value <= parameter_value <= max_value
-#
-#     @staticmethod
-#     def is_parameter_value_in_range_expanded(
-#         speckle_object: Base,
-#         parameter_name: str,
-#         min_value: int | float,
-#         max_value: int | float,
-#         inclusive: bool = True,
-#     ) -> bool:
-#         """Checks if the value of the specified parameter falls within the given range.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             min_value (Union[int, float]): The minimum value of the range.
-#             max_value (Union[int, float]): The maximum value of the range.
-#             inclusive (bool): If True (default), the range is inclusive (min <= value <= max).
-#                               If False, the range is exclusive (min < value < max).
-#
-#         Returns:
-#             bool: True if the parameter value falls within the range (inclusive), False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         if parameter_value is None:
-#             return False
-#         if not isinstance(parameter_value, int | float):
-#             raise ValueError(f"Parameter value must be a number, got {type(parameter_value)}")
-#
-#         return min_value <= parameter_value <= max_value if inclusive else min_value < parameter_value < max_value
-#
-#     @staticmethod
-#     def is_parameter_value_in_list(speckle_object: Base, parameter_name: str, value_list: list[Any] | str) -> bool:
-#         """Checks if the value of the specified parameter is present in the given list of values.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             parameter_name (str): The name of the parameter to check.
-#             value_list (List[Any]): The list of values to check against.
-#
-#         Returns:
-#             bool: True if the parameter value is found in the list, False otherwise.
-#         """
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#
-#         if isinstance(value_list, str):
-#             value_list = [value.strip() for value in value_list.split(",")]
-#
-#         # parameter_value is effectively Any type, so to find its value in the value_list
-#         def is_value_in_list(value: Any, my_list: Any) -> bool:
-#             # Ensure that my_list is actually a list
-#             if isinstance(my_list, list):
-#                 return value in my_list or str(value) in my_list
-#             else:
-#                 speckle_print(f"Expected a list, got {type(my_list)} instead.")
-#                 return False
-#
-#         return is_value_in_list(parameter_value, value_list)
-#
-#     @staticmethod
-#     def _check_boolean_value(value: Any, values_to_match: tuple[str, ...]) -> bool:
-#         """Check if a value matches any target value in expected format."""
-#         if isinstance(value, bool):
-#             return value is (True if "true" in values_to_match else False)
-#
-#         if isinstance(value, str):
-#             return value.lower() in values_to_match
-#
-#         return False
-#
-#     @staticmethod
-#     def is_parameter_value_true(speckle_object: Base, parameter_name: str) -> bool:
-#         """Check if parameter value represents true (boolean True, 'yes', 'true', '1')."""
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         return PropertyRules._check_boolean_value(parameter_value, ("yes", "true", "1"))
-#
-#     @staticmethod
-#     def is_parameter_value_false(speckle_object: Base, parameter_name: str) -> bool:
-#         """Check if parameter value represents false (boolean False, 'no', 'false', '0')."""
-#         parameter_value = PropertyRules.get_parameter_value(speckle_object, parameter_name)
-#         return PropertyRules._check_boolean_value(parameter_value, ("no", "false", "0"))
-#
-#     @staticmethod
-#     def has_category(speckle_object: Base) -> bool:
-#         """Checks if the speckle_object has a 'category' parameter.
-#
-#         This method checks if the speckle_object has a 'category' parameter.
-#         If the 'category' parameter exists, it returns True; otherwise, it returns False.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#
-#         Returns:
-#             bool: True if the object has the 'category' parameter, False otherwise.
-#         """
-#         return PropertyRules.has_parameter(speckle_object, "category")
-#
-#     @staticmethod
-#     def is_category(speckle_object: Base, category_input: str) -> bool:
-#         """Checks if the value of the 'category' property matches the given input.
-#
-#         This method checks if the 'category' property of the speckle_object
-#         matches the given category_input. If they match, it returns True;
-#         otherwise, it returns False.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to check.
-#             category_input (str): The category value to compare against.
-#
-#         Returns:
-#             bool: True if the 'category' property matches the input, False otherwise.
-#         """
-#         category_value = PropertyRules.get_parameter_value(speckle_object, "category")
-#         return category_value == category_input
-#
-#     @staticmethod
-#     def get_category_value(speckle_object: Base) -> str:
-#         """Retrieves the value of the 'category' parameter from the speckle_object.
-#
-#         This method retrieves the value of the 'category' parameter from the speckle_object.
-#         If the 'category' parameter exists and its value is not None, it returns the value.
-#         If the 'category' parameter does not exist or its value is None, it returns an empty string.
-#
-#         Args:
-#             speckle_object (Base): The Speckle object to retrieve the 'category' parameter value from.
-#
-#         Returns:
-#             str: The value of the 'category' parameter if it exists and is not None, or an empty string otherwise.
-#         """
-#         return PropertyRules.get_parameter_value(speckle_object, "category")
-#
-#
-# class ParameterSearch:
-#     """Unified parameter search functionality for Speckle objects."""
-#
-#     @staticmethod
-#     def convert_revit_boolean(value: Any) -> Any:
-#         """Convert Revit-style Yes/No strings to boolean values.
-#
-#         Args:
-#             value: The value to potentially convert
-#
-#         Returns:
-#             bool if value is a Revit boolean string, original value otherwise
-#         """
-#         if isinstance(value, str):
-#             if value.lower() == "yes":
-#                 return True
-#             if value.lower() == "no":
-#                 return False
-#         return value
-#
-#     @staticmethod
-#     def search_parameters(
-#         params: dict, search_name: str, mode: PropertyMatchMode = PropertyMatchMode.STRICT
-#     ) -> tuple[bool, Any]:
-#         """Search for parameters using consistent matching logic.
-#
-#         Supports flexible property chain matching that can find paths like "Instance Parameters.Dimensions.Length"
-#         within longer chains like "properties.Parameters.Instance Parameters.Dimensions.Length.value".
-#         Uses STRICT matching by default for more predictable results.
-#
-#         Args:
-#             params: Parameter dictionary to search
-#             search_name: Name of parameter to find, can be dot-separated chain
-#             mode: Matching mode to use (STRICT by default, or FUZZY/MIXED for looser matching)
-#
-#         Returns:
-#             Tuple of (value_found: bool, value: Any)
-#         """
-#
-#         def matches_name(match_key: str, target: str, match_mode: PropertyMatchMode) -> bool:
-#             if match_mode == PropertyMatchMode.STRICT:
-#                 return match_key.lower() == target.lower()
-#             elif match_mode == PropertyMatchMode.FUZZY:
-#                 return target.lower() in match_key.lower()
-#             else:  # MIXED mode
-#                 return match_key.lower() == target.lower() or target.lower() in match_key.lower()
-#
-#         def try_get_value(obj: Any) -> Any:
-#             """Extract value from parameter object or return as is.
-#
-#             Handles both dict and Base objects, checking for 'value' property in both cases.
-#             Returns the 'value' if found, otherwise returns the original object.
-#             """
-#             # Handle dictionary objects
-#             if isinstance(obj, dict):
-#                 return obj.get("value", obj)
-#
-#             # Handle Base objects
-#             if isinstance(obj, Base):
-#                 return getattr(obj, "value", obj)
-#
-#             # For all other types, return as is
-#             return obj
-#
-#         # First try property chain lookup
-#         if "." in search_name:
-#             search_parts = search_name.split(".")
-#
-#             def try_match_path(current: dict, remaining_search_parts: list[str], depth: int = 0) -> tuple[bool, Any]:
-#                 if not isinstance(current, dict):
-#                     return False, None
-#
-#                 if not remaining_search_parts:  # We've matched all parts
-#                     return True, try_get_value(current)
-#
-#                 current_search = remaining_search_parts[0]
-#
-#                 # Try each key at current level
-#                 for key, item_value in current.items():
-#                     if matches_name(key, current_search, mode):
-#                         # Found a match for current part, recurse with rest
-#                         match_found, result = try_match_path(item_value, remaining_search_parts[1:], depth + 1)
-#                         if match_found:
-#                             return True, result
-#
-#                     # If no match found and value is a dict, try searching deeper
-#                     if isinstance(item_value, dict):
-#                         match_found, result = try_match_path(item_value, remaining_search_parts, depth)
-#                         if match_found:
-#                             return True, result
-#
-#                 return False, None
-#
-#             try:
-#                 found, value = try_match_path(params, search_parts)
-#                 if found:
-#                     return True, value
-#             except Exception:
-#                 pass  # Fall through to recursive search if chain lookup fails
-#
-#         # Recursive search through nested dictionaries
-#         def recursive_search(data: dict | Base, target: str) -> tuple[bool, Any]:
-#             if not isinstance(data, dict | Base):
-#                 return False, None
-#
-#             # Handle both dict and Base objects for iteration
-#             if isinstance(data, dict):
-#                 items = data.items()
-#             else:
-#                 items = [(k, getattr(data, k)) for k in dir(data) if not k.startswith("_")]
-#
-#             # First check current level
-#             for key, item_value in items:
-#                 if matches_name(key, target, mode):
-#                     return True, try_get_value(item_value)
-#
-#             # Then check nested levels
-#             for _, item_value in items:
-#                 if isinstance(item_value, dict | Base):
-#                     item_found, result = recursive_search(item_value, target)
-#                     if item_found:
-#                         return True, result
-#
-#             return False, None
-#
-#         return recursive_search(params, search_name.split(".")[-1] if "." in search_name else search_name)
-#
-#     @staticmethod
-#     def lookup_parameter(
-#         obj: Base, param_name: str, mode: PropertyMatchMode = PropertyMatchMode.MIXED
-#     ) -> tuple[bool, Any]:
-#         """Unified parameter lookup for both checking existence and getting values.
-#
-#         Args:
-#             obj: Speckle object to search
-#             param_name: Parameter name to find
-#             mode: Matching mode to use
-#
-#         Returns:
-#             Tuple of (found: bool, value: Any)
-#         """
-#         # Check direct property first
-#         if has_item(obj, param_name):
-#             value = get_item(obj, param_name)
-#             # Check if the direct property has a value field
-#             if isinstance(value, dict) and "value" in value:
-#                 return True, value["value"]
-#             return True, value
-#
-#         # Handle v3 structure
-#         if PropertyRules.is_v3(obj):
-#             properties = get_item(obj, "properties")
-#             if not properties or not has_item(properties, "Parameters"):
-#                 return False, None
-#
-#             parameters = get_item(properties, "Parameters")
-#             if not parameters:
-#                 return False, None
-#
-#             return ParameterSearch.search_parameters(parameters, param_name, mode)
-#
-#         # Handle v2 structure
-#         parameters = get_item(obj, "parameters")
-#         if not parameters:
-#             return False, None
-#
-#         return ParameterSearch.search_parameters(parameters, param_name, mode)

src/spreadsheet.py

@@ -1,4 +1,26 @@
-"""Module for reading and processing rules from a cloud hosted TSV file."""
+"""Module for reading and processing rules from a cloud hosted TSV file.
+
+This module handles the loading and processing of validation rules from external
+spreadsheet data, enabling non-technical users to define and modify rules.
+
+Key features:
+1. Reading from hosted TSV files (e.g., from Google Sheets)
+2. Processing rule numbers for consistent grouping
+3. Handling mixed data types in spreadsheet columns
+4. Validating rule structure and providing feedback
+5. Grouping related rule conditions for execution
+
+The spreadsheet format used follows a specific structure:
+- Rule Number: Groups related conditions together
+- Logic: WHERE/AND/CHECK to define condition relationships
+- Property Name: The property path to check
+- Predicate: The comparison operation (equals, greater than, etc.)
+- Value: The value to compare against
+- Message: The message to display for rule results
+- Severity: INFO/WARNING/ERROR level for failures
+"""
+
+import traceback
 
 import pandas as pd
 from pandas import DataFrame
@@ -8,14 +30,20 @@ from pandas.core.groupby import DataFrameGroupBy
 def process_rule_numbers(df: DataFrame) -> DataFrame:
     """Process rule numbers in a DataFrame while preserving original rule identifiers.
 
-    Makes no assumptions about rule number format - preserves them exactly as provided.
-    Only generates new numbers (as integers) when no rule number exists.
+    This function handles various rule numbering scenarios:
+    1. Preserves existing rule numbers exactly as provided
+    2. Generates sequential numbers for missing rule numbers
+    3. Ensures all rows in a logical rule group have the same rule number
+
+    This is important because rule numbers determine how conditions are grouped
+    and executed together.
 
     Args:
         df: DataFrame with columns including 'Rule Number' and 'Logic'
 
     Returns:
-        DataFrame with processed rule numbers
+        DataFrame with processed rule numbers, where all related conditions
+        have the same rule number
     """
     # Create a copy to avoid modifying original
     df = df.copy()
@@ -62,7 +90,16 @@ def process_rule_numbers(df: DataFrame) -> DataFrame:
 
 
 def validate_rule_numbers(df: DataFrame) -> list[str]:
-    """Validate rule numbers and return any warnings or errors.
+    """ "
+    Validate rule numbers and return any warnings or errors.
+
+    This checks for issues like:
+    1. Missing rule numbers
+    2. Non-integer rule numbers
+    3. Duplicate rule numbers
+
+    These validations help ensure rule integrity without being overly strict,
+    allowing for different user approaches to rule numbering.
 
     Args:
         df: DataFrame with processed rule numbers
@@ -76,10 +113,10 @@ def validate_rule_numbers(df: DataFrame) -> list[str]:
     if df["Rule Number"].isna().any():
         messages.append("Warning: Some rules are missing rule numbers")
 
-    # Check for non-integer rule numbers
-    non_int_mask = df["Rule Number"].apply(lambda x: not pd.isna(x) and not float(x).is_integer())
-    if non_int_mask.any():
-        messages.append("Warning: Some rule numbers are not integers")
+    # # Check for non-integer rule numbers
+    # non_int_mask = df["Rule Number"].apply(lambda x: not pd.isna(x) and not float(x).is_integer())
+    # if non_int_mask.any():
+    #     messages.append("Warning: Some rule numbers are not integers")
 
     # Check for duplicate rule numbers in WHERE rows
     where_rules = df[df["Logic"].str.upper() == "WHERE"]["Rule Number"]
@@ -91,10 +128,18 @@ def validate_rule_numbers(df: DataFrame) -> list[str]:
 
 
 def read_rules_from_spreadsheet(url: str) -> tuple[DataFrameGroupBy, list[str]] | tuple[None, list[str]]:
-    """Reads a TSV file from a provided URL, processes rule numbers, and returns grouped rules.
+    """ "
+    Reads rules from a TSV file at the provided URL, processes them, and returns grouped rules.
+
+    This function is the main entry point for rule loading:
+    1. Reads the TSV file from the provided URL
+    2. Converts mixed type columns to appropriate types
+    3. Processes rule numbers for consistent grouping
+    4. Validates rule numbers and collects messages
+    5. Groups rules by rule number for execution
 
     Args:
-        url (str): The URL to the TSV file
+        url: The URL to the TSV file containing rule definitions
 
     Returns:
         Tuple containing:
@@ -103,33 +148,48 @@ def read_rules_from_spreadsheet(url: str) -> tuple[DataFrameGroupBy, list[str]]
     """
     try:
         # Read the TSV file
+        # The TSV format is chosen for compatibility with Google Sheets
+        # and other spreadsheet applications
         df = pd.read_csv(url, sep="\t")
 
         # Convert mixed type columns
+        # This handles inconsistencies in spreadsheet data
         df = convert_mixed_columns(df)
 
         # Process rule numbers
+        # This ensures all related conditions have the same rule number
         df = process_rule_numbers(df)
 
         # Get validation messages
+        # These are warnings about potential issues with the rules
         messages = validate_rule_numbers(df)
 
         # Group by rule number
+        # This creates a DataFrameGroupBy object that groups related conditions
         grouped_rules = df.groupby("Rule Number")
 
         return grouped_rules, messages
 
     except Exception as e:
-        return None, [f"Failed to read the TSV from the URL: {str(e)}"]
+        # Handle any errors in reading or processing the spreadsheet
+        traceback.print_exc()
+        return None, [f"Failed to read the TSV from the URL: {str(e)}:{e.with_traceback(None)}"]
 
 
 def convert_mixed_columns(df: DataFrame) -> DataFrame:
     """Converts columns in a DataFrame to appropriate types based on their content.
 
-    null or empty strings are converted to empty strings instead of NaN.
+    This handles common issues with spreadsheet data:
+    1. Numeric columns that contain strings
+    2. Mixed type columns
+    3. Empty cells and NaN values
+
+    The approach is to convert each column appropriately:
+    - Numeric columns remain as numbers
+    - Other columns are converted to strings, with empty strings for missing values
 
     Args:
-        df (DataFrame): The DataFrame whose columns are to be converted
+        df: The DataFrame whose columns are to be converted
 
     Returns:
         DataFrame with columns converted to appropriate types