pythios 0.1.0__py3-none-any.whl

pythios/data.py

@@ -0,0 +1,572 @@
+"""Data class — universal entry point for Pythios."""
+
+import pandas as pd
+import numpy as np
+from ._utils import lazy_import, detect_task_type, format_table
+
+
+class Data:
+    """
+    Universal container for data flowing through the Pythios pipeline.
+
+    Wraps a pandas DataFrame and adds:
+    - Knowledge of the target column
+    - Auto-detected task type: "binary", "multiclass", or "regression"
+    - Train/test split (after .split() is called)
+    - A clean .describe() summary
+
+    The Data object is the currency of Pythios — every class
+    (Preprocess, Models, Visualize, etc.) takes a Data object as input.
+
+    Examples:
+        >>> d = Data.from_csv("titanic.csv", target="Survived")
+        >>> d.describe()
+        >>> d.split(test=0.2)
+        >>> print(d.X_train.shape)
+
+        >>> df = pd.read_csv("data.csv")
+        >>> d = Data.from_dataframe(df, target="price")
+    """
+
+    def __init__(self, df: pd.DataFrame, target: str = None):
+        """
+        Create a Data object from a pandas DataFrame.
+
+        Args:
+            df: pandas DataFrame to wrap
+            target: Name of the target column (optional)
+        """
+        self._df = df.copy()
+        self.target = target
+
+        if target:
+            if target not in self._df.columns:
+                raise ValueError(
+                    f"Target column '{target}' not found. "
+                    f"Available columns: {self._df.columns.tolist()}"
+                )
+            self.task_type = detect_task_type(self._df[target])
+        else:
+            self.task_type = None
+
+        # These are set after .split() is called
+        self.X_train = None
+        self.X_test = None
+        self.y_train = None
+        self.y_test = None
+        self._is_split = False
+
+    # ──────────────────────────────────────────────────────────────────
+    # CONSTRUCTORS
+    # ──────────────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_csv(
+        cls,
+        path: str,
+        target: str,
+        sep: str = ",",
+        encoding: str = "utf-8"
+    ) -> "Data":
+        """
+        Load a CSV file and return a Data object.
+
+        Args:
+            path: Path to the CSV file
+            target: Name of target column
+            sep: Column separator (default: ",")
+            encoding: File encoding (default: "utf-8")
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_csv("titanic.csv", target="Survived")
+        """
+        df = pd.read_csv(path, sep=sep, encoding=encoding)
+        return cls(df, target=target)
+
+    @classmethod
+    def from_dataframe(cls, df: pd.DataFrame, target: str) -> "Data":
+        """
+        Create a Data object from an existing pandas DataFrame.
+
+        Args:
+            df: pandas DataFrame
+            target: Name of target column
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_dataframe(df, target="price")
+        """
+        return cls(df, target=target)
+
+    @classmethod
+    def from_url(cls, url: str, target: str, sep: str = ",") -> "Data":
+        """
+        Download a CSV from a URL and return a Data object.
+
+        Args:
+            url: URL pointing to a CSV file
+            target: Name of target column
+            sep: Column separator (default: ",")
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_url("https://example.com/data.csv", target="label")
+        """
+        requests = lazy_import("requests")
+        response = requests.get(url)
+        response.raise_for_status()
+
+        from io import StringIO
+        df = pd.read_csv(StringIO(response.text), sep=sep)
+        return cls(df, target=target)
+
+    @classmethod
+    def from_excel(cls, path: str, target: str, sheet=0) -> "Data":
+        """
+        Load an Excel file and return a Data object.
+
+        Args:
+            path: Path to .xlsx or .xls file
+            target: Name of target column
+            sheet: Sheet index or name (default: 0)
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_excel("data.xlsx", target="price")
+        """
+        df = pd.read_excel(path, sheet_name=sheet)
+        return cls(df, target=target)
+    @classmethod
+    def from_sklearn(cls, name: str, target: str = None) -> "Data":
+        """
+        Load a built-in sklearn dataset by name — no file download needed.
+
+        Available datasets:
+            Classification: "iris", "wine", "breast_cancer", "digits"
+            Regression:     "diabetes", "california_housing", "linnerud"
+
+        Args:
+            name: Dataset name (case-insensitive)
+            target: Name to give the target column (optional, defaults to "target")
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_sklearn("iris")
+            >>> d = Data.from_sklearn("diabetes", target="disease_progression")
+        """
+        from sklearn import datasets
+
+        loaders = {
+            "iris":                 datasets.load_iris,
+            "wine":                 datasets.load_wine,
+            "breast_cancer":        datasets.load_breast_cancer,
+            "digits":               datasets.load_digits,
+            "diabetes":             datasets.load_diabetes,
+            "california_housing":   datasets.fetch_california_housing,
+            "linnerud":             datasets.load_linnerud,
+        }
+
+        name_lower = name.lower().strip()
+
+        if name_lower not in loaders:
+            available = ", ".join(loaders.keys())
+            raise ValueError(
+                f"Unknown dataset '{name}'. "
+                f"Available datasets: {available}"
+            )
+
+        # Load the dataset
+        dataset = loaders[name_lower]()
+
+        # Build DataFrame from features
+        if hasattr(dataset, "feature_names"):
+            df = pd.DataFrame(dataset.data, columns=dataset.feature_names)
+        else:
+            n_features = dataset.data.shape[1]
+            df = pd.DataFrame(dataset.data, columns=[f"feature_{i}" for i in range(n_features)])
+
+        # Add target column
+        target_col = target or "target"
+
+        if hasattr(dataset, "target"):
+            target_values = dataset.target
+            # Linnerud exposes three regression targets; Data intentionally
+            # models one target column, so use the first documented response.
+            if getattr(target_values, "ndim", 1) > 1:
+                target_values = target_values[:, 0]
+            # For classification, use string class names if available
+            if hasattr(dataset, "target_names") and target_values.dtype.kind == "i":
+                # Check it's actually a classification task (small number of unique values)
+                if len(np.unique(target_values)) <= 20:
+                    df[target_col] = pd.Categorical.from_codes(
+                        target_values, dataset.target_names
+                    )
+                else:
+                    df[target_col] = target_values
+            else:
+                df[target_col] = target_values
+
+        print(f"✓ Loaded sklearn dataset '{name_lower}' — {df.shape[0]} rows, {df.shape[1]} cols")
+
+        return cls(df, target=target_col)
+
+
+    @classmethod
+    def from_tab(cls, path: str, target: str) -> "Data":
+        """
+        Load an Orange .tab file and return a Data object.
+
+        Orange .tab files have a specific 3-row header:
+            Row 1: Column names
+            Row 2: Column types (continuous, discrete, string)
+            Row 3: Column roles (class, meta, ignore, or blank)
+
+        Args:
+            path: Path to the .tab file
+            target: Name of the target column
+
+        Returns:
+            Data object
+
+        Example:
+            >>> d = Data.from_tab("iris.tab", target="iris")
+        """
+        # Read the three header rows first
+        with open(path, "r", encoding="utf-8") as f:
+            col_names  = f.readline().strip().split("\t")   # row 1: names
+            col_types  = f.readline().strip().split("\t")   # row 2: types
+            col_roles  = f.readline().strip().split("\t")   # row 3: roles
+
+        # Read the actual data (everything after the 3-row header)
+        df = pd.read_csv(path, sep="\t", skiprows=3, header=None, names=col_names)
+
+        # Drop columns marked as "meta" or "ignore" in row 3
+        cols_to_drop = [
+            col_names[i]
+            for i, role in enumerate(col_roles)
+            if role.strip().lower() in ("meta", "ignore")
+            and col_names[i] != target
+        ]
+        if cols_to_drop:
+            df = df.drop(columns=cols_to_drop, errors="ignore")
+            print(f"  Dropped {len(cols_to_drop)} meta/ignore column(s): {cols_to_drop}")
+
+        # Cast continuous columns to float
+        for i, (col, col_type) in enumerate(zip(col_names, col_types)):
+            if col not in df.columns:
+                continue
+            if col_type.strip().lower() == "continuous":
+                df[col] = pd.to_numeric(df[col], errors="coerce")
+
+        print(f"✓ Loaded .tab file '{path}' — {df.shape[0]} rows, {df.shape[1]} cols")
+
+        return cls(df, target=target)
+    # ──────────────────────────────────────────────────────────────────
+    # INSPECTION
+    # ──────────────────────────────────────────────────────────────────
+
+    def describe(self):
+        """
+        Print a detailed summary of the dataset.
+
+        Shows: row/column counts, target and task type, missing values,
+        and a per-column breakdown of dtype, % missing, unique count,
+        and any notable flags.
+
+        Example:
+            >>> d.describe()
+
+            Pythios · Data Summary
+            ─────────────────────────────────────────────────────────
+             Rows: 891   Columns: 12   Target: Survived (binary)
+             Missing values: 3 column(s) affected
+
+             Column     Type      Missing   Unique   Notes
+             ─────────────────────────────────────────────────────────
+             Age        float64   19.9%     88
+             Cabin      object    77.1%     147      high cardinality
+             Survived   int64     0.0%      2        ← TARGET
+        """
+        print("\nPythios · Data Summary")
+        print("─" * 80)
+        print(f" Rows: {len(self._df):,}   Columns: {len(self._df.columns)}")
+
+        if self.target:
+            print(f" Target: {self.target} ({self.task_type})")
+
+        # Missing value overview
+        missing_counts = self._df.isnull().sum()
+        n_cols_missing = (missing_counts > 0).sum()
+        if n_cols_missing > 0:
+            print(f" Missing values: {n_cols_missing} column(s) affected")
+
+        print("\n Column          Type        Missing    Unique    Notes")
+        print("─" * 80)
+
+        rows = []
+        for col in self._df.columns:
+            dtype_str = str(self._df[col].dtype)
+            n_missing = self._df[col].isnull().sum()
+            pct_missing = 100 * n_missing / len(self._df)
+            n_unique = self._df[col].nunique()
+
+            # Notes
+            if col == self.target:
+                notes = "← TARGET"
+            elif pct_missing > 50:
+                notes = "mostly missing"
+            elif pct_missing > 20:
+                notes = "high missing"
+            elif n_unique == 1:
+                notes = "constant value"
+            elif n_unique > 100 and dtype_str == "object":
+                notes = "high cardinality"
+            else:
+                notes = ""
+
+            rows.append([col, dtype_str, f"{pct_missing:.1f}%", str(n_unique), notes])
+
+        format_table(["Column", "Type", "Missing", "Unique", "Notes"], rows)
+
+    def missing_report(self) -> pd.DataFrame:
+        """
+        Return a DataFrame showing missing values per column.
+
+        Returns:
+            DataFrame with Column, Missing_Count, Missing_Percent columns,
+            sorted by Missing_Count descending.
+
+        Example:
+            >>> d.missing_report()
+        """
+        counts = self._df.isnull().sum()
+        pcts = 100 * counts / len(self._df)
+
+        report = pd.DataFrame({
+            "Column": counts.index,
+            "Missing_Count": counts.values,
+            "Missing_Percent": pcts.round(2).values,
+        })
+
+        return (
+            report[report["Missing_Count"] > 0]
+            .sort_values("Missing_Count", ascending=False)
+            .reset_index(drop=True)
+        )
+
+    # ──────────────────────────────────────────────────────────────────
+    # TRAIN / TEST SPLIT
+    # ──────────────────────────────────────────────────────────────────
+
+    def split(
+        self,
+        test: float = 0.2,
+        seed: int = 42,
+        stratify: bool = True,
+        verbose: bool = True,
+    ):
+        """
+        Split the data into training and test sets.
+
+        For classification tasks, stratification is applied by default
+        so class proportions are preserved in both splits.
+
+        Sets the following attributes:
+            X_train, X_test: Feature DataFrames
+            y_train, y_test: Target Series
+
+        Args:
+            test: Fraction of data for test set (default: 0.2)
+            seed: Random seed for reproducibility (default: 42)
+            stratify: Stratify by target for classification (default: True)
+
+        Raises:
+            ValueError: If .split() has already been called
+
+        Example:
+            >>> d.split(test=0.2)
+            ✓ Split 891 rows → 712 train (79.9%), 179 test (20.1%)
+        """
+        if self._is_split:
+            raise ValueError(
+                "Data has already been split. "
+                "Call .copy() first if you want to re-split."
+            )
+
+        from sklearn.model_selection import train_test_split
+
+        # Separate features and target
+        if self.target:
+            X = self._df.drop(columns=[self.target])
+            y = self._df[self.target]
+        else:
+            X = self._df
+            y = None
+
+        # Stratify only for classification
+        stratify_col = None
+        if stratify and self.task_type in ["binary", "multiclass"] and y is not None:
+            stratify_col = y
+
+        # Perform the split
+        if y is not None:
+            X_train, X_test, y_train, y_test = train_test_split(
+                X, y,
+                test_size=test,
+                random_state=seed,
+                stratify=stratify_col
+            )
+        else:
+            X_train, X_test = train_test_split(
+                X,
+                test_size=test,
+                random_state=seed,
+            )
+            y_train, y_test = None, None
+
+        # Store with clean index
+        self.X_train = X_train.reset_index(drop=True)
+        self.X_test  = X_test.reset_index(drop=True)
+        self.y_train = y_train.reset_index(drop=True) if y_train is not None else None
+        self.y_test  = y_test.reset_index(drop=True)  if y_test  is not None else None
+        self._is_split = True
+
+        n_total = len(self.X_train) + len(self.X_test)
+        if verbose:
+            print(
+                f"✓ Split {n_total:,} rows → "
+                f"{len(self.X_train):,} train ({100*len(self.X_train)/n_total:.1f}%), "
+                f"{len(self.X_test):,} test ({100*len(self.X_test)/n_total:.1f}%)"
+            )
+
+    # ──────────────────────────────────────────────────────────────────
+    # PROPERTIES
+    # ──────────────────────────────────────────────────────────────────
+
+    @property
+    def shape(self) -> tuple:
+        """Return (rows, columns) of the full dataset."""
+        return self._df.shape
+
+    @property
+    def dtypes(self) -> pd.Series:
+        """Return data types of all columns."""
+        return self._df.dtypes
+
+    @property
+    def columns(self) -> list:
+        """Return list of column names."""
+        return self._df.columns.tolist()
+
+    # ──────────────────────────────────────────────────────────────────
+    # UTILITY METHODS
+    # ──────────────────────────────────────────────────────────────────
+
+    def head(self, n: int = 5) -> pd.DataFrame:
+        """Return the first n rows."""
+        return self._df.head(n)
+
+    def tail(self, n: int = 5) -> pd.DataFrame:
+        """Return the last n rows."""
+        return self._df.tail(n)
+
+    def copy(self) -> "Data":
+        """
+        Return a deep copy of this Data object.
+
+        Copies the DataFrame, target, task type, and split if it exists.
+
+        Returns:
+            New independent Data object
+
+        Example:
+            >>> d2 = d.copy()
+        """
+        new = Data(self._df.copy(), target=self.target)
+
+        if self._is_split:
+            new.X_train  = self.X_train.copy()
+            new.X_test   = self.X_test.copy()
+            new.y_train  = self.y_train.copy() if self.y_train is not None else None
+            new.y_test   = self.y_test.copy()  if self.y_test  is not None else None
+            new._is_split = True
+
+        return new
+
+    def drop_columns(self, cols: list) -> "Data":
+        """
+        Return a new Data object with specified columns removed.
+
+        Args:
+            cols: List of column names to drop
+
+        Returns:
+            New Data object
+
+        Example:
+            >>> d2 = d.drop_columns(["Cabin", "Name", "Ticket"])
+        """
+        # The target is part of the Data contract and is never removed here.
+        safe_cols = [c for c in cols if c != self.target]
+        new_df = self._df.drop(columns=safe_cols, errors="ignore")
+        return Data(new_df, target=self.target)
+
+    def select_columns(self, cols: list) -> "Data":
+        """
+        Return a new Data object with only the specified columns.
+
+        Args:
+            cols: List of column names to keep
+
+        Returns:
+            New Data object
+
+        Example:
+            >>> d2 = d.select_columns(["Age", "Fare", "Survived"])
+        """
+        new_df = self._df[cols]
+        new_target = self.target if self.target in cols else None
+        return Data(new_df, target=new_target)
+
+    def sample(self, n: int = 1000, seed: int = 42) -> "Data":
+        """
+        Return a new Data object with a random sample of n rows.
+
+        Useful for quick prototyping on large datasets.
+
+        Args:
+            n: Number of rows to sample (capped at dataset size)
+            seed: Random seed for reproducibility
+
+        Returns:
+            New Data object
+
+        Example:
+            >>> d_small = d.sample(500)
+        """
+        n = min(n, len(self._df))
+        sampled = self._df.sample(n=n, random_state=seed)
+        return Data(sampled, target=self.target)
+    
+    def __repr__(self) -> str:
+        split_str = " [split]" if self._is_split else ""
+        return (
+            f"Data(shape={self.shape}, "
+            f"target='{self.target}', "
+            f"task={self.task_type})"
+            f"{split_str}"
+        )
+
+    def __str__(self) -> str:
+        return f"Pythios Data — {self.shape[0]:,} rows × {self.shape[1]} cols"

