@plazmodium/odin 0.3.3-beta → 0.3.5-beta

package/builtin/skills/backend/python-fastapi/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: python-fastapi
+description: FastAPI framework for building high-performance async Python APIs with automatic OpenAPI docs
+category: backend
+version: "0.100+"
+compatible_with:
+  - postgresql
+  - mongodb
+  - redis
+  - rest-api
+---
+
+# Python FastAPI
+
+## Overview
+
+FastAPI is a modern, high-performance Python web framework for building APIs. It uses Python type hints for automatic validation, serialization, and OpenAPI documentation.
+
+## Project Structure
+
+```
+src/
+├── main.py                  # FastAPI app instance + startup
+├── config.py                # Settings via pydantic-settings
+├── routers/
+│   ├── auth.py              # Auth endpoints
+│   └── users.py             # User endpoints
+├── models/
+│   ├── user.py              # SQLAlchemy / ORM models
+│   └── schemas.py           # Pydantic request/response schemas
+├── services/
+│   └── user_service.py      # Business logic
+├── middleware/
+│   └── auth.py              # Auth dependency
+├── db/
+│   ├── session.py           # Database session
+│   └── migrations/          # Alembic migrations
+└── tests/
+    ├── conftest.py           # Fixtures
+    └── test_users.py
+```
+
+## Core Patterns
+
+### App Setup
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await db.connect()
+    yield
+    # Shutdown
+    await db.disconnect()
+
+app = FastAPI(title="My API", lifespan=lifespan)
+app.include_router(auth_router, prefix="/auth", tags=["auth"])
+app.include_router(users_router, prefix="/users", tags=["users"])
+```
+
+### Pydantic Schemas
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8)
+    name: str = Field(max_length=100)
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    name: str
+
+    model_config = {"from_attributes": True}  # ORM mode
+```
+
+### Dependency Injection
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
+    payload = decode_jwt(token)
+    if not payload:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+    user = await user_service.get_by_id(payload["sub"])
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+    return user
+
+# Use in endpoint
+@router.get("/me", response_model=UserResponse)
+async def get_me(user: User = Depends(get_current_user)):
+    return user
+```
+
+### Error Handling
+
+```python
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+
+class AppException(Exception):
+    def __init__(self, status_code: int, detail: str, code: str):
+        self.status_code = status_code
+        self.detail = detail
+        self.code = code
+
+@app.exception_handler(AppException)
+async def app_exception_handler(request, exc: AppException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.code, "detail": exc.detail},
+    )
+```
+
+## Best Practices
+
+1. **Use async** — prefer `async def` endpoints with async DB drivers (asyncpg, motor)
+2. **Pydantic v2** — use `model_config` dict, not inner `Config` class
+3. **Dependency injection** — use `Depends()` for auth, DB sessions, services
+4. **Response models** — always set `response_model` to control serialization
+5. **Background tasks** — use `BackgroundTasks` for non-blocking operations
+6. **Settings** — use `pydantic-settings` with `.env` files for configuration
+7. **Alembic** — use for database migrations, never raw SQL in app code
+
+## Gotchas
+
+- **Sync vs async**: Mixing sync and async code blocks the event loop — use `run_in_executor` for sync operations
+- **Pydantic v1 vs v2**: Many tutorials use v1 syntax — check for `model_config` vs inner `Config`
+- **Dependency scope**: Dependencies are per-request by default; use `yield` dependencies for cleanup
+- **OpenAPI schema**: Circular model references require `model_rebuild()` calls

package/builtin/skills/database/mongodb/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: mongodb
+description: MongoDB document database patterns, schema design, indexing, and aggregation
+category: database
+version: "7.x"
+compatible_with:
+  - nodejs-express
+  - nodejs-fastify
+  - python-fastapi
+  - rest-api
+---
+
+# MongoDB
+
+## Overview
+
+MongoDB is a document database that stores data in flexible JSON-like documents. This skill covers schema design, queries, indexing, and aggregation pipelines.
+
+## Schema Design
+
+### Embedding vs Referencing
+
+```javascript
+// EMBED when data is read together and has a 1:few relationship
+{
+  _id: ObjectId("..."),
+  name: "John",
+  addresses: [
+    { street: "123 Main", city: "Springfield", type: "home" },
+    { street: "456 Work", city: "Springfield", type: "work" }
+  ]
+}
+
+// REFERENCE when data is many:many, frequently updated independently, or large
+{
+  _id: ObjectId("..."),
+  name: "John",
+  organization_id: ObjectId("...")  // Reference to organizations collection
+}
+```
+
+### Schema Validation
+
+```javascript
+db.createCollection("users", {
+  validator: {
+    $jsonSchema: {
+      bsonType: "object",
+      required: ["email", "name", "createdAt"],
+      properties: {
+        email: { bsonType: "string", pattern: "^.+@.+$" },
+        name: { bsonType: "string", maxLength: 100 },
+        role: { enum: ["admin", "member", "viewer"] },
+        createdAt: { bsonType: "date" }
+      }
+    }
+  }
+});
+```
+
+## Query Patterns
+
+### CRUD
+
+```javascript
+// Find with projection
+const user = await db.collection('users').findOne(
+  { email: "john@example.com" },
+  { projection: { password_hash: 0 } }  // Exclude sensitive fields
+);
+
+// Update with operators
+await db.collection('users').updateOne(
+  { _id: userId },
+  { $set: { name: "New Name" }, $currentDate: { updatedAt: true } }
+);
+
+// Upsert
+await db.collection('metrics').updateOne(
+  { date: today, type: "pageview" },
+  { $inc: { count: 1 } },
+  { upsert: true }
+);
+```
+
+### Aggregation Pipeline
+
+```javascript
+const result = await db.collection('orders').aggregate([
+  { $match: { status: "completed", createdAt: { $gte: thirtyDaysAgo } } },
+  { $group: { _id: "$customerId", totalSpent: { $sum: "$total" }, orderCount: { $sum: 1 } } },
+  { $sort: { totalSpent: -1 } },
+  { $limit: 10 },
+  { $lookup: { from: "customers", localField: "_id", foreignField: "_id", as: "customer" } },
+  { $unwind: "$customer" },
+  { $project: { name: "$customer.name", totalSpent: 1, orderCount: 1 } }
+]).toArray();
+```
+
+### Indexes
+
+```javascript
+// Single field
+db.users.createIndex({ email: 1 }, { unique: true });
+
+// Compound (order matters for query optimization)
+db.orders.createIndex({ customerId: 1, createdAt: -1 });
+
+// TTL (auto-delete documents after expiry)
+db.sessions.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+
+// Text search
+db.articles.createIndex({ title: "text", body: "text" });
+```
+
+## Best Practices
+
+1. **Design for queries** — model data based on access patterns, not normalization
+2. **Embed by default** — reference only when there's a clear reason
+3. **Index for your queries** — use `explain()` to verify index usage
+4. **Use `$project` early** — reduce document size in aggregation pipelines
+5. **Avoid unbounded arrays** — arrays that grow without limit cause performance issues
+6. **Use transactions sparingly** — multi-document transactions add overhead; design schemas to minimize need
+7. **Connection pooling** — reuse client instances; don't connect/disconnect per request
+
+## Gotchas
+
+- **No JOINs** — `$lookup` exists but is expensive; embed data you read together
+- **Document size limit** — 16MB per document; watch out for growing arrays
+- **ObjectId ordering** — ObjectIds contain timestamps, so default `_id` sort is chronological
+- **Schemaless trap** — lack of enforced schema leads to inconsistent data; use validation
+- **Write concern** — default `w:1` may lose data on failover; use `w:"majority"` for durability

package/builtin/skills/database/postgresql/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: postgresql
+description: PostgreSQL database best practices, query patterns, indexing, and performance optimization
+category: database
+version: "15+"
+compatible_with:
+  - prisma-orm
+  - supabase
+  - nodejs-express
+  - nodejs-fastify
+  - python-fastapi
+  - python-django
+---
+
+# PostgreSQL
+
+## Overview
+
+PostgreSQL is an advanced open-source relational database. This skill covers schema design, query patterns, indexing, and performance for application developers.
+
+## Schema Design
+
+### Tables
+
+```sql
+-- Always use explicit types and constraints
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    name TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Use enums for fixed value sets
+CREATE TYPE user_role AS ENUM ('admin', 'member', 'viewer');
+ALTER TABLE users ADD COLUMN role user_role NOT NULL DEFAULT 'member';
+
+-- Junction table for many-to-many
+CREATE TABLE user_organizations (
+    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+    org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
+    role user_role NOT NULL DEFAULT 'member',
+    joined_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, org_id)
+);
+```
+
+### Indexes
+
+```sql
+-- B-tree (default) for equality and range queries
+CREATE INDEX idx_users_email ON users(email);
+
+-- Partial index for common filtered queries
+CREATE INDEX idx_active_users ON users(created_at) WHERE is_active = true;
+
+-- GIN for JSONB and full-text search
+CREATE INDEX idx_metadata ON products USING GIN(metadata);
+CREATE INDEX idx_search ON articles USING GIN(to_tsvector('english', title || ' ' || body));
+
+-- Composite for multi-column queries (leftmost prefix rule)
+CREATE INDEX idx_org_role ON user_organizations(org_id, role);
+```
+
+## Query Patterns
+
+### Common Patterns
+
+```sql
+-- Upsert (INSERT ... ON CONFLICT)
+INSERT INTO users (email, name) VALUES ($1, $2)
+ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name, updated_at = now()
+RETURNING *;
+
+-- Pagination with cursor (better than OFFSET for large tables)
+SELECT * FROM users
+WHERE created_at < $1  -- cursor: last item's created_at
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- CTE for complex queries
+WITH active_users AS (
+    SELECT * FROM users WHERE last_login > now() - interval '30 days'
+)
+SELECT org_id, count(*) as active_count
+FROM user_organizations uo
+JOIN active_users au ON uo.user_id = au.id
+GROUP BY org_id;
+```
+
+### JSONB
+
+```sql
+-- Query JSONB fields
+SELECT * FROM products WHERE metadata->>'category' = 'electronics';
+SELECT * FROM products WHERE metadata @> '{"tags": ["sale"]}';
+
+-- Update JSONB
+UPDATE products SET metadata = metadata || '{"featured": true}' WHERE id = $1;
+```
+
+## Best Practices
+
+1. **Use UUID primary keys** for distributed-friendly IDs (`gen_random_uuid()`)
+2. **Always `TIMESTAMPTZ`** — never `TIMESTAMP` without timezone
+3. **Parameterized queries** — never interpolate user input into SQL
+4. **Foreign keys with ON DELETE** — explicit cascade/restrict/set null behavior
+5. **`EXPLAIN ANALYZE`** — profile queries before optimizing; check seq scans
+6. **Connection pooling** — use PgBouncer or built-in pool (Supabase provides this)
+7. **Migrations** — use a migration tool (Alembic, Prisma, Flyway); never manual DDL in production
+
+## Gotchas
+
+- **NULL semantics** — `NULL != NULL`, use `IS NOT DISTINCT FROM` for nullable comparisons
+- **OFFSET performance** — degrades linearly with page number; use cursor-based pagination
+- **Lock contention** — long-running transactions block writes; keep transactions short
+- **Index bloat** — `REINDEX` or `pg_repack` for heavily updated tables
+- **Text search** — `LIKE '%term%'` can't use B-tree indexes; use GIN + `tsvector` for full-text