symfonia-ai-tools 1.7.1 → 1.8.0

package/README.md

@@ -73,6 +73,7 @@ Instead of choosing a single stack, you pick any combination of instruction & sk
 | **Vitest** | 1 instruction | Yes |
 | **Storybook** | 1 instruction | No |
 | **Laravel + PHP** | 4 instructions, 7 skills | No |
+| **Python FastAPI** | 4 instructions, 7 skills | No |
 | **Playwright E2E** | 1 instruction, 3 skills | No |
 | **Docker** | 1 instruction | No |
 
@@ -155,6 +156,15 @@ When AI opens/edits a file matching `applyTo`, it automatically loads those inst
 | `api-resource.instructions.md` | `**/*Resource*.php, **/*Request*.php` | Resources with whenLoaded(), Form Requests, Policies |
 | `testing.instructions.md` | `**/*Test*.php, **/tests/**` | PHPUnit, data providers, factories, Laravel fakes |
 
+### Python FastAPI (4 instructions)
+
+| Instruction | applyTo | What it teaches AI |
+|-------------|---------|-------------------|
+| `api-schema.instructions.md` | `**/schemas.py, **/*schema*.py, **/*request*.py, **/*response*.py` | Pydantic v2 schemas, StrEnum status fields, `PaginatedResponse[T]`, frozen request models, `ErrorResponse` |
+| `module.instructions.md` | `**/modules/**/router.py, **/modules/**/dependencies.py, **/modules/**/domain/**, **/modules/**/infrastructure/**` | Module structure, FastAPI router pattern, SQLAlchemy 2.0 ORM models, `lifespan=` setup, DI wiring |
+| `service-repository.instructions.md` | `**/domain/services.py, **/infrastructure/repositories/**, **/domain/entities.py, **/domain/value_objects.py` | CQRS repos, domain entities, EventPublisher pattern, layer isolation rules |
+| `testing.instructions.md` | `**/tests/**, **/*test*.py, **/conftest.py` | pytest-asyncio conftest, `async_sessionmaker`, rollback pattern, `AsyncClient` |
+
 ### Playwright (1 instruction)
 
 | Instruction | applyTo | What it teaches AI |
@@ -267,6 +277,18 @@ All skills have the `smf-` prefix (Symfonia). The configurator lets you choose w
 | `smf-testing-unit` | Unit tests | Isolated tests without DB, PHPUnit mocks, data providers |
 | `smf-testing-manual` | Manual HTTP tests | JetBrains HTTP Client — `.http` files for interactive API testing |
 
+### Python FastAPI skills (7 skills)
+
+| Skill | Purpose | When to use |
+|-------|---------|-------------|
+| `smf-new-module` | New module from scratch | router → schemas → ORM model → CQRS repos → service → migration → tests |
+| `smf-new-endpoint` | New endpoint in existing module | request schema → route → service method → response schema → tests |
+| `smf-migration` | Alembic migration | autogenerate → review → upgrade → verify; async env.py setup |
+| `smf-background-task` | Celery background task | task def (sync) → `SyncSessionLocal` → dispatch from router → beat schedule → tests |
+| `smf-testing-integration` | Integration tests (HTTP) | `AsyncClient` → real DB via rollback conftest → router assertions |
+| `smf-testing-unit` | Unit tests (service) | mock repos → service logic → no DB needed |
+| `smf-testing-manual` | Manual HTTP tests | JetBrains HTTP Client `.http` files for interactive API testing |
+
 ### Playwright skills (3 skills)
 
 | Skill | Purpose | When to use |
@@ -524,6 +546,7 @@ templates/
     ├── vitest/                  # 1 instr.
     ├── storybook/               # 1 instr.
     ├── laravel/                 # 4 instr. · 7 skills
