docs(examples): runnable demos for cleaning memory replay and interactive HTML reports

[JohnnyWilson16]

Problem and motivation

The v1.1 flagship surfaces — cleaning memory (fd.learn_cleaning_memory / fd.load_cleaning_memory) and the interactive HTML report layer (freshdata.render: to_html() / show() on CleanReport, Profile, CleanPlan, ExplainReport, plus ReportFrame) — shipped in 1.1.0 with docs but no runnable examples. Every other headline feature has one under examples/. These two scripts close that gap; they were written alongside the 1.1 work but never committed.

What this PR adds

• examples/cleaning_memory_replay.py — three-day replay story: learn a memory from a reviewed CleanReport, replay it on a matching batch (decisions marked memory_influenced), show a drifted batch being blocked with an on-report explanation rather than silently replayed, and diff two learned memories.
• examples/interactive_html_reports.py — show() / to_html() across all four report objects plus ReportFrame results from compare_plans / infer_roles; self-contained HTML, no optional deps.

Both follow the examples/ conventions: synthetic inline data, plain-script runnable, no new dependencies. No changelog entry (per convention, examples are only mentioned inside feature entries) and no README-table entry (the table indexes the numbered core walkthroughs only).

Review scope: what was inspected and excluded

This PR is the outcome of a review of all unpushed local work in the primary clone (branch feature/ai-copilot-jwd):

• Retained (this PR): the two example scripts above, rebased onto current main and verified to run end-to-end against it.
• Excluded — internal planning artifacts: 3 local docs-only commits adding docs/superpowers/{specs,plans}/2026-07-16-production-readiness-*.md. These are agent-workflow planning documents (machine-specific absolute paths, session constraints, tooling directives); docs/superpowers/ does not exist on main, and main already carries the real outcome doc docs/production-readiness.md. Preserved locally on the original branch and a backup branch, not published.
• Excluded — accidental artifact: an untracked uv.lock in the old worktree; main already tracks uv.lock, the stray copy is just a side effect of the branch predating it. Nothing to commit.
• The remaining commits on feature/ai-copilot-jwd are the already-merged PR AI Copilot (experimental): deterministic, privacy-first dataset analysis with explainable cleaning plans #112 history (main's copies of those files are newer); nothing to salvage.

Validation

Run from a worktree of this branch (based on main @ 8a15842):

Check	Command	Result
Lint	ruff check .	pass
Examples run	python examples/cleaning_memory_replay.py	exit 0; 8 decisions replayed on day 2, day-3 drift blocked with explanation
Examples run	python examples/interactive_html_reports.py	exit 0; all four HTML reports + ReportFrame rendered
Tests	pytest -m "not online and not large"	pass — exit 0 under the configured gates, including --cov-fail-under=93 (run log lost to tmp cleanup; CI will republish exact counts)
Build	python -m build && twine check dist/*	pass; both examples present in sdist, wheel unchanged
Typecheck	mypy src/freshdata	not run locally (known numpy≥2.5 stubs vs. py3.10 target issue; CI pins numpy<2.5); diff touches no mypy-scoped files

Risks and compatibility

• Docs/examples-only change: no runtime code, no API surface, no dependency changes.
• The sdist gains the two scripts (it already ships examples/); wheel contents are unchanged.
• The scripts write small output files (crm_daily_memory.json; show() writes HTML to the OS temp dir) — same behavior class as existing examples like 08_csv_automation.py.

Prepared with AI tooling assistance.

Summary by CodeRabbit

• Documentation
  • Added examples demonstrating reusable cleaning memory, safe replay, drift detection, and memory comparisons.
  • Added an example showing interactive HTML reports for cleaning, profiling, plan suggestions, explanations, strategy comparisons, and role inference.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds examples for learning and replaying cleaning decisions across data batches, handling dataset drift, comparing cleaning memories, and rendering freshdata reports as interactive HTML.

Changes

Cleaning memory replay

Layer / File(s)	Summary
Learn and persist cleaning memory examples/cleaning_memory_replay.py	Builds Day 1 data, creates a cleaning report, learns dataset-specific cleaning memory, saves it, and prints its summary.
Replay, block, and compare memory examples/cleaning_memory_replay.py	Replays decisions for Day 2, reports warnings and recommendations when Day 3 data drifts, compares newly learned memory, and adds the executable entry point.

Interactive HTML reports

Layer / File(s)	Summary
Run and display report workflows examples/interactive_html_reports.py	Runs cleaning, profiling, planning, explanation, strategy comparison, and role inference examples while displaying report outputs and providing an executable entry point.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• FreshCode-Org/freshdata#84: Adds related examples for cleaning-memory replay and interactive HTML reporting APIs.

Suggested reviewers: johnnywilson-portfolio

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed, but it does not follow the required template and is missing the Type of Change and Checklist sections.	Add the required ## Description, ## Type of Change, and ## Checklist sections, and include a Fixes # reference if applicable.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the added runnable example demos and matches the main changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/examples-memory-and-render-jwd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[strix-security]

Strix is installed on this repository, but we couldn't run this PR security review because this workspace's trial has ended. Add a card to resume code reviews here.

[coderabbitai]

🧹 Nitpick comments (2)

examples/interactive_html_reports.py (2)

40-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use fd.plan instead of fd.suggest_plan.

Consider using fd.plan(df) here to better represent the recommended API. fd.plan is the intended front door that wraps suggest_plan and additionally provides execution and backend fallback details.
As per the relevant code snippets context, fd.plan is a thin front door over suggest_plan.

♻️ Proposed refactor

-    plan = fd.suggest_plan(df)
+    plan = fd.plan(df)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/interactive_html_reports.py` at line 40, Update the plan creation
call in the interactive report flow to use the public fd.plan API instead of
fd.suggest_plan, preserving the existing df argument and downstream handling.

---

56-59: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consistently capture and print the HTML report paths.

The preceding comment mentions that infer_roles also renders as HTML via .show(). However, roles.show() is omitted, and the path for strategy_diff.show() is not printed. Updating these lines will make this section consistent with the rest of the example script and demonstrate .show() for both operations.

♻️ Proposed refactor

-    strategy_diff.show()
+    diff_path = strategy_diff.show()
+    print(f"ComparePlans -> {diff_path}")
 
     roles = fd.infer_roles(df)
     print(roles)
+    roles_path = roles.show()
+    print(f"InferRoles -> {roles_path}")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/interactive_html_reports.py` around lines 56 - 59, Update the
reporting section around strategy_diff.show() and infer_roles so both rendered
reports call their show() methods and capture the returned HTML paths. Print
each path consistently, including the path returned by strategy_diff.show(),
then call roles.show() and print its path.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/interactive_html_reports.py`:
- Line 40: Update the plan creation call in the interactive report flow to use
the public fd.plan API instead of fd.suggest_plan, preserving the existing df
argument and downstream handling.
- Around line 56-59: Update the reporting section around strategy_diff.show()
and infer_roles so both rendered reports call their show() methods and capture
the returned HTML paths. Print each path consistently, including the path
returned by strategy_diff.show(), then call roles.show() and print its path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8c71d0e8-5def-4341-9a68-9ad3baf2c516

📥 Commits

Reviewing files that changed from the base of the PR and between 8a15842 and 37f425d.

📒 Files selected for processing (2)

• examples/cleaning_memory_replay.py
• examples/interactive_html_reports.py