{"id":29744649,"url":"https://github.com/softinio/python-starter-template","last_synced_at":"2026-05-08T09:35:35.399Z","repository":{"id":301981242,"uuid":"1010757816","full_name":"softinio/python-starter-template","owner":"softinio","description":"A modern GitHub template for starting AI-centric Python projects with batteries included.","archived":false,"fork":false,"pushed_at":"2026-03-22T19:33:17.000Z","size":156,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T08:46:49.545Z","etag":null,"topics":["ai","anthropic","huggingface","nix","openai","pyrefly","python","python-starter","ruff","uv"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softinio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T18:35:03.000Z","updated_at":"2026-03-22T19:33:19.000Z","dependencies_parsed_at":"2025-06-30T00:21:23.844Z","dependency_job_id":null,"html_url":"https://github.com/softinio/python-starter-template","commit_stats":null,"previous_names":["softinio/python-starter-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/softinio/python-starter-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fpython-starter-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fpython-starter-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fpython-starter-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fpython-starter-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softinio","download_url":"https://codeload.github.com/softinio/python-starter-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softinio%2Fpython-starter-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32775152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","huggingface","nix","openai","pyrefly","python","python-starter","ruff","uv"],"created_at":"2025-07-26T05:24:35.680Z","updated_at":"2026-05-08T09:35:35.389Z","avatar_url":"https://github.com/softinio.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/softinio/python-starter-template/actions/workflows/ci.yml/badge.svg)](https://github.com/softinio/python-starter-template/actions/workflows/ci.yml)\n\n# Python AI Starter Template\n\nA modern GitHub template for starting AI-centric Python projects with batteries included.\n\n## Features\n\nThis template provides a complete development environment for AI/ML applications with:\n\n- **AI/ML SDKs**: Pre-configured with Anthropic, OpenAI, Hugging Face, and MCP (Model Context Protocol) SDKs\n- **Modern Python tooling**: Uses `poetry` for package management\n- **Type safety**: Pyrefly for type checking\n- **Code quality**: Black, isort, and Flake8 for formatting and linting\n- **HTTP client**: httpx for async HTTP operations\n- **Development environment**: Optional Nix flakes for reproducible environments\n- **Python 3.13**: Latest Python version support\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.13+\n- [Poetry](https://python-poetry.org/) (Python package manager)\n- [Nix](https://nixos.org/download.html) (optional, for development environment)\n- [direnv](https://direnv.net/) (optional, for automatic environment activation)\n\n### Setting Up Your Development Environment\n\n#### Option 1: Using Nix (Recommended)\n\n1. Clone this template:\n   ```bash\n   git clone \u003cyour-repo-url\u003e\n   cd \u003cyour-repo-name\u003e\n   ```\n\n2. Set up direnv for automatic environment activation:\n   ```bash\n   echo \"use flake\" \u003e .envrc \u0026\u0026 direnv allow\n   ```\n\n3. The Nix environment will automatically provide:\n   - Python 3.13\n   - Poetry\n\n4. Install all development tools (black, isort, flake8, pyrefly, pre-commit, etc.) via Poetry:\n   ```bash\n   poetry install\n   ```\n\n#### Option 2: Without Nix (You already have Python)\n\n1. Ensure Python 3.13+ is installed\n2. Install Poetry:\n   ```bash\n   pip install poetry\n   ```\n3. Install dependencies:\n   ```bash\n   poetry install\n   ```\n\n### Development Commands\n\n#### Running the Application\n```bash\npoetry run pai\n```\n\n#### Testing\n```bash\n# Using Nix command\nrunTests\n\n# Or directly with poetry\npoetry run pytest --cov=pai --cov-report=term-missing --cov-report=html\n\n# Run specific tests\npoetry run pytest tests/pai/test_main.py::test_specific_function\n```\n\n#### Linting and Formatting\n```bash\n# Using Nix command\nrunLint\n\n# Or individually with poetry\npoetry run black src        # Format code\npoetry run isort src        # Sort imports\npoetry run flake8 src       # Lint\npoetry run pyrefly check    # Type checking\n```\n\n#### Pre-commit Hooks\n```bash\npoetry run pre-commit run --all-files\n```\n\n## Configuration\n\n### Environment Variables\n\nThe template supports multiple environment files:\n- `.env` - Default environment variables\n- `.test.env` - Test-specific configuration\n- `.deploy.env` - Deployment configuration\n\n### Dependencies\n\nCore dependencies included:\n- [`anthropic`](https://docs.anthropic.com/en/api/client-sdks#python) - Claude AI API\n- [`openai`](https://platform.openai.com/docs/libraries/python-library) - OpenAI API\n- [`huggingface-hub`](https://huggingface.co/docs/huggingface_hub/index) - Access to Hugging Face models\n- [`mcp[cli]`](https://modelcontextprotocol.io/docs/python/reference) - Model Context Protocol for AI interactions\n- [`httpx`](https://www.python-httpx.org/) - Modern async HTTP client (preferred over requests)\n- [`pydantic`](https://docs.pydantic.dev/) \u0026 [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - Data validation and settings\n- [`structlog`](https://www.structlog.org/) - Structured logging\n- [`tenacity`](https://tenacity.readthedocs.io/) - Retry logic for API calls\n\n## Development Workflow\n\n1. **Make changes** to code in `src/pai/`\n2. **Write tests** in `tests/` mirroring the source structure\n3. **Run linting** with `runLint` or `poetry run flake8 src`\n4. **Run tests** with `runTests` or `poetry run pytest`\n5. **Commit** - pre-commit hooks will run automatically\n\n## Adding Dependencies\n\n```bash\n# Add a production dependency\npoetry add \u003cpackage-name\u003e\n\n# Add a development dependency\npoetry add --group dev \u003cpackage-name\u003e\n```\n\n## Type Checking\n\nThis template uses Pyrefly for type checking. Run type checks with:\n```bash\npoetry run pyrefly check\n```\n\n## Tips for Development\n\n- Use `httpx` for all HTTP operations (async-first design)\n- Store API keys in environment variables or use `.env` files (never commit them)\n- Implement proper retry logic with `tenacity` for API calls\n- Use `pydantic` models for API request/response validation\n- Leverage `structlog` for debugging and logging\n\n## Contributing\n\n**GitHub Issues** are disabled to encourage direct community contribution. When you encounter bugs or documentation issues, please contribute fixes through Pull Requests instead.\n\n**How to contribute:** [Open a PR](https://github.com/softinio/python-starter-template/pulls) with your solution, draft changes, or a test reproducing the issue. We'll collaborate from there to refine and merge improvements.\n\nThis approach creates faster fixes while building a stronger, community-driven project where everyone benefits from shared contributions.\n\n## Using AI Help to use or contribute to this project\n\nThis project is optimized and setup for you to use [Claude Code](https://www.anthropic.com/claude-code) as your AI programming agent. It is recommended to use Claude Code.\n\n\n## License\n\npython-starter-template is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## This Template was created by\n\n[Salar Rahmanian](https://www.softinio.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftinio%2Fpython-starter-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftinio%2Fpython-starter-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftinio%2Fpython-starter-template/lists"}