potatopt 1.6.0__py3-none-any.whl

potatopt/__init__.py

@@ -0,0 +1,227 @@
+# ==============================================================================
+# PotatOpt: Universal Potato-Optimized Industrial AI Engine (OOP Architecture)
+# Designed for Low-Resource, CPU-Friendly Machine Learning & Smart Manufacturing
+# ==============================================================================
+"""
+PotatOpt is a zero-code, production-grade Machine Learning engine designed 
+specifically for Industrial Engineering (IE) and Smart Factory environments.
+
+Key Architecture Principles:
+----------------------------
+1. LowSpecML (Potato Hardware First):
+   Minimizes RAM and CPU overhead using lossless numerical downcasting and 
+   ordinal encoding instead of memory-heavy one-hot matrices.
+
+2. Production Guardrails:
+   Automatically detects extreme class imbalance and seamlessly transitions 
+   to unsupervised Anomaly Detection (Isolation Forest) when defects are too rare (< 5 samples).
+
+3. Zero Data Leakage:
+   Strictly learns statistical boundaries, imputations, and encodings during `fit()`, 
+   and applies them idempotently during `transform()` inference.
+
+4. Industrial Financial Layer:
+   Integrates Cost of Quality (CoQ) equations directly into threshold tuning, 
+   maximizing ROI by balancing scrap costs against false-alarm inspection labor.
+
+5. ISO 9001 Traceability:
+   Serializes each model alongside a SHA-256 integrity hash and a metadata
+   sidecar, so a deployed file can be shown to be the file that was released.
+   That is an integrity record, not a signature - it detects a corrupted or
+   swapped file but cannot prove who produced one. See `PotatOptEngine.save()`.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.6.0"
+
+from typing import Any
+
+# The redundant `x as x` form marks a deliberate re-export rather than an unused
+# import. These four are private, so they cannot be declared in __all__, but the
+# test suite reaches for them through the package object and they have to resolve.
+from ._lazy import _load_automl as _load_automl
+from ._lazy import _load_shap as _load_shap
+from ._lazy import _quiet_dependency_warnings as _quiet_dependency_warnings
+from ._lazy import logger
+from ._utils import (
+    enable_audit_log,
+    get_library_versions,
+    to_jsonable,
+)
+from .analysis import (
+    auto_analyze,
+    run_seed_sweep,
+)
+from .calibration import (
+    check_calibration,
+)
+from .constants import (
+    AUTOCORRELATION_WARN,
+    CALIBRATION_DEFAULT_BINS,
+    CALIBRATION_ECE_LIMIT,
+    CAPABILITY_OUTLIER_RATE_LIMIT,
+    CAPABILITY_SIGMA_RATIO_LIMIT,
+    CONTROL_RULE_DESCRIPTIONS,
+    CONTROL_RULES_NELSON,
+    CONTROL_RULES_WESTERN_ELECTRIC,
+    CUSUM_DEFAULT_DECISION,
+    CUSUM_DEFAULT_SLACK,
+    DEFAULT_RANDOM_STATE,
+    DQS_PRODUCTION_READY,
+    DQS_USABLE,
+    DQS_WEIGHTS,
+    DRIFT_MIN_ROWS,
+    DRIFT_NOISE_SIGMAS,
+    EWMA_DEFAULT_LAMBDA,
+    EWMA_DEFAULT_SIGMAS,
+    MIN_TRAIN_ROWS,
+    MISSING_SCHEMA_WARN_RATIO,
+    MODIFIED_ZSCORE_THRESHOLD,
+    MOVING_RANGE_D2,
+    NUMERIC_SENTINELS,
+    OEE_WORLD_CLASS,
+    OUT_OF_BOUNDS_WARN_RATIO,
+    PARETO_CUTOFF,
+    PSI_DEFAULT_BINS,
+    PSI_MAJOR_SHIFT,
+    PSI_MAX_CATEGORIES,
+    PSI_MODERATE_SHIFT,
+    SEED_SWEEP_DEFAULT,
+    SILENT_NULL_TOKENS,
+)
+from .data import (
+    audit_data_quality,
+    calculate_correlations,
+    detect_outliers,
+    detect_silent_nulls,
+    inspect_data,
+    split_data,
+    split_data_three_way,
+)
+from .drift import (
+    calculate_categorical_psi,
+    calculate_psi,
+    check_asset_drift,
+    check_data_drift,
+)
+from .engine import (
+    PotatOpt,
+    PotatOptEngine,
+)
+from .quality import (
+    calculate_capability,
+    calculate_gauge_rr,
+)
+from .reliability import (
+    calculate_availability,
+    calculate_maintenance_savings,
+    calculate_mtbf,
+    calculate_mttr,
+    calculate_oee,
+    calculate_pareto,
+    wilson_confidence_interval,
+)
+from .spc import _lag1_autocorrelation as _lag1_autocorrelation
+from .spc import (
+    calculate_control_rules,
+    calculate_cusum_chart,
+    calculate_ewma_chart,
+    calculate_spc_limits,
+)
+
+
+def __getattr__(name: str) -> Any:
+    """
+    PEP 562 module-level attribute access.
+
+    Keeps `potatopt.AutoML` and `potatopt.shap` resolvable for callers and tests
+    that reach for them directly; they simply trigger the import on first touch
+    instead of at module load.
+    """
+    if name == "AutoML":
+        return _load_automl()
+    if name == "shap":
+        return _load_shap()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# The supported public surface. Everything not listed here is an implementation
+# detail and may change without notice - including the third-party modules this
+# file imports, which would otherwise leak out as `potatopt.np`, `potatopt.shap`
+# and so on.
+__all__ = [  # noqa: RUF022
+    # Engine
+    "PotatOptEngine",
+    "PotatOpt",
+    # Data inspection, calibration and splitting
+    "inspect_data",
+    "calculate_correlations",
+    "split_data",
+    "split_data_three_way",
+    "auto_analyze",
+    "check_calibration",
+    "run_seed_sweep",
+    # Data quality
+    "audit_data_quality",
+    "detect_silent_nulls",
+    "detect_outliers",
+    # Statistical process control and drift
+    "calculate_spc_limits",
+    "calculate_ewma_chart",
+    "calculate_cusum_chart",
+    "calculate_control_rules",
+    "calculate_capability",
+    "calculate_gauge_rr",
+    "check_data_drift",
+    "check_asset_drift",
+    "calculate_psi",
+    "calculate_categorical_psi",
+    "wilson_confidence_interval",
+    "calculate_maintenance_savings",
+    # Reliability, availability and OEE
+    "calculate_mtbf",
+    "calculate_mttr",
+    "calculate_availability",
+    "calculate_oee",
+    "calculate_pareto",
+    # Interop and traceability
+    "to_jsonable",
+    "enable_audit_log",
+    "get_library_versions",
+    "logger",
+    "__version__",
+    # Tuning constants
+    "DEFAULT_RANDOM_STATE",
+    "SEED_SWEEP_DEFAULT",
+    "CALIBRATION_DEFAULT_BINS",
+    "CALIBRATION_ECE_LIMIT",
+    "CAPABILITY_SIGMA_RATIO_LIMIT",
+    "CAPABILITY_OUTLIER_RATE_LIMIT",
+    "MIN_TRAIN_ROWS",
+    "MISSING_SCHEMA_WARN_RATIO",
+    "OUT_OF_BOUNDS_WARN_RATIO",
+    "PSI_MODERATE_SHIFT",
+    "PSI_MAJOR_SHIFT",
+    "PSI_DEFAULT_BINS",
+    "PSI_MAX_CATEGORIES",
+    "DRIFT_MIN_ROWS",
+    "DRIFT_NOISE_SIGMAS",
+    "EWMA_DEFAULT_LAMBDA",
+    "EWMA_DEFAULT_SIGMAS",
+    "CUSUM_DEFAULT_SLACK",
+    "CUSUM_DEFAULT_DECISION",
+    "MOVING_RANGE_D2",
+    "AUTOCORRELATION_WARN",
+    "CONTROL_RULES_WESTERN_ELECTRIC",
+    "CONTROL_RULES_NELSON",
+    "CONTROL_RULE_DESCRIPTIONS",
+    "DQS_WEIGHTS",
+    "DQS_PRODUCTION_READY",
+    "DQS_USABLE",
+    "SILENT_NULL_TOKENS",
+    "NUMERIC_SENTINELS",
+    "MODIFIED_ZSCORE_THRESHOLD",
+    "PARETO_CUTOFF",
+    "OEE_WORLD_CLASS",
+]

potatopt/_lazy.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import contextlib  # contextmanager for _quiet_dependency_warnings() - scoped, not global, suppression
+import logging  # the "potatopt" audit logger every guardrail/warning flows through
+import warnings  # scoped suppression of third-party noise; see _quiet_dependency_warnings()
+from collections.abc import Iterator  # return annotation for the context manager below
+
+
+@contextlib.contextmanager
+def _quiet_dependency_warnings() -> Iterator[None]:
+    """
+    Silence third-party warning noise for the duration of ONE call into a dependency.
+
+    This module used to call `warnings.filterwarnings("ignore")` at import time. That
+    is a process-global mutation: merely writing `import potatopt` switched off every
+    warning in the importing application, including warnings raised by the caller's
+    own code, for the rest of the run. A library has no business doing that, so the
+    suppression now wraps only the specific calls that are noisy - FLAML's search and
+    SHAP's explainers - and the caller's filters are restored on the way out.
+
+    Known caveat: Python's warning filters are global to the process, not to the
+    thread, so while this block is open another thread's warnings are suppressed too.
+    That is a narrow, bounded window and is accepted deliberately; the alternative it
+    replaced suppressed them permanently.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        yield
+
+
+# ------------------------------------------------------------------------------
+# Optional heavy backends, imported the first time they are actually needed.
+#
+# FLAML and SHAP together dominate both install size and import time, and neither
+# is touched unless you call fit() or ask for explanations. Keeping them out of
+# the module's import path is what lets the core install be numpy, pandas, scipy
+# and scikit-learn - the difference between a library that runs on low-spec
+# hardware and one that merely claims to.
+# ------------------------------------------------------------------------------
+
+def _load_automl():
+    """
+    Return FLAML's AutoML class, importing it on first use.
+
+    Cached into module globals so `potatopt.AutoML` and the class used inside
+    fit() are the same object - patching one patches the other.
+    """
+    automl = globals().get("AutoML")
+    if automl is None:
+        try:
+            from flaml import AutoML as _AutoML
+        except ImportError as exc:
+            raise ImportError(
+                "PotatOptEngine.fit() needs the FLAML AutoML backend, which is not installed. "
+                "Install it with:  pip install potatopt[automl]"
+            ) from exc
+        globals()["AutoML"] = _AutoML
+        automl = _AutoML
+    return automl
+
+
+def _load_shap():
+    """
+    Return the shap module, importing it on first use.
+
+    Cached into module globals for the same reason as _load_automl.
+    """
+    module = globals().get("shap")
+    if module is None:
+        try:
+            import shap as _shap
+        except ImportError as exc:
+            raise ImportError(
+                "get_shap_values() needs the SHAP explainability backend, which is not installed. "
+                "Install it with:  pip install potatopt[xai]"
+            ) from exc
+        globals()["shap"] = _shap
+        module = _shap
+    return module
+
+
+# ISO 9001 audit trail: all guardrail events flow through one named logger so
+# they can be silenced, redirected, or persisted to a file by the operator.
+logger = logging.getLogger("potatopt")
+
+logger.setLevel(logging.INFO)
+if not logger.handlers:
+    _console_handler = logging.StreamHandler()
+    _console_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+    logger.addHandler(_console_handler)

