@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/fastapi-expert/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fastapi-expert
+description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: backend
+  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, django-expert, test-master
+---
+
+# FastAPI Expert
+
+Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+
+## Role Definition
+
+You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+
+## When to Use This Skill
+
+- Building REST APIs with FastAPI
+- Implementing Pydantic V2 validation schemas
+- Setting up async database operations
+- Implementing JWT authentication/authorization
+- Creating WebSocket endpoints
+- Optimizing API performance
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify endpoints, data models, auth needs
+2. **Design schemas** - Create Pydantic V2 models for validation
+3. **Implement** - Write async endpoints with proper dependency injection
+4. **Secure** - Add authentication, authorization, rate limiting
+5. **Test** - Write async tests with pytest and httpx
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+
+## Constraints
+
+### MUST DO
+- Use type hints everywhere (FastAPI requires them)
+- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
+- Use `Annotated` pattern for dependency injection
+- Use async/await for all I/O operations
+- Use `X | None` instead of `Optional[X]`
+- Return proper HTTP status codes
+- Document endpoints (auto-generated OpenAPI)
+
+### MUST NOT DO
+- Use synchronous database operations
+- Skip Pydantic validation
+- Store passwords in plain text
+- Expose sensitive data in responses
+- Use Pydantic V1 syntax (`@validator`, `class Config`)
+- Mix sync and async code improperly
+- Hardcode configuration values
+
+## Output Templates
+
+When implementing FastAPI features, provide:
+1. Schema file (Pydantic models)
+2. Endpoint file (router with endpoints)
+3. CRUD operations if database involved
+4. Brief explanation of key decisions
+
+## Knowledge Reference
+
+FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/fastapi-expert/references/async-sqlalchemy.md

@@ -0,0 +1,146 @@
+# Async SQLAlchemy
+
+## Engine & Session Setup
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+)
+
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+class Base(DeclarativeBase):
+    pass
+```
+
+## Model Definition
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy import String, ForeignKey, DateTime, func
+from datetime import datetime
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(50), unique=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author", lazy="selectin")
+
+class Post(Base):
+    __tablename__ = "posts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str] = mapped_column(String(200))
+    content: Mapped[str]
+    author_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+
+    author: Mapped["User"] = relationship(back_populates="posts")
+```
+
+## Database Dependency
+
+```python
+from typing import AsyncGenerator
+from fastapi import Depends
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+# Type alias for injection
+DB = Annotated[AsyncSession, Depends(get_db)]
+```
+
+## CRUD Operations
+
+```python
+from sqlalchemy import select, update, delete
+from sqlalchemy.orm import selectinload
+
+async def get_user(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(select(User).where(User.id == user_id))
+    return result.scalar_one_or_none()
+
+async def get_user_with_posts(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(
+        select(User)
+        .options(selectinload(User.posts))
+        .where(User.id == user_id)
+    )
+    return result.scalar_one_or_none()
+
+async def get_users(db: AsyncSession, skip: int = 0, limit: int = 100) -> list[User]:
+    result = await db.execute(select(User).offset(skip).limit(limit))
+    return list(result.scalars().all())
+
+async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
+    user = User(**user_in.model_dump())
+    db.add(user)
+    await db.flush()
+    await db.refresh(user)
+    return user
+
+async def update_user(db: AsyncSession, user_id: int, user_in: UserUpdate) -> User:
+    await db.execute(
+        update(User)
+        .where(User.id == user_id)
+        .values(**user_in.model_dump(exclude_unset=True))
+    )
+    return await get_user(db, user_id)
+
+async def delete_user(db: AsyncSession, user_id: int) -> bool:
+    result = await db.execute(delete(User).where(User.id == user_id))
+    return result.rowcount > 0
+```
+
+## Lifespan Handler
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown
+    await engine.dispose()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Quick Reference
+
+| Operation | Method |
+|-----------|--------|
+| Select one | `result.scalar_one_or_none()` |
+| Select many | `result.scalars().all()` |
+| Eager load | `.options(selectinload(...))` |
+| Create | `db.add(obj)` + `await db.flush()` |
+| Update | `update(Model).where(...).values(...)` |
+| Delete | `delete(Model).where(...)` |
+| Commit | `await db.commit()` |
+| Rollback | `await db.rollback()` |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/fastapi-expert/references/authentication.md

