Merge pull request #180 from WilliamK112/agent/great-expectations-recipe

docs: add Great Expectations validation recipe

Author: JohnnyWilson16

CHANGELOG.md

@@ -9,6 +9,8 @@ adheres to [Semantic Versioning](https://semver.org/).
 ### Added
 - Added a runnable PyJanitor interoperability example that demonstrates both
   tool orderings while keeping PyJanitor optional.
+- A dependency-optional Great Expectations recipe demonstrating the
+  repair-then-validate workflow with an in-memory checkpoint.
 
 ## [2.0.0] - 2026-07-20
 

docs/examples.md

@@ -22,9 +22,9 @@ directory has narrated Jupyter walkthroughs.
 | `05_ml_pipeline.py` | End-to-end ML preprocessing with scikit-learn |
 | `06_large_dataset.py` | Cleaning a large synthetic dataset, with timing |
 | `07_pandas_integration.py` | Dropping freshdata into an existing pandas workflow |
-| `08_csv_automation.py` | Batch CSV cleaning automation with audit logs |
 | `09_pandera_recipe.py` | Validating with pandera before and after freshdata cleaning |
 | `10_pyjanitor_interop.py` | Combining PyJanitor transforms with FreshData quality repair |
+| `11_great_expectations_recipe.py` | Repair string-typed data, then run an optional Great Expectations checkpoint |
 
 ## Missing-value cleaning
 
@@ -97,3 +97,20 @@ install the compatible PyJanitor 0.31 line to run the example:
 pip install "pyjanitor<0.32"
 python examples/10_pyjanitor_interop.py
 ```
+
+## Great Expectations: repair, then validate
+
+FreshData and Great Expectations have complementary roles: FreshData repairs
+representational problems and records the changes, while Great Expectations
+checks the result against an explicit data contract. Great Expectations remains
+an optional dependency:
+
+```bash
+pip install great-expectations
+python examples/11_great_expectations_recipe.py
+```
+
+The recipe runs the same checkpoint before and after `fd.clean()`. The raw
+currency and boolean strings fail the typed contract; after FreshData converts
+them to `float64` and `bool`, the checkpoint passes. The checkpoint validates
+the result but does not modify the DataFrame.

examples/11_great_expectations_recipe.py

@@ -0,0 +1,101 @@
+"""Repair a DataFrame with freshdata, then validate it with GX Core.
+
+Great Expectations is optional and remains separate from freshdata's core
+dependencies. Install it before running this recipe:
+
+    pip install great-expectations
+    python examples/11_great_expectations_recipe.py
+"""
+
+import os
+
+import pandas as pd
+
+import freshdata as fd
+
+os.environ.setdefault("GX_ANALYTICS_ENABLED", "false")
+
+import great_expectations as gx  # noqa: E402
+
+
+def make_checkpoint():
+    """Build an in-memory checkpoint for the cleaned orders contract."""
+    context = gx.get_context(mode="ephemeral")
+    context.variables.progress_bars = {
+        "globally": False,
+        "metric_calculations": False,
+    }
+    data_source = context.data_sources.add_pandas(name="freshdata_recipe")
+    data_asset = data_source.add_dataframe_asset(name="orders")
+    batch_definition = data_asset.add_batch_definition_whole_dataframe("whole_frame")
+
+    suite = context.suites.add(gx.ExpectationSuite(name="clean_orders"))
+    suite.add_expectation(
+        gx.expectations.ExpectColumnValuesToBeOfType(
+            column="order_amount",
+            type_="float64",
+        )
+    )
+    suite.add_expectation(
+        gx.expectations.ExpectColumnValuesToBeOfType(
+            column="active",
+            type_="bool",
+        )
+    )
+    suite.add_expectation(
+        gx.expectations.ExpectColumnValuesToBeBetween(
+            column="order_amount",
+            min_value=0,
+        )
+    )
+
+    validation_definition = context.validation_definitions.add(
+        gx.ValidationDefinition(
+            name="clean_orders_validation",
+            data=batch_definition,
+            suite=suite,
+        )
+    )
+    return context.checkpoints.add(
+        gx.Checkpoint(
+            name="clean_orders_checkpoint",
+            validation_definitions=[validation_definition],
+        )
+    )
+
+
+def validate(checkpoint, frame: pd.DataFrame) -> bool:
+    """Run the checkpoint against one in-memory DataFrame."""
+    result = checkpoint.run(batch_parameters={"dataframe": frame})
+    return bool(result.success)
+
+
+def main() -> None:
+    raw = pd.DataFrame(
+        {
+            "customer_id": [1, 2, 3, 4, 5],
+            "order_amount": ["$19.99", "$5.00", "$8.25", "$12.40", "$7.10"],
+            "active": ["true", "false", "true", "true", "false"],
+        }
+    )
+    checkpoint = make_checkpoint()
+
+    before = validate(checkpoint, raw)
+    print(f"Before freshdata: checkpoint passed = {before}")
+
+    cleaned, report = fd.clean(
+        raw,
+        id_columns=("customer_id",),
+        return_report=True,
+    )
+    after = validate(checkpoint, cleaned)
+
+    print(f"After freshdata:  checkpoint passed = {after}")
+    print(report.summary())
+
+    assert not before, "the raw string values should fail the typed contract"
+    assert after, "the freshdata-cleaned values should pass the checkpoint"
+
+
+if __name__ == "__main__":
+    main()

examples/README.md

@@ -21,13 +21,19 @@ python examples/01_missing_values.py
 | [`08_csv_automation.py`](08_csv_automation.py) | Batch CSV cleaning automation with audit logs |
 | [`09_pandera_recipe.py`](09_pandera_recipe.py) | Validating with pandera before and after freshdata cleaning |
 | [`10_pyjanitor_interop.py`](10_pyjanitor_interop.py) | Combining explicit PyJanitor transforms with FreshData quality repair |
+| [`11_great_expectations_recipe.py`](11_great_expectations_recipe.py) | Repairing with freshdata, then validating through a Great Expectations checkpoint |
 
-The PyJanitor example has one optional dependency. FreshData 2.0 supports
-pandas 1.5–2.x, so install the compatible PyJanitor 0.31 line before running it:
+The PyJanitor and Great Expectations examples have optional dependencies.
+Install them only when running the corresponding example:
 
 ```bash
+# PyJanitor example (pandas 1.5–2.x compatible line)
 pip install "pyjanitor<0.32"
 python examples/10_pyjanitor_interop.py
+
+# Great Expectations recipe
+pip install great-expectations
+python examples/11_great_expectations_recipe.py
 ```
 
 See the [documentation](https://freshcode-org.github.io/freshdata/) for full guides.