devray-datalab-mcp 0.1.0__py3-none-any.whl

devray_datalab/__init__.py

@@ -0,0 +1,3 @@
+"""DevRay DataLab MCP - Local-first data science and ML MCP server."""
+
+__version__ = "0.1.0"

devray_datalab/config.py

@@ -0,0 +1,72 @@
+"""Server configuration.
+
+Settings are read from environment variables with sensible defaults so the
+server runs on modest hardware without any cloud credentials.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _env_str(name: str, default: str) -> str:
+    return os.environ.get(name, default)
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    return os.environ.get(name, str(default)).lower() in ("1", "true", "yes", "on")
+
+
+@dataclass
+class DevRayConfig:
+    """Runtime configuration for the DevRay DataLab MCP server."""
+
+    # Filesystem locations.
+    workspace_dir: Path = field(
+        default_factory=lambda: Path(_env_devray("DEVRAY_WORKSPACE_DIR", "datasets"))
+    )
+    artifacts_dir: Path = field(
+        default_factory=lambda: Path(_env_devray("DEVRAY_ARTIFACTS_DIR", "artifacts"))
+    )
+
+    # Dataset limits.
+    max_dataset_size_bytes: int = _env_int("DEVRAY_MAX_DATASET_SIZE_BYTES", 200 * 1024 * 1024)
+    allowed_extensions: tuple[str, ...] = (".csv",)
+
+    # Preview limits.
+    max_preview_rows: int = _env_int("DEVRAY_MAX_PREVIEW_ROWS", 25)
+
+    # Training / resource limits.
+    max_cpu_threads: int | None = _env_int("DEVRAY_MAX_CPU_THREADS", 0) or None
+    training_memory_budget_mb: int | None = _env_int("DEVRAY_TRAINING_MEMORY_BUDGET_MB", 0) or None
+    max_concurrent_jobs: int = _env_int("DEVRAY_MAX_CONCURRENT_JOBS", 1)
+    training_timeout_seconds: int = _env_int("DEVRAY_TRAINING_TIMEOUT_SECONDS", 1800)
+
+    # Logging.
+    log_level: str = _env_str("DEVRAY_LOG_LEVEL", "INFO")
+
+    def __post_init__(self) -> None:
+        self.workspace_dir = self.workspace_dir.resolve()
+        self.artifacts_dir = self.artifacts_dir.resolve()
+        self.workspace_dir.mkdir(parents=True, exist_ok=True)
+        self.artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _env_devray(name: str, default: str) -> str:
+    return os.environ.get(name, default)

devray_datalab/core/__init__.py

@@ -0,0 +1 @@
+"""Core ML utilities package."""

devray_datalab/core/evaluator.py

@@ -0,0 +1,145 @@
+"""Evaluation metrics for classification and regression.
+
+Metrics are computed with scikit-learn and include clear explanations so
+clients can interpret results without guessing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from sklearn.metrics import (
+    accuracy_score,
+    f1_score,
+    mean_absolute_error,
+    mean_squared_error,
+    precision_score,
+    r2_score,
+    recall_score,
+    roc_auc_score,
+)
+
+
+@dataclass
+class ClassificationMetrics:
+    accuracy: float
+    precision: float
+    recall: float
+    f1: float
+    roc_auc: float | None
+    support: int
+    explanation: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "accuracy": round(self.accuracy, 6),
+            "precision": round(self.precision, 6),
+            "recall": round(self.recall, 6),
+            "f1": round(self.f1, 6),
+            "roc_auc": None if self.roc_auc is None else round(self.roc_auc, 6),
+            "support": self.support,
+            "explanation": self.explanation,
+        }
+
+
+@dataclass
+class RegressionMetrics:
+    mae: float
+    rmse: float
+    r2: float
+    support: int
+    explanation: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "mae": round(self.mae, 6),
+            "rmse": round(self.rmse, 6),
+            "r2": round(self.r2, 6),
+            "support": self.support,
+            "explanation": self.explanation,
+        }
+
+
+def classification_explanation() -> str:
+    return (
+        "Accuracy = fraction of correct predictions. Precision = fraction of "
+        "positive predictions that are correct. Recall = fraction of actual "
+        "positives found. F1 = harmonic mean of precision and recall. "
+        "ROC-AUC = ability to rank positives above negatives (binary only)."
+    )
+
+
+def regression_explanation() -> str:
+    return (
+        "MAE = average absolute error (same units as target). RMSE = root mean "
+        "squared error (penalizes large errors). R^2 = fraction of target "
+        "variance explained (1 = perfect, 0 = mean baseline, negative = worse "
+        "than mean)."
+    )
+
+
+def evaluate_classification(
+    y_true: np.ndarray, y_pred: np.ndarray, y_proba: np.ndarray | None = None
+) -> ClassificationMetrics:
+    """Compute classification metrics with zero-division safety."""
+    average = "binary" if len(np.unique(y_true)) == 2 else "macro"
+    zero_division = 0
+
+    try:
+        roc_auc: float | None = None
+        if y_proba is not None and len(np.unique(y_true)) == 2:
+            # Use probability of the positive class when available.
+            proba = np.asarray(y_proba)
+            if proba.ndim == 2 and proba.shape[1] >= 2:
+                roc_auc = float(roc_auc_score(y_true, proba[:, 1]))
+            elif proba.ndim == 1:
+                roc_auc = float(roc_auc_score(y_true, proba))
+    except Exception:  # noqa: BLE001
+        roc_auc = None
+
+    return ClassificationMetrics(
+        accuracy=float(accuracy_score(y_true, y_pred)),
+        precision=float(
+            precision_score(y_true, y_pred, average=average, zero_division=zero_division)
+        ),
+        recall=float(recall_score(y_true, y_pred, average=average, zero_division=zero_division)),
+        f1=float(f1_score(y_true, y_pred, average=average, zero_division=zero_division)),
+        roc_auc=roc_auc,
+        support=int(len(y_true)),
+        explanation=classification_explanation(),
+    )
+
+
+def evaluate_regression(y_true: np.ndarray, y_pred: np.ndarray) -> RegressionMetrics:
+    """Compute regression metrics."""
+    mae = float(mean_absolute_error(y_true, y_pred))
+    rmse = float(np.sqrt(mean_squared_error(y_true, y_pred)))
+    r2 = float(r2_score(y_true, y_pred))
+    return RegressionMetrics(
+        mae=mae,
+        rmse=rmse,
+        r2=r2,
+        support=int(len(y_true)),
+        explanation=regression_explanation(),
+    )
+
+
+def cross_validate_classification(
+    estimator: Any,
+    X: np.ndarray,
+    y: np.ndarray,
+    cv: int = 5,
+    scoring: str = "accuracy",
+) -> dict[str, float]:
+    """Run stratified cross-validation and return mean/std per metric."""
+    from sklearn.model_selection import StratifiedKFold, cross_validate
+
+    cv_splitter = StratifiedKFold(n_splits=min(cv, len(np.unique(y))), shuffle=True)
+    scores = cross_validate(estimator, X, y, cv=cv_splitter, scoring=scoring, n_jobs=1)
+    key = f"test_{scoring}"
+    return {
+        "mean": float(np.mean(scores[key])),
+        "std": float(np.std(scores[key])),
+    }