+    ├── python-fastapi/          # 4 instr. · 7 skills
     ├── playwright/              # 1 instr. · 3 skills
     └── docker/                  # 1 instr.
 ```

package/lib/questions.mjs

@@ -156,9 +156,10 @@ export async function askQuestions(packsDir) {
 
     const hasVue = answers.packs.includes('vue3');
     const hasLaravel = answers.packs.includes('laravel');
-    answers.testCommand = await ask(t('q.cmd.test'), hasVue ? 'npm run test' : hasLaravel ? 'php artisan test' : 'npm test');
-    answers.buildCommand = await ask(t('q.cmd.build'), hasVue ? 'npm run build' : hasLaravel ? 'composer build' : 'npm run build');
-    answers.lintCommand = await ask(t('q.cmd.lint'), hasVue ? 'npm run lint' : hasLaravel ? 'php artisan pint' : 'npm run lint');
+    const hasPythonFastapi = answers.packs.includes('python-fastapi');
+    answers.testCommand = await ask(t('q.cmd.test'), hasVue ? 'npm run test' : hasLaravel ? 'php artisan test' : hasPythonFastapi ? 'pytest' : 'npm test');
+    answers.buildCommand = await ask(t('q.cmd.build'), hasVue ? 'npm run build' : hasLaravel ? 'composer build' : hasPythonFastapi ? 'docker build .' : 'npm run build');
+    answers.lintCommand = await ask(t('q.cmd.lint'), hasVue ? 'npm run lint' : hasLaravel ? 'php artisan pint' : hasPythonFastapi ? 'ruff check . && mypy .' : 'npm run lint');
 
     // --- CI ---
     section(t('q.section.ci'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "symfonia-ai-tools",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "AI tooling setup for your project - Claude Code, GitHub Copilot, Cursor, Gemini, Junie, GSD",
   "type": "module",
   "bin": {

package/templates/packs/python-fastapi/_ai/instructions/api-schema.instructions.md

@@ -0,0 +1,177 @@
+---
+applyTo: "**/schemas.py,**/*schema*.py,**/*request*.py,**/*response*.py"
+---
+
+# API Schemas, Request & Response Models — Instructions
+
+## Pydantic v2 Schemas
+
+Never return ORM models directly from endpoints. All input/output passes through Pydantic schemas.
+
+```python
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FeatureResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    name: str
+    description: str | None
+    status: FeatureStatus          # use the StrEnum — not bare `str`
+    created_at: datetime
+
+    # Nested relations — use None default (loaded on demand)
+    author: UserResponse | None = None
+    category: CategoryResponse | None = None
+```
+
+### Request Schemas (Input Validation)
+
+Request schemas are **read-only once validated** — add `frozen=True` to catch accidental mutation:
+
+```python
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from uuid import UUID
+
+
+class StoreFeatureRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(min_length=2, max_length=255)
+    description: str | None = Field(default=None, max_length=5000)
+    category_id: UUID | None = None
+    status: FeatureStatus
+    tags: list[str] = Field(default_factory=list)
+
+    @field_validator("tags")
+    @classmethod
+    def validate_tags(cls, v: list[str]) -> list[str]:
+        if any(len(tag) > 50 for tag in v):
+            raise ValueError("Each tag must be at most 50 characters")
+        return v
+
+
+class UpdateFeatureRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str | None = Field(default=None, min_length=2, max_length=255)
+    description: str | None = None
+    status: FeatureStatus | None = None
+```
+
+### List / Index Request with Filtering and Sorting
+
+```python
+from __future__ import annotations
+
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+class IndexFeatureRequest(BaseModel):
+    page: int = Field(default=1, ge=1)
+    limit: int = Field(default=20, ge=1, le=100)
+    status: FeatureStatus | None = None
+    sort_by: Literal["created_at", "name", "status"] = "created_at"
+    sort_dir: Literal["asc", "desc"] = "desc"
+```
+
+### Paginated Collection Response
+
+`PaginatedResponse` and `PaginationMeta` are **shared types** — define them once in `app/core/schemas.py`, never per-module:
+
+```python
+# app/core/schemas.py
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class PaginationMeta(BaseModel):
+    total: int
+    per_page: int
+    current_page: int
+    last_page: int
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    data: list[T]
+    meta: PaginationMeta
+```
+
+Import from `app.core.schemas` in every module that needs it.
+
+## Error Responses
+
+Standardize the error body shape. Define `ErrorResponse` in `app/core/schemas.py`:
+
+```python
+# app/core/schemas.py
+class ErrorResponse(BaseModel):
+    code: str           # machine-readable code: "FEATURE_NOT_FOUND"
+    message: str        # human-readable description
+    field: str | None = None  # which field caused the error (optional)
+```
+
+Raise via `HTTPException` — the exception handler converts it:
+
+```python
+from fastapi import HTTPException, status
+
+# In service (expected domain errors):
+raise HTTPException(
+    status_code=status.HTTP_404_NOT_FOUND,
+    detail={"code": "FEATURE_NOT_FOUND", "message": "Feature not found"},
+)
+```
+
+Register a handler in `app/main.py` to enforce consistent shape:
+
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    if isinstance(exc.detail, dict):
+        body = exc.detail
+    else:
+        body = {"code": "HTTP_ERROR", "message": str(exc.detail)}
+    return JSONResponse(status_code=exc.status_code, content=body)
+```
+
+## Enums
+
+```python
+from enum import StrEnum
+
+
+class FeatureStatus(StrEnum):
+    DRAFT = "draft"
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+```
+
+Use `StrEnum` (Python 3.11+) — auto-serializes to string in JSON.
+
+## Rules
+
+- `from_attributes=True` on every response schema that reads from ORM
+- Never expose internal IDs as integers — use UUID
+- Use `Field(...)` for constraints, not just annotations
+- `StrEnum` for all enums — clean JSON serialization, use in both request and response schemas
+- Nested relations are always `| None = None` — populate only when loaded
+- `frozen=True` on all request/input schemas — prevents accidental mutation after validation
+- `PaginatedResponse[T]` and `PaginationMeta` live in `app/core/schemas.py` — import, never redefine
+- `ErrorResponse` body has `code` (machine) and `message` (human) — register a global exception handler

