# {{ 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), using **[uv](https://docs.astral.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`.

{%- if use_config or use_env %}
### ⚙️ Configuration

{%- if use_config %}
- **Config**: `src/{{ package_name }}/config.yaml` (Loaded automatically)
{%- endif %}
{%- if use_env %}
- **Environment**: `src/{{ package_name }}/.env` (Isolated variables)
- **Template**: `src/{{ package_name }}/.env.example` (Copy this to `.env`)
{%- endif %}

The project uses a **Config-in-Package** architecture:
{%- if use_config %}
1. `config.yaml` is inside the package.
1. `config.py` loads it safely (even in production wheels).
{%- endif %}
{%- if use_env %}
1. `.env` is isolated within the package source.
1. `.env.example` serves as a template for new developers.
{%- endif %}
{%- endif %}

---

{%- if not is_subpackage %}
## 🚀 Getting Started

### Prerequisites

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

### Installation

```bash
# Ensure you are in the project directory
cd {{ project_name }}

# Sync dependencies (creates .venv and installs python if needed)
uv sync
```
{%- endif %}

## 🧑‍💻 Usage

### For Developers (Code)

To run the package entry point or scripts:

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

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

{%- if project_type in ['ml', 'dl'] and not is_subpackage %}
### 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.

### ☁️ Cloud (Colab / Kaggle)

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

**Step 1: Install directly from Git**
```python
!pip install url_to_repo.git
```

**Step 2: Use the unified config**
```python
{%- if project_type == 'classic' %}
from {{ package_name }} import SETTINGS
{%- else %}
from {{ package_name }} import get_dataset_path, SETTINGS
import kagglehub as kh
{%- endif %}

# Transparency: You can inspect what was loaded
print(f"Loaded config for: {SETTINGS.get('project_name', 'Unknown')}")

{%- if project_type != 'classic' %}
# Download datasets defined in config.yaml
# The key 'titanic' maps to 'heptapod/titanic' in the yaml
if 'datasets' in SETTINGS and 'titanic' in SETTINGS['datasets']:
    path = kh.dataset_download(SETTINGS['datasets']['titanic'])
{%- endif %}
```
{%- endif %}

## 🔧 Internal Structure

```text
{%- if is_subpackage %}
{{ package_name }}/
├── __init__.py
{%- if use_config %}
├── config.yaml # EDIT THIS for project settings
├── config.py   # Code that loads the yaml above
{%- endif %}
{%- if use_env %}
├── .env        # Secrets (Ignored by git)
├── .env.example # Template for secrets
{%- endif %}
{%- if use_tests %}
└── tests/      # Unit tests
{%- endif %}
{%- else %}
{{ project_name }}/
├── pyproject.toml      # The Single Source of Truth (Dependencies, Metadata)
├── uv.lock             # Exact versions lockfile
├── .python-version     # Pinned Python version
├── src/
{%- if packages %}
{%- for pkg in packages %}
│   └── {{ pkg.clean_name }}/
│       ├── __init__.py
{%- if pkg.use_config %}
│       ├── config.yaml # EDIT THIS for project settings
│       ├── config.py   # Code that loads the yaml above
{%- endif %}
{%- if pkg.use_env %}
│       ├── .env        # Secrets (Ignored by git)
│       ├── .env.example # Template for secrets
{%- endif %}
{%- if pkg.use_tests %}
│       └── tests/      # Unit tests
{%- endif %}
{%- endfor %}
{%- else %}
│   └── {{ package_name }}/
│       ├── __init__.py
{%- if use_config %}
│       ├── config.yaml # EDIT THIS for project settings
│       ├── config.py   # Code that loads the yaml above
{%- endif %}
{%- if use_env %}
│       ├── .env        # Secrets (Ignored by git)
│       ├── .env.example # Template for secrets
{%- endif %}
{%- if use_tests %}
│       └── tests/      # Unit tests
{%- endif %}
{%- endif %}
{%- if project_type in ['ml', 'dl'] %}
└── notebooks/          # Experimentation (Jupyter)
{%- endif %}
{%- endif %}
```
