heroalgorithm 0.1.0__py3-none-any.whl

heroalgorithm/__init__.py

@@ -0,0 +1,6 @@
+"""
+HeroAlgorithm - Instant AI/ML Lab Problem Sheets, Datasets & Code Manager.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

heroalgorithm/assignments/PS-1/README.md

@@ -0,0 +1,11 @@
+# Problem Sheet 1 (PS-1)
+
+## Objectives
+- Load and preprocess tabular dataset from `dataset/data.csv`.
+- Implement simple classification model.
+- Analyze feature correlation and accuracy metrics.
+
+## Files
+- `dataset/data.csv`: Input training data.
+- `notebook.ipynb`: Interactive analysis & visualization.
+- `solution.py`: Standalone Python implementation script.

heroalgorithm/assignments/PS-1/dataset/data.csv

@@ -0,0 +1,7 @@
+feature1,feature2,target
+1.2,3.4,0
+2.5,1.1,0
+5.8,7.9,1
+6.1,8.3,1
+1.9,2.4,0
+7.3,9.1,1

heroalgorithm/assignments/PS-1/notebook.ipynb

@@ -0,0 +1,32 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# PS-1: Linear Classification\n",
+        "\n",
+        "Jupyter Notebook for AIML Lab.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import pandas as pd\n",
+        "import numpy as np\n",
+        "df = pd.read_csv(\"dataset/data.csv\")\n",
+        "df.head()\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

heroalgorithm/assignments/PS-1/solution.py

@@ -0,0 +1,28 @@
+"""
+AIML Problem Sheet 1 (PS-1)
+Linear Regression / Classification Implementation
+"""
+
+import pandas as pd
+from pathlib import Path
+
+
+def load_dataset():
+    data_path = Path(__file__).parent / "dataset" / "data.csv"
+    if not data_path.exists():
+        raise FileNotFoundError(f"Dataset not found at: {data_path}")
+    df = pd.read_csv(data_path)
+    print(f"Loaded dataset with {len(df)} rows:")
+    print(df.head())
+    return df
+
+
+def main():
+    print("Executing PS-1 Solution...")
+    df = load_dataset()
+    print("Features:", [c for c in df.columns if c != "target"])
+    print("Target distribution:", df["target"].value_counts().to_dict())
+
+
+if __name__ == "__main__":
+    main()

heroalgorithm/assignments/PS-2/README.md

@@ -0,0 +1,5 @@
+# Problem Sheet 2 (PS-2)
+
+## Objectives
+- Decision Trees and Random Forests on housing data.
+- Evaluate MAE, RMSE, and R2 score.

heroalgorithm/assignments/PS-2/dataset/housing.csv

@@ -0,0 +1,5 @@
+area,bedrooms,price
+1200,2,250000
+1800,3,380000
+2400,4,520000
+850,1,160000

heroalgorithm/assignments/PS-2/notebook.ipynb

@@ -0,0 +1,32 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# PS-2: Decision Trees & Regression\n",
+        "\n",
+        "Jupyter Notebook for AIML Lab.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import pandas as pd\n",
+        "import numpy as np\n",
+        "df = pd.read_csv(\"dataset/housing.csv\")\n",
+        "df.head()\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

heroalgorithm/assignments/PS-2/solution.py

@@ -0,0 +1,10 @@
+"""AIML Problem Sheet 2 (PS-2): Decision Trees & Regression"""
+import pandas as pd
+from pathlib import Path
+
+def main():
+    df = pd.read_csv(Path(__file__).parent / "dataset" / "housing.csv")
+    print("PS-2 Housing dataset loaded:", df.shape)
+
+if __name__ == "__main__":
+    main()

heroalgorithm/assignments/PS-3/README.md

@@ -0,0 +1,5 @@
+# Problem Sheet 3 (PS-3)
+
+## Objectives
+- Clustering (K-Means) and Classification on Iris dataset.
+- Dimensionality Reduction with PCA.

heroalgorithm/assignments/PS-3/dataset/iris.csv

@@ -0,0 +1,4 @@
+sepal_length,sepal_width,petal_length,petal_width,species
+5.1,3.5,1.4,0.2,setosa
+7.0,3.2,4.7,1.4,versicolor
+6.3,3.3,6.0,2.5,virginica

heroalgorithm/assignments/PS-3/notebook.ipynb

@@ -0,0 +1,32 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# PS-3: Clustering & PCA\n",
+        "\n",
+        "Jupyter Notebook for AIML Lab.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import pandas as pd\n",
+        "import numpy as np\n",
+        "df = pd.read_csv(\"dataset/iris.csv\")\n",
+        "df.head()\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

heroalgorithm/assignments/PS-3/solution.py

@@ -0,0 +1,10 @@
+"""AIML Problem Sheet 3 (PS-3): Neural Networks / Clustering"""
+import pandas as pd
+from pathlib import Path
+
+def main():
+    df = pd.read_csv(Path(__file__).parent / "dataset" / "iris.csv")
+    print("PS-3 Iris dataset loaded:", df.shape)
+
+if __name__ == "__main__":
+    main()

heroalgorithm/assignments/README.md

@@ -0,0 +1,28 @@
+# 🤖 AI / ML Lab Assignments Repository
+
+This repository hosts all AI & Machine Learning lab problem sheets and code.
+
+Each problem sheet follows a consistent structure:
+```text
+PS-X/
+├── dataset/
+│   └── dataset.csv
+├── psX_notebook.ipynb
+├── psX_solution.py
+└── README.md
+```
+
+## Quick Download with AssignVault
+Students can download and organize everything locally with a single terminal command:
+
+```bash
+# 1. Download all Problem Sheets
+assignvault download
+
+# 2. Or download a specific Problem Sheet (e.g. PS-1)
+assignvault download ps-1
+# or: assignvault download 1
+
+# 3. List all available problem sheets
+assignvault list
+```

heroalgorithm/cli.py

@@ -0,0 +1,293 @@
+"""
+CLI interface for HeroAlgorithm.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from heroalgorithm import __version__
+from heroalgorithm.config import (
+    get_branch,
+    get_destination,
+    get_repo,
+    get_token,
+    load_config,
+    reset_config,
+    set_branch,
+    set_destination,
+    set_repo,
+)
+from heroalgorithm.downloader import (
+    HeroAlgorithmError,
+    extract_archive,
+    extract_bundled,
+    fetch_archive,
+    inspect_archive,
+    parse_repo_string,
+)
+
+# Reconfigure console streams on Windows to prevent cp1252 charmap errors
+if sys.platform == "win32":
+    try:
+        if hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        if hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+def run_install(
+    destination: Path,
+    subject: Optional[str] = None,
+    repo_str: Optional[str] = None,
+    branch: Optional[str] = None,
+    token: Optional[str] = None,
+    force: bool = True,
+    quiet: bool = False,
+) -> int:
+    """
+    Executes assignment extraction. Keeps verbose installation logs hidden.
+    """
+    target_info = f" ({subject})" if subject else ""
+    if not quiet:
+        print(f"📦 HeroAlgorithm: Organizing AIML Problem Sheets{target_info} into:\n   {destination.resolve()}")
+
+    try:
+        # If a remote GitHub repository is specified, fetch from GitHub
+        if repo_str:
+            owner, repo = parse_repo_string(repo_str)
+            branch = branch or get_branch()
+            archive_data = fetch_archive(
+                owner=owner,
+                repo=repo,
+                branch=branch,
+                token=token,
+                silent=True,
+            )
+            extracted = extract_archive(
+                archive_data=archive_data,
+                destination=destination,
+                subject_filter=subject,
+                overwrite=force,
+            )
+        else:
+            # Extract bundled problem sheets directly from package
+            extracted = extract_bundled(
+                destination=destination,
+                subject_filter=subject,
+                overwrite=force,
+            )
+
+    except HeroAlgorithmError as e:
+        print(f"❌ Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+        return 1
+
+    if not extracted:
+        if subject:
+            print(f"⚠️  No problem sheets found matching '{subject}'.")
+        else:
+            print("⚠️  No files were extracted.")
+        return 0
+
+    if not quiet:
+        print(f"\n✅ Ready! {len(extracted)} files organized at:\n   {destination.resolve()}\n")
+
+    return 0
+
+
+def handle_download(args: argparse.Namespace) -> int:
+    destination = get_destination(args.output)
+    repo = get_repo(args.repo)
+    branch = get_branch(args.branch)
+    token = get_token(args.token)
+    return run_install(
+        destination=destination,
+        subject=args.subject,
+        repo_str=repo,
+        branch=branch,
+        token=token,
+        force=args.force,
+        quiet=args.quiet,
+    )
+
+
+def handle_list(args: argparse.Namespace) -> int:
+    repo_str = get_repo(args.repo)
+    if not repo_str:
+        # List bundled sheets
+        from heroalgorithm.downloader import BUNDLED_DIR
+        print(f"📚 Available Bundled Problem Sheets:\n")
+        if BUNDLED_DIR.exists():
+            for folder in sorted(BUNDLED_DIR.iterdir()):
+                if folder.is_dir() and not folder.name.startswith("."):
+                    files = [f.relative_to(folder).as_posix() for f in folder.rglob("*") if f.is_file()]
+                    print(f"📁 {folder.name} ({len(files)} files)")
+                    for f in files:
+                        print(f"   ├── {f}")
+        print("\n💡 Tip: Run 'heroalgorithm <sheet-number>' to unpack a specific sheet.")
+        return 0
+
+    # Remote GitHub repo list
+    try:
+        owner, repo = parse_repo_string(repo_str)
+        branch = get_branch(args.branch)
+        token = get_token(args.token)
+        print(f"🔍 Inspecting remote catalogue in {owner}/{repo} (branch: {branch})...\n")
+        archive_data = fetch_archive(owner=owner, repo=repo, branch=branch, token=token, silent=True)
+        structure = inspect_archive(archive_data)
+        print("📚 Available Problem Sheets & Lab Files:")
+        for subject, files in sorted(structure.items()):
+            print(f"\n📁 {subject} ({len(files)} files)")
+            for f in files[:8]:
+                print(f"   ├── {f}")
+            if len(files) > 8:
+                print(f"   └── ... and {len(files) - 8} more files")
+        return 0
+    except HeroAlgorithmError as e:
+        print(f"❌ Error: {e}")
+        return 1
+
+
+def handle_config(args: argparse.Namespace) -> int:
+    if args.reset:
+        reset_config()
+        print("✅ Configuration reset to defaults.")
+        return 0
+
+    if args.set_dest:
+        set_destination(args.set_dest)
+        print(f"✅ Default destination set to: '{get_destination()}'")
+
+    if args.set_repo:
+        try:
+            parse_repo_string(args.set_repo)
+            set_repo(args.set_repo)
+            print(f"✅ Default GitHub repo set to: '{args.set_repo}'")
+        except HeroAlgorithmError as e:
+            print(f"❌ {e}")
+            return 1
+
+    if args.set_branch:
+        set_branch(args.set_branch)
+        print(f"✅ Default branch set to: '{args.set_branch}'")
+
+    cfg = load_config()
+    print("\n⚙️  HeroAlgorithm Configuration:")
+    print(f"   • Destination: {get_destination()} {'(custom)' if 'destination' in cfg else '(system default)'}")
+    print(f"   • Remote Repo: {get_repo() or 'None (using bundled offline vault)'}")
+    print(f"   • Config File: {Path.home() / '.heroalgorithm' / 'config.json'}\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="heroalgorithm",
+        description="HeroAlgorithm: Instant AI/ML Lab Problem Sheets, Datasets & Code Vault.",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # download subcommand (default action)
+    p_dl = subparsers.add_parser("download", help="Download / extract problem sheets")
+    p_dl.add_argument(
+        "subject",
+        nargs="?",
+        default=None,
+        help="Problem sheet (e.g. ps-1, 1)",
+    )
+    p_dl.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Target folder (default: C:\\AIML_Assignments)",
+    )
+    p_dl.add_argument(
+        "-r",
+        "--repo",
+        default=None,
+        help="Remote GitHub repository ('owner/repo')",
+    )
+    p_dl.add_argument(
+        "-b",
+        "--branch",
+        default=None,
+        help="Branch name (default: main)",
+    )
+    p_dl.add_argument(
+        "-t",
+        "--token",
+        default=None,
+        help="GitHub PAT for private repos",
+    )
+    p_dl.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        default=True,
+        help="Overwrite existing files",
+    )
+    p_dl.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Run silently without output",
+    )
+    p_dl.set_defaults(func=handle_download)
+
+    # list subcommand
+    p_list = subparsers.add_parser("list", help="List available problem sheets and files")
+    p_list.add_argument("-r", "--repo", default=None, help="Remote GitHub repository")
+    p_list.add_argument("-b", "--branch", default=None, help="Branch name")
+    p_list.add_argument("-t", "--token", default=None, help="GitHub PAT for private repos")
+    p_list.set_defaults(func=handle_list)
+
+    # config subcommand
+    p_cfg = subparsers.add_parser("config", help="View or modify saved settings")
+    p_cfg.add_argument("--set-dest", metavar="PATH", help="Set default destination directory")
+    p_cfg.add_argument("--set-repo", metavar="OWNER/REPO", help="Set default remote repository")
+    p_cfg.add_argument("--set-branch", metavar="BRANCH", help="Set default branch")
+    p_cfg.add_argument("--reset", action="store_true", help="Reset configuration back to defaults")
+    p_cfg.set_defaults(func=handle_config)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    else:
+        argv = list(argv)
+
+    subcommands = {"download", "list", "config", "-h", "--help", "-v", "--version"}
+
+    # Seamless shortcut routing:
+    # 1. `heroalgorithm` -> `heroalgorithm download`
+    # 2. `heroalgorithm 1` -> `heroalgorithm download 1`
+    # 3. `heroalgorithm -o <path>` -> `heroalgorithm download -o <path>`
+    if not argv:
+        argv = ["download"]
+    elif argv[0] not in subcommands:
+        if not argv[0].startswith("-"):
+            argv = ["download"] + argv
+        elif argv[0] not in {"-h", "--help", "-v", "--version"}:
+            argv = ["download"] + argv
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+
+if __name__ == "__main__":
+    sys.exit(main())

