@vespermcp/mcp-server 1.0.4 → 1.0.6

package/build/python/splitter_engine.py

@@ -0,0 +1,283 @@
+import sys
+import json
+import polars as pl
+import numpy as np
+from sklearn.model_selection import train_test_split
+
+def execute_split(file_path, config):
+    # Load Data
+    if file_path.endswith(".csv"):
+        df = pl.read_csv(file_path, ignore_errors=True)
+    elif file_path.endswith(".parquet"):
+        df = pl.read_parquet(file_path)
+    else:
+        raise ValueError("Unsupported format")
+
+    train_ratio = config["ratios"]["train"]
+    val_ratio = config["ratios"]["val"]
+    test_ratio = config["ratios"]["test"]
+    holdout_ratio = config["ratios"].get("holdout", 0)
+    seed = config.get("random_seed", 42)
+    shuffle = config.get("shuffle", True)
+    
+    # Strategy
+    strategy = config["type"]
+    target_col = config.get("target_column", None)
+    time_col = config.get("time_column", None)
+
+    train_df, val_df, test_df, holdout_df = None, None, None, None
+
+    # --- 1. RANDOM / STRATIFIED SPLIT ---
+    if strategy in ["random", "stratified"]:
+        if strategy == "random":
+            if shuffle:
+                df = df.sample(fraction=1.0, seed=seed, shuffle=True)
+            
+            n = len(df)
+            n_train = int(n * train_ratio)
+            n_val = int(n * val_ratio)
+            n_test = int(n * test_ratio)
+            
+            train_df = df.slice(0, n_train)
+            val_df = df.slice(n_train, n_val)
+            test_df = df.slice(n_train + n_val, n_test)
+            holdout_df = df.slice(n_train + n_val + n_test, n - (n_train + n_val + n_test))
+
+        elif strategy == "stratified":
+            if not target_col or target_col not in df.columns:
+                return {"error": f"Target column '{target_col}' not found needed for stratification"}
+            
+            y = df[target_col].to_list()
+            indices = np.arange(len(df))
+            
+            # Split 1: Train vs Others
+            others_ratio = val_ratio + test_ratio + holdout_ratio
+            if others_ratio == 0:
+                 train_idx, others_idx = indices, []
+            else:
+                 train_idx, others_idx = train_test_split(indices, test_size=others_ratio, stratify=y, random_state=seed, shuffle=True)
+            
+            train_df = df[train_idx]
+            
+            if len(others_idx) > 0:
+                y_others = [y[i] for i in others_idx]
+                
+                # Split 2: Val vs (Test + Holdout)
+                test_holdout_ratio = (test_ratio + holdout_ratio) / others_ratio
+                if test_holdout_ratio > 0 and test_holdout_ratio < 1:
+                    val_idx, test_holdout_idx = train_test_split(others_idx, test_size=test_holdout_ratio, stratify=y_others, random_state=seed, shuffle=True)
+                    val_df = df[val_idx]
+                    
+                    if len(test_holdout_idx) > 0:
+                        y_th = [y[i] for i in test_holdout_idx]
+                        relative_holdout_ratio = holdout_ratio / (test_ratio + holdout_ratio)
+                        
+                        if relative_holdout_ratio > 0 and relative_holdout_ratio < 1:
+                            test_idx, holdout_idx = train_test_split(test_holdout_idx, test_size=relative_holdout_ratio, stratify=y_th, random_state=seed, shuffle=True)
+                            test_df = df[test_idx]
+                            holdout_df = df[holdout_idx]
+                        elif relative_holdout_ratio >= 1:
+                            test_df = df.slice(0, 0)
+                            holdout_df = df[test_holdout_idx]
+                        else:
+                            test_df = df[test_holdout_idx]
+                            holdout_df = df.slice(0, 0)
+                elif test_holdout_ratio >= 1:
+                    val_df = df.slice(0, 0)
+                    # Chained split for Test/Holdout
+                    y_th = y_others
+                    relative_holdout_ratio = holdout_ratio / (test_ratio + holdout_ratio)
+                    if relative_holdout_ratio > 0 and relative_holdout_ratio < 1:
+                        test_idx, holdout_idx = train_test_split(others_idx, test_size=relative_holdout_ratio, stratify=y_th, random_state=seed, shuffle=True)
+                        test_df = df[test_idx]
+                        holdout_df = df[holdout_idx]
+                    else:
+                        test_df = df[others_idx]
+                        holdout_df = df.slice(0, 0)
+                else:
+                    val_df = df[others_idx]
+                    test_df = df.slice(0, 0)
+                    holdout_df = df.slice(0, 0)
+
+    # --- 2. TIME-BASED SPLIT ---
+    elif strategy == "time":
+        if not time_col or time_col not in df.columns:
+             return {"error": f"Time column '{time_col}' not found"}
+        
+        df = df.sort(time_col)
+        
+        n = len(df)
+        n_train = int(n * train_ratio)
+        n_val = int(n * val_ratio)
+        n_test = int(n * test_ratio)
+        
+        train_df = df.slice(0, n_train)
+        val_df = df.slice(n_train, n_val)
+        test_df = df.slice(n_train + n_val, n_test)
+        holdout_df = df.slice(n_train + n_val + n_test, n - (n_train + n_val + n_test))
+        
+    # --- 3. GROUP-BASED SPLIT ---
+    elif strategy == "group":
+        if not config.get("group_column") or config["group_column"] not in df.columns:
+            return {"error": f"Group column '{config.get('group_column')}' not found"}
+        
+        group_col = config["group_column"]
+        groups = df[group_col].unique().to_list()
+        
+        # Split groups first to ensure zero leakage
+        n_grps = len(groups)
+        n_train = int(n_grps * train_ratio)
+        n_val = int(n_grps * val_ratio)
+        n_test = int(n_grps * test_ratio)
+        
+        if shuffle:
+            np.random.seed(seed)
+            np.random.shuffle(groups)
+            
+        train_grps = set(groups[:n_train])
+        val_grps = set(groups[n_train:n_train+n_val])
+        test_grps = set(groups[n_train+n_val:n_train+n_val+n_test])
+        holdout_grps = set(groups[n_train+n_val+n_test:])
+        
+        train_df = df.filter(pl.col(group_col).is_in(train_grps))
+        val_df = df.filter(pl.col(group_col).is_in(val_grps))
+        test_df = df.filter(pl.col(group_col).is_in(test_grps))
+        holdout_df = df.filter(pl.col(group_col).is_in(holdout_grps))
+
+    else:
+        return {"error": f"Strategy {strategy} not implemented yet"}
+
+    # Save outputs
+    base_name = file_path.replace(".csv", "").replace(".parquet", "")
+    train_path = f"{base_name}_train.csv"
+    val_path = f"{base_name}_val.csv"
+    test_path = f"{base_name}_test.csv"
+    holdout_path = f"{base_name}_holdout.csv"
+    
+    train_df.write_csv(train_path)
+    val_df.write_csv(val_path)
+    test_df.write_csv(test_path)
+    holdout_df.write_csv(holdout_path)
+    
+    return {
+        "success": True,
+        "paths": { "train": train_path, "val": val_path, "test": test_path, "holdout": holdout_path },
+        "stats": {
+            "train_rows": len(train_df),
+            "val_rows": len(val_df),
+            "test_rows": len(test_df),
+            "holdout_rows": len(holdout_df)
+        }
+    }
+
+def validate_split(config):
+    # Config contains paths to check and optional ID column
+    train_path = config["paths"]["train"]
+    val_path = config["paths"]["val"]
+    test_path = config["paths"]["test"]
+    holdout_path = config["paths"].get("holdout")
+    id_col = config.get("id_column", "id") # Default to 'id' if exists
+    target_col = config.get("target_column", None)
+
+    # Load dfs
+    try:
+        train_df = pl.read_csv(train_path) if train_path.endswith(".csv") else pl.read_parquet(train_path)
+        val_df = pl.read_csv(val_path) if val_path.endswith(".csv") else pl.read_parquet(val_path)
+        test_df = pl.read_csv(test_path) if test_path.endswith(".csv") else pl.read_parquet(test_path)
+        holdout_df = None
+        if holdout_path:
+             holdout_df = pl.read_csv(holdout_path) if holdout_path.endswith(".csv") else pl.read_parquet(holdout_path)
+    except:
+        return {"error": "Failed to load split files for validation"}
+
+    report = {
+        "leakage_detected": False,
+        "leakage_count": 0,
+        "distribution_mismatch": False,
+        "warnings": []
+    }
+
+    # 1. Leakage Check (ID intersection)
+    if id_col in train_df.columns:
+        train_ids = set(train_df[id_col].to_list())
+        val_ids = set(val_df[id_col].to_list())
+        test_ids = set(test_df[id_col].to_list())
+        holdout_ids = set(holdout_df[id_col].to_list()) if holdout_df is not None else set()
+        
+        leakage_tv = len(train_ids.intersection(val_ids))
+        leakage_tt = len(train_ids.intersection(test_ids))
+        leakage_th = len(train_ids.intersection(holdout_ids))
+        leakage_vt = len(val_ids.intersection(test_ids))
+        leakage_vh = len(val_ids.intersection(holdout_ids))
+        leakage_th_val = len(test_ids.intersection(holdout_ids))
+        
+        total_leakage = leakage_tv + leakage_tt + leakage_th + leakage_vt + leakage_vh + leakage_th_val
+        
+        if total_leakage > 0:
+            report["leakage_detected"] = True
+            report["leakage_count"] = total_leakage
+            report["warnings"].append(f"Found {total_leakage} overlapping IDs between splits.")
+    else:
+        report["warnings"].append(f"ID column '{id_col}' not found. Skipping exact leakage check.")
+
+    # 2. Distribution Check (Target Distribution)
+    if target_col and target_col in train_df.columns:
+        try:
+           def get_ratios(df, col):
+               counts = df[col].value_counts()
+               total = len(df)
+               ratios = {}
+               for row in counts.rows():
+                   ratios[str(row[0])] = row[1] / total
+               return ratios
+
+           train_metrics = get_ratios(train_df, target_col)
+           val_metrics = get_ratios(val_df, target_col)
+           # test_metrics = get_ratios(test_df, target_col) # Optional: could check all
+           
+           for cls in train_metrics:
+               train_r = train_metrics[cls]
+               val_r = val_metrics.get(cls, 0)
+               diff = abs(train_r - val_r)
+               if diff > 0.1: # 10% drift
+                   report["distribution_mismatch"] = True
+                   report["warnings"].append(f"Class '{cls}' drift: Train={train_r:.2f}, Val={val_r:.2f}")
+        except:
+             pass
+
+    return report
+
+def main():
+    # Usage: 
+    #   split:   python splitter_engine.py split <file_path> <config_json>
+    #   validate: python splitter_engine.py validate <config_json> (dummy file arg ignored)
+    
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "Usage: splitter_engine.py <action> <arg1> [arg2]"}), file=sys.stderr)
+        sys.exit(1)
+
+    action = sys.argv[1]
+    
+    try:
+        if action == "split":
+            file_path = sys.argv[2]
+            config = json.loads(sys.argv[3])
+            result = execute_split(file_path, config)
+            print(json.dumps(result))
+        
+        elif action == "validate":
+            config = json.loads(sys.argv[2])
+            result = validate_split(config)
+            print(json.dumps(result))
+            
+        else:
+            # Fallback for old calls (implicit split) - if users used old signature
+            # But since we control the caller, we can just update the caller (DataSplitter.ts).
+            raise ValueError(f"Unknown action: {action}")
+
+    except Exception as e:
+        print(json.dumps({"success": False, "error": str(e)}))
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/build/python/target_engine.py

