everything-gemini 1.1.1 → 1.8.0

package/skills/fastapi-production/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: fastapi-production
+description: >-
+  Architects, builds, and reviews production-grade async FastAPI backends with Pydantic v2, lifespan context management, JWT auth, dependency injection, and health probes.
+---
+
+# FastAPI Production Architect
+
+This skill guides building high-performance, asynchronous REST APIs with FastAPI, adhering to production standards, strict type safety with Pydantic v2, clean dependency injection, and cloud-native observability.
+
+## 🏗️ Production Directory Layout
+
+```text
+app/
+├── api/
+│   ├── deps.py               # Shared dependencies (DB sessions, current user, rate limiters)
+│   └── v1/
+│       ├── router.py         # Root v1 router aggregating feature endpoints
+│       └── endpoints/
+│           ├── auth.py       # Authentication & token renewal
+│           └── users.py      # User management endpoints
+├── core/
+│   ├── config.py             # Pydantic BaseSettings environment validation
+│   ├── database.py           # Async SQLAlchemy engine & session factory
+│   └── security.py           # JWT encoding/decoding & Argon2/bcrypt hashing
+├── models/                   # SQLAlchemy ORM database models
+├── schemas/                  # Pydantic v2 request/response schemas
+├── services/                 # Pure domain business logic
+└── main.py                   # FastAPI application initialization & lifespan
+```
+
+---
+
+## ⚡ Core Patterns
+
+### 1. Lifespan State Management
+
+Avoid deprecated `@app.on_event("startup")` and `@app.on_event("shutdown")`. Use modern async context lifespans:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from app.core.database import engine
+from app.core.redis import init_redis_pool, close_redis_pool
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: Initialize connection pools, caches, and telemetry
+    app.state.redis = await init_redis_pool()
+    try:
+        yield
+    finally:
+        # Shutdown: Gracefully drain connections
+        await close_redis_pool(app.state.redis)
+        await engine.dispose()
+
+app = FastAPI(title="Production Service", lifespan=lifespan)
+```
+
+### 2. Pydantic v2 Request & Response Schemas
+
+Enforce strict validation, immutable attributes where appropriate, and forbid undeclared payloads:
+
+```python
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+class UserBase(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+    email: EmailStr
+    is_active: bool = True
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8, max_length=128)
+
+class UserResponse(UserBase):
+    id: int
+```
+
+### 3. Dependency Injection & Database Sessions
+
+Inject asynchronous SQLAlchemy sessions using an `async_sessionmaker` generator yielding into FastAPI's `Depends`:
+
+```python
+from collections.abc import AsyncGenerator
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import async_session_factory
+
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+### 4. JWT Authentication & Permission Guards
+
+```python
+from typing import Annotated
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from app.schemas.user import UserResponse
+from app.services.auth import decode_jwt_token
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/token")
+
+async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> UserResponse:
+    user = await decode_jwt_token(token)
+    if not user or not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return user
+```
+
+### 5. Standardized Problem Details Error Envelope (RFC 7807)
+
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    return JSONResponse(
+        status_code=500,
+        content={
+            "type": "https://errors.example.com/internal-server-error",
+            "title": "Internal Server Error",
+            "status": 500,
+            "detail": "An unexpected error occurred. Please contact engineering support.",
+            "instance": str(request.url.path),
+        },
+    )
+```
+
+### 6. Kubernetes Liveness & Readiness Probes
+
+Expose separate endpoints for orchestrator checks:
+
+```python
+@app.get("/healthz/liveness", tags=["Health"])
+async def liveness_check():
+    return {"status": "ok"}
+
+@app.get("/healthz/readiness", tags=["Health"])
+async def readiness_check(db: AsyncSession = Depends(get_db_session)):
+    await db.execute(text("SELECT 1"))
+    return {"status": "ready"}
+```

package/skills/graphql-architect/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: graphql-architect
+description: Designs, specifies, and implements production GraphQL APIs, DataLoader N+1 query batching, Relay-style cursor pagination, and schema federation.
+---
+
+# GraphQL Architecture & API Craftsmanship
+
+This skill guides the design, schema modeling, query optimization, and implementation of production-grade GraphQL APIs.
+
+---
+
+## 1. Core Principles
+
+1. **Schema-First Design**:
+   - Model client domain requirements into a declarative Schema Definition Language (SDL) before implementing resolvers.
+2. **Defeat the N+1 Problem**:
+   - Never query database tables inside nested resolvers without a batching mechanism (e.g., `DataLoader`).
+3. **Cursor-Based Pagination**:
+   - For real-time or dynamic lists, implement Relay-compliant cursor pagination (`Connection`, `Edge`, `PageInfo`) rather than offset/limit pagination.
+
+---
+
+## 2. Relay-Compliant Cursor Pagination Pattern
+
+```graphql
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type UserEdge {
+  cursor: String!
+  node: User!
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type Query {
+  users(first: Int, after: String): UserConnection!
+}
+```
+
+---
+
+## 3. DataLoader Batching Blueprint
+
+Prevent database query fan-out by batching IDs into a single SQL `IN` query per event loop tick:
+
+```typescript
+import DataLoader from 'dataloader';
+
+// Batch function loading users by array of IDs
+const batchUsers = async (userIds: readonly string[]): Promise<(User | Error)[]> => {
+  const users = await db.user.findMany({
+    where: { id: { in: [...userIds] } },
+  });
+  
+  // Map results back to exact input order
+  const userMap = new Map(users.map(u => [u.id, u]));
+  return userIds.map(id => userMap.get(id) || new Error(`User ${id} not found`));
+};
+
+export const createUserDataLoader = () => new DataLoader(batchUsers);
+```
+
+---
+
+## 4. Query Complexity & Depth Limiting
+
+To prevent Denial-of-Service attacks through cyclic or deeply nested queries:
+- Enforce maximum query depth (e.g., max 6 levels).
+- Assign cost multipliers to nested connections to reject queries exceeding complexity thresholds.

package/skills/grpc-connect-rpc/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: grpc-connect-rpc
+description: >-
+  Architects and implements high-performance, browser-compatible gRPC and Protocol Buffer services using Connect-RPC (Connect-ES & Connect-Go), HTTP/2 & HTTP/3 streaming, and type-safe schema generation.
+---
+
+# Connect-RPC & Modern Protocol Buffers
+
+This skill guides building fast, ergonomic, and 100% browser-compatible RPC services using Connect-RPC (by Buf). Connect implements the gRPC, gRPC-Web, and Connect protocols natively over HTTP/1.1, HTTP/2, and HTTP/3 without requiring Envoy proxy sidecars.
+
+---
+
+## ⚡ Core Patterns
+
+### 1. Protobuf Service Definition (`buf.build` Standard)
+
+Define service contracts and strongly-typed data structures:
+
+```protobuf
+// proto/commerce/v1/order.proto
+syntax = "proto3";
+
+package commerce.v1;
+
+option go_package = "github.com/company/commerce/gen/commerce/v1;commercev1";
+
+service OrderService {
+  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
+  rpc StreamOrderUpdates(StreamOrderUpdatesRequest) returns (stream StreamOrderUpdatesResponse);
+}
+
+message CreateOrderRequest {
+  string customer_id = 1;
+  repeated OrderItem items = 2;
+  double total_usd = 3;
+}
+
+message OrderItem {
+  string sku = 1;
+  int32 quantity = 2;
+  double price_usd = 3;
+}
+
+message CreateOrderResponse {
+  string order_id = 1;
+  string status = 2;
+  int64 created_at_unix = 3;
+}
+
+message StreamOrderUpdatesRequest {
+  string order_id = 1;
+}
+
+message StreamOrderUpdatesResponse {
+  string order_id = 1;
+  string current_status = 2;
+  string message = 3;
+  int64 timestamp = 4;
+}
+```
+
+Compile with `buf generate`:
+
+```yaml
+# buf.gen.yaml
+version: v2
+plugins:
+  - local: protoc-gen-es
+    out: gen/ts
+    opt: target=ts
+  - local: protoc-gen-connect-es
+    out: gen/ts
+    opt: target=ts
+  - local: protoc-gen-go
+    out: gen/go
+    opt: paths=source_relative
+  - local: protoc-gen-connect-go
+    out: gen/go
+    opt: paths=source_relative
+```
+
+---
+
+### 2. Node.js / TypeScript Server Implementation (Connect-ES)
+
+Implement the typed service handler with zero boilerplate:
+
+```typescript
+import { ConnectRouter } from '@connectrpc/connect';
+import { OrderService } from './gen/ts/commerce/v1/order_connect';
+import { fastify } from 'fastify';
+import { fastifyConnectPlugin } from '@connectrpc/connect-fastify';
+
+function routes(router: ConnectRouter) {
+  router.service(OrderService, {
+    async createOrder(req) {
+      if (!req.customerId || req.items.length === 0) {
+        throw new ConnectError('Order must contain a customerId and items', Code.InvalidArgument);
+      }
+
+      const orderId = `ord_${crypto.randomUUID().slice(0, 8)}`;
+      return {
+        orderId,
+        status: 'PENDING_PAYMENT',
+        createdAtUnix: BigInt(Date.now()),
+      };
+    },
+
+    async *streamOrderUpdates(req) {
+      const statuses = ['PAYMENT_CONFIRMED', 'WAREHOUSE_PICKED', 'IN_TRANSIT', 'DELIVERED'];
+      for (const status of statuses) {
+        await new Promise((r) => setTimeout(r, 1000));
+        yield {
+          orderId: req.orderId,
+          currentStatus: status,
+          message: `Package status updated to ${status}`,
+          timestamp: BigInt(Date.now()),
+        };
+      }
+    },
+  });
+}
+
+const server = fastify({ http2: true });
+await server.register(fastifyConnectPlugin, { routes });
+await server.listen({ host: '0.0.0.0', port: 8080 });
+```
+
+---
+
+### 3. Native Browser Client (No Envoy Proxy Needed)
+
+Invoke typed RPCs directly from modern browsers or Next.js applications:
+
+```typescript
+import { createClient } from '@connectrpc/connect';
+import { createConnectTransport } from '@connectrpc/connect-web';
+import { OrderService } from './gen/ts/commerce/v1/order_connect';
+
+// Transport supports pure HTTP POST requests with JSON or binary Protobuf envelopes
+const transport = createConnectTransport({
+  baseUrl: 'https://api.example.com',
+});
+
+const client = createClient(OrderService, transport);
+
+// 1. Unary RPC Call
+const response = await client.createOrder({
+  customerId: 'cust_98234',
+  items: [{ sku: 'CLOUD-GPU-A100', quantity: 2, priceUsd: 1450.0 }],
+  totalUsd: 2900.0,
+});
+console.log('Created order:', response.orderId);
+
+// 2. Server Streaming RPC Call
+for await (const update of client.streamOrderUpdates({ orderId: response.orderId })) {
+  console.log(`Live Status [${update.currentStatus}]: ${update.message}`);
+}
+```
+
+---
+
+## 🎯 Verification & Diagnostics
+
+1. **Test Service with cURL (Standard HTTP POST)**:
+   ```bash
+   curl \
+     --header "Content-Type: application/json" \
+     --data '{"customerId": "cust_123", "items": [{"sku": "PROD-1", "quantity": 1, "priceUsd": 99.0}], "totalUsd": 99.0}' \
+     https://api.example.com/commerce.v1.OrderService/CreateOrder
+   ```
+2. **Inspect Buf Lint & Breaking Change Rules**:
+   ```bash
+   buf lint
+   buf breaking --against ".git#branch=main"
+   ```

package/skills/langgraph-orchestrator/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: langgraph-orchestrator
+description: >-
+  Designs and implements stateful multi-agent systems, cyclic graphs, persistent checkpoints, human-in-the-loop pauses, and streaming orchestration using LangGraph (Python/TypeScript).
+---
+
+# LangGraph Multi-Agent Orchestration & Stateful Graphs
+
+This skill guides the design, construction, and deployment of complex multi-agent architectures using LangGraph. It provides deterministic patterns for cyclic routing, persistent graph checkpointing, and human-in-the-loop (HITL) approval gates.
+
+---
+
+## ⚡ Core Concepts
+
+1. **State Graph (`StateGraph`)**: Typed dictionary or Pydantic state passed through graph nodes.
+2. **Nodes**: Discrete execution functions that receive current state and return state updates.
+3. **Edges & Conditional Edges**: Transition rules between nodes (deterministic or LLM-routed).
+4. **Checkpointers (`BaseCheckpointSaver`)**: Persists graph state across turns and enables time-travel debugging.
+5. **Human-in-the-Loop (`interrupt_before`)**: Pauses execution graph at critical checkpoints for human intervention.
+
+---
+
+## 🏗️ Production Implementation (Python)
+
+### 1. State Definition & Reducers (`state.py`)
+
+Define immutable state schemas with explicit reducer operators:
+
+```python
+from typing import Annotated, Sequence, TypedDict
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+
+class AgentState(TypedDict):
+    # add_messages reducer appends new messages rather than overwriting
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+    sender: str
+    iteration_count: int
+    is_approved: bool
+    context_data: dict
+```
+
+---
+
+### 2. Multi-Agent Nodes & Graph Assembly (`graph.py`)
+
+```python
+from langgraph.graph import StateGraph, END, START
+from langgraph.checkpoint.memory import MemorySaver
+from langchain_core.messages import AIMessage, HumanMessage
+
+def researcher_node(state: AgentState) -> dict:
+    """Researches user inquiry and extracts factual grounding."""
+    # LLM invocation logic here
+    result = "Research findings: latency reduced by 40% via caching."
+    return {
+        "messages": [AIMessage(content=result, name="researcher")],
+        "sender": "researcher",
+        "iteration_count": state.get("iteration_count", 0) + 1,
+    }
+
+def reviewer_node(state: AgentState) -> dict:
+    """Validates research quality and enforces compliance."""
+    last_msg = state["messages"][-1].content
+    approved = "latency" in last_msg.lower()
+    return {
+        "messages": [AIMessage(content="Review complete.", name="reviewer")],
+        "sender": "reviewer",
+        "is_approved": approved,
+    }
+
+def human_approval_node(state: AgentState) -> dict:
+    """Node executed after human approval gate."""
+    return {"messages": [AIMessage(content="Action executed after sign-off.", name="human_gate")]}
+
+def router_condition(state: AgentState) -> str:
+    """Evaluate whether to loop or terminate."""
+    if state.get("is_approved", False):
+        return "human_approval"
+    if state.get("iteration_count", 0) >= 3:
+        return "abort"
+    return "researcher"
+
+# Build State Graph
+workflow = StateGraph(AgentState)
+
+# Add Nodes
+workflow.add_node("researcher", researcher_node)
+workflow.add_node("reviewer", reviewer_node)
+workflow.add_node("human_approval", human_approval_node)
+
+# Add Edges
+workflow.add_edge(START, "researcher")
+workflow.add_edge("researcher", "reviewer")
+workflow.add_conditional_edges(
+    "reviewer",
+    router_condition,
+    {
+        "human_approval": "human_approval",
+        "researcher": "researcher",
+        "abort": END,
+    }
+)
+workflow.add_edge("human_approval", END)
+
+# Compile with Persistent Checkpointer and Human-in-the-Loop Interruption
+checkpointer = MemorySaver()
+app = workflow.compile(
+    checkpointer=checkpointer,
+    interrupt_before=["human_approval"]
+)
+```
+
+---
+
+### 3. Execution & Human-in-the-Loop Resumption
+
+```python
+thread_config = {"configurable": {"thread_id": "session-prod-1024"}}
+
+# Run until human interrupt
+inputs = {"messages": [HumanMessage(content="Optimize database latency.")], "iteration_count": 0}
+for event in app.stream(inputs, config=thread_config):
+    print(f"Step: {event}")
+
+# Inspect current snapshot before approval
+snapshot = app.get_state(thread_config)
+print(f"Next Node Pending Approval: {snapshot.next}")
+
+# Resume graph after human confirmation
+for event in app.stream(None, config=thread_config):
+    print(f"Post-approval Step: {event}")
+```
+
+---
+
+## 🛡️ Best Practices & Anti-Patterns
+
+| Category | ❌ Anti-Pattern | ✅ Production Best Practice |
+| :--- | :--- | :--- |
+| **State Mutation** | Modifying state objects in-place | Return clean partial state dictionaries with reducer keys |
+| **Cycles** | Unbounded recursive loops | Enforce explicit `iteration_count` or recursion limit (`recursion_limit=25`) |
+| **Checkpoints** | Storing giant binary blobs in state | Keep state lean; persist media in object stores (GCS/S3) and store URIs |
+| **HITL** | Hardcoded polling loops | Use native `interrupt_before` / `interrupt_after` with thread configurations |