Metadata-Version: 2.4
Name: vtu-ml-lab
Version: 1.1.0
Summary: VTU Machine Learning Lab programs — library, viewer, and exam assistant
Author-email: Pratham Balehosur <pratham.balehosur@example.com>
Project-URL: Homepage, https://github.com/prathamb/vtu-ml-lab
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scikit-learn>=1.3
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Requires-Dist: numpy>=1.24
Requires-Dist: statsmodels>=0.14
Dynamic: license-file

# vtu-ml-lab

[![PyPI version](https://img.shields.io/pypi/v/vtu-ml-lab.svg)](https://pypi.org/project/vtu-ml-lab/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

**vtu-ml-lab** is a comprehensive Python library, interactive viewer, and command-line examination assistant tailored for VTU Machine Learning Laboratory (21CS63 / 18CSL76 / similar schemes). It is designed to help students and educators view, save, execute, and prepare for exams with inline viva questions and memory tricks.

---

## Features

- **All 10 Lab Programs**: Ready-to-use, clean, and fully-commented implementations of standard VTU Machine Learning laboratory algorithms.
- **Dual Viewer Support**: Seamless rendering of code with syntax highlighting in Jupyter Notebooks (`IPython.display.Code`) and standard outputs in standard terminals.
- **Code Saver**: Export any lab script instantly to a file, automatically building any missing parent directories.
- **Isolated Execution**: Execute lab code locally in isolated namespaces, with options to prompt for confirmations or run non-interactively (Google Colab / script environments).
- **Exam Assistant / Viva Prep**: Embedded metadata including 6–8 inline Viva Q&As per lab, step-by-step logic, and specific memory mnemonics for memorization.
- **Interactive CLI**: Rich, argument-parsed command-line utility with shortcuts.

---

## Project Structure

| File / Folder | Description |
| :--- | :--- |
| `vtu_ml_lab/` | Core package folder |
| `├── __init__.py` | Package entry point, exposing standard APIs |
| `├── programs.py` | Central database containing code, titles, and metadata for all 10 programs |
| `├── viewer.py` | Code retrieval, listing, and Jupyter-sensitive code display helpers |
| `├── saver.py` | Disk storage helper with automatic directory creation |
| `├── runner.py` | Clean python execution engine using isolated dictionary scope namespaces |
| `├── metadata.py` | Query helpers for Viva lists, logic guides, memory tricks, and expected outputs |
| `└── cli.py` | Command line routing, supporting argument parsing and digit shortcuts |
| `tests/` | Unit testing suites |
| `├── test_vtu_ml_lab.py` | Complete `pytest` suites verifying API behavior and metadata sanity |
| `pyproject.toml` | Standard modern build setup, dependencies, and script routing |
| `setup.py` | Minimal legacy compatibility wrapper |
| `requirements.txt` | Clean development dependency lists |
| `LICENSE` | MIT License |

---

## Installation

Install directly from PyPI:
```bash
pip install vtu-ml-lab
```

For development or local setup:
```bash
git clone https://github.com/prathamb/vtu-ml-lab.git
cd vtu-ml-lab
pip install -r requirements.txt
pip install -e .
```

### Dependencies
- `scikit-learn >= 1.3`
- `pandas >= 2.0`
- `matplotlib >= 3.7`
- `seaborn >= 0.12`
- `numpy >= 1.24`
- `statsmodels >= 0.14`

---

## Python API Usage

Here is how you can use `vtu-ml-lab` programmatically within your Python scripts or Jupyter Notebooks:

```python
import vtu_ml_lab as ml

# 1. List all available lab programs
ml.list_programs()

# 2. Get program code as a string
code_str = ml.get_program(3)
print(code_str[:200])

# 3. View program inside terminal or Jupyter
ml.show_program(3)

# 4. Save program to disk (defaults to lab<N>.py if path not specified)
ml.save_program(3, "my_labs/lab3_pca.py")

# 5. Run the lab program (confirm=True prompts the user first)
ml.run_program(3, confirm=False)

# 6. Retrieve Exam Study Material
print("Viva Q&As:", ml.get_viva(3))
print("Memory Mnemonic:", ml.get_memory_trick(3))
print("Key Lines of Code:", ml.get_important_lines(3))
print("Program Logic:", ml.get_logic(3))
print("Expected Output:", ml.get_output(3))
```

---

## CLI Usage

The package exposes a `vtu-ml-lab` CLI script when installed.

### List available programs:
```bash
vtu-ml-lab list
```

### Display code for a program:
```bash
vtu-ml-lab show 3
```
*Or use the bare integer shortcut:*
```bash
vtu-ml-lab 3
```

### Save code to file:
```bash
# Saves as lab3.py in current directory
vtu-ml-lab save 3

# Saves to custom path, automatically creating parent directories
vtu-ml-lab save 3 my_workspace/lab3_iris_pca.py
```

### Execute a program:
```bash
# Prompts for confirmation before running
vtu-ml-lab run 3

# Runs directly without interactive confirmation (ideal for scripts/Colab)
vtu-ml-lab run 3 --yes
```

### Get Viva Q&As:
```bash
vtu-ml-lab viva 3
```

### Get Memory Trick:
```bash
vtu-ml-lab trick 3
```

### Get Step-by-step Logic:
```bash
vtu-ml-lab logic 3
```

### Get Key Lines of Code:
```bash
vtu-ml-lab lines 3
```

### Get Expected Output Details:
```bash
vtu-ml-lab output 3
```

---

## PyPI Publishing Steps

Follow these steps to build and upload the package to PyPI:

1. **Verify Local Setup**:
   Ensure you have `build` and `twine` installed:
   ```bash
   pip install --upgrade build twine
   ```

2. **Run Tests**:
   Ensure all package tests are passing:
   ```bash
   pytest tests/ -v
   ```

3. **Build the Distribution Packages**:
   Build the source distribution and wheel:
   ```bash
   python -m build
   ```
   This will create a `dist/` directory containing `.tar.gz` and `.whl` files.

4. **Verify Build Contents**:
   Verify that files are packaged correctly:
   ```bash
   twine check dist/*
   ```

5. **Upload to TestPyPI (Optional but Recommended)**:
   Upload to the TestPyPI registry to verify packaging:
   ```bash
   python -m twine upload --repository testpypi dist/*
   ```
   Provide your TestPyPI API token when prompted.

6. **Upload to PyPI**:
   Upload the final package to the live PyPI registry:
   ```bash
   python -m twine upload dist/*
   ```
   Provide your PyPI API token when prompted.

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Author: **Pratham Balehosur**
