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

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 poetry for package management
• Type safety: Pyrefly for type checking
• Code quality: Black, isort, and Flake8 for formatting and linting
• HTTP client: httpx for async HTTP operations
• Development environment: Optional Nix flakes for reproducible environments
• Python 3.13: Latest Python version support

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

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
   • Poetry

4. Install all development tools (black, isort, flake8, pyrefly, pre-commit, etc.) via Poetry:

   poetry install

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

   pip install poetry

3. Install dependencies:

   poetry install

poetry run pai

# Using Nix command
runTests

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

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

# Using Nix command
runLint

# Or individually with poetry
poetry run black src        # Format code
poetry run isort src        # Sort imports
poetry run flake8 src       # Lint
poetry run pyrefly check    # Type checking

poetry run pre-commit run --all-files

The template supports multiple environment files:

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

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

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

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

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

This template uses Pyrefly for type checking. Run type checks with:

poetry run pyrefly check

• 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

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.

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

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

Salar Rahmanian