devray_datalab/core/hardware.py

@@ -0,0 +1,104 @@
+"""Hardware and resource detection.
+
+Reports CPU, memory, storage and GPU availability using only psutil and the
+standard library. No PyTorch, TensorFlow, or CUDA dependencies are required.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from dataclasses import dataclass, field
+
+import psutil
+
+from devray_datalab.utils.errors import HardwareError
+
+
+@dataclass
+class GpuInfo:
+    """Detected GPU information."""
+
+    detected: bool = False
+    detail: str = "No supported GPU detected"
+    backend_available: bool = False
+
+
+@dataclass
+class SystemInfo:
+    operating_system: str
+    os_version: str
+    processor: str
+    cpu_cores_logical: int
+    cpu_cores_physical: int
+    cpu_percent: float
+    ram_total_gb: float
+    ram_available_gb: float
+    ram_percent: float
+    storage_total_gb: float
+    storage_free_gb: float
+    storage_used_percent: float
+    gpu: GpuInfo = field(default_factory=GpuInfo)
+    sklearn_cpu_backend: bool = True
+
+
+def _detect_gpu() -> GpuInfo:
+    """Best-effort GPU detection without GPU dependencies.
+
+    Checks common GPU indicators exposed by psutil/the OS and reports whether
+    a GPU-accelerated sklearn backend appears to be installed.
+    """
+    detail_parts: list[str] = []
+    detected = False
+
+    # NVIDIA GPU hint via nvidia-smi availability.
+    nvidia_smi = shutil.which("nvidia-smi")
+    if nvidia_smi:
+        detected = True
+        detail_parts.append("NVIDIA GPU (nvidia-smi available)")
+
+    # Try to detect GPU via py3nvml if present (optional, no hard dep).
+    try:
+        import py3nvml  # type: ignore
+
+        try:
+            py3nvml.nvmlInit()
+            count = py3nvml.nvmlDeviceGetCount()
+            if count > 0:
+                detected = True
+                detail_parts.append(f"NVIDIA GPU(s) via NVML: {count}")
+        except Exception:
+            pass
+    except ImportError:
+        pass
+
+    detail = "; ".join(detail_parts) if detail_parts else "No supported GPU detected"
+    return GpuInfo(detected=detected, detail=detail)
+
+
+def get_system_info() -> SystemInfo:
+    """Gather system hardware information."""
+    try:
+        vm = psutil.virtual_memory()
+        cpu_percent = psutil.cpu_percent(interval=0.1)
+        disk = shutil.disk_usage(os.getcwd())
+        gpu = _detect_gpu()
+
+        return SystemInfo(
+            operating_system=platform.system(),
+            os_version=platform.version(),
+            processor=platform.processor() or platform.machine(),
+            cpu_cores_logical=psutil.cpu_count(logical=True) or 1,
+            cpu_cores_physical=psutil.cpu_count(logical=False) or 1,
+            cpu_percent=cpu_percent,
+            ram_total_gb=round(vm.total / (1024**3), 2),
+            ram_available_gb=round(vm.available / (1024**3), 2),
+            ram_percent=round(vm.percent, 1),
+            storage_total_gb=round(disk.total / (1024**3), 2),
+            storage_free_gb=round(disk.free / (1024**3), 2),
+            storage_used_percent=round(disk.used / disk.total * 100, 1),
+            gpu=gpu,
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise HardwareError(f"Failed to gather system info: {exc}") from exc

devray_datalab/core/loader.py

@@ -0,0 +1,71 @@
+"""Dataset loading utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from devray_datalab.config import DevRayConfig
+from devray_datalab.utils.errors import DatasetError
+from devray_datalab.utils.validation import (
+    MAX_PREVIEW_ROWS,
+    validate_dataset_path,
+    validate_file_size,
+)
+
+
+def list_datasets(workspace: Path) -> list[dict[str, Any]]:
+    """List datasets in the workspace with filenames, formats, and sizes."""
+    if not workspace.is_dir():
+        return []
+
+    datasets: list[dict[str, Any]] = []
+    for entry in sorted(workspace.iterdir()):
+        if not entry.is_file():
+            continue
+        if entry.suffix.lower() not in (".csv",):
+            continue
+        try:
+            stat = entry.stat()
+        except OSError:
+            continue
+        datasets.append(
+            {
+                "filename": entry.name,
+                "format": entry.suffix.lower().lstrip("."),
+                "size_bytes": stat.st_size,
+                "size_mb": round(stat.st_size / (1024 * 1024), 3),
+            }
+        )
+    return datasets
+
+
+def load_dataset(config: DevRayConfig, name: str) -> pd.DataFrame:
+    """Load a CSV dataset from the workspace, validating path and size."""
+    path = validate_dataset_path(config.workspace_dir, name, must_exist=True)
+    validate_file_size(path, config.max_dataset_size_bytes)
+
+    try:
+        df = pd.read_csv(path)
+    except Exception as exc:  # noqa: BLE001 - surface a clear dataset error
+        raise DatasetError(f"Failed to load dataset '{name}': {exc}") from exc
+
+    if df.empty:
+        raise DatasetError(f"Dataset '{name}' is empty.")
+    return df
+
+
+def preview_dataframe(df: pd.DataFrame, max_rows: int = MAX_PREVIEW_ROWS) -> list[dict[str, Any]]:
+    """Return the first ``max_rows`` rows as a list of dicts."""
+    return df.head(max_rows).to_dict(orient="records")
+
+
+def dataset_statistics(df: pd.DataFrame) -> dict[str, Any]:
+    """Compute numerical statistics for a dataframe."""
+    numeric = df.select_dtypes(include="number")
+    if numeric.empty:
+        return {}
+    stats = numeric.describe().to_dict()
+    return stats

