# Python AI Dev Template

![Python](https://img.shields.io/badge/python-3.11+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Style](https://img.shields.io/badge/code%20style-black-000000)
![Lint](https://img.shields.io/badge/lint-ruff-red)
![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)

A universal and adaptable **Python project template** designed for professional development and AI‑assisted coding workflows (OpenCode, AI agents, etc.).

License: MIT

This repository provides a clean and production‑ready starting point for building:

- CLI tools
- backend services
- automation scripts
- desktop applications
- internal developer tools

The template enforces **modern Python standards**, **clean architecture**, and **automated quality checks**.

---

# Requirements

- Python **3.11+**
- `pyenv` recommended for Python version management

Check Python version:

```bash
python --version
```

---

# Quick Start

Clone the template repository:

```bash
git clone <template-repository-url> new-project
cd new-project
```

Create a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
```

Install development dependencies:

```bash
pip install --upgrade pip
pip install -e '.[dev]'
```

---

# Using the Makefile (Recommended)

This template includes a **Makefile** to simplify common development tasks.

### First time setup

To prepare the full development environment automatically:

```bash
make dev
```

This command will:

- create the `.venv` virtual environment
- install project dependencies
- install development tools
- configure `pre-commit` hooks

This is the **recommended command after cloning the repository**.

### Reinstall or update dependencies

If the virtual environment already exists and you only want to reinstall or update dependencies:

```bash
make install
```

### Development utilities

Some useful commands:

```bash
make fix        # auto‑format and fix code issues
make quality    # run full quality checks
make ci         # simulate CI validation
make doctor     # show environment and tool versions
make run        # run the application
```

Using the Makefile ensures a consistent development workflow across machines.

---

# Environment Configuration

This template supports **environment-based configuration** using a `.env` file.

An example configuration file is provided:

```
.env.example
```

To create your local configuration, copy the example file:

```bash
cp .env.example .env
```

Then edit `.env` and adjust the values for your local environment.

Typical uses include:

- application settings
- API endpoints
- API keys
- database connection strings
- feature flags

⚠️ The `.env` file is **ignored by git** and should **never contain secrets in the repository**.

Only `.env.example` should be committed.

---

# Run the Application

```bash
python -m app.main
```

Expected output:

```
cd-browser is ready.
```

---

# Development Workflow

Before committing changes, always validate the project using the following steps.

### 1. Run the application

```bash
python -m app.main
```

### 2. Run tests

```bash
pytest
```

### 3. Format code

```bash
black src tests
```

### 4. Check formatting

```bash
black --check src tests
```

### 5. Lint code

```bash
ruff check src tests
```

### 6. Type checking

```bash
mypy src
```

If all commands succeed, the project is considered valid.

---

# Quick Quality Check

Run all checks quickly:

```bash
black src tests
ruff check src tests
mypy src
pytest
```

---


# Create a New Repository From This Template

If you downloaded or cloned this template and want to start a **new project repository**, follow these steps.

### 1. Clone the template

```bash
git clone https://gitea.sakydogalo.es/saky/python-ai-dev-template.git new-project
cd new-project
```

### Recommended: Initialize the project automatically

You can initialize a new project using the helper script:

```bash
./scripts/init_project.sh my-project-name
```

This script will:

- reset the git history
- prepare the repository for a fresh start
- keep the template structure intact

After running the script, create your new remote repository and push the code as described below.

---

### Manual initialization (alternative)

If you prefer to perform the steps manually, follow the instructions below.

### 2. Remove the original remote

```bash
git remote remove origin
```

### 3. Reset Git history (start clean)

```bash
rm -rf .git
git init
```

### 4. Update project metadata

Update these files to match your new project:

- `pyproject.toml` → project name and description
- `README.md`
- `src/app/config.py` → application name

### 5. Validate the project

```bash
make fix
make quality
```

### 6. Create your new repository

Create a new repository on your Git server (Gitea, GitHub, etc.).

Example:

```
https://gitea.sakydogalo.es/saky/new-project
```

### 7. Connect the new remote

```bash
git remote add origin <your-new-repository-url>
```

### 8. Create the first commit

```bash
git add .
git commit -m "Initial new-project from template"
```

### 9. Push to the new repository

```bash
git branch -M main
git push -u origin main
```

Your new project repository is now ready.

---

# Project Structure

```
new-project/
│
├── src/
│   └── app/
│       ├── main.py
│       ├── config.py
│       ├── logging_config.py
│       ├── services/
│       ├── domain/
│       ├── infrastructure/
│       └── utils/
│
├── tests/
│   └── test_smoke.py
│
├── scripts/
│
├── pyproject.toml
├── instructions-agent.md
├── README.md
└── .editorconfig
```

---

# Tooling

This template includes modern Python development tools:

| Tool | Purpose |
|-----|--------|
| pytest | testing framework |
| black | automatic code formatting |
| ruff | linting and static analysis |
| mypy | static type checking |

---

# Purpose of this Template

This repository is intentionally **generic and adaptable**.

It can evolve into:

- a CLI tool
- a web API
- a microservice
- a desktop application
- an automation system

The goal is to provide a **clean, maintainable, and AI‑friendly Python project foundation**.

---

# AI Agent Support

This repository includes:

instructions-agent.md

This file defines rules and expectations for AI coding agents such as:

- OpenCode
- AI IDE assistants
- autonomous coding agents

Agents should follow those instructions when modifying the project.

---

# License

This project is released under the **MIT License**, one of the most permissive open‑source licenses available.

You are free to:

- use this code for personal or commercial projects
- modify it
- distribute it
- include it in proprietary software

No special permission is required.

Copyright (c) 2025 Saky

This template was created by **Saky**, drawing on many years of professional software engineering experience and with the assistance of modern AI development tools.

The goal of this repository is to provide a practical, production‑ready starting point for Python projects while remaining as open and reusable as possible.