From 33f50fa05bd79fc61bb3e79851ff533b46ed3efd Mon Sep 17 00:00:00 2001 From: WilliamK112 <164879897+WilliamK112@users.noreply.github.com> Date: Wed, 12 Aug 2026 14:05:41 +0800 Subject: [PATCH 1/2] docs: link subpackages to architecture map Signed-off-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com> --- src/freshdata/adapters/__init__.py | 5 ++++- src/freshdata/compliance/__init__.py | 2 ++ src/freshdata/context/__init__.py | 2 ++ src/freshdata/domains/__init__.py | 2 ++ src/freshdata/engine/__init__.py | 2 ++ src/freshdata/enterprise/__init__.py | 2 ++ src/freshdata/execution/__init__.py | 2 ++ src/freshdata/experimental/__init__.py | 2 ++ src/freshdata/imputation/__init__.py | 5 ++++- src/freshdata/integrations/__init__.py | 2 ++ src/freshdata/learning/__init__.py | 2 ++ src/freshdata/models/__init__.py | 2 ++ src/freshdata/parsers/__init__.py | 2 ++ src/freshdata/render/__init__.py | 2 ++ src/freshdata/semantic/__init__.py | 2 ++ src/freshdata/steps/__init__.py | 2 ++ src/freshdata/streaming/__init__.py | 2 ++ 17 files changed, 38 insertions(+), 2 deletions(-) diff --git a/src/freshdata/adapters/__init__.py b/src/freshdata/adapters/__init__.py index 4a4d0d20..d5eb48b5 100644 --- a/src/freshdata/adapters/__init__.py +++ b/src/freshdata/adapters/__init__.py @@ -1,4 +1,7 @@ -"""Optional framework adapters (Polars, etc.).""" +"""Optional framework adapters (Polars, etc.). + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +""" from .polars import from_pandas, is_polars_frame, to_pandas diff --git a/src/freshdata/compliance/__init__.py b/src/freshdata/compliance/__init__.py index a3423934..53cd384c 100644 --- a/src/freshdata/compliance/__init__.py +++ b/src/freshdata/compliance/__init__.py @@ -13,6 +13,8 @@ per-column roles and missing ratios via :func:`freshdata.infer_roles`) and/or an ``enterprise_result=`` (to fold in the 0–100 Data Trust Score, PII-masking events, and fuzzy-clustering lineage) when richer evidence is available. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/context/__init__.py b/src/freshdata/context/__init__.py index 43775522..ed95976c 100644 --- a/src/freshdata/context/__init__.py +++ b/src/freshdata/context/__init__.py @@ -6,6 +6,8 @@ :class:`ContextPolicy` that lowers into the existing :class:`~freshdata.CleanConfig` machinery. Fully offline, model-free, and dependency-free — unresolved or unparsed sentences are always surfaced, never guessed at. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from .compiler import apply_policy_to_config, compile_context, resolve_policy diff --git a/src/freshdata/domains/__init__.py b/src/freshdata/domains/__init__.py index 3306b8f1..adccfea1 100644 --- a/src/freshdata/domains/__init__.py +++ b/src/freshdata/domains/__init__.py @@ -10,6 +10,8 @@ Third-party packs register via the ``freshdata.domains`` entry-point group; see ``CONTRIBUTING_DOMAINS.md``. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/engine/__init__.py b/src/freshdata/engine/__init__.py index 3f33e5df..778144d1 100644 --- a/src/freshdata/engine/__init__.py +++ b/src/freshdata/engine/__init__.py @@ -5,6 +5,8 @@ dataset (size, duplicate ratio), then chooses cleaning actions from explicit threshold rules. Every decision — including the decision to leave a column untouched — is logged with a rationale, a risk level, and a confidence score. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from .context import ColumnContext, build_contexts, infer_role diff --git a/src/freshdata/enterprise/__init__.py b/src/freshdata/enterprise/__init__.py index f50b83f3..7a17e5a6 100644 --- a/src/freshdata/enterprise/__init__.py +++ b/src/freshdata/enterprise/__init__.py @@ -13,6 +13,8 @@ Optional dependencies are imported lazily, so ``import freshdata`` stays cheap and pandas-only installs keep working; the Polars-native fast paths activate automatically when polars is installed. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from .cleaner import ( diff --git a/src/freshdata/execution/__init__.py b/src/freshdata/execution/__init__.py index ee8a5dd9..ddf4db34 100644 --- a/src/freshdata/execution/__init__.py +++ b/src/freshdata/execution/__init__.py @@ -7,6 +7,8 @@ Public entry point: :func:`run_with_engine`, wired into :func:`freshdata.clean` via its ``engine`` / ``output_format`` / ``engine_config`` keyword arguments. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/experimental/__init__.py b/src/freshdata/experimental/__init__.py index a3049dc0..45ff4a2d 100644 --- a/src/freshdata/experimental/__init__.py +++ b/src/freshdata/experimental/__init__.py @@ -12,6 +12,8 @@ :mod:`freshdata.experimental.ai_copilot` Deterministic, privacy-first dataset analysis that produces an explainable cleaning plan and copy-ready freshdata code. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/imputation/__init__.py b/src/freshdata/imputation/__init__.py index 6b67197a..667d3736 100644 --- a/src/freshdata/imputation/__init__.py +++ b/src/freshdata/imputation/__init__.py @@ -1,3 +1,6 @@ -"""Internal imputation engines.""" +"""Internal imputation engines. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +""" __all__: list[str] = [] diff --git a/src/freshdata/integrations/__init__.py b/src/freshdata/integrations/__init__.py index 0e3ccd10..a60b56ba 100644 --- a/src/freshdata/integrations/__init__.py +++ b/src/freshdata/integrations/__init__.py @@ -12,6 +12,8 @@ Install the extras as needed, e.g. ``pip install "freshdata-cleaner[dagster]"`` or ``pip install "freshdata-cleaner[integrations]"`` for all three. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/learning/__init__.py b/src/freshdata/learning/__init__.py index 8a7e6346..4582d602 100644 --- a/src/freshdata/learning/__init__.py +++ b/src/freshdata/learning/__init__.py @@ -6,6 +6,8 @@ examples, and an embedded :class:`~freshdata.CleaningMemory` — into an auditable profile that replays through the exact same policy gates as every other proposal source. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/models/__init__.py b/src/freshdata/models/__init__.py index 06fa0b25..39494881 100644 --- a/src/freshdata/models/__init__.py +++ b/src/freshdata/models/__init__.py @@ -10,6 +10,8 @@ fd.models.pull("fd-col-encoder-v1") # explicit download (network) fd.models.path("fd-col-encoder-v1") # local artifact path fd.models.list_available() # registry metadata + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from .download import pull diff --git a/src/freshdata/parsers/__init__.py b/src/freshdata/parsers/__init__.py index 01217287..03838d9f 100644 --- a/src/freshdata/parsers/__init__.py +++ b/src/freshdata/parsers/__init__.py @@ -4,6 +4,8 @@ :class:`ParseResult`; the frames can then be cleaned and domain-validated with :func:`freshdata.clean`. See :func:`freshdata.parse_domain` and :func:`freshdata.clean_domain_file` for the high-level entry points. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/render/__init__.py b/src/freshdata/render/__init__.py index 4339500d..b084a456 100644 --- a/src/freshdata/render/__init__.py +++ b/src/freshdata/render/__init__.py @@ -8,6 +8,8 @@ vanilla JS for filtering/collapsing) with *zero* optional dependencies. The ``freshdata-cleaner[viz]`` / ``freshdata-cleaner[notebook]`` extras (itables, plotly, great-tables, anywidget) merely *upgrade* the output when installed. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/semantic/__init__.py b/src/freshdata/semantic/__init__.py index 074080bb..b9aaccaa 100644 --- a/src/freshdata/semantic/__init__.py +++ b/src/freshdata/semantic/__init__.py @@ -18,6 +18,8 @@ - ``policy`` is the single place to add semantic-memory replay and privacy redaction (``semantic_privacy_policy``) before any future external inference. - proposals project cleanly to OpenLineage / quality-ops events. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/steps/__init__.py b/src/freshdata/steps/__init__.py index 8aaf9e89..95a398f8 100644 --- a/src/freshdata/steps/__init__.py +++ b/src/freshdata/steps/__init__.py @@ -5,4 +5,6 @@ Steps never mutate the caller's original DataFrame: the pipeline hands them a frame it owns, and steps only ever rebind whole columns or produce new frames (``.loc`` row selection), never write into shared blocks in place. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ diff --git a/src/freshdata/streaming/__init__.py b/src/freshdata/streaming/__init__.py index d6033322..5de0a355 100644 --- a/src/freshdata/streaming/__init__.py +++ b/src/freshdata/streaming/__init__.py @@ -10,6 +10,8 @@ The cleaner keeps **bounded** running statistics across batches (Welford mean/variance, reservoir-sampled medians, Space-Saving top-k categories), so memory stays flat whether you feed it 100k rows or 100M. See :class:`StreamingCleaner`. + +See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. """ from __future__ import annotations From 3deb9b3f94aad2a1b62456617bd72212fa94748e Mon Sep 17 00:00:00 2001 From: WilliamK112 <164879897+WilliamK112@users.noreply.github.com> Date: Wed, 12 Aug 2026 15:34:19 +0800 Subject: [PATCH 2/2] docs: make architecture breadcrumbs clickable Signed-off-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com> --- src/freshdata/adapters/__init__.py | 3 ++- src/freshdata/compliance/__init__.py | 3 ++- src/freshdata/context/__init__.py | 3 ++- src/freshdata/domains/__init__.py | 3 ++- src/freshdata/engine/__init__.py | 3 ++- src/freshdata/enterprise/__init__.py | 3 ++- src/freshdata/execution/__init__.py | 3 ++- src/freshdata/experimental/__init__.py | 3 ++- src/freshdata/imputation/__init__.py | 3 ++- src/freshdata/integrations/__init__.py | 3 ++- src/freshdata/learning/__init__.py | 3 ++- src/freshdata/models/__init__.py | 3 ++- src/freshdata/parsers/__init__.py | 3 ++- src/freshdata/render/__init__.py | 3 ++- src/freshdata/semantic/__init__.py | 3 ++- src/freshdata/steps/__init__.py | 3 ++- src/freshdata/streaming/__init__.py | 3 ++- 17 files changed, 34 insertions(+), 17 deletions(-) diff --git a/src/freshdata/adapters/__init__.py b/src/freshdata/adapters/__init__.py index d5eb48b5..841f7735 100644 --- a/src/freshdata/adapters/__init__.py +++ b/src/freshdata/adapters/__init__.py @@ -1,6 +1,7 @@ """Optional framework adapters (Polars, etc.). -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from .polars import from_pandas, is_polars_frame, to_pandas diff --git a/src/freshdata/compliance/__init__.py b/src/freshdata/compliance/__init__.py index 53cd384c..71c55140 100644 --- a/src/freshdata/compliance/__init__.py +++ b/src/freshdata/compliance/__init__.py @@ -14,7 +14,8 @@ ``enterprise_result=`` (to fold in the 0–100 Data Trust Score, PII-masking events, and fuzzy-clustering lineage) when richer evidence is available. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/context/__init__.py b/src/freshdata/context/__init__.py index ed95976c..1f9b044f 100644 --- a/src/freshdata/context/__init__.py +++ b/src/freshdata/context/__init__.py @@ -7,7 +7,8 @@ machinery. Fully offline, model-free, and dependency-free — unresolved or unparsed sentences are always surfaced, never guessed at. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from .compiler import apply_policy_to_config, compile_context, resolve_policy diff --git a/src/freshdata/domains/__init__.py b/src/freshdata/domains/__init__.py index adccfea1..5ff21595 100644 --- a/src/freshdata/domains/__init__.py +++ b/src/freshdata/domains/__init__.py @@ -11,7 +11,8 @@ Third-party packs register via the ``freshdata.domains`` entry-point group; see ``CONTRIBUTING_DOMAINS.md``. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/engine/__init__.py b/src/freshdata/engine/__init__.py index 778144d1..5c31ad16 100644 --- a/src/freshdata/engine/__init__.py +++ b/src/freshdata/engine/__init__.py @@ -6,7 +6,8 @@ threshold rules. Every decision — including the decision to leave a column untouched — is logged with a rationale, a risk level, and a confidence score. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from .context import ColumnContext, build_contexts, infer_role diff --git a/src/freshdata/enterprise/__init__.py b/src/freshdata/enterprise/__init__.py index 7a17e5a6..159d0c0a 100644 --- a/src/freshdata/enterprise/__init__.py +++ b/src/freshdata/enterprise/__init__.py @@ -14,7 +14,8 @@ pandas-only installs keep working; the Polars-native fast paths activate automatically when polars is installed. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from .cleaner import ( diff --git a/src/freshdata/execution/__init__.py b/src/freshdata/execution/__init__.py index ddf4db34..a36a29a2 100644 --- a/src/freshdata/execution/__init__.py +++ b/src/freshdata/execution/__init__.py @@ -8,7 +8,8 @@ Public entry point: :func:`run_with_engine`, wired into :func:`freshdata.clean` via its ``engine`` / ``output_format`` / ``engine_config`` keyword arguments. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/experimental/__init__.py b/src/freshdata/experimental/__init__.py index 45ff4a2d..076fa57e 100644 --- a/src/freshdata/experimental/__init__.py +++ b/src/freshdata/experimental/__init__.py @@ -13,7 +13,8 @@ Deterministic, privacy-first dataset analysis that produces an explainable cleaning plan and copy-ready freshdata code. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/imputation/__init__.py b/src/freshdata/imputation/__init__.py index 667d3736..d516d795 100644 --- a/src/freshdata/imputation/__init__.py +++ b/src/freshdata/imputation/__init__.py @@ -1,6 +1,7 @@ """Internal imputation engines. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ __all__: list[str] = [] diff --git a/src/freshdata/integrations/__init__.py b/src/freshdata/integrations/__init__.py index a60b56ba..974b4bb4 100644 --- a/src/freshdata/integrations/__init__.py +++ b/src/freshdata/integrations/__init__.py @@ -13,7 +13,8 @@ Install the extras as needed, e.g. ``pip install "freshdata-cleaner[dagster]"`` or ``pip install "freshdata-cleaner[integrations]"`` for all three. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/learning/__init__.py b/src/freshdata/learning/__init__.py index 4582d602..7d75862a 100644 --- a/src/freshdata/learning/__init__.py +++ b/src/freshdata/learning/__init__.py @@ -7,7 +7,8 @@ auditable profile that replays through the exact same policy gates as every other proposal source. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/models/__init__.py b/src/freshdata/models/__init__.py index 39494881..2afb98d7 100644 --- a/src/freshdata/models/__init__.py +++ b/src/freshdata/models/__init__.py @@ -11,7 +11,8 @@ fd.models.path("fd-col-encoder-v1") # local artifact path fd.models.list_available() # registry metadata -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from .download import pull diff --git a/src/freshdata/parsers/__init__.py b/src/freshdata/parsers/__init__.py index 03838d9f..4e031581 100644 --- a/src/freshdata/parsers/__init__.py +++ b/src/freshdata/parsers/__init__.py @@ -5,7 +5,8 @@ :func:`freshdata.clean`. See :func:`freshdata.parse_domain` and :func:`freshdata.clean_domain_file` for the high-level entry points. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/render/__init__.py b/src/freshdata/render/__init__.py index b084a456..c5da9ea0 100644 --- a/src/freshdata/render/__init__.py +++ b/src/freshdata/render/__init__.py @@ -9,7 +9,8 @@ ``freshdata-cleaner[viz]`` / ``freshdata-cleaner[notebook]`` extras (itables, plotly, great-tables, anywidget) merely *upgrade* the output when installed. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/semantic/__init__.py b/src/freshdata/semantic/__init__.py index b9aaccaa..309b76ea 100644 --- a/src/freshdata/semantic/__init__.py +++ b/src/freshdata/semantic/__init__.py @@ -19,7 +19,8 @@ redaction (``semantic_privacy_policy``) before any future external inference. - proposals project cleanly to OpenLineage / quality-ops events. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations diff --git a/src/freshdata/steps/__init__.py b/src/freshdata/steps/__init__.py index 95a398f8..868e4e91 100644 --- a/src/freshdata/steps/__init__.py +++ b/src/freshdata/steps/__init__.py @@ -6,5 +6,6 @@ frame it owns, and steps only ever rebind whole columns or produce new frames (``.loc`` row selection), never write into shared blocks in place. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ diff --git a/src/freshdata/streaming/__init__.py b/src/freshdata/streaming/__init__.py index 5de0a355..214ad5e3 100644 --- a/src/freshdata/streaming/__init__.py +++ b/src/freshdata/streaming/__init__.py @@ -11,7 +11,8 @@ reservoir-sampled medians, Space-Saving top-k categories), so memory stays flat whether you feed it 100k rows or 100M. See :class:`StreamingCleaner`. -See ``ARCHITECTURE.md`` for how this package fits into the overall cleaning flow. +See `ARCHITECTURE.md `_ +for how this package fits into the overall cleaning flow. """ from __future__ import annotations