Merge pull request #1 from FreshCode-Org/feature/repair-plan-p0

Add repair plan artifacts

Author: JohnnyWilson16

README.md

@@ -177,6 +177,8 @@ level, and confidence score — no silent mutations.
 | name | purpose |
 |---|---|
 | `fd.clean(df, *, return_report=False, config=None, **options)` | clean, optionally returning a `CleanReport` |
+| `fd.plan(df, *, mode="suggest", **options)` | build a serializable `RepairPlan` with row, column, and cell patches |
+| `fd.repair(df, *, mode="repair_safe", return_plan=False, **options)` | apply safe, reviewed, or aggressive repair modes |
 | `fd.profile(df, *, include_plan=False, **options)` | read-only inspection with actionable issues |
 | `fd.suggest_plan(df, **options)` | dry-run: primary + alternative models per column |
 | `fd.compare_plans(df, *, strategies=...)` | side-by-side models across strategies |
@@ -185,6 +187,7 @@ level, and confidence score — no silent mutations.
 | `fd.Cleaner(config=None, **options)` | reusable configured pipeline (`.clean()`, `.report_`) |
 | `fd.CleanConfig` | frozen dataclass holding every option |
 | `fd.CleanReport` / `fd.Action` | audit trail with rationale / risk / confidence |
+| `fd.RepairPlan` / `fd.RepairPatch` | reversible repair artifact and patch log |
 
 ```python
 # Tune the engine — explicit choices always override the defaults

docs/api-reference.md

@@ -1,8 +1,8 @@
 ---
 title: API reference
 description: >-
-  Complete freshdata API reference — clean, profile, suggest_plan, compare_plans,
-  compare_clean, explain_clean, the Cleaner pipeline, CleanConfig, and reports.
+  Complete freshdata API reference — clean, plan, repair, profile, suggest_plan,
+  compare_plans, compare_clean, explain_clean, Cleaner, CleanConfig, and reports.
 keywords: freshdata api, fd.clean, CleanConfig, CleanReport, pandas cleaning api
 ---
 
@@ -15,6 +15,8 @@ top-level attribute of `freshdata` (e.g. `import freshdata as fd; fd.clean(...)`
 
 ::: freshdata.clean
 
+::: freshdata.repair
+
 ::: freshdata.Cleaner
 
 ## Profiling & inspection
@@ -29,6 +31,8 @@ top-level attribute of `freshdata` (e.g. `import freshdata as fd; fd.clean(...)`
 
 ::: freshdata.suggest_plan
 
+::: freshdata.plan
+
 ::: freshdata.compare_plans
 
 ::: freshdata.compare_clean
@@ -47,6 +51,12 @@ top-level attribute of `freshdata` (e.g. `import freshdata as fd; fd.clean(...)`
 
 ::: freshdata.ColumnPlan
 
+::: freshdata.RepairPlan
+
+::: freshdata.RepairPatch
+
+::: freshdata.ReviewItem
+
 ::: freshdata.Profile
 
 ::: freshdata.ColumnProfile

src/freshdata/__init__.py

@@ -22,11 +22,19 @@
   sample-based pre-screening so type inference stays cheap on large frames.
 """
 
-from .api import clean, infer_roles, profile, suggest_plan
+from .api import clean, infer_roles, plan, profile, repair, suggest_plan
 from .cleaner import Cleaner
 from .config import CleanConfig
 from .explain import ExplainReport, explain_clean
-from .plan import CleanPlan, ColumnPlan, compare_clean, compare_plans
+from .plan import (
+    CleanPlan,
+    ColumnPlan,
+    RepairPatch,
+    RepairPlan,
+    ReviewItem,
+    compare_clean,
+    compare_plans,
+)
 from .profile import ColumnProfile, Profile
 from .report import Action, CleanReport
 
@@ -42,13 +50,18 @@
     "ExplainReport",
     "ColumnProfile",
     "Profile",
+    "RepairPatch",
+    "RepairPlan",
+    "ReviewItem",
     "__version__",
     "clean",
     "compare_clean",
     "compare_plans",
     "explain_clean",
     "infer_roles",
+    "plan",
     "profile",
+    "repair",
     "suggest_plan",
 ]
 

src/freshdata/api.py

@@ -11,7 +11,7 @@
 from .config import CleanConfig, merge_options
 from .engine.context import build_contexts
 from .engine.model_select import EngineMode, rank_missing_models
-from .plan import suggest_plan
+from .plan import RepairPlan, build_repair_plan, suggest_plan
 from .profile import Profile, build_profile
 from .report import CleanReport
 
@@ -132,6 +132,46 @@ def clean(
     return from_pandas(result, df)
 
 
+def plan(
+    df: pd.DataFrame,
+    *,
+    mode: str = "suggest",
+    config: CleanConfig | None = None,
+    **options: object,
+) -> RepairPlan:
+    """Build a previewable, serializable repair plan without changing *df*.
+
+    ``mode="suggest"`` runs the configured cleaner and records the proposed
+    row, column, and cell patches. ``mode="inspect"`` records only the source
+    fingerprint and shape. ``mode="repair_safe"`` limits the plan to
+    deterministic representation repairs by disabling statistical engine
+    actions.
+    """
+    return build_repair_plan(to_pandas(df), mode=mode, config=config, **options)
+
+
+def repair(
+    df: pd.DataFrame,
+    *,
+    mode: str = "repair_safe",
+    approved_patch_ids: set[str] | None = None,
+    return_plan: bool = False,
+    config: CleanConfig | None = None,
+    **options: object,
+) -> pd.DataFrame | tuple[pd.DataFrame, RepairPlan]:
+    """Apply a repair mode and optionally return the repair plan.
+
+    ``mode="repair_reviewed"`` applies only ``approved_patch_ids``. Other
+    modes apply every patch proposed by the plan.
+    """
+    repair_plan = build_repair_plan(to_pandas(df), mode=mode, config=config, **options)
+    approved = set(approved_patch_ids or ()) if mode == "repair_reviewed" else None
+    repaired = from_pandas(repair_plan.apply(approved), df)
+    if return_plan:
+        return repaired, repair_plan
+    return repaired
+
+
 def _engine_mode(cfg: CleanConfig) -> EngineMode:
     mode = cfg.engine_mode or "balanced"
     return "balanced" if mode == "balanced" else "aggressive"