@kenkaiiii/queen-python/README.md

Create modern Python projects with uv, ruff, mypy, FastAPI, AI integration, and Queen Claude foundation - universal for APIs, AI applications, CLI tools, and automation

# 🐍 Python Queen - Queen Claude Python Template

Complete Python project generator with multiple pathways - CLI tools, REST APIs, AI applications, automation scripts, and libraries.

## What This Is

**Python Queen** is a dynamic project generator that creates complete, production-ready Python applications from scratch. It's NOT a template repository - it's a generator that builds exactly what you need based on your choices.

## Available Pathways

### 1. CLI Tool 🖥️
- **Framework**: Typer + Rich
- **Use Case**: Command-line applications, developer tools, scripts
- **Features**: Beautiful terminal UI, subcommands, progress bars, tables

### 2. REST API 🌐
- **Framework**: FastAPI
- **Use Case**: Web services, microservices, backend APIs
- **Features**: Auto-documentation, async support, type safety, validation

### 3. AI Application 🤖
- **Frameworks**: OpenAI/Anthropic/Ollama + Pydantic AI
- **Use Case**: Chatbots, agents, AI-powered tools
- **Features**: Type-safe agents, function calling, streaming, embeddings

### 4. Automation 🔄
- **Framework**: APScheduler
- **Use Case**: Cron jobs, background tasks, data pipelines
- **Features**: Scheduled execution, job monitoring, async tasks

### 5. Python Library 📦
- **Framework**: Standard packaging
- **Use Case**: Reusable packages, PyPI distribution
- **Features**: Proper structure, build config, version management

## Quick Start

### With Claude (Recommended)

1. **Setup Python Project**:
   ```
   User: /1-setup-python
   Claude: What type of Python project?
   User: 2 (for REST API)
   Claude: *Creates complete FastAPI project*
   ```

2. **Add Database** (Optional):
   ```
   User: /2-setup-database
   Claude: Database type? (1=SQLite, 2=PostgreSQL)
   User: 2
   Claude: *Adds SQLAlchemy + migrations*
   ```

3. **Add AI** (Optional):
   ```
   User: /3-setup-ai
   Claude: AI Provider? (1=OpenAI, 2=Anthropic, 3=Local)
   User: 1
   Claude: *Adds OpenAI integration*
   ```

### Direct MCP Usage

```javascript
// Create a FastAPI project
await mcp_queen_mcp_setup_python_foundation({
  project_path: "/path/to/my-api",
  project_type: "api",
  database_type: "postgresql"
});

// Add database
await mcp_queen_mcp_setup_python_database({
  project_path: "/path/to/my-api",
  database_type: "postgresql",
  auth_type: "simple"
});

// Add AI capabilities
await mcp_queen_mcp_setup_python_ai({
  project_path: "/path/to/my-api",
  ai_provider: "openai",
  vector_store: "chroma"
});
```

## What Gets Created

### Base Structure (All Types)
```
my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── main.py              # Entry point
│       ├── core/
│       │   ├── config.py        # Pydantic settings
│       │   └── logging.py       # Structured logging
│       └── utils/              # Utility functions
├── tests/
│   ├── unit/
│   └── integration/
├── .env.example                # Environment template
├── pyproject.toml              # Dependencies & config
├── README.md                   # Complete documentation
└── .gitignore
```

### Type-Specific Additions

**CLI Tool:**
- `commands/` - Typer subcommands
- `models/` - Data models
- Rich tables and progress bars
- YAML config support

**REST API:**
- `routers/` - API endpoints
- `models/` - SQLAlchemy models
- `middleware/` - CORS, auth
- Swagger UI at `/docs`

**AI Application:**
- `agents/` - AI agent definitions
- `prompts/` - Prompt templates
- `tools/` - Function tools
- Provider integrations

**Automation:**
- `jobs/` - Scheduled tasks
- `services/` - Business logic
- Scheduler configuration
- Job monitoring

**Library:**
- Proper package structure
- `__version__.py`
- Build configuration
- PyPI metadata

## Running Generated Projects

### CLI Tools
```bash
cd my-cli-tool
uv run python -m src.my_cli_tool.main --help
```

### REST APIs
```bash
cd my-api
uv run uvicorn src.my_api.main:app --reload
# API at http://localhost:8000
# Docs at http://localhost:8000/docs
```

### AI Applications
```bash
cd my-ai-app
export OPENAI_API_KEY="sk-..."
uv run python -m src.my_ai_app.main
```

### Automation Scripts
```bash
cd my-automation
uv run python -m src.my_automation.main
# Runs scheduler with configured jobs
```

### Libraries
```bash
cd my-library
uv run pytest                    # Run tests
uv run python -m build           # Build package
uv run twine upload dist/*       # Upload to PyPI
```

## Development Commands

All projects include:

```bash
# Dependency management
uv add package-name              # Add dependency
uv add --dev package-name        # Add dev dependency
uv sync                          # Install all deps

# Code quality
uv run ruff check .              # Lint code
uv run ruff format .             # Format code
uv run mypy src/                 # Type checking

# Testing
uv run pytest                    # Run tests
uv run pytest --cov              # With coverage
uv run pytest -v                 # Verbose output

# Database (if applicable)
uv run alembic revision --autogenerate -m "message"  # Create migration
uv run alembic upgrade head                          # Apply migrations
```

## Environment Configuration

Each project includes `.env.example`:

```bash
# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

# Database (if added)
DATABASE_URL=postgresql://user:pass@localhost/dbname

# AI Provider (if added)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_HOST=http://localhost:11434

# Security (if auth enabled)
SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
```

## Key Features

### 🚀 Instant Start
- Projects run immediately after generation
- All dependencies installed
- Configuration ready
- Example code included

### 🎯 Type Safety
- Pydantic models everywhere
- Full type hints
- Mypy configuration
- Runtime validation

### 🧪 Testing Ready
- Pytest configured
- Test structure created
- Fixtures included
- Coverage setup

### 📦 Modern Python
- Python 3.11+ features
- Async/await support
- UV package manager
- Ruff for linting

### 🔧 Production Ready
- Structured logging
- Error handling
- Environment management
- Docker support

## System Requirements

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Git (for version control)

## How It Works

1. **You Choose**: Select your project type (CLI, API, AI, etc.)
2. **Generator Creates**: Complete project structure with all files
3. **Dependencies Install**: Via uv automatically
4. **Ready to Run**: Immediately functional application

This is **NOT** a template you clone. It's a generator that creates fresh projects tailored to your specific needs.

## Integration with Queen Claude

Python Queen is part of the larger Queen Claude ecosystem:

- **Queen Claude**: Main autonomous development system
- **Python Queen**: Python project generator (this)
- **Next.js Queen**: Next.js/React project generator
- **Queen MCP**: Model Context Protocol server

All work together to provide complete full-stack development capabilities.

## License

MIT