pythios 0.1.0__py3-none-any.whl

pythios/__init__.py

@@ -0,0 +1,78 @@
+"""
+Pythios — The oracle for your data.
+
+Low-code machine learning for everyone.
+pip install pythios | pythios.xyz
+
+Classes:
+    Data         — load, inspect, split
+    Preprocess   — scale, encode, impute, select
+    Visualize    — distributions, correlations, missing
+    Models       — compare, train, tune, save
+    Evaluate     — metrics, SHAP, ROC, cross-validate
+    Unsupervised — cluster, reduce dimensions
+    Embeddings   — text and image vectors, similarity search
+    Tools        — utilities, profiling, balancing, outliers
+"""
+
+from .data import Data
+from .tools import Tools
+
+# These are imported lazily so missing files don't break the base install.
+# As you build each class, they will automatically become available.
+
+try:
+    from .preprocess import Preprocess
+except ImportError:
+    pass
+
+try:
+    from .visualize import Visualize
+except ImportError:
+    pass
+
+try:
+    from .models import Models
+except ImportError:
+    pass
+
+try:
+    from .evaluate import Evaluate
+except ImportError:
+    pass
+
+try:
+    from .unsupervised import Unsupervised
+except ImportError:
+    pass
+
+try:
+    from .embeddings import Embeddings
+except ImportError:
+    pass
+
+
+__version__ = "0.1.0"
+__author__  = "Advaith"
+__all__ = [
+    "Data",
+    "Preprocess",
+    "Visualize",
+    "Models",
+    "Evaluate",
+    "Unsupervised",
+    "Embeddings",
+    "Tools",
+]
+
+
+def __getattr__(name):
+    """Friendly error when accessing a class that hasn't been built yet."""
+    available = ["Data", "Tools"]
+    if name in __all__ and name not in available:
+        raise ImportError(
+            f"'{name}' hasn't been built yet.\n"
+            f"Currently available: {available}\n"
+            f"Check the build order in your Obsidian vault."
+        )
+    raise AttributeError(f"module 'pythios' has no attribute '{name}'")

pythios/_utils.py

@@ -0,0 +1,155 @@
+"""Shared utilities for Pythios library."""
+
+import importlib
+
+
+def lazy_import(module_name: str, install_name: str = None):
+    """
+    Import a module only when needed, with helpful error if missing.
+
+    Args:
+        module_name: Name of module to import (e.g. "torch", "xgboost")
+        install_name: Package name for pip install. Defaults to module_name.
+
+    Returns:
+        The imported module object.
+
+    Raises:
+        ImportError: If module is not installed, with clear install instructions.
+    """
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        pkg = install_name or module_name
+        raise ImportError(
+            f"'{module_name}' is required for this feature.\n"
+            f"Install it with: pip install {pkg}\n"
+            f"Or install everything: pip install pythios[full]"
+        ) from None
+
+
+def detect_task_type(target_series) -> str:
+    """
+    Automatically detect whether the task is binary classification,
+    multiclass classification, or regression.
+
+    Logic:
+        - String/object target → classification
+            - 2 unique values  → binary
+            - 3+ unique values → multiclass
+        - Integer target with few unique values → classification
+            - 2 unique values  → binary (e.g. 0/1 encoded labels)
+            - 3-20 unique values → multiclass
+        - Float target OR integer with many unique values → regression
+    """
+    if target_series is None or len(target_series) == 0:
+        return None
+
+    n_unique = target_series.nunique()
+    is_categorical = (
+        target_series.dtype == "object"
+        or target_series.dtype.name == "category"
+    )
+    is_float = target_series.dtype.kind == "f"
+
+    if is_categorical:
+        return "binary" if n_unique == 2 else "multiclass"
+
+    elif is_float:
+        return "regression"
+
+    else:
+        unique_vals = sorted(target_series.dropna().unique())
+        if not unique_vals:
+            return None
+        min_val, max_val = unique_vals[0], unique_vals[-1]
+        is_contiguous = max_val == min_val + n_unique - 1
+        is_small = n_unique <= 20 and max_val <= 100
+        if is_contiguous and is_small:
+            return "binary" if n_unique == 2 else "multiclass"
+        return "regression"
+
+def format_table(headers: list, rows: list, title: str = None):
+    """
+    Pretty-print a formatted table to the console.
+
+    Args:
+        headers: List of column header strings
+        rows: List of rows, where each row is a list of values
+        title: Optional title printed above the table
+    """
+    if not rows:
+        print("(empty table)")
+        return
+
+    # Calculate column widths from headers and row values
+    widths = [len(str(h)) for h in headers]
+    for row in rows:
+        for i, val in enumerate(row):
+            if i < len(widths):
+                widths[i] = max(widths[i], len(str(val)))
+
+    divider = "  ".join("─" * w for w in widths)
+
+    if title:
+        print(f"\n{title}")
+
+    print(divider)
+    print("  ".join(f"{str(h):<{w}}" for h, w in zip(headers, widths)))
+    print(divider)
+
+    for row in rows:
+        print("  ".join(f"{str(v):<{w}}" for v, w in zip(row, widths)))
+
+    print()
+
+
+METRICS = {
+    "binary": ["accuracy", "f1", "recall", "precision", "auc_roc"],
+    "multiclass": ["accuracy", "f1", "recall", "precision"],
+    "regression": ["r2", "rmse", "mae"],
+}
+
+DEFAULT_METRIC = {
+    "binary": "accuracy",
+    "multiclass": "accuracy",
+    "regression": "r2",
+}
+
+
+def validate_metric(metric: str, task_type: str) -> str:
+    valid = METRICS.get(task_type, [])
+    if metric not in valid:
+        raise ValueError(
+            f"Metric '{metric}' is not valid for task '{task_type}'.\n"
+            f"Valid metrics for {task_type}: {valid}"
+        )
+    return metric
+
+
+def compute_metric(metric: str, model, X, y_true, task_type: str) -> float:
+    import numpy as np
+    from sklearn import metrics as skmetrics
+    y_pred = model.predict(X)
+    if metric == "accuracy":
+        return skmetrics.accuracy_score(y_true, y_pred)
+    if metric in {"f1", "recall", "precision"}:
+        average = "binary" if task_type == "binary" and set(np.unique(y_true)).issubset({0, 1}) else "macro"
+        fn = getattr(skmetrics, f"{metric}_score")
+        return fn(y_true, y_pred, average=average, zero_division=0)
+    if metric == "auc_roc":
+        if hasattr(model, "predict_proba"):
+            y_prob = model.predict_proba(X)
+            if task_type == "binary":
+                return skmetrics.roc_auc_score(y_true, y_prob[:, 1])
+            return skmetrics.roc_auc_score(y_true, y_prob, multi_class="ovr", average="macro")
+        if hasattr(model, "decision_function"):
+            return skmetrics.roc_auc_score(y_true, model.decision_function(X))
+        return skmetrics.accuracy_score(y_true, y_pred)
+    if metric == "r2":
+        return skmetrics.r2_score(y_true, y_pred)
+    if metric == "rmse":
+        return -np.sqrt(skmetrics.mean_squared_error(y_true, y_pred))
+    if metric == "mae":
+        return -skmetrics.mean_absolute_error(y_true, y_pred)
+    raise ValueError(f"Unknown metric: '{metric}'")