# {{ project_name }}

{{ description }}

---

## 🧐 Philosophy & Architecture

Values transparency and standard tooling over "black box" magic.
This project was generated with [ViperX](https://github.com/kpihx/viperx).sh/uv/)**, the extremely fast Python package and project manager written in Rust.

### Why `uv`?
Unlike traditional workflows (pip, poetry, venv mixing), `uv` manages the **entire lifecycle**:
- **Python Version**: It installs and manages the correct Python version for this project automatically.
- **Dependencies**: Locking is instant.
{% if project_type == 'dl' %}
- **Stack**: {{ framework|title }}
{% endif %}
- **Environment**: Virtual environments are managed internally, you just run `uv run`.

### ⚙️ Configuration

- **Config**: `src/{{ package_name }}/config.yaml` (Loaded automatically)
{% if has_config %}
- **Environment**: `src/{{ package_name }}/.env` (Isolated variables)
{% endif %}

Edit `config.yaml` to change parameters. The project uses a **Config-in-Package** architecture:
1. `config.yaml` is inside the package.
2. `config.py` loads it safely (even in production wheels).
3. `.env` is isolated within the package source.

---

## 🚀 Getting Started

### Prerequisites

You only need **[uv](https://docs.astral.sh/uv/)**.
No need to install Python or create venvs manually.

### Installation

```bash
# Clone the repo
git clone https://github.com/{{ author_name | lower | replace(" ", "") }}/{{ project_name }}.git
cd {{ project_name }}

# Sync dependencies (creates .venv and installs python if needed)
uv sync
```

## 🧑‍💻 Usage

The entry point depends on your project type.

### For Developers (Code)

To run the package entry point or scripts:

```bash
# Run the main package
uv run {{ package_name }}

# Or run a specific script
uv run python src/{{ package_name }}/main.py
```

{% if project_type in ['ml', 'dl'] %}
### For Data Scientists (Notebooks)

We use `uv` to launch Jupyter, ensuring it sees the local package and config.

```bash
uv run jupyter notebook
```

- Open `notebooks/Base.ipynb`.
- Note how it imports `config` from the package.
{% endif %}

### ☁️ Cloud (Colab / Kaggle)

You can use the code and config from this repository directly in cloud environments without cloning.

**Step 1: Install directly from GitHub**
```python
!pip install git+https://github.com/{{ author_name | lower | replace(" ", "") }}/{{ project_name }}.git
```

**Step 2: Use the unified config**
```python
from {{ package_name }} import get_dataset_path, SETTINGS
import kagglehub as kh

# Transparency: You can inspect what was loaded
print(f"Loaded config for: {SETTINGS['project_name']}")

# Download datasets defined in config.yaml
# The key 'titanic' maps to 'heptapod/titanic' in the yaml
path = kh.dataset_download(SETTINGS['datasets']['titanic'])
```

## 🔧 Internal Structure

```text
{{ project_name }}/
├── pyproject.toml      # The Single Source of Truth (Dependencies, Metadata)
├── uv.lock             # Exact versions lockfile
├── .python-version     # Pinned Python version
├── src/
│   └── {{ package_name }}/
│       ├── __init__.py
│       ├── config.yaml # EDIT THIS for project settings
│       ├── config.py   # Code that loads the yaml above
│       └── tests/      # Unit tests
{% if project_type in ['ml', 'dl'] %}
└── notebooks/          # Experimentation (Jupyter)
{% endif %}
```


