omgkit 2.13.0 → 2.15.0

package/plugin/skills/ai-ml/model-serving/SKILL.md

@@ -0,0 +1,386 @@
+# Model Serving
+
+TensorFlow Serving, TorchServe, Triton Inference Server, model optimization, and production deployment patterns.
+
+## Overview
+
+Model serving provides infrastructure for deploying ML models to production with low latency, high throughput, and operational reliability.
+
+## Core Concepts
+
+### Serving Patterns
+- **Online Inference**: Real-time, synchronous
+- **Batch Inference**: Offline, bulk processing
+- **Streaming Inference**: Continuous data streams
+- **Edge Inference**: On-device deployment
+
+### Key Metrics
+- **Latency**: p50, p95, p99 response times
+- **Throughput**: Requests per second
+- **Availability**: Uptime percentage
+- **Resource Utilization**: CPU/GPU/Memory
+
+## TensorFlow Serving
+
+### Model Export
+```python
+import tensorflow as tf
+
+# Save model in SavedModel format
+model = tf.keras.models.load_model("model.h5")
+
+# Define serving signature
+@tf.function(input_signature=[tf.TensorSpec(shape=[None, 224, 224, 3], dtype=tf.float32)])
+def serve(images):
+    return {"predictions": model(images)}
+
+tf.saved_model.save(
+    model,
+    "models/image_classifier/1",
+    signatures={"serving_default": serve}
+)
+```
+
+### Docker Deployment
+```dockerfile
+FROM tensorflow/serving:latest
+
+COPY models /models
+
+ENV MODEL_NAME=image_classifier
+ENV MODEL_BASE_PATH=/models
+
+EXPOSE 8500 8501
+```
+
+### Client Request
+```python
+import requests
+import numpy as np
+
+# REST API
+data = {"instances": images.tolist()}
+response = requests.post(
+    "http://localhost:8501/v1/models/image_classifier:predict",
+    json=data
+)
+predictions = response.json()["predictions"]
+
+# gRPC (more efficient)
+import grpc
+from tensorflow_serving.apis import predict_pb2, prediction_service_pb2_grpc
+
+channel = grpc.insecure_channel("localhost:8500")
+stub = prediction_service_pb2_grpc.PredictionServiceStub(channel)
+
+request = predict_pb2.PredictRequest()
+request.model_spec.name = "image_classifier"
+request.inputs["images"].CopyFrom(tf.make_tensor_proto(images))
+
+response = stub.Predict(request, timeout=10.0)
+```
+
+## TorchServe
+
+### Model Handler
+```python
+# custom_handler.py
+from ts.torch_handler.base_handler import BaseHandler
+import torch
+import json
+
+class ImageClassifierHandler(BaseHandler):
+    def __init__(self):
+        super().__init__()
+        self.initialized = False
+
+    def initialize(self, context):
+        self.manifest = context.manifest
+        model_dir = context.system_properties.get("model_dir")
+
+        self.model = torch.jit.load(f"{model_dir}/model.pt")
+        self.model.eval()
+        self.initialized = True
+
+    def preprocess(self, data):
+        images = []
+        for row in data:
+            image = row.get("data") or row.get("body")
+            # Transform image
+            tensor = self.transform(image)
+            images.append(tensor)
+        return torch.stack(images)
+
+    def inference(self, data):
+        with torch.no_grad():
+            return self.model(data)
+
+    def postprocess(self, inference_output):
+        return inference_output.tolist()
+```
+
+### Model Archive
+```bash
+# Create model archive
+torch-model-archiver \
+    --model-name image_classifier \
+    --version 1.0 \
+    --model-file model.py \
+    --serialized-file model.pt \
+    --handler custom_handler.py \
+    --extra-files index_to_name.json
+
+# Start TorchServe
+torchserve --start \
+    --model-store model_store \
+    --models image_classifier=image_classifier.mar
+```
+
+## Triton Inference Server
+
+### Model Repository
+```
+model_repository/
+├── image_classifier/
+│   ├── config.pbtxt
+│   ├── 1/
+│   │   └── model.onnx
+│   └── 2/
+│       └── model.onnx
+└── text_classifier/
+    ├── config.pbtxt
+    └── 1/
+        └── model.pt
+```
+
+### Configuration
+```protobuf
+# config.pbtxt
+name: "image_classifier"
+platform: "onnxruntime_onnx"
+max_batch_size: 32
+
+input [
+  {
+    name: "images"
+    data_type: TYPE_FP32
+    dims: [ 3, 224, 224 ]
+  }
+]
+
+output [
+  {
+    name: "predictions"
+    data_type: TYPE_FP32
+    dims: [ 1000 ]
+  }
+]
+
+instance_group [
+  {
+    count: 2
+    kind: KIND_GPU
+    gpus: [ 0 ]
+  }
+]
+
+dynamic_batching {
+  preferred_batch_size: [ 8, 16, 32 ]
+  max_queue_delay_microseconds: 100
+}
+```
+
+### Ensemble Models
+```protobuf
+# ensemble_config.pbtxt
+name: "ensemble_pipeline"
+platform: "ensemble"
+max_batch_size: 32
+
+input [
+  { name: "raw_image" data_type: TYPE_UINT8 dims: [ -1, -1, 3 ] }
+]
+
+output [
+  { name: "classification" data_type: TYPE_FP32 dims: [ 1000 ] }
+]
+
+ensemble_scheduling {
+  step [
+    {
+      model_name: "preprocessing"
+      model_version: -1
+      input_map { key: "raw_image" value: "raw_image" }
+      output_map { key: "processed_image" value: "images" }
+    },
+    {
+      model_name: "image_classifier"
+      model_version: -1
+      input_map { key: "images" value: "processed_image" }
+      output_map { key: "predictions" value: "classification" }
+    }
+  ]
+}
+```
+
+## Model Optimization
+
+### Quantization
+```python
+import torch
+
+# Dynamic quantization (CPU)
+quantized_model = torch.quantization.quantize_dynamic(
+    model,
+    {torch.nn.Linear, torch.nn.LSTM},
+    dtype=torch.qint8
+)
+
+# Static quantization
+model.qconfig = torch.quantization.get_default_qconfig("fbgemm")
+prepared_model = torch.quantization.prepare(model)
+# Calibrate with representative data
+for data in calibration_loader:
+    prepared_model(data)
+quantized_model = torch.quantization.convert(prepared_model)
+```
+
+### ONNX Export
+```python
+import torch.onnx
+
+torch.onnx.export(
+    model,
+    dummy_input,
+    "model.onnx",
+    export_params=True,
+    opset_version=13,
+    do_constant_folding=True,
+    input_names=["input"],
+    output_names=["output"],
+    dynamic_axes={
+        "input": {0: "batch_size"},
+        "output": {0: "batch_size"}
+    }
+)
+```
+
+### TensorRT Optimization
+```python
+import tensorrt as trt
+
+logger = trt.Logger(trt.Logger.WARNING)
+builder = trt.Builder(logger)
+network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
+parser = trt.OnnxParser(network, logger)
+
+with open("model.onnx", "rb") as f:
+    parser.parse(f.read())
+
+config = builder.create_builder_config()
+config.max_workspace_size = 1 << 30  # 1GB
+config.set_flag(trt.BuilderFlag.FP16)  # Enable FP16
+
+engine = builder.build_engine(network, config)
+
+with open("model.trt", "wb") as f:
+    f.write(engine.serialize())
+```
+
+## Kubernetes Deployment
+
+### Serving Deployment
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: model-serving
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: model-serving
+  template:
+    metadata:
+      labels:
+        app: model-serving
+    spec:
+      containers:
+      - name: triton
+        image: nvcr.io/nvidia/tritonserver:23.10-py3
+        args:
+          - tritonserver
+          - --model-repository=s3://models/repository
+          - --strict-model-config=false
+        ports:
+        - containerPort: 8000
+          name: http
+        - containerPort: 8001
+          name: grpc
+        - containerPort: 8002
+          name: metrics
+        resources:
+          limits:
+            nvidia.com/gpu: 1
+            memory: 8Gi
+          requests:
+            memory: 4Gi
+        livenessProbe:
+          httpGet:
+            path: /v2/health/live
+            port: 8000
+        readinessProbe:
+          httpGet:
+            path: /v2/health/ready
+            port: 8000
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: model-serving-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: model-serving
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70
+```
+
+## Best Practices
+
+1. **Model Versioning**: Support multiple versions
+2. **A/B Testing**: Traffic splitting capabilities
+3. **Canary Deployments**: Gradual rollouts
+4. **Health Checks**: Readiness and liveness probes
+5. **Monitoring**: Latency, throughput, errors
+
+## Anti-Patterns
+
+- No model versioning
+- Missing health checks
+- Ignoring batch optimization
+- No request validation
+- Skipping load testing
+
+## When to Use
+
+- Real-time predictions needed
+- Multiple models to serve
+- Need for GPU acceleration
+- High availability requirements
+- Model version management
+
+## When NOT to Use
+
+- Simple batch processing
+- One-off predictions
+- No latency requirements
+- Single model, low traffic

package/plugin/skills/event-driven/cqrs-patterns/SKILL.md

@@ -0,0 +1,348 @@
+# CQRS Patterns
+
+Command Query Responsibility Segregation patterns for separating read and write models, eventual consistency, and optimized query performance.
+
+## Overview
+
+CQRS separates read and write operations into different models, allowing each to be optimized independently.
+
+## Core Concepts
+
+### Command Side (Write)
+- Handles state changes
+- Validates business rules
+- Emits domain events
+- Optimized for consistency
+
+### Query Side (Read)
+- Handles data retrieval
+- Denormalized for queries
+- Eventually consistent
+- Optimized for performance
+
+## Architecture Patterns
+
+### Simple CQRS
+```
+┌─────────────┐     ┌─────────────┐
+│   Client    │     │   Client    │
+└──────┬──────┘     └──────┬──────┘
+       │                   │
+   Commands              Queries
+       │                   │
+       ▼                   ▼
+┌─────────────┐     ┌─────────────┐
+│  Command    │     │   Query     │
+│  Handler    │     │   Handler   │
+└──────┬──────┘     └──────┬──────┘
+       │                   │
+       ▼                   ▼
+┌─────────────────────────────────┐
+│          Single Database        │
+│  (Different tables/views)       │
+└─────────────────────────────────┘
+```
+
+### Full CQRS with Event Sourcing
+```
+┌─────────────┐     ┌─────────────┐
+│   Client    │     │   Client    │
+└──────┬──────┘     └──────┬──────┘
+       │                   │
+   Commands              Queries
+       │                   │
+       ▼                   ▼
+┌─────────────┐     ┌─────────────┐
+│  Command    │     │   Query     │
+│  Handler    │     │  Service    │
+└──────┬──────┘     └──────┬──────┘
+       │                   │
+       ▼                   ▼
+┌─────────────┐     ┌─────────────┐
+│   Event     │────▶│    Read     │
+│   Store     │     │   Database  │
+└─────────────┘     └─────────────┘
+         │
+         │ Events
+         ▼
+    ┌─────────────┐
+    │ Projections │
+    └─────────────┘
+```
+
+## Command Implementation
+
+### Command Handler
+```typescript
+// Command definition
+interface CreateOrderCommand {
+  type: 'CreateOrder';
+  orderId: string;
+  customerId: string;
+  items: OrderItem[];
+}
+
+// Command handler
+class CreateOrderHandler {
+  constructor(
+    private readonly orderRepository: OrderRepository,
+    private readonly eventBus: EventBus
+  ) {}
+
+  async handle(command: CreateOrderCommand): Promise<void> {
+    // Validate
+    const customer = await this.customerRepository.find(command.customerId);
+    if (!customer) {
+      throw new CustomerNotFoundError(command.customerId);
+    }
+
+    // Create aggregate
+    const order = Order.create({
+      orderId: command.orderId,
+      customerId: command.customerId,
+      items: command.items
+    });
+
+    // Persist
+    await this.orderRepository.save(order);
+
+    // Publish events
+    for (const event of order.getUncommittedEvents()) {
+      await this.eventBus.publish(event);
+    }
+  }
+}
+```
+
+### Command Bus
+```typescript
+class CommandBus {
+  private handlers: Map<string, CommandHandler<any>> = new Map();
+
+  register<T extends Command>(
+    commandType: string,
+    handler: CommandHandler<T>
+  ): void {
+    this.handlers.set(commandType, handler);
+  }
+
+  async dispatch<T extends Command>(command: T): Promise<void> {
+    const handler = this.handlers.get(command.type);
+    if (!handler) {
+      throw new Error(`No handler for command: ${command.type}`);
+    }
+    await handler.handle(command);
+  }
+}
+```
+
+## Query Implementation
+
+### Read Model
+```typescript
+// Denormalized read model
+interface OrderSummaryReadModel {
+  orderId: string;
+  customerName: string;
+  customerEmail: string;
+  status: string;
+  itemCount: number;
+  totalAmount: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// Query
+interface GetOrdersQuery {
+  customerId?: string;
+  status?: string;
+  fromDate?: Date;
+  toDate?: Date;
+  page: number;
+  pageSize: number;
+}
+
+// Query handler
+class GetOrdersQueryHandler {
+  constructor(private readonly readDb: ReadDatabase) {}
+
+  async handle(query: GetOrdersQuery): Promise<PaginatedResult<OrderSummaryReadModel>> {
+    const conditions: string[] = [];
+    const params: any[] = [];
+
+    if (query.customerId) {
+      conditions.push(`customer_id = $${params.length + 1}`);
+      params.push(query.customerId);
+    }
+
+    if (query.status) {
+      conditions.push(`status = $${params.length + 1}`);
+      params.push(query.status);
+    }
+
+    const where = conditions.length > 0
+      ? `WHERE ${conditions.join(' AND ')}`
+      : '';
+
+    const offset = (query.page - 1) * query.pageSize;
+
+    const result = await this.readDb.query(`
+      SELECT * FROM order_summaries
+      ${where}
+      ORDER BY created_at DESC
+      LIMIT $${params.length + 1} OFFSET $${params.length + 2}
+    `, [...params, query.pageSize, offset]);
+
+    return {
+      items: result.rows,
+      page: query.page,
+      pageSize: query.pageSize,
+      total: await this.getCount(where, params)
+    };
+  }
+}
+```
+
+## Projection Patterns
+
+### Synchronous Projection (Same Transaction)
+```typescript
+class OrderProjector {
+  async project(event: DomainEvent, transaction: Transaction): Promise<void> {
+    switch (event.type) {
+      case 'OrderCreated':
+        await transaction.query(`
+          INSERT INTO order_summaries (...)
+          VALUES (...)
+        `);
+        break;
+    }
+  }
+}
+
+// Used in command handler
+await this.db.transaction(async (tx) => {
+  await this.eventStore.append(events, tx);
+  for (const event of events) {
+    await this.projector.project(event, tx);
+  }
+});
+```
+
+### Asynchronous Projection
+```typescript
+class OrderProjectionHandler {
+  @Subscribe('order-events')
+  async handle(event: DomainEvent): Promise<void> {
+    await this.projector.project(event);
+  }
+}
+
+// Idempotent projection
+class IdempotentProjector {
+  async project(event: DomainEvent): Promise<void> {
+    const processed = await this.checkProcessed(event.eventId);
+    if (processed) return;
+
+    await this.db.transaction(async (tx) => {
+      await this.applyProjection(event, tx);
+      await this.markProcessed(event.eventId, tx);
+    });
+  }
+}
+```
+
+## Eventual Consistency
+
+### Handling in UI
+```typescript
+// Optimistic UI update
+async function submitOrder(orderData: CreateOrderCommand): Promise<void> {
+  // Immediately update UI
+  uiState.orders.push({
+    ...orderData,
+    status: 'pending',
+    createdAt: new Date()
+  });
+
+  // Send command
+  await commandBus.dispatch(orderData);
+
+  // Poll for confirmation
+  await waitForEventualConsistency(orderData.orderId);
+}
+
+async function waitForEventualConsistency(orderId: string): Promise<void> {
+  const maxAttempts = 10;
+  const delay = 500;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const order = await queryService.getOrder(orderId);
+    if (order && order.status !== 'pending') {
+      return;
+    }
+    await sleep(delay);
+  }
+
+  throw new Error('Read model not updated in time');
+}
+```
+
+## Best Practices
+
+1. **Command Validation**: Validate before persisting
+2. **Idempotent Projections**: Handle duplicate events
+3. **Event Ordering**: Maintain order in projections
+4. **Projection Rebuild**: Ability to rebuild from events
+5. **Monitoring**: Track projection lag
+
+## Read Model Optimization
+
+### Materialized Views
+```sql
+-- Denormalized for specific query pattern
+CREATE MATERIALIZED VIEW customer_order_stats AS
+SELECT
+  c.customer_id,
+  c.name,
+  COUNT(o.order_id) as total_orders,
+  SUM(o.total_amount) as lifetime_value,
+  MAX(o.created_at) as last_order_date
+FROM customers c
+LEFT JOIN orders o ON c.customer_id = o.customer_id
+GROUP BY c.customer_id, c.name;
+
+-- Refresh strategy
+REFRESH MATERIALIZED VIEW CONCURRENTLY customer_order_stats;
+```
+
+### Multiple Read Models
+```
+Same events -> Different projections:
+- OrderListProjection -> For order listing
+- OrderSearchProjection -> For full-text search (Elasticsearch)
+- OrderAnalyticsProjection -> For dashboards (ClickHouse)
+- OrderNotificationProjection -> For alerts
+```
+
+## Anti-Patterns
+
+- Using queries in command handlers
+- Sharing models between read and write
+- Not planning for projection failures
+- Over-complicated when simple CRUD suffices
+- Ignoring eventual consistency in UX
+
+## When to Use
+
+- Complex domains with different read/write patterns
+- High read-to-write ratio
+- Need for specialized query databases
+- Event sourcing architectures
+
+## When NOT to Use
+
+- Simple CRUD applications
+- Low complexity domains
+- When strong consistency is mandatory
+- Small teams without CQRS experience