potatopt/_utils.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import logging  # the "potatopt" audit logger every guardrail/warning flows through
+import os  # path handling in enable_audit_log
+from datetime import datetime  # UTC timestamps in to_jsonable
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import (
+    version as pkg_version,  # get_library_versions() ISO 9001 traceability record
+)
+from typing import Any  # loose return-type annotations for JSON-shaped dicts
+
+import numpy as np  # arrays + math for downcasting, NaN/finite checks in to_jsonable and _finite_float
+import pandas as pd  # DataFrame/Series is the data contract for every public function
+
+from ._lazy import logger
+
+
+def _is_numeric_series(series: pd.Series) -> bool:
+    """
+    np.issubdtype only understands numpy dtypes and raises TypeError on a pandas
+    extension dtype such as CategoricalDtype, so every dtype test in this module
+    goes through pandas' own predicate instead. A category column is categorical
+    whatever its categories hold, which is the answer this code wants anyway.
+    """
+    return bool(pd.api.types.is_numeric_dtype(series))
+
+
+def _finite_float(value: Any, name: str) -> tuple[float | None, str | None]:
+    """
+    Coerce a control-chart parameter to a finite float.
+
+    Returns `(value, None)` on success or `(None, message)` on failure, so the
+    caller can hand the message back in an error dict instead of raising - the
+    contract both chart functions document.
+
+    NaN and infinity are rejected explicitly because they slip past ordinary
+    comparisons: every comparison against NaN is False, so a plain `<= 0` guard
+    lets it through, and it then propagates silently into the limits.
+    """
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None, f"{name} must be a number, got {value!r}."
+    if not np.isfinite(number):
+        return None, f"{name} must be a finite number, got {value!r}."
+    return number, None
+
+
+def _require_frame(df: Any, name: str, columns: tuple[str, ...]) -> str | None:
+    """
+    Return an error sentence if `df` is unusable, otherwise None.
+
+    Shared by the reliability metrics so a missing column reports which columns
+    the frame actually has - the same courtesy `auto_analyze` extends when the
+    target column is wrong, and the difference between a caller who can fix the
+    call and one who has to guess.
+    """
+    if df is None or not isinstance(df, pd.DataFrame):
+        return f"{name} must be a pandas DataFrame."
+    if df.empty:
+        return f"{name} is empty."
+    missing = [c for c in columns if c not in df.columns]
+    if missing:
+        return f"{name} is missing column(s) {missing}. Columns present: {list(df.columns)}."
+    return None
+
+
+def enable_audit_log(filepath: str = "potatopt_audit.log", level: int = logging.INFO) -> str | None:
+    """
+    Persist every guardrail and drift event to a timestamped log file.
+    Required for ISO 9001 traceability: the operator must be able to prove
+    afterwards which production batches triggered a warning and when.
+    """
+    try:
+        abs_path = os.path.abspath(filepath)
+        for handler in logger.handlers:
+            if isinstance(handler, logging.FileHandler) and getattr(handler, "baseFilename", None) == abs_path:
+                return abs_path
+
+        parent_dir = os.path.dirname(abs_path)
+        if parent_dir:
+            os.makedirs(parent_dir, exist_ok=True)
+
+        file_handler = logging.FileHandler(abs_path, encoding="utf-8")
+        file_handler.setFormatter(logging.Formatter("%(asctime)s | %(levelname)s | %(message)s"))
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+        return abs_path
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def get_library_versions() -> dict[str, Any]:
+    """
+    Collect installed versions of the runtime stack for ISO 9001 reproducibility.
+    """
+    names = ["numpy", "pandas", "scipy", "scikit-learn", "flaml", "lightgbm", "xgboost", "shap", "joblib"]
+    versions = {}
+    for name in names:
+        try:
+            versions[name] = pkg_version(name)
+        except (PackageNotFoundError, ValueError, TypeError):
+            versions[name] = None
+    return versions
+
+
+def to_jsonable(value: Any) -> Any:
+    """
+    Convert NumPy / pandas output into plain Python that `json.dumps` accepts.
+
+    Written for the tool-call boundary: an MCP server, a REST endpoint, or a
+    dashboard all need the engine's output as ordinary dicts, lists, numbers and
+    strings. Every stateless utility in this module already returns JSON-clean
+    dicts; this covers the remaining cases - `predict()` returns an ndarray,
+    `get_feature_importance()` returns a DataFrame - without changing either
+    method's contract.
+
+    NaN and Infinity become None rather than passing through, because
+    `json.dumps` would otherwise emit the bare tokens `NaN` / `Infinity`, which
+    are not valid JSON and are rejected by strict parsers such as
+    JavaScript's `JSON.parse`.
+
+    Anything it does not recognise is rendered with `str()` rather than raising,
+    so a serialisation boundary never brings down a request.
+
+    Returns:
+    --------
+    A structure built only from dict, list, str, int, float, bool and None.
+    """
+    if value is None or isinstance(value, (str, bool)):
+        return value
+
+    if isinstance(value, (np.bool_,)):
+        return bool(value)
+
+    if isinstance(value, (int, np.integer)):
+        return int(value)
+
+    if isinstance(value, (float, np.floating)):
+        as_float = float(value)
+        # NaN/Inf are not representable in JSON.
+        return as_float if np.isfinite(as_float) else None
+
+    if isinstance(value, (datetime,)):
+        return value.isoformat()
+
+    if isinstance(value, pd.DataFrame):
+        return [to_jsonable(record) for record in value.to_dict(orient="records")]
+
+    if isinstance(value, (pd.Series, pd.Index)):
+        return [to_jsonable(item) for item in value.tolist()]
+
+    if isinstance(value, np.ndarray):
+        return [to_jsonable(item) for item in value.tolist()]
+
+    if isinstance(value, dict):
+        return {str(key): to_jsonable(item) for key, item in value.items()}
+
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [to_jsonable(item) for item in value]
+
+    return str(value)