@@ -0,0 +1,154 @@
+import sys
+import json
+import pandas as pd
+import numpy as np
+
+# Common names for target variables in datasets
+TARGET_CANDIDATES = [
+    'target', 'label', 'class', 'outcome', 'y', 
+    'price', 'saleprice', 'sales', 'cost', 'value', 'total',
+    'diagnosis', 'species', 'churn', 'survived', 'credit_risk'
+]
+
+def load_data(file_path):
+    if file_path.endswith('.csv'):
+        return pd.read_csv(file_path)
+    elif file_path.endswith('.parquet'):
+        return pd.read_parquet(file_path)
+    else:
+        raise ValueError("Unsupported file format")
+
+def detect_target(file_path):
+    try:
+        df = load_data(file_path)
+        columns = [c.lower() for c in df.columns]
+        candidates = []
+
+        # 1. Exact Name Match
+        for col_original in df.columns:
+            col_lower = col_original.lower()
+            confidence = 0.0
+            reasons = []
+
+            if col_lower in TARGET_CANDIDATES:
+                confidence += 0.6
+                reasons.append(f"Matches common target name '{col_lower}'")
+                
+                # Boost if exact match 'target' or 'label'
+                if col_lower in ['target', 'label', 'class']:
+                    confidence += 0.2
+
+            # 2. Position Heuristic (Last column is often target)
+            if col_original == df.columns[-1]:
+                confidence += 0.3
+                reasons.append("Is the last column")
+
+            # 3. Completeness
+            missing_rate = df[col_original].isnull().mean()
+            if missing_rate > 0.5:
+                confidence -= 0.5
+                reasons.append(f"High missing rate ({missing_rate:.1%})")
+            elif missing_rate > 0:
+                confidence -= 0.1
+                reasons.append(f"Has missing values ({missing_rate:.1%})")
+
+            # 4. Cardinality / Unique Values
+            # If regression-like (many unique numeric values) or class-like (few unique values)
+            # This is hard to score generally, but extremes are bad for targets (e.g. all unique = ID usually)
+            n_unique = df[col_original].nunique()
+            if n_unique == len(df):
+                confidence -= 0.8
+                reasons.append("All values are unique (likely ID)")
+            
+            if confidence > 0.3:
+                candidates.append({
+                    "column": col_original,
+                    "confidence": min(confidence, 1.0),
+                    "reason": reasons
+                })
+
+        # Sort by confidence
+        candidates.sort(key=lambda x: x['confidence'], reverse=True)
+
+        best_target = None
+        best_conf = 0.0
+        
+        if candidates:
+            best_target = candidates[0]['column']
+            best_conf = candidates[0]['confidence']
+
+        return {
+            "target_column": best_target,
+            "confidence": best_conf,
+            "candidates": candidates,
+            "is_unified": False # Wrapper will handle unification logic
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+
+def validate_target(file_path, target_column):
+    try:
+        df = load_data(file_path)
+        if target_column not in df.columns:
+            return {"error": f"Column '{target_column}' not found in dataset."}
+
+        series = df[target_column]
+        total_rows = len(df)
+        missing_count = series.isnull().sum()
+        
+        # Determine type
+        is_numeric = pd.api.types.is_numeric_dtype(series)
+        n_unique = series.nunique()
+        
+        problem_type = "unknown"
+        if is_numeric and n_unique > 20:
+             problem_type = "regression"
+        elif n_unique < 50: # String or few numeric values
+             problem_type = "classification"
+        else:
+             # Heuristic fallback
+             problem_type = "regression" if is_numeric else "classification"
+
+        warnings = []
+        if missing_count > 0:
+            warnings.append(f"Target has {missing_count} missing values.")
+        
+        # Imbalance check for classification
+        if problem_type == "classification":
+            counts = series.value_counts(normalize=True)
+            if counts.iloc[0] > 0.9: # Dominant class > 90%
+                warnings.append(f"Highly imbalanced target: Class '{counts.index[0]}' is {counts.iloc[0]:.1%}")
+
+        return {
+            "valid": True,
+            "problem_type": problem_type,
+            "missing_count": int(missing_count),
+            "total_rows": total_rows,
+            "warnings": warnings
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "Usage: target_engine.py <action> <file_path> [args]"}));
+        sys.exit(1)
+
+    action = sys.argv[1]
+    file_path = sys.argv[2]
+    
+    result = {}
+    if action == "detect":
+        result = detect_target(file_path)
+    elif action == "validate":
+        target_col = sys.argv[3] if len(sys.argv) > 3 else None
+        if target_col:
+            result = validate_target(file_path, target_col)
+        else:
+            result = {"error": "Target column required for validation"}
+    else:
+        result = {"error": f"Unknown action: {action}"}
+
+    print(json.dumps(result))