devray_datalab/core/preprocessing.py

@@ -0,0 +1,115 @@
+"""Preprocessing pipelines built from scikit-learn transformers.
+
+Transformations are fitted on training data only and preserved for later
+prediction, preventing data leakage.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from sklearn.compose import ColumnTransformer
+from sklearn.impute import SimpleImputer
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder, StandardScaler
+
+from devray_datalab.utils.errors import ValidationError
+
+
+@dataclass
+class PreprocessingArtifact:
+    """A fitted preprocessing pipeline plus the schema it was fitted on."""
+
+    preprocessor: ColumnTransformer
+    feature_columns: list[str]
+    target_column: str
+    task_type: str
+    numeric_features: list[str] = field(default_factory=list)
+    categorical_features: list[str] = field(default_factory=list)
+
+
+def _infer_feature_types(df: pd.DataFrame, target_column: str) -> tuple[list[str], list[str]]:
+    """Split feature columns into numeric and categorical lists."""
+    if target_column not in df.columns:
+        raise ValidationError(f"Target column '{target_column}' not found in dataset.")
+    features = [c for c in df.columns if c != target_column]
+
+    numeric_features: list[str] = []
+    categorical_features: list[str] = []
+    for col in features:
+        if pd.api.types.is_numeric_dtype(df[col]):
+            numeric_features.append(col)
+        else:
+            categorical_features.append(col)
+    return numeric_features, categorical_features
+
+
+def build_preprocessor(
+    df: pd.DataFrame,
+    target_column: str,
+    task_type: str,
+    impute_strategy: str = "mean",
+    scale_numeric: bool = True,
+    encode_categorical: bool = True,
+) -> PreprocessingArtifact:
+    """Build and fit a preprocessing pipeline on ``df`` (training data only).
+
+    - Numeric columns: impute (median for robustness) then optionally standard-scale.
+    - Categorical columns: one-hot encode with unknown categories ignored.
+    """
+    numeric_features, categorical_features = _infer_feature_types(df, target_column)
+
+    transformers: list[tuple[str, Any, list[str]]] = []
+
+    if numeric_features:
+        numeric_steps: list[tuple[str, Any]] = [("imputer", SimpleImputer(strategy="median"))]
+        if scale_numeric:
+            numeric_steps.append(("scaler", StandardScaler()))
+        transformers.append(("num", Pipeline(steps=numeric_steps), numeric_features))
+
+    if categorical_features:
+        encode_steps: list[tuple[str, Any]] = [("imputer", SimpleImputer(strategy="most_frequent"))]
+        if encode_categorical:
+            encode_steps.append(
+                (
+                    "onehot",
+                    OneHotEncoder(handle_unknown="ignore", sparse_output=False),
+                )
+            )
+        transformers.append(("cat", Pipeline(steps=encode_steps), categorical_features))
+
+    if not transformers:
+        raise ValidationError("No feature columns available for preprocessing.")
+
+    preprocessor = ColumnTransformer(transformers=transformers, remainder="drop")
+    feature_columns = [c for c in df.columns if c != target_column]
+    preprocessor.fit(df[feature_columns])
+
+    return PreprocessingArtifact(
+        preprocessor=preprocessor,
+        feature_columns=feature_columns,
+        target_column=target_column,
+        task_type=task_type,
+        numeric_features=numeric_features,
+        categorical_features=categorical_features,
+    )
+
+
+def transform_features(artifact: PreprocessingArtifact, df: pd.DataFrame) -> np.ndarray:
+    """Transform a dataframe using a fitted preprocessing artifact."""
+    missing = [c for c in artifact.feature_columns if c not in df.columns]
+    if missing:
+        raise ValidationError(f"Missing feature columns: {', '.join(missing)}")
+    return artifact.preprocessor.transform(df[artifact.feature_columns])
+
+
+def get_feature_names_out(artifact: PreprocessingArtifact) -> list[str]:
+    """Return the output feature names after preprocessing."""
+    try:
+        names = artifact.preprocessor.get_feature_names_out()
+        return [str(n) for n in names]
+    except Exception:  # pragma: no cover - fallback for older sklearn
+        return list(artifact.feature_columns)