@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

package/pipeline/skills/shared/external/python-patterns/references/python-examples.md

@@ -0,0 +1,176 @@
+# Python pattern examples
+
+<!-- toc -->
+- [Pydantic v2](#pydantic-v2)
+- [Async/Await with asyncio](#asyncawait-with-asyncio)
+- [Pattern Matching (match/case)](#pattern-matching-matchcase)
+<!-- /toc -->
+
+Code for Pydantic v2 models, asyncio patterns and structural pattern matching. SKILL.md keeps the principles and the rules.
+
+## Pydantic v2
+
+```python
+from pydantic import BaseModel, Field, field_validator, model_validator, ConfigDict
+from datetime import datetime
+
+class CreateUserRequest(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, frozen=True)
+
+    name: str = Field(min_length=1, max_length=100)
+    email: str = Field(pattern=r'^[\w.-]+@[\w.-]+\.\w+$')
+    age: int = Field(ge=0, le=150)
+    role: Role = Role.USER
+    tags: list[str] = Field(default_factory=list, max_length=10)
+
+    @field_validator('email')
+    @classmethod
+    def normalize_email(cls, v: str) -> str:
+        return v.lower()
+
+    @model_validator(mode='after')
+    def validate_admin_age(self) -> 'CreateUserRequest':
+        if self.role == Role.ADMIN and self.age < 18:
+            raise ValueError("Admin must be 18 or older")
+        return self
+
+class UserResponse(BaseModel):
+    id: str
+    name: str
+    email: str
+    role: Role
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+# Validation
+try:
+    user = CreateUserRequest(name="Alice", email="ALICE@example.com", age=25)
+    print(user.email)  # "alice@example.com" (normalized)
+except ValidationError as e:
+    print(e.errors())
+
+# Serialization
+user_dict = user.model_dump()
+user_json = user.model_dump_json()
+
+# From ORM object
+db_user = db.query(UserModel).first()
+response = UserResponse.model_validate(db_user)
+```
+
+## Async/Await with asyncio
+
+```python
+import asyncio
+from collections.abc import AsyncIterator
+import httpx
+
+# Async function
+async def fetch_user(user_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"https://api.example.com/users/{user_id}")
+        response.raise_for_status()
+        return response.json()
+
+# Parallel execution
+async def fetch_all_users(user_ids: list[str]) -> list[dict]:
+    async with httpx.AsyncClient() as client:
+        tasks = [
+            client.get(f"https://api.example.com/users/{uid}")
+            for uid in user_ids
+        ]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+        return [
+            r.json() for r in responses
+            if not isinstance(r, Exception) and r.status_code == 200
+        ]
+
+# Async context manager
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def get_db_session() -> AsyncIterator[AsyncSession]:
+    session = AsyncSession(engine)
+    try:
+        yield session
+        await session.commit()
+    except Exception:
+        await session.rollback()
+        raise
+    finally:
+        await session.close()
+
+# Async generator
+async def stream_events(url: str) -> AsyncIterator[dict]:
+    async with httpx.AsyncClient() as client:
+        async with client.stream("GET", url) as response:
+            async for line in response.aiter_lines():
+                if line.startswith("data: "):
+                    yield json.loads(line[6:])
+
+# Semaphore for rate limiting
+async def fetch_with_limit(urls: list[str], max_concurrent: int = 10) -> list[str]:
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def fetch_one(url: str) -> str:
+        async with semaphore:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(url)
+                return resp.text
+
+    return await asyncio.gather(*[fetch_one(url) for url in urls])
+```
+
+## Pattern Matching (match/case)
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: float
+    y: float
+
+def describe_point(point: Point) -> str:
+    match point:
+        case Point(x=0, y=0):
+            return "origin"
+        case Point(x=0, y=y):
+            return f"on y-axis at y={y}"
+        case Point(x=x, y=0):
+            return f"on x-axis at x={x}"
+        case Point(x=x, y=y) if x == y:
+            return f"on diagonal at {x}"
+        case _:
+            return f"at ({point.x}, {point.y})"
+
+# Matching on type and structure
+def handle_response(response: dict) -> str:
+    match response:
+        case {"status": 200, "data": data}:
+            return f"Success: {data}"
+        case {"status": 404}:
+            return "Not found"
+        case {"status": status} if 500 <= status < 600:
+            return f"Server error: {status}"
+        case {"error": str(message)}:
+            return f"Error: {message}"
+        case _:
+            return "Unknown response"
+
+# Matching sequences
+def process_command(command: list[str]) -> None:
+    match command:
+        case ["quit" | "exit"]:
+            sys.exit(0)
+        case ["go", direction]:
+            move(direction)
+        case ["pick", "up", item]:
+            pick_up(item)
+        case ["drop", *items] if items:
+            for item in items:
+                drop(item)
+        case _:
+            print(f"Unknown command: {' '.join(command)}")
+```

package/pipeline/skills/shared/external/rest-api-design/SKILL.md

@@ -82,93 +82,13 @@ GET    /api/v1/posts?fields=id,title,slug      # Sparse fieldsets
 
 ## Response Envelope
 
-```typescript
-// Consistent response shape
-
-// Success: single resource
-{
-  "data": {
-    "id": "user_abc123",
-    "type": "user",
-    "attributes": {
-      "name": "Alice Johnson",
-      "email": "alice@example.com",
-      "role": "admin",
-      "created_at": "2025-01-15T10:30:00Z"
-    }
-  }
-}
-
-// Success: collection
-{
-  "data": [
-    { "id": "post_1", "type": "post", "attributes": { ... } },
-    { "id": "post_2", "type": "post", "attributes": { ... } }
-  ],
-  "meta": {
-    "total": 150,
-    "page": 1,
-    "per_page": 20,
-    "has_next": true
-  }
-}
-
-// Error response
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Request validation failed",
-    "details": [
-      { "field": "email", "message": "Must be a valid email address" },
-      { "field": "age", "message": "Must be between 0 and 150" }
-    ],
-    "request_id": "req_xyz789"
-  }
-}
-```
+Code for this section: [REST API examples](references/api-examples.md).
 
 ## Pagination
 
 ### Cursor-Based (Recommended)
 
-```typescript
-// Request
-// GET /api/v1/posts?limit=20&after=eyJpZCI6InBvc3RfMTAwIn0
-
-// Response
-{
-  "data": [ ... ],
-  "pagination": {
-    "has_next": true,
-    "has_prev": false,
-    "next_cursor": "eyJpZCI6InBvc3RfMTIwIn0",
-    "prev_cursor": null
-  }
-}
-
-// Server implementation (Node.js / Express)
-async function listPosts(req: Request, res: Response) {
-  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
-  const cursor = req.query.after ? decodeCursor(req.query.after as string) : null;
-
-  const posts = await db.post.findMany({
-    where: cursor ? { id: { gt: cursor.id } } : undefined,
-    orderBy: { id: 'asc' },
-    take: limit + 1, // Fetch one extra to check has_next
-  });
-
-  const hasNext = posts.length > limit;
-  if (hasNext) posts.pop();
-
-  res.json({
-    data: posts,
-    pagination: {
-      has_next: hasNext,
-      next_cursor: hasNext ? encodeCursor({ id: posts[posts.length - 1].id }) : null,
-    },
-  });
-}
-```
+Code for this section: [REST API examples](references/api-examples.md).
 
 ### Offset-Based (Simple, for small datasets)
 
@@ -279,81 +199,7 @@ app.get('/api/v1/posts/:id', async (req, res) => {
 
 ## OpenAPI / Swagger Documentation
 
-```yaml
-# openapi.yaml
-openapi: 3.1.0
-info:
-  title: My API
-  version: 1.0.0
-  description: Production REST API
-
-servers:
-  - url: https://api.example.com/v1
-
-paths:
-  /users:
-    get:
-      summary: List users
-      tags: [Users]
-      parameters:
-        - name: page
-          in: query
-          schema: { type: integer, minimum: 1, default: 1 }
-        - name: per_page
-          in: query
-          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
-      responses:
-        '200':
-          description: List of users
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: array
-                    items: { $ref: '#/components/schemas/User' }
-                  meta:
-                    $ref: '#/components/schemas/PaginationMeta'
-
-    post:
-      summary: Create user
-      tags: [Users]
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/CreateUserRequest' }
-      responses:
-        '201':
-          description: User created
-          headers:
-            Location:
-              schema: { type: string }
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data: { $ref: '#/components/schemas/User' }
-        '422':
-          description: Validation error
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
-
-components:
-  schemas:
-    User:
-      type: object
-      required: [id, name, email, role, created_at]
-      properties:
-        id: { type: string, format: uuid }
-        name: { type: string }
-        email: { type: string, format: email }
-        role: { type: string, enum: [admin, user, viewer] }
-        created_at: { type: string, format: date-time }
-```
+Code for this section: [REST API examples](references/api-examples.md).
 
 ## Do's
 
@@ -387,3 +233,7 @@ components:
 | CORS errors | Missing headers on OPTIONS response | Configure CORS middleware with allowed origins |
 | Stale cache | No cache invalidation strategy | Use ETag + conditional requests, short max-age |
 | Breaking clients | Schema change without versioning | Add new version, deprecate old with Sunset header |
+
+## References
+
+- [REST API examples](references/api-examples.md): open when shaping response envelopes, implementing cursor pagination or writing an OpenAPI spec.

package/pipeline/skills/shared/external/rest-api-design/references/api-examples.md

@@ -0,0 +1,175 @@
+# REST API examples
+
+<!-- toc -->
+- [Response Envelope](#response-envelope)
+- [Cursor-Based (Recommended)](#cursor-based-recommended)
+- [OpenAPI / Swagger Documentation](#openapi-swagger-documentation)
+<!-- /toc -->
+
+Response envelope shapes, cursor pagination code and an OpenAPI document. SKILL.md keeps the URL, method, status, versioning, rate limiting and caching rules.
+
+## Response Envelope
+
+```typescript
+// Consistent response shape
+
+// Success: single resource
+{
+  "data": {
+    "id": "user_abc123",
+    "type": "user",
+    "attributes": {
+      "name": "Alice Johnson",
+      "email": "alice@example.com",
+      "role": "admin",
+      "created_at": "2025-01-15T10:30:00Z"
+    }
+  }
+}
+
+// Success: collection
+{
+  "data": [
+    { "id": "post_1", "type": "post", "attributes": { ... } },
+    { "id": "post_2", "type": "post", "attributes": { ... } }
+  ],
+  "meta": {
+    "total": 150,
+    "page": 1,
+    "per_page": 20,
+    "has_next": true
+  }
+}
+
+// Error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" },
+      { "field": "age", "message": "Must be between 0 and 150" }
+    ],
+    "request_id": "req_xyz789"
+  }
+}
+```
+
+### Cursor-Based (Recommended)
+
+```typescript
+// Request
+// GET /api/v1/posts?limit=20&after=eyJpZCI6InBvc3RfMTAwIn0
+
+// Response
+{
+  "data": [ ... ],
+  "pagination": {
+    "has_next": true,
+    "has_prev": false,
+    "next_cursor": "eyJpZCI6InBvc3RfMTIwIn0",
+    "prev_cursor": null
+  }
+}
+
+// Server implementation (Node.js / Express)
+async function listPosts(req: Request, res: Response) {
+  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
+  const cursor = req.query.after ? decodeCursor(req.query.after as string) : null;
+
+  const posts = await db.post.findMany({
+    where: cursor ? { id: { gt: cursor.id } } : undefined,
+    orderBy: { id: 'asc' },
+    take: limit + 1, // Fetch one extra to check has_next
+  });
+
+  const hasNext = posts.length > limit;
+  if (hasNext) posts.pop();
+
+  res.json({
+    data: posts,
+    pagination: {
+      has_next: hasNext,
+      next_cursor: hasNext ? encodeCursor({ id: posts[posts.length - 1].id }) : null,
+    },
+  });
+}
+```
+
+## OpenAPI / Swagger Documentation
+
+```yaml
+# openapi.yaml
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+  description: Production REST API
+
+servers:
+  - url: https://api.example.com/v1
+
+paths:
+  /users:
+    get:
+      summary: List users
+      tags: [Users]
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: per_page
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: '#/components/schemas/User' }
+                  meta:
+                    $ref: '#/components/schemas/PaginationMeta'
+
+    post:
+      summary: Create user
+      tags: [Users]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CreateUserRequest' }
+      responses:
+        '201':
+          description: User created
+          headers:
+            Location:
+              schema: { type: string }
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: '#/components/schemas/User' }
+        '422':
+          description: Validation error
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, name, email, role, created_at]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        email: { type: string, format: email }
+        role: { type: string, enum: [admin, user, viewer] }
+        created_at: { type: string, format: date-time }
+```