p2predict 1.1.1__tar.gz → 1.2.0__tar.gz

{p2predict-1.1.1/src/p2predict.egg-info → p2predict-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: p2predict
-Version: 1.1.1
+Version: 1.2.0
 Summary: Parametric price benchmarking for engineering and procurement trade-offs. Agentic first, runs on your data, stays on your machine.
 Author: Ahmed Khalil Hafsi
 License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0-with-Internal-Use-Exception
@@ -263,6 +263,10 @@ P2Predict comes out of that work: the tools a procurement team actually needs to
 - **Set it up with your agent:** see **[INSTALL.md](INSTALL.md)** to install, connect your AI assistant, and point it at your data.
 - **How it works under the hood:** the models, the math, the full reference live in **[TECHNICAL.md](TECHNICAL.md)**.
 
+## Related
+
+**[P2CLPFD](https://github.com/ahmed-khalil-hafsi/P2CLPFD)** — the companion tool for the decision that comes next. P2Predict tells you what a part *should* cost; P2CLPFD decides *who gets the volume*: the lowest-TCO award across your suppliers under capacity, MOQ, share caps, dual-sourcing, and volume-discount rules, with the reasoning you can show in the room. Open source under the GPLv3. More at **[ahmedhafsi.com/p2clpfd](https://ahmedhafsi.com/p2clpfd/)**.
+
 ## Licensing
 
 Source-available under the [PolyForm Noncommercial License 1.0.0, with an additional grant of permission for internal company use](LICENSE).

{p2predict-1.1.1 → p2predict-1.2.0}/README.md

@@ -215,6 +215,10 @@ P2Predict comes out of that work: the tools a procurement team actually needs to
 - **Set it up with your agent:** see **[INSTALL.md](INSTALL.md)** to install, connect your AI assistant, and point it at your data.
 - **How it works under the hood:** the models, the math, the full reference live in **[TECHNICAL.md](TECHNICAL.md)**.
 
+## Related
+
+**[P2CLPFD](https://github.com/ahmed-khalil-hafsi/P2CLPFD)** — the companion tool for the decision that comes next. P2Predict tells you what a part *should* cost; P2CLPFD decides *who gets the volume*: the lowest-TCO award across your suppliers under capacity, MOQ, share caps, dual-sourcing, and volume-discount rules, with the reasoning you can show in the room. Open source under the GPLv3. More at **[ahmedhafsi.com/p2clpfd](https://ahmedhafsi.com/p2clpfd/)**.
+
 ## Licensing
 
 Source-available under the [PolyForm Noncommercial License 1.0.0, with an additional grant of permission for internal company use](LICENSE).

{p2predict-1.1.1 → p2predict-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "p2predict"
-version = "1.1.1"
+version = "1.2.0"
 description = "Parametric price benchmarking for engineering and procurement trade-offs. Agentic first, runs on your data, stays on your machine."
 readme = "README.md"
 license = "LicenseRef-PolyForm-Noncommercial-1.0.0-with-Internal-Use-Exception"

{p2predict-1.1.1 → p2predict-1.2.0}/src/p2predict/cli/train.py

@@ -34,6 +34,9 @@ from p2predict.outliers import (
     apply_outlier_policy,
 )
 from p2predict.feature_selection import (
+    FeatureChoiceError,
+    choose_training_features,
+    find_auto_exclusions,
     find_high_variation_features,
     find_no_variation_features,
     get_most_predictable_features,
@@ -126,6 +129,10 @@ def _feature_outlier_summary_block(summary: dict) -> dict:
                    "Default 6 preserves prior behaviour. Pass a higher number (or use -tf to pick "
                    "features explicitly) when ranking suggests more columns are predictive. "
                    "Ignored in expert mode (the user selects features interactively or via -tf).")
+@click.option("--allow-leaky-features", is_flag=True, default=False,
+              help="Train on a -tf column even though it looks like target leakage "
+                   "(a near-duplicate of the price, e.g. the price at another "
+                   "quantity break). Without this, such a column aborts training.")
 @click.option("--tune/--no-tune", default=None,
               help="Expert mode only: run HPO on the chosen algorithm and save the tuned model.")
 @click.option("--outliers", type=click.Choice(list(OUTLIER_POLICIES)), default="warn",
@@ -162,7 +169,7 @@ def _feature_outlier_summary_block(summary: dict) -> dict:
                    "Rich-formatted output. Useful for agents and scripts. "
                    "See p2predict.json_output for the schema.")
 def train(input, target, expert, algorithm, verbose, interactive, training_features,
-          budget, max_features, tune, outliers, feature_outliers, time_column,
+          budget, max_features, allow_leaky_features, tune, outliers, feature_outliers, time_column,
           log_target_mode, report, json_mode):
 
     # Redirect Rich to /dev/null under --json so any console.print that
@@ -337,6 +344,7 @@ def train(input, target, expert, algorithm, verbose, interactive, training_featu
     feature_data = data.drop(columns=[time_column]) if time_column else data
     high_vars = find_high_variation_features(feature_data)
     low_vars = find_no_variation_features(feature_data)
+    exclusions = find_auto_exclusions(feature_data, target)
 
     if not json_mode:
         print("")
@@ -345,55 +353,87 @@ def train(input, target, expert, algorithm, verbose, interactive, training_featu
         console.print(f"High variation (potentially noisy): {high_vars}")
         print("")
 
-    if interactive and (low_vars or high_vars):
-        to_remove = questionary.checkbox(
-            "Which features would you like to remove? ", choices=low_vars + high_vars
-        ).ask()
-        if to_remove:
+    # Interactive: show the same columns auto-mode would leave out, pre-ticked
+    # with the reason, plus wide-ranging numeric columns (usually real specs)
+    # unticked. The user's final choice replaces the automatic screen.
+    auto_exclude = True
+    if interactive:
+        excluded_names = {e["column"] for e in exclusions}
+        choices = [
+            questionary.Choice(f"{e['column']} — {e['reason']}", value=e["column"], checked=True)
+            for e in exclusions
+        ] + [
+            questionary.Choice(f"{c} — varies a lot, but numeric specs often do", value=c)
+            for c in high_vars
+            if c != target and c not in excluded_names
+        ]
+        if choices:
+            to_remove = questionary.checkbox(
+                "Which features would you like to remove? ", choices=choices
+            ).ask() or []
             data = data.drop(to_remove, axis=1)
-    elif low_vars:
-        data = data.drop(low_vars, axis=1)
+            auto_exclude = False
 
     feature_data = data.drop(columns=[time_column]) if time_column else data
 
-    if not training_features:
-        if expert:
-            best_features_ranked = get_most_predictable_features(feature_data, target)
-            if not json_mode:
-                console.print("Best features detected for prediction:", style="bold white")
-                print("")
-                print_dataframe(best_features_ranked)
-
-            options_list = [c for c in feature_data.columns.tolist() if c != target]
-            selected_columns = questionary.checkbox(
-                "Select the features for training: ", choices=options_list
-            ).ask()
-            if not selected_columns:
-                _abort(json_mode, console, "missing_features",
-                       "You must select training features.")
-        else:
-            ranked = get_most_predictable_features(feature_data, target, output_only_headers=True)
-            n_ranked = len(ranked)
-            cap = max(2, min(n_ranked, max_features))
-            selected_columns = ranked.head(cap).tolist()
-            if not json_mode:
-                console.print(
-                    f"Auto-selected features for training: {selected_columns}", style="bold blue"
-                )
-                if n_ranked > cap:
-                    console.print(
-                        f"Auto-selected {cap} of {n_ranked} features "
-                        f"(use --max-features to override or pass -tf).",
-                        style="italic",
-                    )
-                print("")
-    else:
+    requested = None
+    allow_leaky = allow_leaky_features
+    if training_features:
         requested = [c.strip() for c in training_features.split(",")]
-        missing = [c for c in requested if c not in data.columns]
-        if missing:
-            _abort(json_mode, console, "unknown_features",
-                   f"requested features not in CSV: {missing}")
-        selected_columns = requested
+    elif expert:
+        best_features_ranked = get_most_predictable_features(feature_data, target)
+        if not json_mode:
+            console.print("Best features detected for prediction:", style="bold white")
+            print("")
+            print_dataframe(best_features_ranked)
+
+        reasons = {e["column"]: e["reason"] for e in exclusions}
+        options = [
+            questionary.Choice(
+                f"{c} — not recommended: {reasons[c]}" if c in reasons else c, value=c
+            )
+            for c in feature_data.columns.tolist() if c != target
+        ]
+        requested = questionary.checkbox(
+            "Select the features for training: ", choices=options
+        ).ask()
+        if not requested:
+            _abort(json_mode, console, "missing_features",
+                   "You must select training features.")
+        # The list showed any leakage warning next to the column itself.
+        allow_leaky = True
+
+    # One chooser for every path (CLI auto, expert, -tf, and the MCP tools):
+    # auto-selection never picks a leakage, ID-like or single-value column.
+    try:
+        choice = choose_training_features(
+            feature_data, target, requested, max_features=max_features,
+            allow_leaky=allow_leaky, auto_exclude=auto_exclude,
+        )
+    except FeatureChoiceError as e:
+        _abort(json_mode, console, e.code, str(e))
+    if choice.leaky_requested:
+        _abort(json_mode, console, "target_leakage",
+               "; ".join(f"'{d['feature']}' {d['reason']}" for d in choice.leaky_requested)
+               + " Remove it from -tf, or pass --allow-leaky-features to train on it anyway.")
+    for note in choice.notes:
+        warnings.append(note)
+        if not json_mode:
+            console.print(note, style="yellow")
+    selected_columns = choice.selected
+
+    if requested is None and not json_mode:
+        n_candidates = feature_data.shape[1] - 1 - len(choice.excluded)
+        console.print(
+            f"Auto-selected features for training: {selected_columns}", style="bold blue"
+        )
+        if n_candidates > len(selected_columns):
+            console.print(
+                f"Auto-selected {len(selected_columns)} of {n_candidates} features "
+                f"(use --max-features to override or pass -tf).",
+                style="italic",
+            )
+        print("")
 
     target_column = target
 
@@ -681,6 +721,7 @@ def train(input, target, expert, algorithm, verbose, interactive, training_featu
             "high_variation": list(high_vars),
         },
         "features_selected": list(selected_columns),
+        "excluded_features": list(choice.excluded),
         "algorithm_selected": algorithm,
         "log_target": bool(log_target),
         "log_target_decision": log_target_decision,

p2predict-1.2.0/src/p2predict/feature_selection.py

@@ -0,0 +1,285 @@
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.pipeline import Pipeline
+
+from p2predict.preprocessing import build_preprocessor
+
+
+def find_high_variation_features(df):
+    high_variation = []
+
+    numeric_df = df.select_dtypes(include=["int64", "float64", "int32", "float32"])
+    if not numeric_df.empty:
+        means = numeric_df.mean()
+        stds = numeric_df.std()
+        # Use |mean| and guard against ~0 to keep CV well-defined.
+        safe_means = means.abs().where(means.abs() > 1e-9)
+        cv = (stds / safe_means).dropna()
+        high_variation.extend(cv[cv > 1].index.tolist())
+
+    categorical_df = df.select_dtypes(include=["object", "bool", "category"])
+    if not categorical_df.empty:
+        unique_ratio = categorical_df.apply(lambda x: x.nunique() / max(len(x), 1))
+        high_variation.extend(unique_ratio[unique_ratio > 0.9].index.tolist())
+
+    return high_variation
+
+
+def find_no_variation_features(df):
+    unique_counts = df.nunique(dropna=False)
+    return unique_counts[unique_counts <= 1].index.tolist()
+
+
+def find_leaky_features(data, target_column, threshold=0.97):
+    """Flag features that look like an alternate form of the target (leakage).
+
+    A numeric feature whose absolute Pearson correlation with the target
+    exceeds ``threshold`` is almost certainly **target leakage** — a
+    near-duplicate of the answer (e.g. the same price at a different quantity
+    break, or a pre-rounded copy) rather than a genuine spec. Training on it
+    inflates every metric while producing a model that is useless on real
+    parts, because at prediction time you wouldn't have the leaked column
+    (or you'd already know the price).
+
+    Only numeric columns are screened — a categorical can't be a linear
+    duplicate of a numeric target — and the target column itself is never
+    returned.
+
+    Returns a list of ``{"feature", "correlation", "reason"}`` dicts sorted
+    by absolute correlation, descending. Empty when nothing looks leaky.
+    """
+    if target_column not in data.columns:
+        return []
+
+    y = pd.to_numeric(data[target_column], errors="coerce")
+    leaks = []
+    for col in data.columns:
+        if col == target_column:
+            continue
+        x = pd.to_numeric(data[col], errors="coerce")
+        pair = pd.concat([x, y], axis=1).dropna()
+        if len(pair) < 3 or pair.iloc[:, 0].nunique() < 2 or pair.iloc[:, 1].nunique() < 2:
+            continue
+        corr = pair.iloc[:, 0].corr(pair.iloc[:, 1])
+        if corr is not None and not pd.isna(corr) and abs(corr) >= threshold:
+            leaks.append({
+                "feature": col,
+                "correlation": round(float(corr), 4),
+                "reason": (
+                    f"correlates {corr:.2f} with the target '{target_column}' — "
+                    "almost certainly an alternate form of the value being "
+                    "predicted (e.g. a different quantity break), not a spec. "
+                    "Training on it makes the model look near-perfect but useless "
+                    "on real parts."
+                ),
+            })
+
+    leaks.sort(key=lambda d: abs(d["correlation"]), reverse=True)
+    return leaks
+
+
+def find_auto_exclusions(data, target_column):
+    """Columns automatic feature selection must never pick, each with a reason.
+
+    The single source of truth for what auto-mode leaves out, shared by the
+    headless CLI, the MCP ``train`` tool and ``propose_training_plan`` so the
+    same CSV yields the same specs on every path. Three kinds, in this order:
+
+    - ``leakage``: a numeric near-duplicate of the target (see
+      :func:`find_leaky_features`).
+    - ``id_like``: a text column where almost every row is unique (part
+      numbers, descriptions). A model can't learn a spec from it, and a new
+      part never shares its value, so it only adds noise. Numeric
+      high-variation columns are *not* excluded: a spec like weight can
+      legitimately span orders of magnitude.
+    - ``constant``: the same value in every row, so it carries no information.
+
+    Explicitly requested features are the caller's decision; this only
+    governs what auto-selection may pick. Returns a list of
+    ``{"column", "kind", "reason"}`` dicts.
+    """
+    excluded = []
+    leaky = find_leaky_features(data, target_column)
+    leaky_names = {d["feature"] for d in leaky}
+    for d in leaky:
+        excluded.append({"column": d["feature"], "kind": "leakage", "reason": d["reason"]})
+
+    for col in find_high_variation_features(data):
+        if (
+            col == target_column
+            or col in leaky_names
+            or pd.api.types.is_numeric_dtype(data[col])
+        ):
+            continue
+        excluded.append({
+            "column": col,
+            "kind": "id_like",
+            "reason": "Looks like an ID / free-text column (almost every row is "
+                      "unique), not a spec the model can learn from.",
+        })
+
+    for col in find_no_variation_features(data):
+        if col == target_column:
+            continue
+        excluded.append({
+            "column": col,
+            "kind": "constant",
+            "reason": "Same value in every row — carries no information.",
+        })
+    return excluded
+
+
+class FeatureChoiceError(ValueError):
+    """Feature selection can't proceed. ``code`` is the stable error code the
+    CLI's ``--json`` output and the MCP error payload report."""
+
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass
+class FeatureChoice:
+    selected: list
+    # Columns auto-mode left out, as returned by find_auto_exclusions.
+    excluded: list = field(default_factory=list)
+    # Plain-language notes on anything left out, for the caller's warnings.
+    notes: list = field(default_factory=list)
+    # Explicitly requested columns that look like target leakage, in the
+    # find_leaky_features format. Non-empty means the caller must stop and
+    # ask (or the user passed allow_leaky); `selected` is then the request.
+    leaky_requested: list = field(default_factory=list)
+
+
+def choose_training_features(
+    data, target_column, requested=None, *, max_features=6,
+    allow_leaky=False, auto_exclude=True,
+):
+    """Decide which columns to train on. Shared by every training path.
+
+    ``data`` holds the candidate columns plus the target (a time column, if
+    any, already removed). With ``requested`` (``-tf`` on the CLI, ``features``
+    over MCP) the user's list is used as given, except that single-value
+    columns are left out with a note, since they cannot move the price. A
+    requested leakage column is reported in ``leaky_requested`` unless
+    ``allow_leaky``. Without ``requested``, the top ``max_features`` columns
+    by random-forest importance are chosen after leaving out everything
+    :func:`find_auto_exclusions` flags. ``auto_exclude=False`` skips that
+    screen, for when the user already chose what to drop interactively.
+
+    Raises :class:`FeatureChoiceError` when nothing usable is left or a
+    requested column doesn't exist.
+    """
+    exclusions = find_auto_exclusions(data, target_column)
+
+    if requested:
+        requested = list(requested)
+        constant = {e["column"] for e in exclusions if e["kind"] == "constant"}
+        dropped = [c for c in requested if c in constant]
+        notes = [
+            f"Left out '{c}': same value in every row, so it carries no information."
+            for c in dropped
+        ]
+        requested = [c for c in requested if c not in constant]
+        missing = [c for c in requested if c not in data.columns]
+        if missing:
+            raise FeatureChoiceError(
+                "unknown_features", f"requested features not in CSV: {missing}"
+            )
+        if not requested:
+            raise FeatureChoiceError(
+                "missing_features",
+                "every requested feature has the same value in every row.",
+            )
+        leaky = [
+            d for d in find_leaky_features(data, target_column)
+            if d["feature"] in requested
+        ]
+        return FeatureChoice(
+            selected=requested,
+            notes=notes,
+            leaky_requested=[] if allow_leaky else leaky,
+        )
+
+    excluded = exclusions if auto_exclude else []
+    drop_all = [e["column"] for e in excluded]
+    candidates = data.drop(columns=drop_all)
+    if candidates.shape[1] < 2:  # the target alone
+        raise FeatureChoiceError(
+            "no_usable_features",
+            "no usable spec columns left after leaving out ID-like, "
+            "single-value and target-leakage columns: "
+            + "; ".join(f"{e['column']} ({e['reason']})" for e in excluded),
+        )
+    ranked = get_most_predictable_features(
+        candidates, target_column, output_only_headers=True
+    )
+    cap = max(2, min(len(ranked), max_features))
+    return FeatureChoice(
+        selected=ranked.head(cap).tolist(),
+        excluded=excluded,
+        notes=[f"Left out '{e['column']}': {e['reason']}" for e in excluded],
+    )
+
+
+def _column_types(X):
+    numerical_cols = X.select_dtypes(include=["int64", "float64", "int32", "float32"]).columns
+    categorical_cols = X.select_dtypes(include=["object", "bool", "category"]).columns
+    return numerical_cols, categorical_cols
+
+
+def get_most_predictable_features(data, target_column, output_only_headers=False):
+    X = data.drop(target_column, axis=1)
+    y = data[target_column]
+
+    numerical_cols, categorical_cols = _column_types(X)
+
+    preprocessor = build_preprocessor(numerical_cols, categorical_cols, model_family="tree")
+    model = RandomForestRegressor(random_state=0, n_jobs=-1)
+    pipeline = Pipeline(
+        steps=[("preprocessor", preprocessor), ("model", model)]
+    )
+    pipeline.fit(X, y)
+
+    # With OrdinalEncoder, each source column maps to a single transformed
+    # column — no expansion, no underscore-grouping needed.
+    raw_names = pipeline.named_steps["preprocessor"].get_feature_names_out()
+    importances = np.asarray(model.feature_importances_, dtype=float)
+
+    source_cols = list(X.columns)
+    by_source = {}
+    for name, imp in zip(raw_names, importances):
+        rest = name.split("__", 1)[1] if "__" in name else name
+        match = None
+        for col in source_cols:
+            if rest == col or rest.startswith(f"{col}_"):
+                if match is None or len(col) > len(match):
+                    match = col
+        source = match if match is not None else rest
+        by_source[source] = by_source.get(source, 0.0) + float(imp)
+
+    feature_importances = pd.DataFrame(
+        sorted(by_source.items(), key=lambda kv: kv[1], reverse=True),
+        columns=["Feature", "Importance"],
+    )
+
+    if output_only_headers:
+        return feature_importances["Feature"]
+
+    total = feature_importances["Importance"].sum()
+    if total > 0:
+        feature_importances["Importance"] = (
+            feature_importances["Importance"] / total * 100
+        ).round(2)
+    feature_importances.rename(columns={"Importance": "Importance (%)"}, inplace=True)
+    return feature_importances
+
+
+# Kept as a thin alias for backwards compatibility with any external callers.
+def get_most_predictable_features_RFE(data, target_column, n_features_to_select=10):
+    return get_most_predictable_features(data, target_column, output_only_headers=True).head(
+        n_features_to_select
+    ).tolist()

{p2predict-1.1.1 → p2predict-1.2.0}/src/p2predict/json_output.py

@@ -119,6 +119,12 @@ Train (``p2predict-train ... --json``)
         "high_variation": [str, ...]
       },
       "features_selected": [str, ...],
+      "excluded_features": [             # auto-mode only; empty with -tf/expert
+        {"column": str,
+         "kind": "leakage" | "id_like" | "constant",
+         "reason": str},
+        ...
+      ],
       "algorithm_selected": str,
       "log_target": bool,
       "log_target_decision": str,        # "auto:skew=<value>" | "manual:on" | "manual:off"

{p2predict-1.1.1 → p2predict-1.2.0}/src/p2predict/mcp/registry.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -7,6 +8,19 @@ from p2predict.model_utils import extract_feature_info, inner_pipeline
 from p2predict.trained_model_io import LoadModel
 
 
+_PATH_UNSAFE = re.compile(r"[\\/\x00]+")
+
+
+def safe_filename_part(text: str) -> str:
+    """Make ``text`` safe to embed in a file name (no separators, no NUL).
+
+    Used for values that come from user data, e.g. a CSV column name that ends
+    up in a saved model's file name. Spaces and other ordinary characters are
+    left alone so existing model IDs stay stable.
+    """
+    return _PATH_UNSAFE.sub("_", text)
+
+
 @dataclass
 class ModelInfo:
     model_id: str
@@ -105,7 +119,22 @@ class ModelRegistry:
         self._cache: dict[str, dict] = {}
 
     def _model_path(self, model_id: str) -> Path:
-        return self.models_dir / f"{model_id}.model"
+        """Resolve a model ID to its file, refusing anything outside models_dir.
+
+        ``model_id`` arrives from an MCP tool call, and ``.model`` files are
+        pickles, so an ID like ``../../elsewhere/x`` must never reach a file
+        outside the models folder. Raised as FileNotFoundError so every tool's
+        existing ``model_not_found`` handling covers it.
+        """
+        not_found = FileNotFoundError(
+            f"No model '{model_id}' found in {self.models_dir}"
+        )
+        if not model_id or _PATH_UNSAFE.search(model_id):
+            raise not_found
+        path = self.models_dir / f"{model_id}.model"
+        if path.parent.resolve() != self.models_dir.resolve():
+            raise not_found
+        return path
 
     def scan(self) -> list[ModelInfo]:
         """List all models in the directory with their metadata."""