integration-helpers

Instructions

This skill provides production-ready integration templates for deploying machine learning models into full-stack applications. It covers FastAPI inference endpoints, Next.js prediction interfaces, and Supabase schemas for ML metadata storage.

1. FastAPI Inference Endpoints

Create production-ready ML inference APIs with proper error handling and validation:

Generate FastAPI ML router

bash ./skills/integration-helpers/scripts/add-fastapi-endpoint.sh <model-type> <endpoint-name>

Model types: classification, regression, text-generation, image-classification, embeddings

What This Creates:

• Pydantic models for request/response validation

• Inference endpoint with proper error handling

• Model loading and caching logic

• Health check endpoint

• Batch prediction support

• Async request handling

Router Structure:

from fastapi import APIRouter, HTTPException, UploadFile from pydantic import BaseModel, Field import numpy as np

router = APIRouter( prefix="/ml", tags=["machine-learning"], responses={500: {"description": "Model inference error"}}, )

Example Usage:

Create text classification endpoint

bash ./skills/integration-helpers/scripts/add-fastapi-endpoint.sh classification sentiment-analysis

Creates: app/routers/ml_sentiment_analysis.py

2. Request/Response Models

Define type-safe ML inference contracts:

Classification Model:

class ClassificationRequest(BaseModel): text: str = Field(..., min_length=1, max_length=10000) model_version: str | None = None return_probabilities: bool = False

class ClassificationResponse(BaseModel): prediction: str confidence: float = Field(..., ge=0.0, le=1.0) probabilities: dict[str, float] | None = None model_version: str inference_time_ms: float

Regression Model:

class RegressionRequest(BaseModel): features: list[float] = Field(..., min_items=1) feature_names: list[str] | None = None

class RegressionResponse(BaseModel): prediction: float feature_importance: dict[str, float] | None = None model_version: str

Image Classification:

class ImageClassificationResponse(BaseModel): predictions: list[dict[str, Any]] top_prediction: str confidence: float processing_time_ms: float

3. Model Loading and Caching

Implement efficient model loading with caching:

from functools import lru_cache import joblib import torch

Singleton model loader

class ModelLoader: _instance = None _model = None

def __new__(cls):
    if cls._instance is None:
        cls._instance = super().__new__(cls)
    return cls._instance

def load_model(self, model_path: str):
    if self._model is None:
        # Load based on framework
        if model_path.endswith('.pkl'):
            self._model = joblib.load(model_path)
        elif model_path.endswith('.pt'):
            self._model = torch.load(model_path)
        # Add TensorFlow, ONNX, etc.
    return self._model

Dependency for endpoints

async def get_model(): loader = ModelLoader() return loader.load_model("models/latest.pkl")

4. Inference Endpoints with Error Handling

Implement robust inference with proper error handling:

@router.post("/predict", response_model=ClassificationResponse) async def predict( request: ClassificationRequest, model = Depends(get_model) ): try: start_time = time.time()

    # Preprocess input
    processed_input = preprocess_text(request.text)

    # Run inference
    prediction = model.predict([processed_input])[0]
    probabilities = None

    if request.return_probabilities:
        probs = model.predict_proba([processed_input])[0]
        probabilities = {
            label: float(prob)
            for label, prob in zip(model.classes_, probs)
        }

    inference_time = (time.time() - start_time) * 1000

    return ClassificationResponse(
        prediction=str(prediction),
        confidence=float(max(probs)) if probabilities else 0.0,
        probabilities=probabilities,
        model_version=MODEL_VERSION,
        inference_time_ms=inference_time
    )

except ValueError as e:
    raise HTTPException(
        status_code=400,
        detail=f"Invalid input: {str(e)}"
    )
except Exception as e:
    raise HTTPException(
        status_code=500,
        detail=f"Model inference failed: {str(e)}"
    )

5. Batch Prediction Support

Enable efficient batch inference:

class BatchClassificationRequest(BaseModel): texts: list[str] = Field(..., min_items=1, max_items=100) model_version: str | None = None

class BatchClassificationResponse(BaseModel): predictions: list[ClassificationResponse] total_inference_time_ms: float

@router.post("/predict/batch", response_model=BatchClassificationResponse) async def predict_batch( request: BatchClassificationRequest, model = Depends(get_model) ): start_time = time.time() predictions = []

