Readme

Data & Type Safety

• Check for pydantic models (Common in modern Python).
• Check for SQLModel, SQLAlchemy, Tortoise for DB schemas.

README Structure (Python)

1. Project Title and Tech Stack

Include version requirements (e.g., Python 3.10+ for Union types |).

## Tech Stack
- **Language**: Python 3.12+
- **Environment Manager**: [uv](https://github.com/astral-sh/uv) or [Poetry](https://python-poetry.org/)
- **Framework**: FastAPI / Flask
- **Validation/Settings**: Pydantic v2
- **Linter/Formatter**: Ruff
- **Database**: PostgreSQL / Redis

2. Getting Started (The Modern Way)

Provide instructions for the specific tool found (UV is preferred in 2026 for speed).

## Getting Started

### 1. Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (recommended)
- Python 3.12+
- Docker Desktop (for services)

### 2. Local Setup
\`\`\`bash
# Clone and enter
git clone <repo-url> && cd <repo-name>

# Create virtualenv and install deps (using uv)
uv sync

# Activate environment
source .venv/bin/activate
\`\`\`

### 3. Environment Configuration
List variables and their purpose in a table. Explain `pydantic-settings` if used.

3. Architecture Overview (Pythonic Depth)

## Architecture

### Directory Structure
Explain the layout (e.g., `src/` layout vs. flat layout).

### Data Flow
Explain how a request/command moves through:
1. **Entrypoint**: `api/v1/endpoints` or `cli.py`
2. **Validation**: Pydantic schemas
3. **Service Layer**: Business logic (independent of framework)
4. **Data Access**: Repository pattern / ORM models

### Pydantic Models & Schemas
Document the core data shapes.

4. Available Commands (Makefile / Taskfile)

Python projects often use a Makefile or pyproject.toml scripts. Document them clearly.

5. Deployment (Python-Centric)

Tailor based on detected files:

• Dockerfile: Explain the multi-stage build (using python:3.12-slim).
• fly.toml / vercel.json: Python-specific deployment steps.
• Gunicorn/Uvicorn: Document worker configurations and process management.

6. Troubleshooting (The Python "Gotchas")

• Pydantic ValidationErrors: How to read them.
• Circular Imports: Common in growing Python projects.
• AsyncIO issues: If using async/await.
• Migrations: alembic upgrade head or manage.py migrate.

Writing Principles

1. **Prefer uv or poetry**: Standard pip is often too slow/manual for modern READMEs.
2. Type Hinting: Assume the user is using static analysis (Mypy/Pyright).
3. Virtual Environments: Always assume the user should be in a .venv.

### How to use this
When you want to document a Python project, trigger this by saying **"Generate a thorough Python README"**. 

**Would you like me to analyze your current directory and draft a README.md based on the files I find?**