Model Registry Quickstart Guide

Time to complete: 5 minutes Prerequisites: Node.js 18+, PostgreSQL (Supabase), AWS credentials

Get up and running with the TRILLbot Model Registry in 5 minutes.

Step 1: Install Dependencies (1 minute)

cd /home/trillbot/TRILLbot/new
npm install

Dependencies installed:

@supabase/supabase-js - Database client
@aws-sdk/client-s3 - S3 storage
@tensorflow/tfjs-node - Model training/inference
zod - Schema validation

Step 2: Configure Environment (1 minute)

Create .env.local in project root:

# Supabase Database
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="eyJhbGc..."

# AWS S3 Storage
AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="..."
AWS_REGION="us-east-1"
S3_BUCKET="trillbot-models"

Get credentials:

Supabase: Dashboard → Settings → API → Service Role Key
AWS: IAM → Users → Create Access Key

Step 3: Run Database Migrations (1 minute)

# Apply Supabase migrations
npx supabase db push

# Or apply manually if needed
psql $DATABASE_URL < migrations/001_create_trained_models.sql

Tables created:

trained_models - Model metadata and metrics
model_version_tags - Version tagging (optional)
ab_tests - A/B test tracking (optional)

Step 4: Save Your First Model (2 minutes)

Create examples/quickstart.ts:

import { ModelRegistry } from "@/lib/ai/training/ModelRegistry";
import * as tf from "@tensorflow/tfjs-node";

async function quickstart() {
  // ========================================
  // 1. Train a Simple Model
  // ========================================
  console.log("📚 Training model...");

  const model = tf.sequential({
    layers: [
      tf.layers.dense({ units: 10, inputShape: [5], activation: "relu" }),
      tf.layers.dense({ units: 1, activation: "linear" }),
    ],
  });

  model.compile({
    optimizer: "adam",
    loss: "meanSquaredError",
    metrics: ["accuracy"],
  });

  // Generate training data
  const xs = tf.randomNormal([100, 5]);
  const ys = tf.randomNormal([100, 1]);

  await model.fit(xs, ys, {
    epochs: 10,
    batchSize: 32,
    verbose: 0,
  });

  console.log("✅ Model trained");

  // ========================================
  // 2. Save to Model Registry
  // ========================================
  console.log("💾 Saving model to registry...");

  const registry = new ModelRegistry();

  const result = await registry.saveModel(model, {
    modelId: "my-first-model",
    version: "1.0.0",
    s3Path: "s3://trillbot-models/my-first-model/v1.json",
    modelType: "neural",
    inputShape: [5],
    outputShape: [1],
    architecture: {
      layers: 2,
      units: [10, 1],
      activation: "relu",
    },
    trainingMetrics: {
      accuracy: 0.95,
      validationAccuracy: 0.93,
      trainingSamples: 100,
      trainingDurationMs: 5000,
      trainedBy: "quickstart-user",
    },
    deploymentStatus: "trained",
    isActive: false,
  });

  console.log("✅ Model saved:", result);

  // ========================================
  // 3. Deploy Model
  // ========================================
  console.log("🚀 Deploying model...");

  await registry.deployModel("my-first-model", "1.0.0", {
    environment: "development",
  });

  console.log("✅ Model deployed to development");

  // ========================================
  // 4. Load Model for Inference
  // ========================================
  console.log("🔍 Loading model...");

  const metadata = await registry.getActiveModel(
    "my-first-model",
    "development",
  );

  if (metadata) {
    console.log("✅ Active model metadata:", {
      modelId: metadata.modelId,
      version: metadata.version,
      accuracy: metadata.trainingMetrics.accuracy,
      deployedAt: metadata.deployedAt,
    });

    // Make prediction
    const testInput = tf.randomNormal([1, 5]);
    const prediction = model.predict(testInput) as tf.Tensor;

    console.log("🎯 Prediction:", await prediction.array());

    // Clean up
    testInput.dispose();
    prediction.dispose();
  }

  // Clean up
  xs.dispose();
  ys.dispose();
  model.dispose();

  console.log("\n🎉 Quickstart complete!");
}

quickstart().catch(console.error);

Run it:

npx ts-node examples/quickstart.ts

Expected output:

📚 Training model...
✅ Model trained
💾 Saving model to registry...
✅ Model saved: {
  modelId: 'my-first-model',
  version: '1.0.0',
  id: 'uuid-here',
  s3Path: 's3://trillbot-models/my-first-model/v1.json',
  savedAt: 2025-11-11T10:30:00.000Z
}
🚀 Deploying model...
✅ Model deployed to development
🔍 Loading model...
✅ Active model metadata: {
  modelId: 'my-first-model',
  version: '1.0.0',
  accuracy: 0.95,
  deployedAt: 2025-11-11T10:30:01.000Z
}
🎯 Prediction: [[0.123]]

🎉 Quickstart complete!

What You Just Did

Trained a model using TensorFlow.js
Saved metadata to Supabase database
Uploaded artifacts to S3 storage
Deployed atomically to development environment
Loaded for inference from active deployment

Next Steps

Version Management

Learn how to manage multiple model versions:

A/B Testing

Deploy multiple versions simultaneously:

Error Handling

Handle failures gracefully:

Production Deployment

Deploy to production safely:

API Reference

Explore the full API:

Troubleshooting

Error: "Supabase credentials missing"

Solution: Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in .env.local

Error: "S3 upload failed"

Solution: Verify AWS credentials and bucket permissions

aws s3 ls s3://trillbot-models  # Test bucket access

Error: "Model not found"

Solution: Check model was saved successfully

const versions = await registry.getModelVersions("my-first-model");
console.log("Available versions:", versions);

Support

Documentation: /docs/api/
Examples: /examples/
Issues: GitHub Issues
Slack: #trill-ml-engineering

Total time: ⏱️ 5 minutes Next: API Reference