package/build/python/test_framework_adapters.py

@@ -0,0 +1,61 @@
+
+import sys
+import os
+import polars as pl
+import numpy as np
+
+# Mock data creation
+def create_mock_data():
+    df = pl.DataFrame({
+        "feature1": np.random.rand(100),
+        "feature2": np.random.rand(100),
+        "label": np.random.randint(0, 2, 100)
+    })
+    os.makedirs("test_adapters", exist_ok=True)
+    df.write_parquet("test_adapters/data.parquet")
+    df.write_csv("test_adapters/data.csv")
+    print("Created mock data in test_adapters/")
+
+def test_pytorch():
+    print("\n--- Testing PyTorch Adapter ---")
+    try:
+        from framework_adapters import VesperPyTorchDataset
+        import torch
+        from torch.utils.data import DataLoader
+
+        dataset = VesperPyTorchDataset("test_adapters/data.parquet", target_col="label")
+        loader = DataLoader(dataset, batch_size=10, shuffle=True)
+        
+        batch = next(iter(loader))
+        print(f"Loaded batch: {batch}")
+        print("PASS: PyTorch DataLoader works")
+        
+    except ImportError:
+        print("SKIP: PyTorch not installed")
+    except Exception as e:
+        print(f"FAIL: PyTorch test failed: {e}")
+
+def test_huggingface():
+    print("\n--- Testing HuggingFace Adapter ---")
+    try:
+        from framework_adapters import load_vesper_dataset
+        ds = load_vesper_dataset("test_adapters/data.csv")
+        print(f"Loaded dataset: {ds}")
+        print("PASS: HuggingFace Dataset works")
+        
+    except ImportError:
+        print("SKIP: HuggingFace datasets not installed")
+    except Exception as e:
+        print(f"FAIL: HuggingFace test failed: {e}")
+
+if __name__ == "__main__":
+    create_mock_data()
+    # Add src/python to path to import adapters
+    sys.path.append(os.path.join(os.getcwd(), "src", "python"))
+    
+    test_pytorch()
+    test_huggingface()
+    
+    # Cleanup
+    import shutil
+    shutil.rmtree("test_adapters")