# Process in batches for efficiency
for text in request.texts:
    pred = await predict(
        ClassificationRequest(text=text),
        model=model
    )
    predictions.append(pred)

total_time = (time.time() - start_time) * 1000

return BatchClassificationResponse(
    predictions=predictions,
    total_inference_time_ms=total_time
)

6. Next.js Prediction Forms

Create React components for ML model interaction:

Generate Next.js prediction form

bash ./skills/integration-helpers/scripts/add-nextjs-component.sh <component-type> <component-name>

Component types: classification-form, regression-form, image-upload, chat-interface

What This Creates:

• TypeScript React component with shadcn/ui

• Form validation with react-hook-form and zod

• Loading states and error handling

• Result visualization components

• API integration with fetch/axios

Example Component:

// components/ml/sentiment-form.tsx 'use client'

import { useState } from 'react' import { useForm } from 'react-hook-form' import { zodResolver } from '@hookform/resolvers/zod' import * as z from 'zod' import { Button } from '@/components/ui/button' import { Textarea } from '@/components/ui/textarea' import { Card } from '@/components/ui/card'

const formSchema = z.object({ text: z.string().min(1).max(10000), })

export function SentimentForm() { const [result, setResult] = useState<any>(null) const [loading, setLoading] = useState(false)

const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), })

async function onSubmit(values: z.infer<typeof formSchema>) { setLoading(true) try { const response = await fetch('/api/ml/predict', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(values), }) const data = await response.json() setResult(data) } catch (error) { console.error(error) } finally { setLoading(false) } }

return ( <Card className="p-6"> <form onSubmit={form.handleSubmit(onSubmit)}> <Textarea {...form.register('text')} /> <Button type="submit" disabled={loading}> {loading ? 'Analyzing...' : 'Analyze Sentiment'} </Button> </form> {result && <ResultDisplay result={result} />} </Card> ) }

7. Result Visualization Components

Display ML predictions with visual feedback:

// Classification result with confidence function ClassificationResult({ prediction, confidence, probabilities }) { return ( <div className="space-y-4"> <div className="text-2xl font-bold">{prediction}</div> <div className="text-muted-foreground"> Confidence: {(confidence * 100).toFixed(1)}% </div> {probabilities && ( <div className="space-y-2"> {Object.entries(probabilities).map(([label, prob]) => ( <div key={label} className="flex items-center gap-2"> <span className="w-24">{label}</span> <div className="flex-1 bg-secondary rounded-full h-2"> <div className="bg-primary h-2 rounded-full" style={{ width: ${prob * 100}% }} /> </div> <span className="w-12 text-right">{(prob * 100).toFixed(1)}%</span> </div> ))} </div> )} </div> ) }

8. Supabase ML Metadata Schemas

Create database schemas for ML model tracking and results:

Generate Supabase schema for ML metadata

bash ./skills/integration-helpers/scripts/create-supabase-schema.sh <schema-type>

Schema types: ml-models, predictions, training-runs, model-versions

ML Models Table:

create table ml_models ( id uuid default gen_random_uuid() primary key, name text not null, model_type text not null, -- classification, regression, etc. framework text not null, -- scikit-learn, pytorch, tensorflow version text not null, artifact_url text, -- Cloud storage URL metrics jsonb, -- Accuracy, F1, RMSE, etc. hyperparameters jsonb, feature_names text[], target_classes text[], is_active boolean default true, created_at timestamptz default now(), updated_at timestamptz default now(), created_by uuid references auth.users(id) );

create index idx_ml_models_active on ml_models(is_active, created_at desc); create index idx_ml_models_type on ml_models(model_type);

Predictions Log Table:

create table predictions ( id uuid default gen_random_uuid() primary key, model_id uuid references ml_models(id), model_version text not null, input_data jsonb not null, prediction jsonb not null, confidence float, inference_time_ms float, user_id uuid references auth.users(id), session_id text, created_at timestamptz default now() );

create index idx_predictions_model on predictions(model_id, created_at desc); create index idx_predictions_user on predictions(user_id, created_at desc); create index idx_predictions_session on predictions(session_id);

Training Runs Table:

