ruleframe 0.1.0

Declarative DataFrame validation with rule bundles and JsonLogic

RuleFrame

RuleFrame validates pandas DataFrames with readable YAML or JSON rule bundles.

RuleFrame is useful when validation rules need to live outside application code: in files, database records, admin screens, or workflow configuration. A rule bundle describes the conditions that should produce findings, and RuleFrame returns both row-level findings and an annotated DataFrame.

Status

RuleFrame is in alpha. The core validation API is usable, but public APIs and rule syntax may change before a stable 1.0.0 release.

Install

pip install ruleframe

Quick Start

import pandas as pd

from ruleframe import RuleBundle, validate_dataframe

rules_yaml = """
version: 1
rules:
  - id: active_customer_missing_name
    severity: error
    fail_when:
      all:
        - column: Status
          equals: "Active"
        - column: Customer Name
          is_blank: true
    message: Active customers must have a name.
"""

df = pd.DataFrame(
    {
        "Status": ["Active", "Closed", "Active"],
        "Customer Name": ["", "Grace Hopper", "Ada Lovelace"],
    }
)

bundle = RuleBundle.from_yaml_string(rules_yaml)
result = validate_dataframe(df, bundle)

print(f"{len(result.findings)} finding(s)")
for finding in result.findings:
    print(f"- row {finding.row_index}: [{finding.severity}] {finding.rule_id}")
    print(f"  {finding.message}")

annotated = result.to_annotated_dataframe()
print("\nRows:")
for row_index, row in annotated.iterrows():
    name = row["Customer Name"] or "(missing)"
    message = row["Validation Errors"] or "OK"
    print(f"- row {row_index}: {row['Status']}, {name} -> {message}")

Expected output:

1 finding(s)
- row 0: [error] active_customer_missing_name
  Active customers must have a name.

Rows:
- row 0: Active, (missing) -> Active customers must have a name.
- row 1: Closed, Grace Hopper -> OK
- row 2: Active, Ada Lovelace -> OK

validate_dataframe() returns a ValidationResult with:

• to_findings_dataframe(): one row per rule finding.
• to_annotated_dataframe(): the original DataFrame plus computed columns and a validation message column.
• to_summary_dataframe(): finding counts grouped by rule and severity.

Rule Bundles

Rule bundles can be loaded from YAML, JSON, strings, or pre-parsed dictionaries:

from ruleframe import RuleBundle

bundle = RuleBundle.from_yaml("rules.yaml")
bundle = RuleBundle.from_json("rules.json")
bundle = RuleBundle.from_yaml_string(yaml_text)
bundle = RuleBundle.from_json_string(json_text)
bundle = RuleBundle.from_json_dict(data)

Rules support boolean nesting, literal comparisons, column-to-column comparisons, date comparisons, blank checks, membership checks, string containment, ranges, and generated computed columns.

Documentation

• Documentation index
• Rule format
• Predicates
• Computed columns
• Validation results