# Repository Boilerplate Setup Plan

## 🎯 Objective
Set up a modern, professional-grade Python repository from scratch with proper tooling, dependency management, and automation.

---

## 🛠️ Setup Process

### 1. Project Configuration
- Create a `pyproject.toml` file to centralize project metadata, dependencies, and tool configurations.
- Define build system requirements and development dependencies.

### 2. Dependency Management
- Use `pyproject.toml` to specify production and development dependencies.
- Leverage `UV` for fast dependency resolution and installation.

### 3. Code Quality Tools
- Configure `ruff` for linting and formatting.
- Set up `mypy` for static type checking.
- Install and configure `pre-commit` hooks to enforce code quality.

### 4. Development Automation
- Create a `Makefile` with commands for setup, formatting, linting, and running the development server.
- Automate common tasks like cleaning, building, and testing.

### 5. Documentation and Onboarding
- Write a `README.md` with setup instructions and development workflows.
- Add a `.gitignore` file and a `.python-version` file for Python version pinning.

### 6. Validation and Testing
- Test the setup by running formatting, linting, and pre-commit hooks.
- Verify that the development server starts correctly and dependencies are installed as expected.

---

## 🛠️ Technology Stack

### Core Tools
- **UV** - Ultra-fast Python package installer and resolver
- **ruff** - Fast Python linter and formatter
- **mypy** - Static type checking
- **pre-commit** - Git hooks for code quality

### Key Features
- **Single pyproject.toml** - All configuration in one place
- **Fast dependency resolution** - UV for lightning-fast installs
- **Automated formatting** - Ruff handles all code style
- **Quality gates** - Pre-commit prevents bad code from entering repo

---

## 🔧 Configuration Details

### pyproject.toml Structure
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "kguru"
version = "0.1.0"
description = "An AI agent platform for Python with domain-specific knowledge capabilities"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[project.optional-dependencies]
dev = [
    "ruff>=0.1.6",
    "mypy>=1.7.0",
    "pre-commit>=3.5.0",
]

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
ignore = []

[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
check_untyped_defs = true
disallow_untyped_defs = false
```

### Makefile Commands
```makefile
##@ Setup
setup: ## Initial project setup
	@echo "Setting up development environment..."
	@echo "Installing Python 3.12 if needed..."
	@uv python install 3.12
	@echo "Creating virtual environment..."
	@uv venv .venv --python 3.12
	@echo "Installing dependencies..."
	@uv pip install -e .[dev]
	@echo "Setting up pre-commit hooks..."
	@uv run pre-commit install

##@ Development
format: ## Format code with ruff
	@echo "Formatting code..."
	@uv run ruff format .
	@uv run ruff check --fix .

lint: ## Lint code with ruff and mypy
	@echo "Linting code..."
	@uv run ruff check .
	@uv run mypy src

test: ## Run tests
	@echo "Running tests..."
	@uv run pytest

clean: ## Clean build artifacts and cache
	@echo "Cleaning build artifacts..."
	@rm -rf build/ dist/ *.egg-info

all: format lint ## Format and lint
```

### Pre-commit Configuration
```yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-added-large-files
      - id: detect-private-key

  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.5.11
    hooks:
      - id: uv-lock
        stages: [post-checkout, post-merge]
```

---

## ✅ Success Criteria

### Immediate Benefits
- UV installs dependencies in seconds.
- Ruff formats and lints entire codebase instantly.
- Pre-commit prevents poorly formatted code.
- Single command setup for new developers (`make setup`).
- Consistent code style across the project.

### Developer Experience
- `make format` - Instant code formatting.
- `make lint` - Fast linting with actionable errors.
- `make test` - Run tests.
- `make clean` - Clean build artifacts and cache.
- `make all` - Complete code quality check.

---