create table training_runs ( id uuid default gen_random_uuid() primary key, model_id uuid references ml_models(id), dataset_name text not null, dataset_size integer, train_test_split jsonb, -- {train: 0.8, test: 0.2} hyperparameters jsonb, training_metrics jsonb, -- Loss curves, accuracy per epoch validation_metrics jsonb, test_metrics jsonb, training_duration_seconds integer, status text default 'running', -- running, completed, failed error_message text, artifact_url text, created_at timestamptz default now(), completed_at timestamptz, created_by uuid references auth.users(id) );

create index idx_training_runs_model on training_runs(model_id, created_at desc); create index idx_training_runs_status on training_runs(status);

Model Versions Table:

create table model_versions ( id uuid default gen_random_uuid() primary key, model_id uuid references ml_models(id), version text not null, changelog text, metrics_comparison jsonb, -- Compare with previous version is_deployed boolean default false, deployment_url text, created_at timestamptz default now(), deployed_at timestamptz, created_by uuid references auth.users(id), unique(model_id, version) );

create index idx_model_versions_deployed on model_versions(model_id, is_deployed);

9. API Route Handlers for Next.js

Create Next.js API routes that call FastAPI backend:

// app/api/ml/predict/route.ts import { NextRequest, NextResponse } from 'next/server'

const FASTAPI_URL = process.env.FASTAPI_URL || 'http://localhost:8000'

export async function POST(request: NextRequest) { try { const body = await request.json()

const response = await fetch(`${FASTAPI_URL}/ml/predict`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})

if (!response.ok) {
  const error = await response.json()
  return NextResponse.json(
    { error: error.detail },
    { status: response.status }
  )
}

const data = await response.json()
return NextResponse.json(data)

} catch (error) { return NextResponse.json( { error: 'Failed to connect to ML service' }, { status: 500 } ) } }

Examples

Example 1: Complete Sentiment Analysis Integration

1. Create FastAPI endpoint

cd /path/to/fastapi-backend bash plugins/ml-training/skills/integration-helpers/scripts/add-fastapi-endpoint.sh classification sentiment-analysis

2. Create Next.js form component

cd /path/to/nextjs-frontend bash plugins/ml-training/skills/integration-helpers/scripts/add-nextjs-component.sh classification-form sentiment-form

3. Create Supabase schema for logging

bash plugins/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh ml-models bash plugins/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh predictions

Result: End-to-end sentiment analysis system with API, UI, and data logging

Example 2: Image Classification Service

1. Create image classification endpoint

bash plugins/ml-training/skills/integration-helpers/scripts/add-fastapi-endpoint.sh image-classification image-classifier

2. Create image upload component

bash plugins/ml-training/skills/integration-helpers/scripts/add-nextjs-component.sh image-upload image-classifier-form

3. Setup model versioning schema

bash plugins/ml-training/skills/integration-helpers/scripts/create-supabase-schema.sh model-versions

Result: Complete image classification service with upload UI and version tracking

Requirements

FastAPI Dependencies:

• FastAPI 0.100+

• Pydantic 2.0+

• scikit-learn, PyTorch, or TensorFlow (based on your model)

• python-multipart (for file uploads)

• joblib or pickle (for model serialization)

Next.js Dependencies:

• Next.js 14+

• React 18+

• shadcn/ui components

• react-hook-form

• zod

• TypeScript

Supabase:

• PostgreSQL 15+

• Row Level Security enabled

• UUID extension enabled

Best Practices

API Design:

• Use proper HTTP status codes (200, 400, 500)

• Implement request validation with Pydantic

• Add rate limiting for production

• Log all predictions for monitoring

• Version your models in URLs or headers

Performance:

• Cache models in memory (singleton pattern)

• Use async endpoints for I/O operations

• Implement batch prediction for efficiency

• Consider model quantization for speed

• Use background tasks for heavy operations

Security:

• Validate all inputs strictly

• Implement authentication for API endpoints

• Use CORS properly in production

• Don't expose model internals in errors

• Rate limit inference endpoints

Monitoring:

• Log inference times

• Track prediction distributions

• Monitor error rates

• Store predictions for retraining

• Set up alerts for degraded performance

Error Handling:

• Return structured error responses

• Differentiate input errors from model errors

• Provide helpful error messages

• Log errors for debugging

• Implement graceful degradation

Plugin: ml-training Version: 1.0.0 Category: ML Integration Skill Type: Integration Templates