agent-skill-kit 3.9.135

package/.agent/skills/python-pro/rules/framework-selection.md

@@ -0,0 +1,167 @@
+---
+name: framework-selection
+description: Python framework comparison — FastAPI vs Django vs Flask with decision tree, benchmarks, and minimal app examples
+title: "Framework Selection (2025)"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: framework, selection
+---
+
+# Framework Selection (2025)
+
+> Pick the right tool. Don't default to one framework for everything.
+
+---
+
+## Decision Tree
+
+```
+What are you building?
+│
+├── API-first / Microservices   → FastAPI
+├── Full-stack web / CMS        → Django
+├── Simple / Script / Learning  → Flask
+├── AI/ML API serving           → FastAPI
+└── Background workers          → Celery + any framework
+```
+
+**If user has explicit preference → respect it.** Ask when unclear.
+
+---
+
+## Comparison
+
+| Factor | FastAPI | Django | Flask |
+|--------|---------|--------|-------|
+| **Best for** | APIs, microservices, ML | Full-stack, CMS, admin | Simple, learning, prototyping |
+| **Performance** | ⭐⭐⭐ (Starlette/uvicorn) | ⭐⭐ (improved in 5.x) | ⭐⭐ (Werkzeug) |
+| **Async** | Native | Django 5.0+ (partial) | Via extensions (Quart) |
+| **Admin** | Manual | Built-in (excellent) | Flask-Admin |
+| **ORM** | SQLAlchemy / Tortoise | Django ORM (built-in) | SQLAlchemy |
+| **Validation** | Pydantic (built-in) | Django Forms / DRF | Manual / Marshmallow |
+| **Auth** | Manual / FastAPI-Users | Built-in | Flask-Login |
+| **Learning curve** | Low | Medium | Low |
+| **Type safety** | Excellent (Pydantic) | Good (mypy support) | Manual |
+| **OpenAPI docs** | Auto-generated | DRF (drf-spectacular) | Flask-RESTX |
+
+---
+
+## Minimal App Examples
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class Item(BaseModel):
+    name: str
+    price: float
+    in_stock: bool = True
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+
+@app.post("/items")
+async def create_item(item: Item) -> Item:
+    return item
+
+# Run: uvicorn main:app --reload
+```
+
+### Django (with DRF)
+
+```python
+# views.py
+from rest_framework import viewsets
+from rest_framework.decorators import api_view
+from rest_framework.response import Response
+
+@api_view(["GET"])
+def root(request):
+    return Response({"message": "Hello World"})
+
+class ItemViewSet(viewsets.ModelViewSet):
+    queryset = Item.objects.all()
+    serializer_class = ItemSerializer
+
+# Run: python manage.py runserver
+```
+
+### Flask
+
+```python
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+
+@app.get("/")
+def root():
+    return jsonify(message="Hello World")
+
+@app.post("/items")
+def create_item():
+    data = request.get_json()
+    return jsonify(data), 201
+
+# Run: flask run --debug
+```
+
+---
+
+## pyproject.toml (Modern Python)
+
+```toml
+[project]
+name = "myapp"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+dependencies = [
+    # FastAPI stack
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "pydantic>=2.0",
+    # Or Django stack
+    # "django>=5.1",
+    # "djangorestframework>=3.15",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Default to Django for simple APIs | Use FastAPI for API-first |
+| Use Flask for complex apps | Use Django (batteries included) |
+| Pick framework by popularity | Pick by project requirements |
+| Skip framework when prototyping | Flask for quick prototypes |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [fastapi-patterns.md](fastapi-patterns.md) | Chosen FastAPI |
+| [django-patterns.md](django-patterns.md) | Chosen Django |
+| [project-structure.md](project-structure.md) | Directory layout |
+| [async-patterns.md](async-patterns.md) | Async decision |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/project-structure.md

@@ -0,0 +1,181 @@
+---
+name: project-structure
+description: Python project structure — directory layouts for small/medium/large apps, FastAPI vs Django, pyproject.toml
+title: "Structure by size. Feature-based for large apps. Layer-based for small."
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: project, structure
+---
+
+# Project Structure
+
+> Structure by size. Feature-based for large apps. Layer-based for small.
+
+---
+
+## By Project Size
+
+### Small (Script / Tool)
+
+```
+myapp/
+├── main.py
+├── utils.py
+├── pyproject.toml
+└── README.md
+```
+
+### Medium (API / Service)
+
+```
+myapp/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              # App entry + lifespan
+│   ├── config.py             # Pydantic Settings
+│   ├── dependencies.py       # Shared DI (db session, auth)
+│   ├── models/               # SQLAlchemy / DB models
+│   │   ├── __init__.py
+│   │   └── user.py
+│   ├── schemas/              # Pydantic request/response
+│   │   ├── __init__.py
+│   │   └── user.py
+│   ├── routes/               # API routes
+│   │   ├── __init__.py
+│   │   └── users.py
+│   └── services/             # Business logic
+│       ├── __init__.py
+│       └── user_service.py
+├── tests/
+│   ├── conftest.py           # Shared fixtures
+│   ├── test_users.py
+│   └── test_services.py
+├── alembic/                  # DB migrations
+├── pyproject.toml
+├── .env.example
+└── README.md
+```
+
+### Large (Monolith / Multiple Domains)
+
+```
+src/
+└── myapp/
+    ├── core/                 # Shared kernel
+    │   ├── config.py
+    │   ├── database.py
+    │   ├── security.py
+    │   └── exceptions.py
+    ├── users/                # Feature module
+    │   ├── models.py
+    │   ├── schemas.py
+    │   ├── routes.py
+    │   ├── service.py
+    │   └── repository.py
+    ├── products/             # Feature module
+    │   └── ...
+    └── main.py
+tests/
+├── users/
+├── products/
+└── conftest.py
+pyproject.toml
+```
+
+---
+
+## FastAPI Entry Point
+
+```python
+# app/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from app.config import settings
+from app.routes import users, products
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await database.connect()
+    yield
+    # Shutdown
+    await database.disconnect()
+
+app = FastAPI(
+    title=settings.app_name,
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.include_router(users.router, prefix="/api/v1/users", tags=["users"])
+app.include_router(products.router, prefix="/api/v1/products", tags=["products"])
+```
+
+---
+
+## Django Structure
+
+```
+myproject/
+├── manage.py
+├── myproject/
+│   ├── __init__.py
+│   ├── settings/
+│   │   ├── __init__.py
+│   │   ├── base.py           # Shared settings
+│   │   ├── dev.py            # Development
+│   │   └── prod.py           # Production
+│   ├── urls.py
+│   └── wsgi.py / asgi.py
+├── users/                    # Django app
+│   ├── models.py
+│   ├── views.py / viewsets.py
+│   ├── serializers.py
+│   ├── urls.py
+│   ├── admin.py
+│   ├── tests.py
+│   └── migrations/
+├── products/                 # Django app
+│   └── ...
+└── requirements/
+    ├── base.txt
+    ├── dev.txt
+    └── prod.txt
+```
+
+---
+
+## Background Tasks Selection
+
+| Solution | Best For | Async | Persistence |
+|----------|----------|:-----:|:-----------:|
+| **BackgroundTasks** (FastAPI) | Quick, in-process | ✅ | ❌ |
+| **Celery** | Distributed workflows | ❌ | ✅ |
+| **ARQ** | Async + Redis | ✅ | ✅ |
+| **Dramatiq** | Actor-based | ❌ | ✅ |
+| **RQ** | Simple Redis queue | ❌ | ✅ |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Flat file dump (all in root) | Organize by feature/layer |
+| Business logic in routes | Routes → services → repos |
+| `settings.py` with hardcoded values | Pydantic Settings + `.env` |
+| Skip `__init__.py` | Always include (explicit packages) |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [framework-selection.md](framework-selection.md) | Which framework |
+| [fastapi-patterns.md](fastapi-patterns.md) | FastAPI specifics |
+| [django-patterns.md](django-patterns.md) | Django specifics |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/testing-patterns.md

@@ -0,0 +1,212 @@
+---
+name: testing-patterns
+description: Python testing patterns — pytest, async tests, fixtures, mocking, FastAPI/Django test clients, coverage
+title: "Python Testing Patterns"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: testing, patterns
+---
+
+# Python Testing Patterns
+
+> pytest for everything. Fixtures for setup. Mock at boundaries. Test behavior, not implementation.
+
+---
+
+## Testing Strategy
+
+| Type | Purpose | Tools | Speed |
+|------|---------|-------|:-----:|
+| **Unit** | Business logic / services | pytest | ⚡ Fast |
+| **Integration** | API endpoints + DB | pytest + httpx/TestClient | 🔄 Medium |
+| **E2E** | Full workflows | pytest + real DB | 🐢 Slow |
+
+---
+
+## FastAPI Testing
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+from app.dependencies import get_db
+
+# Override database dependency for tests
+async def get_test_db():
+    async with test_session_maker() as session:
+        yield session
+
+app.dependency_overrides[get_db] = get_test_db
+
+@pytest.mark.asyncio
+async def test_create_user():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.post("/api/v1/users/", json={
+            "email": "test@example.com",
+            "name": "Test User",
+        })
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert "id" in data
+
+@pytest.mark.asyncio
+async def test_get_user_not_found():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/api/v1/users/99999")
+    assert response.status_code == 404
+    assert response.json()["error"] == "NOT_FOUND"
+```
+
+---
+
+## Django Testing
+
+```python
+from django.test import TestCase
+from rest_framework.test import APIClient
+
+class UserAPITest(TestCase):
+    def setUp(self):
+        self.client = APIClient()
+        self.user = User.objects.create_user(
+            email="test@test.com", password="testpass123"
+        )
+
+    def test_list_users(self):
+        self.client.force_authenticate(user=self.user)
+        response = self.client.get("/api/users/")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.data), 1)
+
+    def test_create_user_unauthenticated(self):
+        response = self.client.post("/api/users/", {"email": "new@test.com"})
+        self.assertEqual(response.status_code, 401)
+```
+
+---
+
+## Fixtures (conftest.py)
+
+```python
+# tests/conftest.py
+import pytest
+from app.models import User
+
+@pytest.fixture
+def sample_user(db) -> User:
+    """Create a test user — available to all tests."""
+    return User.objects.create(
+        email="fixture@test.com",
+        name="Fixture User",
+    )
+
+@pytest.fixture
+def auth_client(sample_user) -> APIClient:
+    """Authenticated API client."""
+    client = APIClient()
+    client.force_authenticate(user=sample_user)
+    return client
+
+@pytest.fixture
+async def async_client() -> AsyncClient:
+    """Async client for FastAPI."""
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        yield client
+```
+
+---
+
+## Mocking
+
+```python
+from unittest.mock import AsyncMock, patch
+
+@pytest.mark.asyncio
+async def test_send_email_on_signup():
+    """Mock external services at boundaries."""
+    with patch("app.services.email.send_welcome_email", new_callable=AsyncMock) as mock_email:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as client:
+            await client.post("/api/v1/users/", json={
+                "email": "new@test.com",
+                "name": "New User",
+            })
+
+        mock_email.assert_called_once_with("new@test.com", "New User")
+
+@pytest.mark.asyncio
+async def test_external_api_failure():
+    """Test error handling when external service fails."""
+    with patch("app.services.payment.charge", side_effect=Exception("Payment failed")):
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as client:
+            response = await client.post("/api/v1/orders/", json={"amount": 100})
+        assert response.status_code == 500
+```
+
+---
+
+## Test Configuration
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+addopts = "-v --tb=short --strict-markers"
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks integration tests",
+]
+
+[tool.coverage.run]
+source = ["app"]
+omit = ["tests/*", "*/migrations/*"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+```
+
+```bash
+# Run tests
+pytest                          # All tests
+pytest -x                       # Stop on first failure
+pytest -k "test_user"           # Filter by name
+pytest --cov=app --cov-report=html  # With coverage
+pytest -m "not slow"            # Skip slow tests
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Test implementation details | Test behavior (inputs → outputs) |
+| Mock everything | Mock only boundaries (DB, APIs, email) |
+| Share state between tests | Each test is independent |
+| Skip error path tests | Test both success AND failure |
+| Ignore coverage | Aim for ≥80% with `fail_under` |
+| Use `print()` for debugging | Use `pytest --pdb` or `breakpoint()` |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [fastapi-patterns.md](fastapi-patterns.md) | FastAPI patterns |
+| [django-patterns.md](django-patterns.md) | Django patterns |
+| [async-patterns.md](async-patterns.md) | Testing async code |
+| [type-hints.md](type-hints.md) | Typed test fixtures |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/python-pro/rules/type-hints.md

@@ -0,0 +1,159 @@
+---
+name: type-hints
+description: Python type hints — modern syntax, Pydantic v2, generics, TypeVar, and validation patterns
+title: "Python Type Hints & Validation"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: type, hints
+---
+
+# Python Type Hints & Validation
+
+> Type all public APIs. Use Pydantic at boundaries. No `Any` in public signatures.
+
+---
+
+## Modern Type Syntax (Python 3.12+)
+
+```python
+# ✅ Modern — use built-in generics (no typing import needed)
+def get_items() -> list[dict[str, int]]:
+    ...
+
+def find_user(user_id: int) -> User | None:  # Union syntax
+    ...
+
+def process(data: str | bytes) -> None:
+    ...
+
+# ❌ Legacy — avoid in new code
+from typing import Optional, Union, List, Dict
+def get_items() -> List[Dict[str, int]]:  # Old style
+    ...
+```
+
+---
+
+## Common Patterns
+
+```python
+from typing import TypeVar, Generic, Callable
+from collections.abc import Sequence, Mapping
+
+# TypeVar for generics
+T = TypeVar("T")
+
+def first(items: Sequence[T]) -> T | None:
+    return items[0] if items else None
+
+# Callable types
+def apply(fn: Callable[[int], str], value: int) -> str:
+    return fn(value)
+
+# Generic class
+class Repository(Generic[T]):
+    def __init__(self, model: type[T]) -> None:
+        self.model = model
+
+    async def get(self, id: int) -> T | None:
+        ...
+
+    async def list(self, limit: int = 20) -> list[T]:
+        ...
+```
+
+---
+
+## Pydantic v2 Models
+
+```python
+from pydantic import BaseModel, Field, EmailStr, field_validator
+from datetime import datetime
+
+class UserCreate(BaseModel):
+    """Input validation at API boundary."""
+    name: str = Field(min_length=1, max_length=100)
+    email: EmailStr
+    age: int = Field(ge=0, le=150)
+    role: str = "user"
+
+    @field_validator("name")
+    @classmethod
+    def name_must_not_be_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Name cannot be blank")
+        return v.strip()
+
+class UserResponse(BaseModel):
+    """Output serialization — never expose internal fields."""
+    id: int
+    name: str
+    email: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}  # Enable ORM mode
+
+class UserUpdate(BaseModel):
+    """Partial update — all fields optional."""
+    name: str | None = None
+    email: EmailStr | None = None
+    age: int | None = Field(default=None, ge=0, le=150)
+```
+
+### Pydantic Settings (Configuration)
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    """Load from environment variables automatically."""
+    database_url: str
+    redis_url: str = "redis://localhost:6379"
+    secret_key: str
+    debug: bool = False
+    allowed_origins: list[str] = ["http://localhost:3000"]
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+settings = Settings()  # Auto-reads from .env + environment
+```
+
+---
+
+## When to Type
+
+| Scope | Rule |
+|-------|------|
+| Function parameters | Always |
+| Return types | Always |
+| Class attributes | Always |
+| Local variables | Let inference work (skip) |
+| Tests | Optional (usually skip) |
+| Scripts | Minimal |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `Any` in public APIs | Use specific types or `TypeVar` |
+| `typing.Optional[X]` | `X \| None` (Python 3.10+) |
+| `typing.List`, `typing.Dict` | `list`, `dict` (Python 3.9+) |
+| Skip return type hints | Always annotate return types |
+| Validate manually | Use Pydantic at boundaries |
+| Hardcode config values | Use Pydantic Settings |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [fastapi-patterns.md](fastapi-patterns.md) | Pydantic with FastAPI |
+| [testing-patterns.md](testing-patterns.md) | Testing typed code |
+| [project-structure.md](project-structure.md) | Where to put models |
+
+---
+
+⚡ PikaKit v3.9.134