Python AI Starter Template

A modern GitHub template for starting AI-centric Python projects with batteries included.

Features

This template provides a complete development environment for AI/ML applications with:

• AI/ML SDKs: Pre-configured with Anthropic, OpenAI, Hugging Face, and MCP (Model Context Protocol) SDKs
• Modern Python tooling: Uses uv for blazing-fast package management
• Type safety: Pyrefly for type checking
• Code quality: Ruff for linting and formatting
• HTTP client: httpx for async HTTP operations
• Development environment: Optional Nix flakes for reproducible environments
• Python 3.13: Latest Python version support

Quick Start

Prerequisites

• Python 3.13+
• uv (Python package manager)
• Nix (optional, for development environment)
• direnv (optional, for automatic environment activation)

Setting Up Your Development Environment

Option 1: Using Nix (Recommended)

1. Clone this template:

   git clone <your-repo-url>
   cd <your-repo-name>

2. Set up direnv for automatic environment activation:

   echo "use flake" > .envrc && direnv allow

3. The Nix environment will automatically provide:

   • Python 3.13
   • All development tools (uv, ruff, pyrefly, etc.)
   • Pre-commit hooks

Option 2: Without Nix (You already have Python)

1. Ensure Python 3.13+ is installed
2. Install uv:

   pip install uv

3. Install dependencies:

   uv sync

Option 3: Using uv

1. Install uv
2. Install Python using uv:

   uv python install 3.13

3. Install dependencies:

   uv sync

Development Commands

Running the Application

uv run pai

Testing

# Using Nix command
runTests

# Or directly with uv
uv run pytest --cov=pai --cov-report=term-missing --cov-report=html

# Run specific tests
uv run pytest tests/pai/test_main.py::test_specific_function

Linting and Formatting

# Using Nix command
runLint

# Or individually with uv
uv run ruff format src          # Format code
uv run ruff check --fix src     # Lint and auto-fix
pyrefly check                   # Type checking

Pre-commit Hooks

pre-commit run --all-files

Configuration

Environment Variables

The template supports multiple environment files:

• .env - Default environment variables
• .test.env - Test-specific configuration
• .deploy.env - Deployment configuration

Dependencies

Core dependencies included:

• anthropic - Claude AI API
• openai - OpenAI API
• huggingface-hub - Access to Hugging Face models
• mcp[cli] - Model Context Protocol for AI interactions
• httpx - Modern async HTTP client (preferred over requests)
• pydantic & pydantic-settings - Data validation and settings
• structlog - Structured logging
• tenacity - Retry logic for API calls

Development Workflow

1. Make changes to code in src/pai/
2. Write tests in tests/ mirroring the source structure
3. Run linting with runLint or uv run ruff check src
4. Run tests with runTests or uv run pytest
5. Commit - pre-commit hooks will run automatically

Adding Dependencies

# Add a production dependency
uv add <package-name>

# Add a development dependency
uv add --dev <package-name>

Type Checking

This template uses Pyrefly (and Basedpyright) for type checking. Run type checks with:

pyrefly check

Tips for Development

• Use httpx for all HTTP operations (async-first design)
• Store API keys in environment variables or use .env files (never commit them)
• Implement proper retry logic with tenacity for API calls
• Use pydantic models for API request/response validation
• Leverage structlog for debugging and logging

Contributing

GitHub Issues are disabled to encourage direct community contribution. When you encounter bugs or documentation issues, please contribute fixes through Pull Requests instead.

How to contribute: Open a PR with your solution, draft changes, or a test reproducing the issue. We'll collaborate from there to refine and merge improvements.

This approach creates faster fixes while building a stronger, community-driven project where everyone benefits from shared contributions.

Using AI Help to use or contribute to this project

This project is optimized and setup for you to use Claude Code as your AI programming agent. It is recommended to use Claude Code.

License

python-starter-template is licensed under the MIT License. See LICENSE for details.

This Template was created by

Salar Rahmanian