pythios/embeddings.py

@@ -0,0 +1,29 @@
+"""Optional text, image, and vector-search helpers."""
+import numpy as np
+from ._utils import lazy_import
+class Embeddings:
+    def __init__(self): self._text_model=None; self._text_model_name=None; self._image_model=None; self._image_model_name=None; self._index=None; self.dim=None
+    def text(self,model_name="all-MiniLM-L6-v2"): self._text_model_name=model_name; return self
+    def encode(self,texts):
+        if self._text_model is None: self._text_model=lazy_import("sentence_transformers").SentenceTransformer(self._text_model_name or "all-MiniLM-L6-v2")
+        result=self._text_model.encode(texts,convert_to_numpy=True,show_progress_bar=len(texts)>100); self.dim=result.shape[1]; return result
+    def image(self,model_name="resnet50"): self._image_model_name=model_name; return self
+    def encode_images(self,paths):
+        torch=lazy_import("torch"); tv=lazy_import("torchvision"); Image=lazy_import("PIL.Image","Pillow"); transforms=tv.transforms
+        if self._image_model is None:
+            self._image_model=getattr(tv.models,self._image_model_name or "resnet50")(weights="DEFAULT"); self._image_model=__import__("torch").nn.Sequential(*list(self._image_model.children())[:-1]); self._image_model.eval()
+        prep=transforms.Compose([transforms.Resize(256),transforms.CenterCrop(224),transforms.ToTensor(),transforms.Normalize([.485,.456,.406],[.229,.224,.225])])
+        with torch.no_grad(): result=self._image_model(torch.stack([prep(Image.open(p).convert("RGB")) for p in paths])).flatten(1).cpu().numpy()
+        self.dim=result.shape[1]; return result
+    def similarity(self,a,b): return float(np.dot(a/(np.linalg.norm(a)+1e-9),b/(np.linalg.norm(b)+1e-9)))
+    def similarity_matrix(self,vectors):
+        v=vectors/(np.linalg.norm(vectors,axis=1,keepdims=True)+1e-9); return v@v.T
+    def search(self,query,corpus_vectors,top_k=5):
+        q=self.encode([query])[0] if isinstance(query,str) else np.asarray(query); scores=corpus_vectors@q/(np.linalg.norm(corpus_vectors,axis=1)*np.linalg.norm(q)+1e-9); return [(int(i),float(scores[i])) for i in np.argsort(scores)[::-1][:top_k]]
+    def build_index(self,vectors):
+        faiss=lazy_import("faiss","faiss-cpu"); self._index=faiss.IndexFlatL2(vectors.shape[1]); self._index.add(vectors.astype("float32")); self.dim=vectors.shape[1]; print(f"✓ Faiss index built — {len(vectors)} vectors, dim={self.dim}"); return self
+    def search_index(self,query_vec,top_k=5):
+        if self._index is None: raise RuntimeError("Build an index first")
+        distances,indices=self._index.search(np.asarray(query_vec,dtype="float32").reshape(1,-1),top_k); return [(int(i),float(d)) for i,d in zip(indices[0],distances[0])]
+    def save_index(self,path): lazy_import("faiss","faiss-cpu").write_index(self._index,path)
+    def load_index(self,path): self._index=lazy_import("faiss","faiss-cpu").read_index(path); self.dim=self._index.d; return self