package/build/python/uci_adapter.py

@@ -0,0 +1,94 @@
+import sys
+import json
+import argparse
+import urllib.request
+import urllib.parse
+from datetime import datetime
+
+# API Endpoint found in network inspection of UCI website
+UCI_API_URL = "https://archive.ics.uci.edu/api/datasets/list"
+
+def search_uci(query: str, limit: int = 10):
+    """
+    Search UCI datasets using their internal API.
+    """
+    try:
+        # Fetch data dictionary from API
+        # Only fetching first 100 to filter locally
+        params = {
+            "skip": 0,
+            "take": 100,
+            "sort": "desc",
+            "orderBy": "NumHits",
+            "search": query 
+        }
+        
+        query_string = urllib.parse.urlencode(params)
+        url = f"{UCI_API_URL}?{query_string}"
+        
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req) as response:
+            data = json.load(response)
+        
+        datasets = data.get('data', [])
+        if not datasets:
+            datasets = []
+
+        results = []
+        count = 0
+        
+        # We trust the API search mostly, but can do extra filtering if needed
+        # The API "search" param is supported
+        
+        for ds in datasets:
+            # Normalize to Vesper schema
+            # API fields: id, name, abstract, numHits, area, task, dateDonated
+            
+            metadata = {
+                "id": f"uci:{ds.get('id')}", 
+                "source": "uci",
+                "name": ds.get('name'),
+                "description": ds.get('abstract') or "No description available.",
+                "downloads": ds.get('numHits') or 0,
+                "likes": 0,
+                "last_updated": ds.get('dateDonated') or datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "quality_score": 80, 
+                "license": {
+                    "id": "other",
+                    "category": "open", 
+                    "usage_restrictions": [],
+                    "warnings": []
+                },
+                "tags": [t for t in [ds.get('area'), ds.get('task')] if t],
+                "total_examples": ds.get('numInstances'),
+                "is_safe_source": True,
+                "is_structured": True,
+                "metadata_url": f"https://archive.ics.uci.edu/dataset/{ds.get('id')}/{ds.get('name').replace(' ', '+')}"
+            }
+            
+            results.append(metadata)
+            count += 1
+            if count >= limit:
+                break
+                    
+        return results
+
+    except Exception as e:
+        # Fallback empty or specific error
+        return {"error": str(e)}
+
+def main():
+    parser = argparse.ArgumentParser(description="UCI Adapter")
+    parser.add_argument("--action", required=True, choices=["search"])
+    parser.add_argument("--query", required=True)
+    parser.add_argument("--limit", type=int, default=10)
+    
+    args = parser.parse_args()
+    
+    if args.action == "search":
+        results = search_uci(args.query, args.limit)
+        # JSON dump print for stdout capture
+        print(json.dumps(results))
+
+if __name__ == "__main__":
+    main()

