Merge pull request #96 from FreshCode-Org/feature/phase4-learning-profiles-jwd

[codex] Align package install and imputation UX

Author: JohnnyWilson16

README.md

@@ -10,12 +10,12 @@
 logs, scores, explains, and *remembers* data-quality decisions, then makes them
 reusable in notebooks, streaming runs, and orchestrated pipelines.
 
-[![PyPI Version](https://img.shields.io/pypi/v/freshdata-cleaner.svg)](https://pypi.org/project/freshdata-cleaner/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/freshdata-cleaner.svg)](https://pypi.org/project/freshdata-cleaner/)
+[![PyPI Version](https://img.shields.io/pypi/v/freshdata.svg)](https://pypi.org/project/freshdata/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/freshdata.svg)](https://pypi.org/project/freshdata/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![CI](https://github.com/FreshCode-Org/freshdata/actions/workflows/ci.yml/badge.svg)](https://github.com/FreshCode-Org/freshdata/actions/workflows/ci.yml)
 [![Docs](https://github.com/FreshCode-Org/freshdata/actions/workflows/docs.yml/badge.svg)](https://freshcode-org.github.io/freshdata/)
-[![Downloads](https://img.shields.io/pypi/dm/freshdata-cleaner.svg)](https://pypi.org/project/freshdata-cleaner/)
+[![Downloads](https://img.shields.io/pypi/dm/freshdata.svg)](https://pypi.org/project/freshdata/)
 [![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/FreshCode-Org/freshdata/badges/coverage.json)](https://github.com/FreshCode-Org/freshdata/actions/workflows/ci.yml)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)
@@ -47,9 +47,12 @@ import freshdata as fd
 
 df = pd.read_csv("export.csv")
 
-cleaned = fd.clean(df)                              # one line
-cleaned, report = fd.clean(df, return_report=True)  # ... with a full audit trail
-print(report.summary())
+result = fd.clean(df)                               # one line
+cleaned = result.data                               # plain pandas DataFrame
+print(result.summary())                             # full audit trail
+result.visualize()                                  # self-contained HTML
+
+cleaned, report = fd.clean(df, return_report=True)  # legacy tuple still works
 ```
 
 ```text
@@ -118,13 +121,13 @@ ML-ready data without writing — or trusting — yet another bespoke script.
 ## 📦 Installation
 
 ```bash
-pip install freshdata-cleaner                 # pandas + numpy only
-pip install "freshdata-cleaner[ml]"           # + scikit-learn (KNN imputation, IsolationForest)
-pip install "freshdata-cleaner[domains]"      # + PyYAML (finance, GS1, and GTFS packs)
-pip install "freshdata-cleaner[enterprise]"   # + polars, pyarrow, requests, pyyaml (enterprise layer + CLI)
-pip install "freshdata-cleaner[privacy]"      # + Presidio NER & pyffx (stronger PII detection / crypto FPE)
-pip install "freshdata-cleaner[entity-resolution]"  # + duckdb (probabilistic linkage at scale)
-pip install "freshdata-cleaner[all]"          # everything, including cleanlab
+pip install freshdata                 # pandas + numpy, reporting, standard HTML visualization
+pip install "freshdata[ml]"           # + scikit-learn (KNN imputation, IsolationForest)
+pip install "freshdata[domains]"      # + PyYAML (finance, GS1, and GTFS packs)
+pip install "freshdata[enterprise]"   # + polars, pyarrow, requests, pyyaml (enterprise layer + CLI)
+pip install "freshdata[privacy]"      # + Presidio NER & pyffx (stronger PII detection / crypto FPE)
+pip install "freshdata[entity-resolution]"  # + duckdb (probabilistic linkage at scale)
+pip install "freshdata[all]"          # everything, including cleanlab
 ```
 
 Requires **Python ≥ 3.9** and **pandas ≥ 1.5**. Verify the install:
@@ -142,12 +145,15 @@ import freshdata as fd
 df = pd.read_csv("messy_export.csv")
 
 # Clean with sensible, explainable defaults
-cleaned, report = fd.clean(df, return_report=True)
+result = fd.clean(df)
+cleaned = result.data
+report = result.report()
 
 print(report.summary())        # human-readable audit trail
 report.to_frame()              # decisions as a DataFrame
 report.to_dict()               # JSON-friendly for logging / dashboards
-report.show()                  # interactive action timeline + audit ledger (notebook)
+result.visualize()             # self-contained HTML action timeline + audit ledger
+report.show()                  # inline in notebooks, or writes a standalone .html file
 ```
 
 Interactive output, decision memory, drift, debt, joins, encoding, and
@@ -170,7 +176,8 @@ lint  = fd.lint_text_encoding(df, columns=["name", "city"])
 brief = fd.stakeholder_summary(report, audience="business", format="markdown")
 ```
 
-Visualization extras are optional and never required by the base install:
+Standard report visualization is included in the base install. Optional
+visualization extras only add richer third-party notebook/table integrations:
 `pip install 'freshdata[viz]'` (or `[notebook]`, `[all]`).
 
 Domain packs add versioned validation and separately audited repairs:
@@ -297,7 +304,7 @@ categorical, and boolean predictors, while preserving FreshData's role gates:
 targets, IDs, and free-text columns are not fabricated.
 
 ```python
-# pip install "freshdata-cleaner[ml]"
+# pip install "freshdata[ml]"
 cleaned, report = fd.clean(
     df,
     impute_method="missforest",
@@ -410,7 +417,7 @@ It accepts **pandas**, and (when installed) **PyArrow** `Table`/`RecordBatch` an
 stream. Optional source connectors live behind extras:
 
 ```python
-# pip install "freshdata-cleaner[kafka]"   /   "freshdata-cleaner[flight]"
+# pip install "freshdata[kafka]"   /   "freshdata[flight]"
 cleaner.clean_kafka(topic="events", bootstrap_servers="localhost:9092", batch_size=10_000)
 cleaner.clean_arrow_flight("grpc://localhost:8815", batch_size=100_000)
 ```

docs/backends.md

@@ -84,7 +84,7 @@ cfg = EngineConfig(engine="duckdb", memory_limit_gb=4, temp_directory="/tmp/spil
 cfg = EngineConfig(engine="spark", spark_shuffle_partitions=200, output_format="spark")
 ```
 
-PySpark is an **optional dependency** (`pip install 'freshdata-cleaner[spark]'`) and
+PySpark is an **optional dependency** (`pip install 'freshdata[spark]'`) and
 also needs a JVM at runtime. Importing `freshdata` never imports pyspark.
 
 FreshCore is also optional. Install the Python package normally, then build the

docs/benchmarks.md

@@ -27,7 +27,7 @@ gated to aggressive mode only.
 MissForest-style imputation is also benchmarked separately because it is
 opt-in, scikit-learn-backed, and intentionally slower than the default engine.
 Use `python benchmarks/bench_missforest.py` after installing
-`freshdata-cleaner[ml]` to compare median/mode, aggressive KNN, and MissForest
+`freshdata[ml]` to compare median/mode, aggressive KNN, and MissForest
 on mixed-type synthetic data.
 
 ## The Benchmark Release harness

docs/cleaning-engine.md

@@ -77,7 +77,7 @@ mixed tabular data, you can opt into MissForest-style random-forest imputation
 with the optional ML extra:
 
 ```bash
-pip install "freshdata-cleaner[ml]"
+pip install "freshdata[ml]"
 ```
 
 ```python
@@ -130,7 +130,7 @@ fd.clean(
     target_column="churn",
     preserve_columns=("notes",),
     id_columns=("ref",),
-    impute_method="missforest",      # optional; requires freshdata-cleaner[ml]
+    impute_method="missforest",      # optional; requires freshdata[ml]
     missforest_max_iter=5,
     missforest_n_estimators=100,
     return_report=True,

docs/faq.md

@@ -47,7 +47,7 @@ you explicitly pass `preserve_original=False` to reuse memory.
 
 ## Does it support Polars?
 
-Yes — install `pip install "freshdata-cleaner[polars]"` and pass a Polars DataFrame to
+Yes — install `pip install "freshdata[polars]"` and pass a Polars DataFrame to
 `fd.clean`; you get a Polars DataFrame back.
 
 ## How do I see what it changed?

docs/feature-overview.md

@@ -71,4 +71,4 @@ import freshdata as fd
 cleaned = fd.clean(pl_df)   # returns a pl.DataFrame when the input is Polars
 ```
 
-Install with `pip install "freshdata-cleaner[polars]"`.
+Install with `pip install "freshdata[polars]"`.

docs/index.md

@@ -43,7 +43,7 @@ score for each decision.
 ## Install
 
 ```bash
-pip install freshdata-cleaner
+pip install freshdata
 ```
 
 See [Installation](installation.md) for optional extras (`ml`, `enterprise`, `all`).

docs/installation.md

@@ -3,7 +3,7 @@ title: Installation
 description: >-
   How to install freshdata for Python and pandas, including optional extras for
   scikit-learn machine-learning imputation, the enterprise layer, and Polars.
-keywords: install freshdata, pip install freshdata-cleaner, pandas data cleaning install
+keywords: install freshdata, pip install freshdata, pandas data cleaning install
 ---
 
 # Installation
@@ -13,11 +13,12 @@ keywords: install freshdata, pip install freshdata-cleaner, pandas data cleaning
 ## Basic install
 
 ```bash
-pip install freshdata-cleaner
+pip install freshdata
 ```
 
-This installs the pandas + NumPy core — everything you need for `fd.clean`,
-`fd.profile`, and the decision engine.
+This installs the pandas + NumPy core plus FreshData's standard reporting and
+self-contained HTML visualization. You do not need an extra to call
+`fd.clean(df).summary()`, `fd.clean(df).report()`, or `fd.clean(df).visualize()`.
 
 ## Optional extras
 
@@ -26,7 +27,7 @@ Install only what you need:
 === "Machine learning"
 
     ```bash
-    pip install "freshdata-cleaner[ml]"
+    pip install "freshdata[ml]"
     ```
 
     Adds **scikit-learn** for KNN imputation and IsolationForest outlier
@@ -35,7 +36,7 @@ Install only what you need:
 === "Enterprise"
 
     ```bash
-    pip install "freshdata-cleaner[enterprise]"
+    pip install "freshdata[enterprise]"
     ```
 
     Adds **polars, pyarrow, requests, pyyaml** for the enterprise layer:
@@ -45,15 +46,15 @@ Install only what you need:
 === "Everything"
 
     ```bash
-    pip install "freshdata-cleaner[all]"
+    pip install "freshdata[all]"
     ```
 
     All extras above plus **cleanlab** for ML label-noise detection.
 
 === "Polars only"
 
     ```bash
-    pip install "freshdata-cleaner[polars]"
+    pip install "freshdata[polars]"
     ```
 
     Pass a Polars DataFrame to `fd.clean` and get a Polars DataFrame back.
@@ -74,11 +75,11 @@ print(fd.clean(df))
 
 ## Note on naming
 
-The PyPI distribution is **`freshdata-cleaner`**, but the import name is simply
+The PyPI distribution is **`freshdata`**, but the import name is simply
 **`freshdata`** — so you install one and import the other:
 
 ```bash
-pip install freshdata-cleaner
+pip install freshdata
 ```
 
 ```python

docs/interactive.md

@@ -18,8 +18,11 @@ visualization library.
 ```python
 import freshdata as fd
 
-cleaned, report = fd.clean(df, return_report=True)
+result = fd.clean(df)
+cleaned = result.data
+report = result.report()
 
+result.visualize()       # self-contained report HTML string
 report.show()            # collapsible action timeline + filterable audit ledger
 fd.profile(df).show()    # inline quality cockpit
 fd.suggest_plan(df).show()   # per-column decision cards

docs/limitations.md

@@ -94,7 +94,7 @@ and cleaning memory need **none** of these.
 ## Optional semantic models (Phase 3)
 
 - **The default install stays model-free**; everything below applies only
-  after `pip install "freshdata-cleaner[semantic]"` *and* an explicit
+  after `pip install "freshdata[semantic]"` *and* an explicit
   `fd.models.pull(...)` (or air-gapped file placement). Nothing is ever
   downloaded during cleaning.
 - **Official model artifacts are not hosted yet.** `fd.models.pull` raises a