howso-engine 65.2.1__tar.gz → 65.3.0__tar.gz

{howso_engine-65.2.1/howso_engine.egg-info → howso_engine-65.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howso-engine
-Version: 65.2.1
+Version: 65.3.0
 Summary: The Howso Engine™ is a natively and fully explainable ML engine, serving as an alternative to black box AI neural networks.
 Author: Howso Incorporated
 Author-email: support@howso.com

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/__init__.py

@@ -34,7 +34,9 @@ from howso.utilities.progress import (
     disable_auto_progress,
     enable_auto_progress,
     engine_polling_supported,
+    print_status,
     reset_auto_progress,
+    status_console,
     with_progress,
 )
 from howso.utilities.tokenizing import (
@@ -137,6 +139,7 @@ __all__ = [
     "lazy_map",
     "matrix_processing",
     "num_list_dimensions",
+    "print_status",
     "replace_doublemax_with_infinity",
     "replace_nan_with_none",
     "replace_none_with_nan",
@@ -145,6 +148,7 @@ __all__ = [
     "seconds_to_time",
     "serialize_cases",
     "serialize_datetimes",
+    "status_console",
     "stringify_json",
     "time_to_seconds",
     "validate_case_indices",

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/abstract_data.py

@@ -91,11 +91,7 @@ class InferFeatureAttributesAbstractData(InferFeatureAttributesBase):
         feature_attributes = self._process(**kwargs)
 
         self.warnings_collector.emit_all()
-
-        if self.suggestions_collector.suggestions:
-            warnings.warn("You have one or more suggestions to consider for your feature attributes "
-                          "configuration. Please view them by printing the `suggestions` property of your "
-                          "returned feature attributes object (`your_attributes_object.suggestions`).")
+        self._emit_summary()
 
         return SingleTableFeatureAttributes(
             feature_attributes, params=kwargs,

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/base.py

@@ -810,6 +810,26 @@ class InferFeatureAttributesBase(ABC):
     warnings_collector: IFAWarningCollector = IFAWarningCollector()
     suggestions_collector: IFASuggestionCollector = IFASuggestionCollector()
 
+    _summarize: bool = True
+    """
+    Whether :meth:`_emit_summary` prints anything.
+
+    An inferrer that delegates to another — time series wraps the DataFrame or
+    AbstractData inferrer — turns this off on the inner instance so the summary
+    is printed once, by the outermost call, after every suggestion has been
+    collected.
+    """
+
+    def _emit_summary(self) -> None:
+        """
+        Print the feature attributes summary, once inference has completed.
+
+        Nothing is printed when there are no suggestions, so a clean run stays
+        silent, and nothing is printed when :attr:`_summarize` is off.
+        """
+        if self._summarize and self.suggestions_collector.suggestions:
+            self.suggestions_collector.print_summary()
+
     def _process(self,
                  attempt_infer_extended_nominals: bool = False,
                  max_distilled_cases: int | None = None,

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/infer_feature_attributes.py

@@ -101,7 +101,8 @@ def infer_feature_attributes(
     of what was inferred and so that any inaccuracies can be corrected before data ingestion. This method makes a best
     guess at the feature attributes and in some cases may not automatically set certain attributes if there is
     ambiguity, instead providing suggestions for further consideration which can be reviewed by accessing the
-    :attr:`~howso.utilities.feature_attributes.base.FeatureAttributesBase.suggestions` attribute.
+    :attr:`~howso.utilities.feature_attributes.base.FeatureAttributesBase.suggestions` attribute. When any
+    suggestions were produced, a short summary of what was found is printed once inference completes.
 
     Parameters
     ----------

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/pandas.py

@@ -91,9 +91,6 @@ class InferFeatureAttributesDataFrame(InferFeatureAttributesBase):
         if prod(self.data.shape) < 25_000_000 and max_workers is None:
             max_workers = 0
 
-        suggestion_warning = ("You have one or more suggestions to consider for your feature attributes "
-                              "configuration. Please view them by printing the `suggestions` property of your "
-                              "returned feature attributes object (`your_attributes_object.suggestions`).")
         if max_workers is None or max_workers >= 1:
             mp_context = mp.get_context("spawn")
             futures: dict[Future, str] = dict()
@@ -130,8 +127,7 @@ class InferFeatureAttributesDataFrame(InferFeatureAttributesBase):
             for collector in processed_suggestions:
                 self.suggestions_collector.merge(collector)
 
-            if self.suggestions_collector.suggestions:
-                warnings.warn(suggestion_warning, UserWarning)
+            self._emit_summary()
 
             return SingleTableFeatureAttributes(
                 feature_attributes=feature_attributes, params=kwargs,
@@ -141,8 +137,7 @@ class InferFeatureAttributesDataFrame(InferFeatureAttributesBase):
         else:
             feature_attributes = self._process(**kwargs)
             self.warnings_collector.emit_all()
-            if self.suggestions_collector.suggestions:
-                warnings.warn(suggestion_warning, UserWarning)
+            self._emit_summary()
             return SingleTableFeatureAttributes(
                 feature_attributes, params=kwargs,
                 unsupported=self.unsupported,

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/suggestions.py

@@ -9,6 +9,8 @@ import warnings
 from rich.console import Console
 from rich.table import Table
 
+from howso.utilities.progress import print_status
+
 if TYPE_CHECKING:
     from howso.client.typing import FullPreserveRareValuesConfig, PreserveRareValuesMap
 
@@ -26,6 +28,12 @@ def wrap_text(text: str, width: int) -> str:
     )) or text
 
 
+def _count(value: int, singular: str, plural: str | None = None) -> str:
+    """Render ``value`` with the correctly pluralized noun, e.g. ``"1 key"`` or ``"3 keys"``."""
+    noun = singular if value == 1 else (plural or f"{singular}s")
+    return f"{value:,} {noun}"
+
+
 def wrap_paragraphs(text: str, width: int) -> str:
     """Wrap text on newlines."""
     out = []
@@ -67,6 +75,16 @@ class IFASuggestion(ABC):
         """A brief description of the suggestion."""
         ...
 
+    @property
+    def summary(self) -> str:
+        """
+        A one-line statement of what was found, for the summary printed when inference completes.
+
+        Should read as a finding rather than an instruction, e.g. ``"Found 3 fan-out features
+        across 1 key"``. Defaults to :attr:`description` for suggestions that do not override it.
+        """
+        return self.description
+
     @abstractmethod
     def apply(self, attributes: dict) -> None:
         """Apply this suggestion to the FeatureAttributesBase object."""
@@ -173,6 +191,13 @@ class FanoutFeaturesSuggestion(IFASuggestion):
         """A brief description of this suggestion."""
         return "Configure fan-out features so that the Howso Engine can more accurately measure uncertainty."
 
+    @property
+    def summary(self) -> str:
+        """A one-line statement of the fan-out features found."""
+        num_features = sum(len(cols) for cols in self._fanout_features.values())
+        return (f"Found {_count(num_features, 'fan-out feature')} across "
+                f"{_count(len(self._fanout_features), 'column')}")
+
     def apply(self, attributes: dict) -> None:
         """Apply the computed fanout features config to the FeatureAttributesBase object."""
         for key_features, fanout_features in self._fanout_features.items():
@@ -310,6 +335,13 @@ class PRVSuggestion(IFASuggestion):
         """A brief description of this suggestion."""
         return "Configure rare values to avoid losing their signal during data distillation."
 
+    @property
+    def summary(self) -> str:
+        """A one-line statement of the rare values found."""
+        num_values = sum(len(cfg["protected_values_multipliers"]) for cfg in self._prvc.values())
+        return (f"Found {_count(num_values, 'rare value')} across {_count(len(self._prvc), 'column')} "
+                "whose signal may be lost during data distillation workflows")
+
     def apply(self, attributes: dict) -> None:
         """Apply the computed rare values preservation config to the FeatureAttributesBase object."""
         if not self._user_set_mdc:
@@ -420,6 +452,46 @@ class IFASuggestionCollector:
         """Get all suggestions that belong to this collector."""
         return self._suggestions
 
+    def summary_lines(self, *, attributes_name: str = "your_attributes_object") -> list[str]:
+        """
+        Render the summary block as lines of console markup.
+
+        The block is styled to sit beside the progress output from
+        :mod:`howso.utilities.progress`: a bold cyan header, the way a progress
+        label is styled, one dim-bulleted finding per suggestion, indented the
+        way progress lines are, and a dim footer pointing at the suggestions.
+
+        Parameters
+        ----------
+        attributes_name : str, default "your_attributes_object"
+            How to refer to the returned feature attributes object in the footer.
+
+        Returns
+        -------
+        list of str
+            One entry per line, or an empty list when there are no suggestions.
+        """
+        if not self._suggestions:
+            return []
+        lines = ["[bold cyan]Feature Attributes Summary[/bold cyan]"]
+        lines.extend(f"  [dim]\u00b7[/dim] {suggestion.summary}" for suggestion in self._suggestions.values())
+        lines.append(f"  [dim]Inspect `{attributes_name}.suggestions` for details and how to apply them.[/dim]")
+        return lines
+
+    def print_summary(self, *, console: Console | None = None) -> None:
+        """
+        Print the summary of collected suggestions, when there are any.
+
+        Parameters
+        ----------
+        console : Console, optional
+            Console to print to. Defaults to the one :func:`howso.utilities.progress.status_console`
+            selects for the current environment.
+        """
+        lines = self.summary_lines()
+        if lines:
+            print_status(*lines, console=console)
+
     def append(self, suggestion: IFASuggestion) -> None:
         """Append a new IFASuggestion to this collector."""
         if suggestion.name in self._suggestions:

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/feature_attributes/time_series.py

@@ -761,6 +761,9 @@ class InferFeatureAttributesTimeSeries(ABC):
                 time_invariant_features.append(id_feature)
 
         infer._time_invariant_features = time_invariant_features
+        # The summary is printed once, from this object's ``__call__``, after the
+        # inner suggestions have been propagated into this collector.
+        infer._summarize = False  # pyright: ignore[reportPrivateUsage]
 
         features = infer(
             attempt_infer_extended_nominals=attempt_infer_extended_nominals,
@@ -901,6 +904,9 @@ class InferFeatureAttributesTimeSeries(ABC):
         """Process and return feature attributes."""
         feature_attributes = self._process(**kwargs)
         self.warnings_collector.emit_all()
+        # Print the summary once, from here, now that the inner inferrer's
+        # suggestions have been propagated into this collector.
+        self.suggestions_collector.print_summary()
         # Put the time_feature_name back into the kwargs dictionary.
         kwargs["time_feature_name"] = self.time_feature_name
         return SingleTableFeatureAttributes(

{howso_engine-65.2.1 → howso_engine-65.3.0}/howso/utilities/progress.py

@@ -75,7 +75,9 @@ __all__ = [
     "disable_auto_progress",
     "enable_auto_progress",
     "engine_polling_supported",
+    "print_status",
     "reset_auto_progress",
+    "status_console",
     "with_progress",
 ]
 
@@ -306,21 +308,7 @@ class BaseProgressReporter:
         -------
         None
         """
-        streams = (
-            self._console.file,
-            sys.stdout,
-            sys.stderr,
-            sys.__stdout__,
-            sys.__stderr__,
-        )
-        seen: set[int] = set()
-        for stream in streams:
-            flush = getattr(stream, "flush", None)
-            if flush is None or id(stream) in seen:
-                continue
-            seen.add(id(stream))
-            with suppress(Exception):
-                flush()
+        _flush_streams(self._console.file)
 
 
 class RichProgressReporter(BaseProgressReporter):
@@ -1768,6 +1756,109 @@ def auto_reporter(*, console: Console | None = None) -> ProgressReporter:
     return SimpleProgressReporter(console=console)
 
 
+def status_console(console: Console | None = None) -> Console:
+    """
+    Build the console a one-off status line should print to.
+
+    A status line — a summary printed once a call has finished — has to land
+    where a progress bar would have, and look the way the bar's completion line
+    looks, whichever front-end is reading. So this follows the same selection
+    :func:`auto_reporter` makes, but stops at the console: a stock console for
+    a tty, the kernel-safe console of :func:`_notebook_console` for a notebook
+    that would get a rich reporter, and a stdout-only console for everything
+    else — including a forced ``HOWSO_SIMPLE_PROGRESS``, which prints plain
+    lines and so should have its summaries print plain too.
+
+    Parameters
+    ----------
+    console : Console, optional
+        A console to use instead. Returned as-is, so a caller who already
+        holds one — a reporter, a test — can route a status line through it.
+
+    Returns
+    -------
+    Console
+        The console to print the status line to.
+    """
+    if console is not None:
+        return console
+    if _parse_tristate(os.environ.get("HOWSO_SIMPLE_PROGRESS")) is True:
+        return Console(force_jupyter=False)
+    if sys.stdout.isatty():
+        return Console()
+    if _in_notebook() and (_display_handle_available() or _interactive_frontend()):
+        return _notebook_console()
+    # ``force_jupyter=False`` keeps the output on stdout rather than in a
+    # separate ``IPython.display`` block; see SimpleProgressReporter.
+    return Console(force_jupyter=False)
+
+
+def print_status(*lines: str, console: Console | None = None) -> None:
+    """
+    Print one or more lines of console markup as a status block.
+
+    This is the static counterpart of a reporter's completion line: the same
+    console selection as :func:`status_console`, and the same flush discipline
+    as a progress session. Every stream is drained before the block so that
+    anything already buffered — a warning on ``stderr``, a ``print`` from the
+    call that just returned — lands *above* it rather than through it, and
+    drained again afterwards so the block itself is out before whatever the
+    caller does next.
+
+    Parameters
+    ----------
+    *lines : str
+        Console markup, one entry per line. Empty entries print blank lines.
+        Lines are never hard-wrapped by rich: a line longer than the console
+        is left to the terminal, which wraps it without the bare, unindented
+        continuation rich would otherwise produce.
+    console : Console, optional
+        Console to print to. Defaults to :func:`status_console`.
+
+    Returns
+    -------
+    None
+    """
+    target = status_console(console)
+    _flush_streams(target.file)
+    for line in lines:
+        target.print(line, soft_wrap=True)
+    _flush_streams(target.file)
+
+
+def _flush_streams(*streams: Any) -> None:
+    """
+    Drain the given streams along with every standard stream.
+
+    Streams are deduplicated by identity (a console's file is normally
+    ``sys.stdout`` itself) and flushed newest-wrapper-first, so a stack such
+    as ipykernel's ``OutStream`` over the real ``stdout`` drains in order.
+    Every flush is individually guarded: a closed, detached, or replaced
+    stream — pytest's captured ``stdout``, a torn-down notebook kernel — must
+    not take down the caller.
+
+    Note that this reaches only Python-level buffers.
+
+    Parameters
+    ----------
+    *streams : Any
+        Streams to drain ahead of ``sys.stdout``, ``sys.stderr`` and their
+        originals.
+
+    Returns
+    -------
+    None
+    """
+    seen: set[int] = set()
+    for stream in (*streams, sys.stdout, sys.stderr, sys.__stdout__, sys.__stderr__):
+        flush = getattr(stream, "flush", None)
+        if flush is None or id(stream) in seen:
+            continue
+        seen.add(id(stream))
+        with suppress(Exception):
+            flush()
+
+
 def _supports_param(bound_func: Callable[..., Any], name: str) -> bool:
     """
     Report whether ``bound_func`` accepts a parameter called ``name``.

{howso_engine-65.2.1 → howso_engine-65.3.0/howso_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howso-engine
-Version: 65.2.1
+Version: 65.3.0
 Summary: The Howso Engine™ is a natively and fully explainable ML engine, serving as an alternative to black box AI neural networks.
 Author: Howso Incorporated
 Author-email: support@howso.com