package/templates/packs/python-fastapi/_ai/instructions/module.instructions.md

@@ -0,0 +1,211 @@
+---
+applyTo: "**/modules/**/router.py,**/modules/**/dependencies.py,**/modules/**/domain/**,**/modules/**/infrastructure/**"
+---
+
+# Modular Architecture — Instructions
+
+## Module Structure
+
+Each business domain has its own directory under `modules/`:
+
+```
+modules/feature/
+├── __init__.py
+├── router.py                        # FastAPI APIRouter — thin, no logic
+├── dependencies.py                  # Depends() factories for DI
+├── domain/
+│   ├── __init__.py
+│   ├── entities.py                  # Domain entities (pure Python dataclasses)
+│   ├── schemas.py                   # Pydantic v2 request/response schemas
+│   ├── services.py                  # Business logic
+│   ├── events.py                    # [optional] Domain events (dataclasses)
+│   └── value_objects.py             # [optional] Value objects (frozen dataclasses)
+├── infrastructure/
+│   ├── __init__.py
+│   ├── orm.py                       # SQLAlchemy ORM mapped classes
+│   ├── repositories/
+│   │   ├── __init__.py
+│   │   ├── base.py                  # Abstract base classes (interfaces)
+│   │   ├── command_repository.py    # SQLAlchemy write implementation
+│   │   └── query_repository.py     # SQLAlchemy read implementation
+│   └── tasks.py                     # [optional] Celery tasks for this module
+└── tests/
+    ├── __init__.py
+    ├── conftest.py                  # Module-level fixtures
+    ├── integration/
+    │   ├── __init__.py
+    │   └── test_feature_router.py
+    └── unit/
+        ├── __init__.py
+        └── test_feature_service.py
+```
+
+> **Optional files** (`events.py`, `value_objects.py`, `tasks.py`) — create only when needed. Do not scaffold files that will stay empty.
+
+## Router (`router.py`)
+
+```python
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, status
+
+from app.core.auth import get_current_user
+from modules.feature.dependencies import get_feature_service
+from modules.feature.domain.schemas import (
+    FeatureResponse,
+    IndexFeatureRequest,
+    PaginatedResponse,
+    StoreFeatureRequest,
+    UpdateFeatureRequest,
+)
+from modules.feature.domain.services import FeatureService
+
+router = APIRouter(prefix="/features", tags=["features"])
+
+
+@router.get("", response_model=PaginatedResponse[FeatureResponse])
+async def index(
+    params: IndexFeatureRequest = Depends(),
+    current_user=Depends(get_current_user),
+    service: FeatureService = Depends(get_feature_service),
+) -> PaginatedResponse[FeatureResponse]:
+    return await service.list_for_user(current_user.id, params)
+
+
+@router.post("", response_model=FeatureResponse, status_code=status.HTTP_201_CREATED)
+async def store(
+    body: StoreFeatureRequest,
+    current_user=Depends(get_current_user),
+    service: FeatureService = Depends(get_feature_service),
+) -> FeatureResponse:
+    return await service.create(current_user.id, body)
+
+
+@router.get("/{feature_id}", response_model=FeatureResponse)
+async def show(
+    feature_id: UUID,
+    current_user=Depends(get_current_user),
+    service: FeatureService = Depends(get_feature_service),
+) -> FeatureResponse:
+    return await service.get_or_404(feature_id, current_user.id)
+
+
+@router.patch("/{feature_id}", response_model=FeatureResponse)
+async def update(
+    feature_id: UUID,
+    body: UpdateFeatureRequest,
+    current_user=Depends(get_current_user),
+    service: FeatureService = Depends(get_feature_service),
+) -> FeatureResponse:
+    return await service.update(feature_id, current_user.id, body)
+
+
+@router.delete("/{feature_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def destroy(
+    feature_id: UUID,
+    current_user=Depends(get_current_user),
+    service: FeatureService = Depends(get_feature_service),
+) -> None:
+    await service.delete(feature_id, current_user.id)
+```
+
+## Dependencies (`dependencies.py`)
+
+```python
+from __future__ import annotations
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from modules.feature.domain.services import FeatureService
+from modules.feature.infrastructure.repositories.command_repository import (
+    SqlAlchemyFeatureCommandRepository,
+)
+from modules.feature.infrastructure.repositories.query_repository import (
+    SqlAlchemyFeatureQueryRepository,
+)
+
+
+def get_feature_service(
+    db: AsyncSession = Depends(get_db),
+) -> FeatureService:
+    return FeatureService(
+        command_repo=SqlAlchemyFeatureCommandRepository(db),
+        query_repo=SqlAlchemyFeatureQueryRepository(db),
+    )
+```
+
+## Router Registration (`app/main.py`)
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from app.core.config import settings
+from modules.feature.router import router as feature_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # startup
+    yield
+    # shutdown
+
+app = FastAPI(lifespan=lifespan)
+app.include_router(feature_router, prefix=f"/api/{settings.API_VERSION}")
+```
+
+> Use `lifespan=` context manager (FastAPI 0.95+). The deprecated `@app.on_event("startup")` pattern must not be used.
+
+## ORM Model (`infrastructure/orm.py`)
+
+```python
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import UUID as SA_UUID
+from sqlalchemy import DateTime, Enum, ForeignKey, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+from modules.feature.domain.entities import FeatureStatus
+
+
+class FeatureORM(Base):
+    __tablename__ = "features"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        SA_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[FeatureStatus] = mapped_column(
+        Enum(FeatureStatus), nullable=False, default=FeatureStatus.DRAFT
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        SA_UUID(as_uuid=True), ForeignKey("users.id"), nullable=False, index=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    user: Mapped["UserORM"] = relationship("UserORM", lazy="noload")
+```
+
+## Rules
+
+- Routers are thin — one line per handler, everything delegated to service
+- `Depends()` factory per module in `dependencies.py`
+- ORM models live in `infrastructure/orm.py`, never in `domain/`
+- Domain entities are plain dataclasses — no SQLAlchemy imports in `domain/`
+- Abstract repository interfaces live in `infrastructure/repositories/base.py`; SQLAlchemy implementations are separate files in the same folder
+- Register all routers in `app/main.py` with versioned prefix
+- Use `server_default=func.now()` for `created_at` — not Python-side `datetime.now()` in ORM defaults
+- Do NOT scaffold `events.py`, `value_objects.py`, or `tasks.py` unless the module actually needs them