mlbuddy-learn 0.1.0__tar.gz

mlbuddy_learn-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# pytest cache
+.pytest_cache/
+.coverage
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Generated files
+feature_importance.png
+*.png

mlbuddy_learn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Jaasir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlbuddy_learn-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: mlbuddy-learn
+Version: 0.1.0
+Summary: An ML library that guides beginners step by step
+Project-URL: Homepage, https://github.com/Mohammedjaasir/mlbuddy-learn
+Author-email: Mohammed Jaasir <jaasir@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: AI,beginners,education,machine learning
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Description-Content-Type: text/markdown
+
+# MLPilot
+
+Machine Learning automation and guidance system.
+
+## Project Structure
+
+- **mlpilot/auto/**: Automated machine learning tasks
+  - `data.py`: Data handling and preprocessing
+  - `trainer.py`: Model training utilities
+  
+- **mlpilot/guide/**: ML guidance and suggestions
+  - `suggest.py`: Suggestions engine for ML workflows
+  
+- **mlpilot/explain/**: Model interpretation and visualization
+  - `visualizer.py`: Model visualization tools
+  
+- **tests/**: Test suite
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```

mlbuddy_learn-0.1.0/README.md

@@ -0,0 +1,37 @@
+# MLPilot
+
+Machine Learning automation and guidance system.
+
+## Project Structure
+
+- **mlpilot/auto/**: Automated machine learning tasks
+  - `data.py`: Data handling and preprocessing
+  - `trainer.py`: Model training utilities
+  
+- **mlpilot/guide/**: ML guidance and suggestions
+  - `suggest.py`: Suggestions engine for ML workflows
+  
+- **mlpilot/explain/**: Model interpretation and visualization
+  - `visualizer.py`: Model visualization tools
+  
+- **tests/**: Test suite
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```

mlbuddy_learn-0.1.0/mlpilot/__init__.py

@@ -0,0 +1,5 @@
+from .auto.data import load, load_csv
+from .auto.trainer import train, compare
+
+__version__ = "0.1.0"
+__all__ = ["load", "load_csv", "train", "compare"]

mlbuddy_learn-0.1.0/mlpilot/auto/__init__.py

@@ -0,0 +1,2 @@
+from .data import load
+from .trainer import train

mlbuddy_learn-0.1.0/mlpilot/auto/data.py

@@ -0,0 +1,69 @@
+import numpy as np
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+
+def load(X, y, test_size=0.2, scale=True, random_state=42):
+    print("\n🔍 mlpilot: Loading your data...\n")
+
+    if not isinstance(X, np.ndarray):
+        X = np.array(X)
+        print("  ✓ Converted X to numpy array")
+
+    if not isinstance(y, np.ndarray):
+        y = np.array(y)
+        print("  ✓ Converted y to numpy array")
+
+    if X.shape[0] != y.shape[0]:
+        raise ValueError(
+            f"\n✗ Mismatch: X has {X.shape[0]} rows but y has {y.shape[0]} values.\n"
+            f"  → Make sure X and y have the same number of samples."
+        )
+
+    if X.shape[0] < 10:
+        print("  ⚠ Warning: Less than 10 samples. ML works better with more data.")
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=test_size, random_state=random_state
+    )
+    print(f"  ✓ Split: {len(X_train)} training samples, {len(X_test)} test samples")
+
+    if scale:
+        scaler = StandardScaler()
+        X_train = scaler.fit_transform(X_train)
+        X_test = scaler.transform(X_test)
+        print("  ✓ Features scaled with StandardScaler (mean=0, std=1)")
+
+    print(f"\n  📦 Data shape: {X_train.shape[1]} features, {len(set(y))} classes")
+    print("\n✅ Data ready! Pass X_train, X_test, y_train, y_test to ml.train()\n")
+
+    return X_train, X_test, y_train, y_test
+
+
+def load_csv(filepath, target_column):
+    """Load data from a CSV file.
+    
+    Args:
+        filepath: Path to the CSV file
+        target_column: Name of the column containing the target labels
+        
+    Returns:
+        Tuple of (X_train, X_test, y_train, y_test)
+    """
+    import pandas as pd
+    
+    print(f"\n📂 Loading CSV from: {filepath}\n")
+    df = pd.read_csv(filepath)
+    
+    print(f"  ✓ Loaded {len(df)} rows and {len(df.columns)} columns")
+    
+    if target_column not in df.columns:
+        raise ValueError(
+            f"✗ Target column '{target_column}' not found.\n"
+            f"  Available columns: {list(df.columns)}"
+        )
+    
+    y = df[target_column].values
+    X = df.drop(columns=[target_column]).values
+    
+    return load(X, y)

mlbuddy_learn-0.1.0/mlpilot/auto/trainer.py

@@ -0,0 +1,93 @@
+from sklearn.linear_model import LogisticRegression
+from sklearn.tree import DecisionTreeClassifier
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.svm import SVC
+from sklearn.metrics import accuracy_score, classification_report
+
+from ..guide.suggest import suggest
+
+
+MODELS = {
+    "logistic":      LogisticRegression(max_iter=1000),
+    "tree":          DecisionTreeClassifier(),
+    "random_forest": RandomForestClassifier(),
+    "svm":           SVC(),
+}
+
+
+class GuidedModel:
+    def __init__(self, model, X_test, y_test, model_name):
+        self.model = model
+        self.X_test = X_test
+        self.y_test = y_test
+        self.model_name = model_name
+
+        y_pred = model.predict(X_test)
+        self.accuracy = accuracy_score(y_test, y_pred)
+        self.y_pred = y_pred
+
+    def predict(self, X):
+        return self.model.predict(X)
+
+    def explain(self):
+        from ..explain.visualizer import explain_model
+        explain_model(self.model, self.X_test, self.y_test, self.model_name)
+
+    def suggest(self):
+        suggest(self)
+
+
+def train(X_train, X_test, y_train, y_test, model="logistic"):
+    if model not in MODELS:
+        available = ", ".join(MODELS.keys())
+        raise ValueError(
+            f"\n✗ Unknown model '{model}'.\n"
+            f"  → Available models: {available}"
+        )
+
+    print(f"\n🤖 mlpilot: Training '{model}' model...\n")
+
+    clf = MODELS[model]
+    clf.fit(X_train, y_train)
+
+    y_pred = clf.predict(X_test)
+    acc = accuracy_score(y_test, y_pred)
+
+    print(f"  ✓ Training complete!")
+    print(f"  📊 Accuracy: {acc * 100:.1f}%")
+    print()
+    print(classification_report(y_test, y_pred))
+    print("💡 Tip: Call model.explain() to see what the model learned.")
+    print("💡 Tip: Call model.suggest() to get advice on improving it.\n")
+
+    return GuidedModel(clf, X_test, y_test, model)
+
+
+def compare(X_train, X_test, y_train, y_test):
+    """Try all available models and show which one performs best.
+    
+    This is the quickest way to find the best model for your data.
+    
+    Args:
+        X_train, X_test, y_train, y_test: Training and test data
+        
+    Returns:
+        Dictionary with model names and their accuracies
+    """
+    print("\n🔬 mlpilot: Comparing all models...\n")
+
+    results = {}
+    for name, clf in MODELS.items():
+        clf.fit(X_train, y_train)
+        acc = accuracy_score(y_test, clf.predict(X_test))
+        results[name] = acc
+        print(f"  {name:15s} → {acc * 100:6.1f}% accuracy")
+
+    print()
+    best_model = max(results, key=results.get)
+    best_acc = results[best_model]
+    
+    print(f"  🏆 Best: {best_model} with {best_acc * 100:.1f}% accuracy\n")
+    print(f"💡 Tip: Use ml.train(..., model='{best_model}') to train the winner.\n")
+    
+    return results

mlbuddy_learn-0.1.0/mlpilot/explain/__init__.py

@@ -0,0 +1,2 @@
+"""Explain module for model interpretation and visualization."""
+from .visualizer import explain_model

mlbuddy_learn-0.1.0/mlpilot/explain/visualizer.py

@@ -0,0 +1,51 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def explain_model(model, X_test, y_test, model_name):
+    print(f"\n📊 mlpilot: Explaining your '{model_name}' model...\n")
+
+    if hasattr(model, "feature_importances_"):
+        _plot_feature_importance(model.feature_importances_, model_name)
+
+    elif hasattr(model, "coef_"):
+        _plot_coefficients(model.coef_[0], model_name)
+
+    else:
+        print("  ℹ This model doesn't expose internals directly.")
+        print("  → Try model='logistic' or model='random_forest'.\n")
+
+
+def _plot_feature_importance(importances, model_name):
+    n = len(importances)
+    features = [f"Feature {i+1}" for i in range(n)]
+    indices = np.argsort(importances)[::-1]
+
+    plt.figure(figsize=(8, 4))
+    plt.bar(range(n), importances[indices], color="steelblue", alpha=0.8)
+    plt.xticks(range(n), [features[i] for i in indices], rotation=45, ha="right")
+    plt.title(f"Feature Importance — {model_name}", fontsize=13, fontweight="bold")
+    plt.ylabel("Importance Score")
+    plt.tight_layout()
+    plt.savefig("feature_importance.png", dpi=120)
+    plt.show()
+    print("  ✓ Saved as 'feature_importance.png'")
+    print("  → Features on the left matter most to your model.\n")
+
+
+def _plot_coefficients(coefs, model_name):
+    n = len(coefs)
+    features = [f"Feature {i+1}" for i in range(n)]
+    colors = ["crimson" if c < 0 else "steelblue" for c in coefs]
+
+    plt.figure(figsize=(8, 4))
+    plt.bar(range(n), coefs, color=colors, alpha=0.8)
+    plt.xticks(range(n), features, rotation=45, ha="right")
+    plt.axhline(0, color="black", linewidth=0.8, linestyle="--")
+    plt.title(f"Model Coefficients — {model_name}", fontsize=13, fontweight="bold")
+    plt.ylabel("Coefficient Value")
+    plt.tight_layout()
+    plt.savefig("coefficients.png", dpi=120)
+    plt.show()
+    print("  ✓ Saved as 'coefficients.png'")
+    print("  → Blue = pushes toward class 1. Red = pushes toward class 0.\n")

mlbuddy_learn-0.1.0/mlpilot/guide/__init__.py

@@ -0,0 +1,2 @@
+"""Guide module for providing ML suggestions and guidance."""
+from .suggest import suggest

mlbuddy_learn-0.1.0/mlpilot/guide/suggest.py

@@ -0,0 +1,43 @@
+from sklearn.metrics import accuracy_score
+
+
+def suggest(guided_model):
+    acc = guided_model.accuracy
+
+    print("\n💬 mlpilot suggestions:\n")
+    print(f"  Your model accuracy: {acc * 100:.1f}%\n")
+
+    if acc < 0.60:
+        print("  ⚠ Accuracy is quite low. Here's what to try:\n")
+        print("    1. Get more training data.")
+        print("    2. Check your labels — are they correct?")
+        if guided_model.model_name != "random_forest":
+            print("    3. Try model='random_forest' — often works better.")
+        else:
+            print("    3. Try model='svm' or model='logistic' instead.")
+        print("    4. Your features might not be informative enough.")
+
+    elif acc < 0.80:
+        print("  🟡 Decent start! Here's how to improve:\n")
+        print("    1. Try model='random_forest'.")
+        print("    2. Add more features if you have them.")
+        print("    3. Check for class imbalance.")
+        print("    4. Try tuning hyperparameters.")
+
+    elif acc < 0.90:
+        print("  🟢 Good accuracy! To push further:\n")
+        print("    1. Try model='svm'.")
+        print("    2. Engineer new features from existing ones.")
+        print("    3. Collect more diverse training data.")
+
+    else:
+        print("  ✅ Excellent accuracy! A few things to check:\n")
+        print("    1. Make sure you're not overfitting.")
+        print("    2. Check for duplicated rows in your dataset.")
+        print("    3. If all looks good — you're ready to deploy!")
+
+    print()
+    print("  📘 Quick guide:")
+    print("    - Accuracy < 60%  → data quality or quantity problem")
+    print("    - Accuracy 60-80% → try different models or more features")
+    print("    - Accuracy > 90%  → check for overfitting\n")

mlbuddy_learn-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mlbuddy-learn"
+version = "0.1.0"
+description = "An ML library that guides beginners step by step"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Mohammed Jaasir", email = "jaasir@example.com" }
+]
+keywords = ["machine learning", "beginners", "education", "AI"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Education",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy",
+    "scikit-learn",
+    "matplotlib",
+    "pandas",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mohammedjaasir/mlbuddy-learn"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mlpilot"]

mlbuddy_learn-0.1.0/tests/test_data.py

@@ -0,0 +1,60 @@
+import numpy as np
+import pytest
+from mlpilot.auto.data import load
+
+
+def test_load_returns_four_splits():
+    X = np.random.rand(100, 4)
+    y = np.random.randint(0, 2, 100)
+    result = load(X, y)
+    assert len(result) == 4
+
+
+def test_load_correct_sizes():
+    X = np.random.rand(100, 4)
+    y = np.random.randint(0, 2, 100)
+    X_train, X_test, y_train, y_test = load(X, y, test_size=0.2)
+    assert len(X_train) == 80
+    assert len(X_test) == 20
+
+
+def test_load_raises_on_shape_mismatch():
+    X = np.random.rand(100, 4)
+    y = np.random.randint(0, 2, 90)   # wrong size — should raise error
+    with pytest.raises(ValueError):
+        load(X, y)
+
+
+def _plot_feature_importance(importances, model_name):
+    n = len(importances)
+    features = [f"Feature {i+1}" for i in range(n)]
+    indices = np.argsort(importances)[::-1]
+
+    plt.figure(figsize=(8, 4))
+    plt.bar(range(n), importances[indices], color="steelblue", alpha=0.8)
+    plt.xticks(range(n), [features[i] for i in indices], rotation=45, ha="right")
+    plt.title(f"Feature Importance — {model_name}", fontsize=13, fontweight="bold")
+    plt.ylabel("Importance Score")
+    plt.tight_layout()
+    plt.savefig("feature_importance.png", dpi=120)
+    plt.show()
+    print("  ✓ Saved as 'feature_importance.png'")
+    print("  → Features on the left matter most to your model.\n")
+
+
+def _plot_coefficients(coefs, model_name):
+    n = len(coefs)
+    features = [f"Feature {i+1}" for i in range(n)]
+    colors = ["crimson" if c < 0 else "steelblue" for c in coefs]
+
+    plt.figure(figsize=(8, 4))
+    plt.bar(range(n), coefs, color=colors, alpha=0.8)
+    plt.xticks(range(n), features, rotation=45, ha="right")
+    plt.axhline(0, color="black", linewidth=0.8, linestyle="--")
+    plt.title(f"Model Coefficients — {model_name}", fontsize=13, fontweight="bold")
+    plt.ylabel("Coefficient Value")
+    plt.tight_layout()
+    plt.savefig("coefficients.png", dpi=120)
+    plt.show()
+    print("  ✓ Saved as 'coefficients.png'")
+    print("  → Blue = pushes toward class 1. Red = pushes toward class 0.\n")