heroalgorithm/config.py

@@ -0,0 +1,132 @@
+"""
+Configuration management for HeroAlgorithm.
+Supports user configuration stored in ~/.heroalgorithm/config.json,
+environment variables, and command-line overrides.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+CONFIG_DIR = Path.home() / ".heroalgorithm"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def get_system_default_destination() -> Path:
+    r"""
+    Default target folder for assignments:
+    - Windows: C:\AIML_Assignments (falls back to ~/AIML_Assignments if C:\ is not writable)
+    - macOS / Linux: ~/AIML_Assignments
+    """
+    if sys.platform == "win32":
+        candidate = Path("C:/AIML_Assignments")
+        try:
+            candidate.mkdir(parents=True, exist_ok=True)
+            return candidate
+        except (PermissionError, OSError):
+            return Path.home() / "AIML_Assignments"
+    return Path.home() / "AIML_Assignments"
+
+
+def load_config() -> Dict[str, Any]:
+    """Load configuration from ~/.heroalgorithm/config.json."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(config: Dict[str, Any]) -> None:
+    """Save configuration to ~/.heroalgorithm/config.json."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2)
+
+
+def get_destination(cli_dest: str | None = None) -> Path:
+    r"""
+    Resolve target directory for problem sheets:
+    1. CLI argument (--output / -o)
+    2. Environment variable HEROALGORITHM_DEST
+    3. User saved config
+    4. System default (C:\AIML_Assignments on Windows)
+    """
+    if cli_dest:
+        return Path(cli_dest).expanduser().resolve()
+    env_dest = os.getenv("HEROALGORITHM_DEST")
+    if env_dest:
+        return Path(env_dest).expanduser().resolve()
+    saved = load_config().get("destination")
+    if saved:
+        return Path(saved).expanduser().resolve()
+    return get_system_default_destination().resolve()
+
+
+def get_repo(cli_repo: str | None = None) -> str | None:
+    """
+    Resolve remote GitHub repository if configured.
+    """
+    if cli_repo:
+        return cli_repo.strip()
+    env_repo = os.getenv("HEROALGORITHM_REPO")
+    if env_repo:
+        return env_repo.strip()
+    saved = load_config().get("repo")
+    if saved:
+        return saved.strip()
+    return None
+
+
+def get_branch(cli_branch: str | None = None) -> str:
+    if cli_branch:
+        return cli_branch.strip()
+    env_branch = os.getenv("HEROALGORITHM_BRANCH")
+    if env_branch:
+        return env_branch.strip()
+    saved = load_config().get("branch")
+    if saved:
+        return saved.strip()
+    return "main"
+
+
+def get_token(cli_token: str | None = None) -> str | None:
+    if cli_token:
+        return cli_token.strip()
+    env_token = os.getenv("HEROALGORITHM_TOKEN") or os.getenv("GITHUB_TOKEN")
+    if env_token:
+        return env_token.strip()
+    saved = load_config().get("token")
+    if saved:
+        return saved.strip()
+    return None
+
+
+def set_destination(dest: str) -> None:
+    cfg = load_config()
+    cfg["destination"] = str(Path(dest).expanduser().resolve())
+    save_config(cfg)
+
+
+def set_repo(repo: str) -> None:
+    cfg = load_config()
+    cfg["repo"] = repo.strip()
+    save_config(cfg)
+
+
+def set_branch(branch: str) -> None:
+    cfg = load_config()
+    cfg["branch"] = branch.strip()
+    save_config(cfg)
+
+
+def reset_config() -> None:
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()

heroalgorithm/downloader.py

@@ -0,0 +1,270 @@
+"""
+Downloader and extractor engine for HeroAlgorithm.
+Extracts bundled AIML assignments or synchronizes with remote GitHub repositories safely.
+"""
+
+from __future__ import annotations
+
+import io
+import shutil
+import sys
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+USER_AGENT = "HeroAlgorithm-CLI/0.1.0"
+MAX_ARCHIVE_SIZE_BYTES = 300 * 1024 * 1024  # 300 MB limit
+MAX_FILE_COUNT = 10000                      # 10,000 files limit
+
+BUNDLED_DIR = Path(__file__).parent / "assignments"
+
+
+class HeroAlgorithmError(Exception):
+    """Base exception for HeroAlgorithm operations."""
+    pass
+
+
+def parse_repo_string(repo_str: str) -> Tuple[str, str]:
+    """Parse 'owner/repo' or GitHub URL into (owner, repo)."""
+    cleaned = repo_str.strip().rstrip("/")
+    if cleaned.startswith("https://github.com/"):
+        cleaned = cleaned[len("https://github.com/"):].rstrip(".git")
+    elif cleaned.startswith("http://github.com/"):
+        cleaned = cleaned[len("http://github.com/"):].rstrip(".git")
+
+    parts = cleaned.split("/")
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise HeroAlgorithmError(
+            f"Invalid repository format '{repo_str}'. Expected 'owner/repo'."
+        )
+    return parts[0], parts[1]
+
+
+def matches_filter(first_segment: str, filter_norm: Optional[str]) -> bool:
+    """Normalize and match problem sheet identifiers (e.g. ps-1, 1, ps1)."""
+    if not filter_norm:
+        return True
+    first_segment = first_segment.strip().lower()
+
+    digits_in_filt = "".join(filter(str.isdigit, filter_norm))
+    digits_in_seg = "".join(filter(str.isdigit, first_segment))
+
+    if digits_in_filt and digits_in_seg:
+        if filter_norm.isdigit() or filter_norm.startswith("ps") or "problem" in filter_norm:
+            return int(digits_in_seg) == int(digits_in_filt)
+
+    clean_segment = first_segment.replace("-", "").replace("_", "").replace(" ", "")
+    clean_filter = filter_norm.replace("-", "").replace("_", "").replace(" ", "")
+    return clean_segment == clean_filter or clean_filter in clean_segment
+
+
+def extract_bundled(
+    destination: Path,
+    subject_filter: Optional[str] = None,
+    overwrite: bool = True,
+) -> List[Path]:
+    """
+    Extract bundled problem sheets directly from the installed package
+    to the target destination folder cleanly and silently.
+    """
+    if not BUNDLED_DIR.exists():
+        raise HeroAlgorithmError("Bundled assignments directory not found inside package.")
+
+    destination = destination.expanduser().resolve()
+    destination.mkdir(parents=True, exist_ok=True)
+
+    filter_norm = subject_filter.strip().lower() if subject_filter else None
+    extracted: List[Path] = []
+
+    for item in BUNDLED_DIR.iterdir():
+        rel_name = item.name
+        if rel_name.startswith(".") or rel_name == "__pycache__":
+            continue
+
+        if filter_norm and item.is_dir() and not matches_filter(rel_name, filter_norm):
+            continue
+
+        target = destination / rel_name
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            for sub_file in item.rglob("*"):
+                if sub_file.name.startswith(".") or "__pycache__" in sub_file.parts:
+                    continue
+                sub_rel = sub_file.relative_to(item)
+                sub_target = target / sub_rel
+                if sub_file.is_dir():
+                    sub_target.mkdir(parents=True, exist_ok=True)
+                else:
+                    sub_target.parent.mkdir(parents=True, exist_ok=True)
+                    if sub_target.exists() and not overwrite:
+                        continue
+                    shutil.copy2(sub_file, sub_target)
+                    extracted.append(sub_target)
+        else:
+            if target.exists() and not overwrite:
+                continue
+            shutil.copy2(item, target)
+            extracted.append(target)
+
+    return extracted
+
+
+def fetch_archive(
+    owner: str,
+    repo: str,
+    branch: str = "main",
+    token: Optional[str] = None,
+    timeout: int = 60,
+    silent: bool = True,
+) -> bytes:
+    """Download zipball from GitHub."""
+    if token:
+        url = f"https://api.github.com/repos/{owner}/{repo}/zipball/{branch}"
+        headers = {
+            "User-Agent": USER_AGENT,
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+        }
+    else:
+        url = f"https://codeload.github.com/{owner}/{repo}/zip/refs/heads/{branch}"
+        headers = {
+            "User-Agent": USER_AGENT,
+            "Accept": "*/*",
+        }
+
+    request = urllib.request.Request(url, headers=headers)
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            chunks: List[bytes] = []
+            downloaded = 0
+            chunk_size = 64 * 1024
+
+            while True:
+                chunk = response.read(chunk_size)
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                downloaded += len(chunk)
+                if downloaded > MAX_ARCHIVE_SIZE_BYTES:
+                    raise HeroAlgorithmError("Remote archive exceeds safety limit.")
+
+            return b"".join(chunks)
+
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            raise HeroAlgorithmError(f"Repository or branch not found: '{owner}/{repo}'.") from e
+        elif e.code in (401, 403):
+            raise HeroAlgorithmError(f"Access denied ({e.code}) for '{owner}/{repo}'.") from e
+        else:
+            raise HeroAlgorithmError(f"HTTP Error {e.code} while connecting to GitHub.") from e
+    except urllib.error.URLError as e:
+        raise HeroAlgorithmError(f"Network error: {e.reason}") from e
+
+
+def is_safe_path(target_path: Path, base_dir: Path) -> bool:
+    try:
+        target_path.resolve().relative_to(base_dir.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def get_archive_root_prefix(archive: zipfile.ZipFile) -> str:
+    names = archive.namelist()
+    if not names:
+        return ""
+    first = names[0].split("/")[0]
+    prefix = f"{first}/"
+    if all(name.startswith(prefix) or name == first for name in names):
+        return prefix
+    return ""
+
+
+def extract_archive(
+    archive_data: bytes,
+    destination: Path,
+    subject_filter: Optional[str] = None,
+    overwrite: bool = True,
+) -> List[Path]:
+    """Extract files safely and silently."""
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(archive_data))
+    except zipfile.BadZipFile as e:
+        raise HeroAlgorithmError("Invalid archive payload.") from e
+
+    members = archive.infolist()
+    if len(members) > MAX_FILE_COUNT:
+        raise HeroAlgorithmError(f"Archive exceeds {MAX_FILE_COUNT} files limit.")
+
+    destination = destination.expanduser().resolve()
+    destination.mkdir(parents=True, exist_ok=True)
+
+    root_prefix = get_archive_root_prefix(archive)
+    extracted: List[Path] = []
+    filter_norm = subject_filter.strip().lower() if subject_filter else None
+
+    for member in members:
+        filename = member.filename
+        rel_name = filename[len(root_prefix):] if root_prefix and filename.startswith(root_prefix) else filename
+        rel_name = rel_name.lstrip("/\\")
+
+        if not rel_name or rel_name.startswith(".git") or "__pycache__" in rel_name:
+            continue
+
+        first_seg = rel_name.split("/")[0]
+        if filter_norm and not matches_filter(first_seg, filter_norm):
+            continue
+
+        target_path = (destination / rel_name).resolve()
+        if not is_safe_path(target_path, destination):
+            raise HeroAlgorithmError(f"Illegal path traversal detected in '{filename}'.")
+
+        if member.is_dir():
+            target_path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        if target_path.exists() and not overwrite:
+            continue
+
+        with archive.open(member) as src, open(target_path, "wb") as dst:
+            dst.write(src.read())
+
+        extracted.append(target_path)
+
+    return extracted
+
+
+def inspect_archive(archive_data: bytes) -> Dict[str, List[str]]:
+    """Inspect archive without extracting."""
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(archive_data))
+    except zipfile.BadZipFile as e:
+        raise HeroAlgorithmError("Invalid archive payload.") from e
+
+    root_prefix = get_archive_root_prefix(archive)
+    structure: Dict[str, List[str]] = {}
+
+    for member in archive.infolist():
+        rel_name = member.filename
+        if root_prefix and rel_name.startswith(root_prefix):
+            rel_name = rel_name[len(root_prefix):]
+
+        rel_name = rel_name.strip("/")
+        if not rel_name:
+            continue
+
+        parts = rel_name.split("/")
+        subject = parts[0] if len(parts) > 1 else "(Root)"
+        if member.is_dir():
+            if subject not in structure:
+                structure[subject] = []
+            continue
+
+        file_display = "/".join(parts[1:]) if len(parts) > 1 else parts[0]
+        structure.setdefault(subject, []).append(file_display)
+
+    return structure

heroalgorithm-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: heroalgorithm
+Version: 0.1.0
+Summary: Instant AI/ML lab problem sheets, datasets, notebooks, and algorithms vault.
+Author: HeroAlgorithm Maintainer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AdityaxDeore/heroalgorithm
+Project-URL: Repository, https://github.com/AdityaxDeore/heroalgorithm.git
+Keywords: heroalgorithm,aiml,machine-learning,problem-sheets,datasets,jupyter-notebook,algorithms,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ⚡ HeroAlgorithm
+
+> **Instant AI/ML Problem Sheets, Datasets & Code Vault**  
+> Download, extract, and organize all your AI & Machine Learning lab assignments, problem sheets, datasets, Jupyter Notebooks (`.ipynb`), and Python scripts cleanly onto your PC with a single command.
+
+[![PyPI Version](https://img.shields.io/pypi/v/heroalgorithm.svg)](https://pypi.org/project/heroalgorithm/)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20runtime-brightgreen.svg)]()
+
+---
+
+## 🌟 The Magic Experience
+
+Install and organize all your AI/ML lab problem sheets into `C:\AIML_Assignments` in one step:
+
+```powershell
+pip install heroalgorithm; heroalgorithm
+```
+
+Or run `heroalgorithm` anytime in your terminal:
+
+```powershell
+heroalgorithm
+```
+
+And your C: drive folder is cleanly populated:
+
+```text
+C:\AIML_Assignments\
+├── PS-1/
+│   ├── dataset/
+│   │   └── data.csv
+│   ├── notebook.ipynb
+│   ├── solution.py
+│   └── README.md
+├── PS-2/
+│   ├── dataset/
+│   │   └── housing.csv
+│   ├── notebook.ipynb
+│   ├── solution.py
+│   └── README.md
+└── PS-3/
+    ├── dataset/
+    │   └── iris.csv
+    ├── notebook.ipynb
+    ├── solution.py
+    └── README.md
+```
+
+> **Clean & Quiet by Design:** No noisy spam or "installing file x" lines. Everything stays hidden and extracts quietly into your folder!
+
+---
+
+## 🚀 Key Features
+
+- ⚡ **Bundled Offline Vault**: Problem sheets, datasets, notebooks, and solutions are packaged directly inside the package. Works 100% offline without needing GitHub.
+- 📁 **Automatic C: Drive Placement**: Automatically organizes files into `C:\AIML_Assignments` on Windows (or `~/AIML_Assignments`).
+- 🎯 **Selective Extraction**: Run `heroalgorithm 1` or `heroalgorithm ps-1` to unpack just Problem Sheet 1.
+- 🤫 **Silent Mode**: Zero annoying logs. Use `-q` or `--quiet` for 100% silent execution.
+- 🔄 **GitHub Sync (Optional)**: Connect to a remote GitHub repository anytime with `heroalgorithm config --set-repo <user>/<repo>` to sync the latest assignments.
+- 🪶 **Zero Dependencies**: 100% built on Python's standard library. Instant installation.
+
+---
+
+## 🛠️ Usage Examples
+
+### 1. Extract All Problem Sheets to C:\AIML_Assignments
+```powershell
+heroalgorithm
+```
+
+### 2. Extract Only Problem Sheet 1
+```powershell
+# Shorthand:
+heroalgorithm 1
+
+# Or:
+heroalgorithm ps-1
+```
+
+### 3. Choose a Custom Output Folder
+```powershell
+heroalgorithm -o "D:\MyCollege\AI_Lab"
+```
+
+### 4. Run Completely Silently
+```powershell
+heroalgorithm -q
+```
+
+### 5. Preview Available Problem Sheets
+```powershell
+heroalgorithm list
+```
+
+### 6. Configure Default Destination or Remote Repo
+```powershell
+# Change default destination:
+heroalgorithm config --set-dest "D:\AIML_Lab"
+
+# Connect to a GitHub repository:
+heroalgorithm config --set-repo your-username/aiml-assignments
+
+# Check active configuration:
+heroalgorithm config
+```
+
+---
+
+## 🚢 Publishing to PyPI (Step-by-Step)
+
+The package name **`heroalgorithm`** is verified available on PyPI!
+
+### Step 1: Build the Package
+```powershell
+python -m build
+```
+This creates the distribution files in `dist/`:
+- `heroalgorithm-0.1.0-py3-none-any.whl`
+- `heroalgorithm-0.1.0.tar.gz`
+
+### Step 2: Upload to PyPI
+```powershell
+python -m twine upload dist/*
+```
+*(Enter `__token__` as the username, and paste your PyPI API Token as the password).*
+
+Once published, anyone in the world can run:
+```powershell
+pip install heroalgorithm; heroalgorithm
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

heroalgorithm-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+heroalgorithm/__init__.py,sha256=--Ia2TfkFLGnLww0Kz8jCPLB9Z-w-y5l5xQ-c7oNctg,132
+heroalgorithm/cli.py,sha256=aGqie9mHpEIe4I8nbLMcxZIkBdCLJous6-Jjm8ihvn4,9359
+heroalgorithm/config.py,sha256=PZhzuQUE3y-E88QcPzI9PlHjXbJUk8XIL_IT2o9iw2M,3703
+heroalgorithm/downloader.py,sha256=DMv00LuD_EXURMpL2O7ZTomsYdfIctnOl-nPR6DNQeo,9197
+heroalgorithm/assignments/README.md,sha256=xxe71YI_Ohnp1CjrdLmPfQLDPEJasdy4HyU5-_2sfqo,668
+heroalgorithm/assignments/PS-1/README.md,sha256=pQYdMwXqpzBc_G2-VrQcqwuXPXkbdOIer0gq2F2gQYc,365
+heroalgorithm/assignments/PS-1/notebook.ipynb,sha256=U1_UtlY88eRYjsMQaSxKYWpICX364ZT4Lx2oUhYVBmE,634
+heroalgorithm/assignments/PS-1/solution.py,sha256=A9Vibm9diUCrG7fGPzBaAFBgR2kJRGuYzYEagRCnpIg,691
+heroalgorithm/assignments/PS-1/dataset/data.csv,sha256=tAb2VmXVN0QD3KuphgL3rhbJKeQr7b28XKs9DMb4KUQ,85
+heroalgorithm/assignments/PS-2/README.md,sha256=I6qu7UfC1Yk6g8-sMhB9TCRHe2jSDiXvdWdyYkuAt1c,134
+heroalgorithm/assignments/PS-2/notebook.ipynb,sha256=XNzUC1Hp5AFFqHKG5EEiKiS2IXIs3N-BN1k1_ovtsbA,643
+heroalgorithm/assignments/PS-2/solution.py,sha256=ChhaOS9q8B0Baj8sTJbmbram9LhoHYZFpxtOkDw03qM,294
+heroalgorithm/assignments/PS-2/dataset/housing.csv,sha256=ZC-rDpAbVtyk2jnFweeLECkRhTuHGP6HuIufroDJ3XQ,80
+heroalgorithm/assignments/PS-3/README.md,sha256=ypthFXdc5S_kiUzetXYwcFAaJDXMBjYlDN2We0Z-qdw,141
+heroalgorithm/assignments/PS-3/notebook.ipynb,sha256=EFFvCQyv0im3eiXgcNlNb-gJ1ZXIDjrUQwDn-fpgLUk,629
+heroalgorithm/assignments/PS-3/solution.py,sha256=kWg-e78iBmRxFRm2dqtxpziDAERHxyHtyoHplV3auZE,289
+heroalgorithm/assignments/PS-3/dataset/iris.csv,sha256=4yQWcLCQdulLfqX8RbVvD2LF0gsqsWf8kagMgurhjTc,138
+heroalgorithm-0.1.0.dist-info/licenses/LICENSE,sha256=kV-nU8WE--XMKqR83AfoIBw9xwjGDLVwaXotCTrIaRM,1081
+heroalgorithm-0.1.0.dist-info/METADATA,sha256=WQHq5z-wCiOy2NSO50dLAMNYCivthw8V8M3NnCXPBio,5203
+heroalgorithm-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+heroalgorithm-0.1.0.dist-info/entry_points.txt,sha256=rO5Idb7pe9dHY7pf1aubIdFWYdwT-12XVH36Owv4HSo,87
+heroalgorithm-0.1.0.dist-info/top_level.txt,sha256=VzSRNFjblVRX-YX3fYqMmNGx3a84whGUIHpvmw3mEDE,14
+heroalgorithm-0.1.0.dist-info/RECORD,,

heroalgorithm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

heroalgorithm-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+hero = heroalgorithm.cli:main
+heroalgorithm = heroalgorithm.cli:main

heroalgorithm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AssignVault Contributors
+
+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.

heroalgorithm-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+heroalgorithm