@@ -0,0 +1,159 @@
+# Authentication
+
+## OAuth2 Password Flow
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from typing import Annotated
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/token")
+
+@router.post("/token")
+async def login(
+    db: DB,
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+) -> Token:
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED,
+            "Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## JWT Token Creation
+
+```python
+from datetime import datetime, timedelta, UTC
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def create_access_token(
+    sub: str,
+    expires_delta: timedelta | None = None,
+) -> str:
+    expire = datetime.now(UTC) + (expires_delta or timedelta(minutes=15))
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "access"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+
+def create_refresh_token(sub: str) -> str:
+    expire = datetime.now(UTC) + timedelta(days=7)
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "refresh"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+```
+
+## Get Current User
+
+```python
+async def get_current_user(
+    db: DB,
+    token: Annotated[str, Depends(oauth2_scheme)],
+) -> User:
+    credentials_exception = HTTPException(
+        status.HTTP_401_UNAUTHORIZED,
+        "Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id = int(payload.get("sub"))
+        if payload.get("type") != "access":
+            raise credentials_exception
+    except (JWTError, ValueError, TypeError):
+        raise credentials_exception
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise credentials_exception
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+```
+
+## Role-Based Access
+
+```python
+from enum import Enum
+
+class UserRole(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+def require_roles(*roles: UserRole):
+    async def role_checker(current_user: CurrentUser) -> User:
+        if current_user.role not in roles:
+            raise HTTPException(
+                status.HTTP_403_FORBIDDEN,
+                f"Required roles: {[r.value for r in roles]}",
+            )
+        return current_user
+    return role_checker
+
+# Usage
+@router.delete("/{id}")
+async def delete_user(
+    user_id: int,
+    admin: Annotated[User, Depends(require_roles(UserRole.ADMIN))],
+) -> None:
+    ...
+```
+
+## Refresh Token
+
+```python
+@router.post("/refresh", response_model=Token)
+async def refresh_token(
+    db: DB,
+    refresh_token: str = Body(..., embed=True),
+) -> Token:
+    try:
+        payload = jwt.decode(refresh_token, settings.SECRET_KEY, algorithms=["HS256"])
+        if payload.get("type") != "refresh":
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token type")
+        user_id = int(payload.get("sub"))
+    except (JWTError, ValueError):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid refresh token")
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "User not found")
+
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `OAuth2PasswordBearer` | Extract token from header |
+| `OAuth2PasswordRequestForm` | Login form data |
+| `jwt.encode()` | Create JWT |
+| `jwt.decode()` | Verify JWT |
+| `pwd_context.hash()` | Hash password |
+| `pwd_context.verify()` | Check password |
+| `Depends(get_current_user)` | Require auth |
+| `require_roles()` | Role-based access |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/fastapi-expert/references/endpoints-routing.md

@@ -0,0 +1,142 @@
+# Endpoints & Routing
+
+## Router Setup
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Path
+from typing import Annotated
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+# Type aliases for common dependencies
+DB = Annotated[AsyncSession, Depends(get_db)]
+CurrentUser = Annotated[User, Depends(get_current_user)]
+Pagination = Annotated[int, Query(ge=1, le=100)]
+```
+
+## CRUD Endpoints
+
+```python
+@router.post("/", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def create_user(db: DB, user_in: UserCreate) -> User:
+    if await get_user_by_email(db, user_in.email):
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Email already registered")
+    return await create_user_db(db, user_in)
+
+@router.get("/", response_model=list[UserOut])
+async def list_users(
+    db: DB,
+    current_user: CurrentUser,
+    skip: int = Query(0, ge=0),
+    limit: Pagination = 20,
+) -> list[User]:
+    return await get_users(db, skip=skip, limit=limit)
+
+@router.get("/{user_id}", response_model=UserOut)
+async def get_user(
+    db: DB,
+    user_id: Annotated[int, Path(gt=0)],
+) -> User:
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "User not found")
+    return user
+
+@router.patch("/{user_id}", response_model=UserOut)
+async def update_user(
+    db: DB,
+    user_id: int,
+    user_in: UserUpdate,
+    current_user: CurrentUser,
+) -> User:
+    if current_user.id != user_id and not current_user.is_admin:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "Not authorized")
+    return await update_user_db(db, user_id, user_in)
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(db: DB, user_id: int, current_user: CurrentUser) -> None:
+    if not await delete_user_db(db, user_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "User not found")
+```
+
+## Custom Dependencies
+
+```python
+from fastapi import Depends
+
+async def get_current_active_user(
+    current_user: CurrentUser,
+) -> User:
+    if not current_user.is_active:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Inactive user")
+    return current_user
+
+ActiveUser = Annotated[User, Depends(get_current_active_user)]
+
+async def require_admin(current_user: CurrentUser) -> User:
+    if not current_user.is_admin:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "Admin required")
+    return current_user
+
+AdminUser = Annotated[User, Depends(require_admin)]
+```
+
+## Query Parameters
+
+```python
+@router.get("/search")
+async def search_users(
+    db: DB,
+    q: str = Query(min_length=1, max_length=100),
+    is_active: bool | None = None,
+    role: UserRole | None = None,
+    created_after: datetime | None = None,
+    sort_by: Annotated[str, Query(pattern="^(name|email|created_at)$")] = "created_at",
+    order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
+) -> list[User]:
+    return await search_users_db(db, q, is_active, role, created_after, sort_by, order)
+```
+
+## Include Router
+
+```python
+# main.py
+from fastapi import FastAPI
+from app.api.v1 import users, auth, posts
+
+app = FastAPI()
+
+app.include_router(users.router, prefix="/api/v1")
+app.include_router(auth.router, prefix="/api/v1")
+app.include_router(posts.router, prefix="/api/v1")
+```
+
+## Response Models
+
+```python
+from fastapi import Response
+
+@router.get("/", response_model=list[UserOut], response_model_exclude_unset=True)
+async def list_users(...) -> list[User]:
+    ...
+
+@router.get("/{id}", responses={
+    200: {"model": UserOut},
+    404: {"description": "User not found"},
+})
+async def get_user(...) -> User:
+    ...
+```
+
+## Quick Reference
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@router.get("/")` | GET endpoint |
+| `@router.post("/", status_code=201)` | POST with status |
+| `Query(ge=0)` | Query param validation |
+| `Path(gt=0)` | Path param validation |
+| `Depends(func)` | Dependency injection |
+| `Annotated[T, Depends()]` | Type alias pattern |
+| `response_model=Model` | Response schema |
+| `HTTPException(status, detail)` | Error response |