package/build/python/worldbank_adapter.py

@@ -0,0 +1,99 @@
+import sys
+import json
+import argparse
+import urllib.request
+import urllib.parse
+from datetime import datetime
+
+# WB API for indicators (Series)
+# Source 2 is World Development Indicators
+WB_API_URL = "https://api.worldbank.org/v2/indicator"
+
+def search_worldbank(query: str, limit: int = 10):
+    """
+    Search World Bank indicators.
+    """
+    try:
+        # The World Bank Indicators API doesn't have a direct "search" parameter for indicators 
+        # that works exactly like a search engine. We fetch a page and filter by query terms.
+        # Alternatively, we could use the 'qterm' on the documents API, but indicators are more tabular.
+        
+        params = {
+            "format": "json",
+            "per_page": 299, # Max per page to search through more indicators
+            "source": 2
+        }
+        
+        query_string = urllib.parse.urlencode(params)
+        url = f"{WB_API_URL}?{query_string}"
+        
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req) as response:
+            data = json.load(response)
+        
+        # WB response is [metadata, data_list]
+        if len(data) < 2:
+            return []
+            
+        indicators = data[1]
+        
+        results = []
+        count = 0
+        
+        query_terms = query.lower().split()
+        
+        for ind in indicators:
+            name = ind.get('name', '')
+            source_note = ind.get('sourceNote', '')
+            text = (name + " " + source_note).lower()
+            
+            # Simple keyword matching
+            if all(term in text for term in query_terms):
+                metadata = {
+                    "id": f"wb:{ind.get('id')}", 
+                    "source": "worldbank",
+                    "name": name,
+                    "description": source_note or "No description available.",
+                    "downloads": 1000, # Placeholder (high relevance for WB)
+                    "likes": 100,
+                    "last_updated": datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
+                    "quality_score": 95, # Institutional data is high quality
+                    "license": {
+                        "id": "cc-by-4.0",
+                        "name": "Creative Commons Attribution 4.0",
+                        "category": "safe",
+                        "usage_restrictions": [],
+                        "warnings": []
+                    },
+                    "tags": [ind.get('source', {}).get('value')] if ind.get('source') else [],
+                    "total_examples": 0, # Time series length varies
+                    "is_safe_source": True,
+                    "is_structured": True,
+                    "metadata_url": f"https://data.worldbank.org/indicator/{ind.get('id')}",
+                    "domain": "economics"
+                }
+                
+                results.append(metadata)
+                count += 1
+                if count >= limit:
+                    break
+                    
+        return results
+
+    except Exception as e:
+        return {"error": str(e)}
+
+def main():
+    parser = argparse.ArgumentParser(description="World Bank Adapter")
+    parser.add_argument("--action", required=True, choices=["search"])
+    parser.add_argument("--query", required=True)
+    parser.add_argument("--limit", type=int, default=10)
+    
+    args = parser.parse_args()
+    
+    if args.action == "search":
+        results = search_worldbank(args.query, args.limit)
+        print(json.dumps(results))
+
+if __name__ == "__main__":
+    main()