everything-gemini 1.2.0 → 1.9.0

package/skills/duckdb-local-olap/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: duckdb-local-olap
+description: >-
+  Architects, queries, and optimizes embedded in-process DuckDB analytical workflows, direct Parquet/S3 querying, zero-copy Apache Arrow dataframes, and MotherDuck hybrid cloud execution.
+---
+
+# DuckDB Local OLAP & Serverless Analytics
+
+This skill guides building high-speed analytical engines using DuckDB—the "SQLite for analytics"—enabling columnar vectorized execution, direct querying of compressed Parquet files on cloud storage, and zero-copy transfers with Apache Arrow.
+
+---
+
+## ⚡ Core Patterns
+
+### 1. Direct Parquet Querying Over S3 Without Ingestion
+
+Query gigabytes of remote compressed files with projection and predicate pushdowns (only requested byte ranges are transferred over the network):
+
+```sql
+-- 1. Install and load HTTP and S3 extensions
+INSTALL httpfs;
+LOAD httpfs;
+
+-- 2. Configure S3 authentication
+SET s3_region = 'us-east-1';
+SET s3_access_key_id = 'YOUR_ACCESS_KEY';
+SET s3_secret_access_key = 'YOUR_SECRET_KEY';
+
+-- 3. Query remote Parquet directory with globs
+SELECT
+    country,
+    count(*) AS total_transactions,
+    round(avg(amount_usd), 2) AS avg_amount,
+    quantile_cont(amount_usd, 0.95) AS p95_amount
+FROM read_parquet('s3://my-data-lake/transactions/year=2026/month=*/*.parquet')
+WHERE status = 'settled'
+GROUP BY country
+ORDER BY total_transactions DESC
+LIMIT 20;
+```
+
+---
+
+### 2. Zero-Copy Python & Polars / Arrow Integration
+
+Pass memory buffers directly between DuckDB's vectorized engine and Polars or PyArrow without JSON or IPC serialization:
+
+```python
+import duckdb
+import polars as pl
+
+# Connect to in-memory instance
+con = duckdb.connect()
+
+# Set aggressive memory limits and worker threads
+con.execute("SET memory_limit = '8GB';")
+con.execute("SET threads = 8;")
+
+# Create a sample Polars DataFrame
+df = pl.DataFrame({
+    "user_id": [101, 102, 103],
+    "scores": [98.5, 76.2, 89.0]
+})
+
+# Query Polars DataFrame directly as a virtual table (zero-copy)
+arrow_table = con.execute("""
+    SELECT 
+        user_id,
+        scores,
+        CASE WHEN scores >= 90 THEN 'A' ELSE 'B' END AS grade
+    FROM df
+    WHERE scores > 80
+""").arrow()
+
+# Convert back to Polars instantaneously
+result_df = pl.from_arrow(arrow_table)
+print(result_df)
+```
+
+---
+
+### 3. Node.js Embedded Analytics Engine
+
+```typescript
+import { Database } from 'duckdb-async';
+
+export async function aggregateLocalParquet(parquetPath: string) {
+  const db = await Database.create(':memory:');
+  
+  const rows = await db.all(`
+    SELECT 
+        category,
+        count(*) AS item_count,
+        sum(price) AS gross_revenue
+    FROM read_parquet(?)
+    GROUP BY category
+    ORDER BY gross_revenue DESC
+  `, [parquetPath]);
+
+  await db.close();
+  return rows;
+}
+```
+
+---
+
+### 4. MotherDuck Cloud Hybrid Execution
+
+Scale seamlessly from a single laptop to collaborative cloud storage without modifying SQL queries:
+
+```python
+import duckdb
+
+# Connect to MotherDuck (cloud database)
+con = duckdb.connect("md:production_analytics")
+
+# Join local disk Parquet files directly with MotherDuck cloud tables
+con.execute("""
+    SELECT 
+        cloud_users.organization_id,
+        count(local_events.event_id) AS event_volume
+    FROM read_parquet('./local_cache/*.parquet') AS local_events
+    JOIN cloud_users ON local_events.user_id = cloud_users.id
+    GROUP BY cloud_users.organization_id
+""")
+```
+
+---
+
+## 🛠️ Performance Checklist
+
+- **Use Parquet Over CSV**: Parquet is 10x-50x faster due to columnar compression, statistics dictionaries, and column skipping.
+- **Configure Memory Limit**: Always set `SET memory_limit = 'XGB';` to ensure DuckDB uses external sorting/joining when data exceeds RAM instead of crashing the process.
+- **Avoid Row-by-Row Inserts**: Use `Appender` or `COPY ... FROM ...` in bulk batches of 50,000+ rows.

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/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 |