pykeres 1.0.0__py3-none-any.whl

keres/__init__.py

@@ -0,0 +1,100 @@
+"""
+keres: A cell-by-cell Deep Learning Practicals Code Guide Library.
+"""
+
+from .guide import Keres, DLPracticals
+
+# Default instance for convenient top-level access
+_default_instance = Keres()
+
+def list_practicals():
+    """List all available practicals."""
+    _default_instance.list_practicals()
+
+def mock_practical(cell=None, tweaks=False):
+    """View Mock Practical cell-by-cell or with tweak recipes."""
+    _default_instance.mock_practical(cell=cell, tweaks=tweaks)
+
+def practical_1(cell=None, tweaks=False):
+    """View Practical 01 (Perceptron AND/OR) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_1(cell=cell, tweaks=tweaks)
+
+def practical_2(cell=None, tweaks=False):
+    """View Practical 02 (MLP on Fashion-MNIST) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_2(cell=cell, tweaks=tweaks)
+
+def practical_3(cell=None, tweaks=False):
+    """View Practical 03 (L2 vs Dropout Regularization) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_3(cell=cell, tweaks=tweaks)
+
+def practical_4(cell=None, tweaks=False):
+    """View Practical 04 (Activation Functions Analysis) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_4(cell=cell, tweaks=tweaks)
+
+def practical_5(cell=None, tweaks=False):
+    """View Practical 05 (CNN vs MLP on Images) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_5(cell=cell, tweaks=tweaks)
+
+def practical_6(cell=None, tweaks=False):
+    """View Practical 06 (LSTM for IMDB Sentiment) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_6(cell=cell, tweaks=tweaks)
+
+def practical_7(cell=None, tweaks=False):
+    """View Practical 07 (Transfer Learning with MobileNetV2) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_7(cell=cell, tweaks=tweaks)
+
+def practical_8(cell=None, tweaks=False):
+    """View Practical 08 (Hyperparameter Tuning & TensorBoard) cell-by-cell or with tweak recipes."""
+    _default_instance.practical_8(cell=cell, tweaks=tweaks)
+
+def get_practical(num, cell=None, tweaks=False):
+    """Retrieve practical text, specific cell code, or code with tweak recipes."""
+    return _default_instance.get_practical(num, cell=cell, tweaks=tweaks)
+
+def tweaks(num):
+    """View quick tweak recipes (dataset switching, optimizers, viva notes) for a practical."""
+    _default_instance.tweaks(num)
+
+def get_tweaks(num):
+    """Retrieve quick tweak recipe string for a practical."""
+    return _default_instance.get_tweaks(num)
+
+def guide():
+    """Display the built-in quickstart guide and cheat sheet."""
+    _default_instance.guide()
+
+help = guide
+quickstart = guide
+
+def export_all_texts(output_dir):
+    """Export all practicals as plaintext files (.txt) to output_dir."""
+    _default_instance.export_all_texts(output_dir)
+
+def get_cells(num):
+    """Retrieve list of cell dicts for a practical."""
+    return _default_instance.get_cells(num)
+
+__all__ = [
+    "Keres",
+    "DLPracticals",
+    "list_practicals",
+    "guide",
+    "help",
+    "quickstart",
+    "mock_practical",
+    "practical_1",
+    "practical_2",
+    "practical_3",
+    "practical_4",
+    "practical_5",
+    "practical_6",
+    "practical_7",
+    "practical_8",
+    "get_practical",
+    "get_cells",
+    "tweaks",
+    "get_tweaks",
+    "export_all_texts",
+]
+
+__version__ = "1.0.0"

keres/cli.py

@@ -0,0 +1,64 @@
+"""
+Command-line interface for keres.
+"""
+
+import argparse
+import sys
+from keres.guide import Keres
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="keres",
+        description="keres: Deep Learning Practicals Code Guide CLI (Roll No. 23 - Shreyas Daptare)"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # guide / help
+    subparsers.add_parser("guide", help="Show built-in quickstart guide and cheat sheet")
+    subparsers.add_parser("help", help="Show built-in quickstart guide and cheat sheet")
+
+    # list
+    subparsers.add_parser("list", help="List all available practicals")
+
+    # show
+    show_parser = subparsers.add_parser("show", help="Display practical code cell-by-cell")
+    show_parser.add_argument("number", help="Practical number (0 for Mock, 1..8 for Practicals 1..8)")
+    show_parser.add_argument("--cell", type=int, default=None, help="Specific cell number (1-based)")
+    show_parser.add_argument("--tweaks", "-t", action="store_true", help="Include quick tweak recipes at the end")
+
+    # tweaks
+    tweaks_parser = subparsers.add_parser("tweaks", help="Display quick tweak recipes (dataset, optimizer, viva)")
+    tweaks_parser.add_argument("number", help="Practical number (0 for Mock, 1..8 for Practicals 1..8)")
+
+    # export
+    export_parser = subparsers.add_parser("export", help="Export practicals to a directory")
+    export_parser.add_argument("--out", "--out-dir", "-o", dest="out", default="./keres_practicals_txt", help="Output directory")
+
+    args = parser.parse_args()
+    guide = Keres()
+
+    if args.command in ("guide", "help") or args.command is None:
+        guide.guide()
+    elif args.command == "list":
+        guide.list_practicals()
+    elif args.command == "show":
+        try:
+            guide._display_or_return(args.number, cell=args.cell, tweaks=args.tweaks)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+    elif args.command == "tweaks":
+        try:
+            guide.tweaks(args.number)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+    elif args.command == "export":
+        guide.export_all_texts(args.out)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

keres/data/__init__.py

@@ -0,0 +1 @@
+# keres data package

keres/data/mock_practical.txt

@@ -0,0 +1,220 @@
+================================================================================
+# Mock Practical: Neural Network Training with Different Loss Functions
+# Library: keres | Framework: PyTorch | Total Cells: 5
+================================================================================
+
+
+# --------------------------------------------------------------------------------
+# [CELL 1 / 5] : Imports & Environment Setup
+# --------------------------------------------------------------------------------
+import random
+import numpy as np
+import matplotlib.pyplot as plt
+import torch
+import torch.nn as nn
+from torch.utils.data import TensorDataset, DataLoader
+from sklearn.datasets import load_digits
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+
+# --------------------------------------------------------------------------------
+# [CELL 2 / 5] : Random Seed & Reproducibility Setup
+# --------------------------------------------------------------------------------
+SEED = 42
+torch.manual_seed(SEED)
+np.random.seed(SEED)
+random.seed(SEED)
+
+
+# --------------------------------------------------------------------------------
+# [CELL 3 / 5] : Synthetic Dataset Generation (Binary Classification)
+# --------------------------------------------------------------------------------
+# Dataset
+digits = load_digits()
+X = digits.data.astype(np.float32)
+y = digits.target
+
+X_train, X_val, y_train, y_val = train_test_split(
+    X, y, test_size=0.20, stratify=y, random_state=SEED
+)
+
+scaler = StandardScaler()
+X_train = scaler.fit_transform(X_train).astype(np.float32)
+X_val = scaler.transform(X_val).astype(np.float32)
+
+train_loader = DataLoader(
+    TensorDataset(torch.tensor(X_train), torch.tensor(y_train)),
+    batch_size=64, shuffle=True
+)
+val_loader = DataLoader(
+    TensorDataset(torch.tensor(X_val), torch.tensor(y_val)),
+    batch_size=256
+)
+
+
+# --------------------------------------------------------------------------------
+# [CELL 4 / 5] : MLP Architecture, Training Loop & Loss Function Experiments
+# --------------------------------------------------------------------------------
+# Same MLP architecture for all experiments
+class MLP(nn.Module):
+    def __init__(self, activation):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(64, 128), activation(),
+            nn.Linear(128, 128), activation(),
+            nn.Linear(128, 64), activation(),
+            nn.Linear(64, 10)
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+activations = {
+    "Sigmoid": nn.Sigmoid,
+    "Tanh": nn.Tanh,
+    "ReLU": nn.ReLU
+}
+
+criterion = nn.CrossEntropyLoss()
+results = {}
+
+for name, activation in activations.items():
+    torch.manual_seed(SEED)
+    model = MLP(activation)
+    optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
+
+    losses, accuracies, gradients = [], [], []
+
+    print(f"\nTraining with {name}")
+
+    for epoch in range(5):
+        model.train()
+        total_loss = 0
+        batch_gradients = []
+
+        for xb, yb in train_loader:
+            optimizer.zero_grad()
+
+            output = model(xb)
+            loss = criterion(output, yb)
+            loss.backward()
+
+            # Global L2 gradient norm
+            sq_norm = sum(
+                p.grad.detach().pow(2).sum().item()
+                for p in model.parameters()
+                if p.grad is not None
+            )
+            batch_gradients.append(np.sqrt(sq_norm))
+
+            optimizer.step()
+            total_loss += loss.item() * len(yb)
+
+        epoch_loss = total_loss / len(X_train)
+
+        model.eval()
+        correct = total = 0
+        with torch.no_grad():
+            for xb, yb in val_loader:
+                pred = model(xb).argmax(dim=1)
+                correct += (pred == yb).sum().item()
+                total += len(yb)
+
+        accuracy = 100 * correct / total
+        gradient = np.mean(batch_gradients)
+
+        losses.append(epoch_loss)
+        accuracies.append(accuracy)
+        gradients.append(gradient)
+
+        print(
+            f"Epoch {epoch+1}: "
+            f"Loss={epoch_loss:.4f}, "
+            f"Val Acc={accuracy:.2f}%"
+        )
+
+    results[name] = {
+        "loss": losses,
+        "accuracy": accuracies,
+        "gradient": gradients
+    }
+
+
+# --------------------------------------------------------------------------------
+# [CELL 5 / 5] : Comparative Loss & Accuracy Curve Visualization
+# --------------------------------------------------------------------------------
+# Plot results
+epochs = np.arange(1, 6)
+fig, axes = plt.subplots(1, 3, figsize=(13, 4.5))
+
+for name in activations:
+    axes[0].plot(epochs, results[name]["loss"], marker="o", label=name)
+    axes[1].plot(epochs, results[name]["accuracy"], marker="o", label=name)
+    axes[2].plot(epochs, results[name]["gradient"], marker="o", label=name)
+
+axes[0].set_title("Training Loss")
+axes[0].set_xlabel("Epoch")
+axes[0].set_ylabel("Loss")
+
+axes[1].set_title("Validation Accuracy")
+axes[1].set_xlabel("Epoch")
+axes[1].set_ylabel("Accuracy (%)")
+
+axes[2].set_title("Gradient Norms (Flow)")
+axes[2].set_xlabel("Epoch")
+axes[2].set_ylabel("Average Gradient Norm")
+
+for ax in axes:
+    ax.set_xticks(epochs)
+    ax.grid(alpha=0.2)
+    ax.legend()
+
+plt.tight_layout()
+plt.savefig("activation_functions_output.png", dpi=180)
+plt.show()
+
+================================================================================
+💡 QUICK TWEAK RECIPES FOR MOCK PRACTICAL (Multi-Loss MLP in PyTorch):
+================================================================================
+1. SWITCH TO LOCAL CSV VIA PANDAS:
+   import pandas as pd
+   from sklearn.model_selection import train_test_split
+   from sklearn.preprocessing import StandardScaler
+   df = pd.read_csv('your_dataset.csv')
+   X_raw = df.drop('target', axis=1).values
+   y_raw = df['target'].values
+   X_tr, X_te, y_tr, y_te = train_test_split(X_raw, y_raw, test_size=0.2, random_state=42)
+   scaler = StandardScaler()
+   X_train = torch.tensor(scaler.fit_transform(X_tr), dtype=torch.float32)
+   X_test = torch.tensor(scaler.transform(X_te), dtype=torch.float32)
+   y_train = torch.tensor(y_tr, dtype=torch.long)
+   y_test = torch.tensor(y_te, dtype=torch.long)
+
+2. SWITCH OPTIMIZERS:
+   # Adam (Default):
+   optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
+   # SGD with Momentum:
+   optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9)
+   # RMSprop:
+   optimizer = torch.optim.RMSprop(model.parameters(), lr=0.005)
+   # AdamW (Adam + decoupled Weight Decay):
+   optimizer = torch.optim.AdamW(model.parameters(), lr=0.01, weight_decay=1e-4)
+
+3. SWITCH LOSS FUNCTIONS:
+   # Multi-class Classification:
+   criterion = nn.CrossEntropyLoss()
+   # Regression / Continuous:
+   criterion = nn.MSELoss()  # or nn.L1Loss()
+   # Robust Regression (less sensitive to outliers):
+   criterion = nn.SmoothL1Loss(beta=1.0)
+   # Binary Classification:
+   criterion = nn.BCEWithLogitsLoss()
+
+4. ADD DROPOUT & BATCH NORMALIZATION:
+   # Inside SimpleMLP __init__:
+   self.fc1 = nn.Linear(input_dim, 64)
+   self.bn1 = nn.BatchNorm1d(64)
+   self.dropout = nn.Dropout(0.3)
+   self.fc2 = nn.Linear(64, num_classes)
+================================================================================

keres/data/practical_01.txt

@@ -0,0 +1,204 @@
+================================================================================
+# Practical 01: Single-Layer Perceptron for AND and OR Gates
+# Library: keres | Framework: NumPy / Matplotlib | Total Cells: 2
+================================================================================
+
+
+# --------------------------------------------------------------------------------
+# [CELL 1 / 2] : Perceptron Class & AND Gate Decision Boundary Plot
+# --------------------------------------------------------------------------------
+import numpy as np
+import matplotlib.pyplot as plt
+
+def step_function(x):
+    return np.where(x >= 0, 1, 0)
+
+class Perceptron:
+    def __init__(self, input_size, learning_rate=0.1, epochs=10):
+        self.weights = np.zeros(input_size + 1)  
+        self.lr = learning_rate
+        self.epochs = epochs
+
+    def predict(self, x):
+        x = np.insert(x, 0, 1)  
+        return step_function(np.dot(self.weights, x))
+
+    def train(self, X, y):
+        for epoch in range(self.epochs):
+            total_error = 0
+
+            for xi, target in zip(X, y):
+                xi_bias = np.insert(xi, 0, 1)
+
+                output = step_function(np.dot(self.weights, xi_bias))
+                error = target - output
+                total_error += abs(error)
+
+                self.weights += self.lr * error * xi_bias
+
+            print(f"Epoch {epoch+1}: Error = {total_error}")
+
+X = np.array([
+    [0, 0],
+    [0, 1],
+    [1, 0],
+    [1, 1]
+])
+
+y = np.array([0, 0, 0, 1])
+
+p = Perceptron(input_size=2)
+p.train(X, y)
+
+print("\nFinal Weights:", p.weights)
+
+print("\nPredictions:")
+for sample in X:
+    print(sample, "->", p.predict(sample))
+
+def plot_decision_boundary(model, X, y):
+    x_min, x_max = -0.2, 1.2
+    y_min, y_max = -0.2, 1.2
+
+    xx, yy = np.meshgrid(
+        np.linspace(x_min, x_max, 100),
+        np.linspace(y_min, y_max, 100)
+    )
+
+    Z = np.array([
+        model.predict(np.array([x, y]))
+        for x, y in zip(xx.ravel(), yy.ravel())
+    ])
+
+    Z = Z.reshape(xx.shape)
+
+    plt.figure(figsize=(6,5))
+    plt.contourf(xx, yy, Z, alpha=0.3, cmap=plt.cm.coolwarm)
+    plt.scatter(X[:,0], X[:,1], c=y, cmap=plt.cm.coolwarm,
+                edgecolors='black', s=120)
+
+    plt.title("Decision Boundary of Perceptron (AND Gate)")
+    plt.xlabel("Input 1")
+    plt.ylabel("Input 2")
+    plt.grid(True)
+    plt.show()
+
+plot_decision_boundary(p, X, y)
+
+
+# --------------------------------------------------------------------------------
+# [CELL 2 / 2] : Perceptron Class & OR Gate Decision Boundary Plot
+# --------------------------------------------------------------------------------
+import numpy as np
+import matplotlib.pyplot as plt
+
+def step_function(x):
+    return np.where(x >= 0, 1, 0)
+
+class Perceptron:
+    def __init__(self, input_size, learning_rate=0.1, epochs=10):
+        self.weights = np.zeros(input_size + 1) 
+        self.lr = learning_rate
+        self.epochs = epochs
+
+    def predict(self, x):
+        x = np.insert(x, 0, 1)  
+        return step_function(np.dot(self.weights, x))
+
+    def train(self, X, y):
+        for epoch in range(self.epochs):
+            total_error = 0
+
+            for xi, target in zip(X, y):
+                xi_bias = np.insert(xi, 0, 1)
+
+                output = step_function(np.dot(self.weights, xi_bias))
+                error = target - output
+                total_error += abs(error)
+
+                self.weights += self.lr * error * xi_bias
+
+            print(f"Epoch {epoch+1}: Error = {total_error}")
+
+X = np.array([
+    [0, 0],
+    [0, 1],
+    [1, 0],
+    [1, 1]
+])
+
+y = np.array([0, 1, 1, 1])
+
+p = Perceptron(input_size=2)
+p.train(X, y)
+
+print("\nFinal Weights:", p.weights)
+
+print("\nPredictions:")
+for sample in X:
+    print(sample, "->", p.predict(sample))
+
+def plot_decision_boundary(model, X, y):
+    x_min, x_max = -0.2, 1.2
+    y_min, y_max = -0.2, 1.2
+
+    xx, yy = np.meshgrid(
+        np.linspace(x_min, x_max, 100),
+        np.linspace(y_min, y_max, 100)
+    )
+
+    Z = np.array([
+        model.predict(np.array([x, y]))
+        for x, y in zip(xx.ravel(), yy.ravel())
+    ])
+
+    Z = Z.reshape(xx.shape)
+
+    plt.figure(figsize=(6,5))
+    plt.contourf(xx, yy, Z, alpha=0.3, cmap=plt.cm.coolwarm)
+    plt.scatter(X[:,0], X[:,1], c=y, cmap=plt.cm.coolwarm,
+                edgecolors='black', s=120)
+
+    plt.title("Decision Boundary of Perceptron (OR Gate)")
+    plt.xlabel("Input 1")
+    plt.ylabel("Input 2")
+    plt.grid(True)
+    plt.show()
+
+plot_decision_boundary(p, X, y)
+
+================================================================================
+💡 QUICK TWEAK RECIPES FOR PRACTICAL 01 (Perceptron for Logic Gates in NumPy):
+================================================================================
+1. SWITCH TO LOCAL CSV VIA PANDAS:
+   import pandas as pd
+   df = pd.read_csv('logic_gate.csv')  # CSV with columns: x1, x2, target
+   X = df[['x1', 'x2']].values
+   y = df['target'].values
+
+2. SWITCH LOGIC GATES:
+   # AND Gate (Default):
+   y = np.array([0, 0, 0, 1])
+   # OR Gate:
+   y = np.array([0, 1, 1, 1])
+   # NAND Gate:
+   y = np.array([1, 1, 1, 0])
+   # NOR Gate:
+   y = np.array([1, 0, 0, 0])
+   # XOR Gate (VIVA TRICK: Single perceptron CANNOT solve XOR because XOR is non-linearly separable!):
+   y = np.array([0, 1, 1, 0])
+
+3. HYPERPARAMETER TWEAKS:
+   # Slower, smoother learning:
+   p = Perceptron(input_size=2, learning_rate=0.01, epochs=30)
+   # Faster, aggressive updates:
+   p = Perceptron(input_size=2, learning_rate=0.5, epochs=10)
+
+4. SWITCH ACTIVATION FUNCTION:
+   # Bipolar Step Function (-1 or +1 output):
+   def step_function_bipolar(x):
+       return np.where(x >= 0, 1, -1)
+   # Sigmoid Perceptron (Continuous output [0, 1]):
+   def sigmoid(x):
+       return 1 / (1 + np.exp(-x))
+================================================================================