pythios/evaluate.py

@@ -0,0 +1,76 @@
+"""Model evaluation and diagnostic plots."""
+import numpy as np
+class Evaluate:
+    def __init__(self,model): self._model=model; self._data=model._data
+    def metrics(self,on="test"):
+        X=getattr(self._data,"X_"+on); y=getattr(self._data,"y_"+on); pred=self._model.predict(X)
+        from sklearn.metrics import accuracy_score,f1_score,precision_score,recall_score,roc_auc_score,matthews_corrcoef,mean_absolute_error,mean_squared_error,r2_score
+        if self._data.task_type=="binary":
+            classes = list(getattr(self._model.current_model, "classes_", []))
+            binary_average = "binary" if set(np.unique(y)).issubset({0, 1}) else None
+            metric_kwargs = {"average": binary_average, "zero_division": 0} if binary_average else {"average": "weighted", "zero_division": 0}
+            if binary_average:
+                metric_kwargs["pos_label"] = 1
+            try: auc=roc_auc_score(y,self._model.predict_proba(X)[:,1])
+            except Exception: auc=roc_auc_score(y,pred)
+            out={"accuracy":accuracy_score(y,pred),"f1":f1_score(y,pred,**metric_kwargs),"precision":precision_score(y,pred,**metric_kwargs),"recall":recall_score(y,pred,**metric_kwargs),"auc_roc":auc,"mcc":matthews_corrcoef(y,pred)}
+        elif self._data.task_type=="multiclass": out={"accuracy":accuracy_score(y,pred),"macro_f1":f1_score(y,pred,average="macro"),"weighted_f1":f1_score(y,pred,average="weighted")}
+        else: out={"mae":mean_absolute_error(y,pred),"rmse":np.sqrt(mean_squared_error(y,pred)),"r2":r2_score(y,pred)}
+        if self._data.task_type == "binary":
+            print("\nPythios · Metrics (binary classification)")
+            print("─" * 42)
+            print(f" Accuracy     {out['accuracy']:.3f}      Precision    {out['precision']:.3f}")
+            print(f" F1 Score     {out['f1']:.3f}      Recall       {out['recall']:.3f}")
+            print(f" AUC-ROC      {out['auc_roc']:.3f}      MCC          {out['mcc']:.3f}")
+        else:
+            print("\n".join(f"{k}: {v:.4f}" for k,v in out.items()))
+        return out
+    def overfit_check(self):
+        train=self.metrics("train"); test=self.metrics("test")
+        for k in train:
+            if abs(train[k]-test[k])>.1: print(f"⚠ Large train/test gap for {k}: {train[k]-test[k]:.3f}")
+        return {"train":train,"test":test}
+    def confusion_matrix(self,normalise=True):
+        import matplotlib.pyplot as plt; from sklearn.metrics import confusion_matrix
+        y=self._data.y_test; pred=self._model.predict(self._data.X_test); cm=confusion_matrix(y,pred,normalize="true" if normalise else None); plt.imshow(cm,cmap="Blues"); plt.colorbar();
+        for (i,j),v in np.ndenumerate(cm): plt.text(j,i,f"{v:.2f}" if normalise else int(v),ha="center",va="center")
+        plt.title(f"Confusion Matrix — {self._model.model_name}"); plt.xlabel("Predicted"); plt.ylabel("Actual"); plt.show()
+    def roc_curve(self):
+        if self._data.task_type=="regression": raise ValueError("ROC curves require classification")
+        import matplotlib.pyplot as plt; from sklearn.metrics import roc_curve,auc
+        if self._data.task_type=="binary":
+            score=self._model.predict_proba(self._data.X_test)[:,1]; fpr,tpr,_=roc_curve(self._data.y_test,score); plt.plot(fpr,tpr,label=f"AUC={auc(fpr,tpr):.3f}")
+        else:
+            from sklearn.preprocessing import label_binarize
+            from sklearn.metrics import roc_curve
+            y=label_binarize(self._data.y_test,classes=self._model.current_model.classes_); scores=self._model.predict_proba(self._data.X_test)
+            for i in range(y.shape[1]): fpr,tpr,_=roc_curve(y[:,i],scores[:,i]); plt.plot(fpr,tpr,label=str(i))
+        plt.legend(); plt.xlabel("False positive rate"); plt.ylabel("True positive rate"); plt.show()
+    def precision_recall_curve(self):
+        if self._data.task_type!="binary": raise ValueError("Precision-recall curve is binary only")
+        import matplotlib.pyplot as plt; from sklearn.metrics import precision_recall_curve
+        p,r,_=precision_recall_curve(self._data.y_test,self._model.predict_proba(self._data.X_test)[:,1]); plt.plot(r,p); plt.xlabel("Recall"); plt.ylabel("Precision"); plt.show()
+    def residuals(self):
+        if self._data.task_type!="regression": raise ValueError("Residuals require regression")
+        import matplotlib.pyplot as plt; pred=self._model.predict(self._data.X_test); y=self._data.y_test; fig,ax=plt.subplots(1,2); ax[0].scatter(y,pred); ax[0].plot([y.min(),y.max()],[y.min(),y.max()]); ax[1].hist(y-pred); plt.show()
+    def feature_importance(self):
+        import pandas as pd; import matplotlib.pyplot as plt
+        model=self._model.current_model; names=self._data.X_test.columns
+        if hasattr(model,"feature_importances_"): values=model.feature_importances_
+        else:
+            from sklearn.inspection import permutation_importance
+            values=permutation_importance(model,self._data.X_test,self._data.y_test,n_repeats=10,random_state=42).importances_mean
+        out=pd.DataFrame({"Feature":names,"Importance":values}).sort_values("Importance",ascending=False).reset_index(drop=True); out.head(20).sort_values("Importance").plot.barh(x="Feature",y="Importance",legend=False); plt.show(); return out
+    def cross_validate(self,k=5,stratify=True):
+        from sklearn.model_selection import cross_val_score,StratifiedKFold,KFold
+        cv=StratifiedKFold(k,shuffle=True,random_state=42) if stratify and self._data.task_type in ("binary","multiclass") else KFold(k,shuffle=True,random_state=42); scoring="roc_auc" if self._data.task_type=="binary" else ("f1_macro" if self._data.task_type=="multiclass" else "r2"); scores=cross_val_score(self._model.current_model,self._data._df.drop(columns=[self._data.target]),self._data._df[self._data.target],cv=cv,scoring=scoring); print(f"{scoring}: {scores.mean():.4f} ± {scores.std():.4f}"); return {scoring:scores}
+    def shap(self,sample=None):
+        shap=__import__("pythios._utils",fromlist=["lazy_import"]).lazy_import("shap"); X=self._data.X_test.sample(min(sample,len(self._data.X_test)),random_state=42) if sample else self._data.X_test; values=shap.Explainer(self._model.current_model,X)(X); shap.plots.beeswarm(values); return values
+    def shap_waterfall(self,index=0):
+        shap=__import__("pythios._utils",fromlist=["lazy_import"]).lazy_import("shap"); values=shap.Explainer(self._model.current_model,self._data.X_test)(self._data.X_test); shap.plots.waterfall(values[index])
+    def shap_dependence(self,feature):
+        shap=__import__("pythios._utils",fromlist=["lazy_import"]).lazy_import("shap"); shap.dependence_plot(feature,shap.TreeExplainer(self._model.current_model)(self._data.X_test).values,self._data.X_test)
+    def report(self,save=None):
+        text=f"Model: {self._model.model_name}\nTask: {self._data.task_type}\nTest set size: {len(self._data.X_test)}\nMetrics:\n"+"\n".join(f"  {k}: {v:.4f}" for k,v in self.metrics().items())
+        if save: open(save,"w",encoding="utf-8").write(text)
+        print(text); return text