Metadata-Version: 2.4
Name: ml-project-scaffold
Version: 0.1.1
Summary: CLI tool for generating machine learning project structures
Author: Erik
License-Expression: MIT
Project-URL: Homepage, https://github.com/KishlakEnjoyer/ml-project-generator
Project-URL: Repository, https://github.com/KishlakEnjoyer/ml-project-generator
Project-URL: Issues, https://github.com/KishlakEnjoyer/ml-project-generator/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Dynamic: license-file

<div align="center">

# ML Project Generator

**A CLI tool for quickly scaffolding machine learning projects**

Python 3.10+ · Typer · MIT License

[Русский](README.md) · English

</div>

ML Project Generator creates a ready-to-use ML project skeleton with directories
for data, models, and notebooks, basic Python files, a `.gitignore`, and a list
of dependencies. Start with a general-purpose template or choose a structure
designed for Scikit-learn or PyTorch.

## Features

- three templates: `basic`, `sklearn`, and `pytorch`;
- automatic creation of directories and files;
- automatic `requirements.txt` generation;
- optional Jupyter dependency with `--jupyter`;
- optional Matplotlib and Seaborn dependencies with `--plotting`;
- dedicated README and `.gitignore` files for generated projects.

## Requirements

You need:

- Python 3.10 or newer;
- `pip`;
- Git, only when installing by cloning the repository.

Check your Python version:

```bash
python --version
```

## Installation

### Quick installation on Windows

Clone the repository and run the installer:

```powershell
git clone https://github.com/KishlakEnjoyer/ml-project-generator.git
cd ml-project-generator
.\install.bat
```

The installer will automatically:

- verify that Python 3.10+ is available;
- install `pipx`;
- add the CLI application directory to `PATH`;
- install the `ml-init` command.

Close and reopen your terminal after installation. You can then run `ml-init`
from any directory:

```powershell
ml-init --help
```

Run `install.bat` again to update the installed command from your current local
copy of the repository.

### Manual installation for development

An editable installation is more convenient when changing the source code.
Create a virtual environment:

```bash
python -m venv .venv
```

Activate it.

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Linux and macOS:

```bash
source .venv/bin/activate
```

Install the tool:

```bash
python -m pip install -e .
```

The `ml-init` command is now available in the active environment.

## Quick start

Create a basic ML project:

```bash
ml-init my-project
```

Create a Scikit-learn project:

```bash
ml-init churn-prediction sklearn
```

Create a PyTorch project with Jupyter and plotting libraries:

```bash
ml-init image-classifier pytorch --jupyter --plotting
```

The project is created in the current directory. For example, the last command
creates an `image-classifier` directory.

## Usage

```text
ml-init NAME [TEMPLATE] [OPTIONS]
```

### Arguments

| Argument | Description | Default |
|---|---|---|
| `NAME` | Name and directory of the new project | required |
| `TEMPLATE` | Template: `basic`, `sklearn`, or `pytorch` | `basic` |

### Options

| Option | Short form | Description |
|---|---|---|
| `--jupyter` | `-j` | Add `jupyter` to the project dependencies |
| `--plotting` | `-p` | Add `matplotlib` and `seaborn` |
| `--version` | `-v` | Display the tool version |
| `--help` |  | Display command help |

Display the built-in help:

```bash
ml-init --help
```

## Templates

### `basic`

A minimal, general-purpose structure for experiments and small ML projects. It
contains `data`, `models`, `notebooks`, `src`, and `tests` directories.

```bash
ml-init experiment basic
```

### `sklearn`

A structure for classical machine learning projects. It includes separate files
for data loading, preprocessing, training, evaluation, and prediction.

```bash
ml-init tabular-model sklearn
```

Main dependencies: NumPy, Pandas, Scikit-learn, and Joblib.

### `pytorch`

A structure for deep learning projects. It includes files for the Dataset,
model, training, evaluation, and inference, along with `checkpoints` and
`outputs` directories.

```bash
ml-init neural-network pytorch
```

Main dependencies: PyTorch, NumPy, and tqdm.

## After generating a project

Enter the generated directory:

```bash
cd my-project
```

Create a separate virtual environment:

```bash
python -m venv .venv
```

Activate it on Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Or on Linux and macOS:

```bash
source .venv/bin/activate
```

Install the generated project dependencies:

```bash
python -m pip install -r requirements.txt
```

You can now place source datasets in `data/raw`, experiments in `notebooks`,
and reusable application code in `src`.

## Example generated structure

```text
my-project/
├── data/
│   ├── raw/
│   └── processed/
├── models/ or checkpoints/
├── notebooks/
├── src/
├── tests/
├── .gitignore
├── README.md
└── requirements.txt
```

The exact set of files depends on the selected template.

## Development

Install the project in editable mode together with Pytest:

```bash
python -m pip install -e . pytest
```

Run the test suite:

```bash
pytest
```

Preset files are located in `src/mlproject/presets`. Each template defines
three values:

- `DEPENDENCIES` — dependencies for the generated project;
- `DIRECTORIES` — directories to create;
- `FILES` — files to create and their contents.

## License

This project is distributed under the [MIT License](LICENSE).
