Custom Router

IronLabs Custom Router lets you train a personalized model selection system on your own data. The router learns from your examples to automatically pick the most appropriate AI model for each task — improving accuracy and reducing costs.

Python SDK

pip install ironlabs

Node.js SDK

npm install ironlabs

When to use Custom Router

Cost optimization — route simple tasks to cheaper models, reserve powerful ones for complex requests
Domain specialization — match prompts to models that excel in your domain (code, legal, creative writing, etc.)
Multi-model pipelines — let the router decide which model handles each stage instead of hardcoding choices
Replace guesswork — use a data-driven system trained on your own examples instead of manual model selection

Prerequisites

Before you start, make sure you have:

An IronLabs API key from the Settings page
A training data file hosted at a publicly accessible URL (GitHub, S3, CDN, etc.)

Installation

Install the SDK for your language:

pip install ironlabs

npm install ironlabs

Initialize the client

Set your API key as an environment variable:

export IRONLABS_API_KEY="your_api_key_here"

Then initialize the trainer in your code:

from ironlabs import RouterTrainer

trainer = RouterTrainer()

const { RouterTrainer } = require('ironlabs');

const trainer = new RouterTrainer();

The client automatically picks up IRONLABS_API_KEY from your environment — no need to pass it explicitly.

Training a Custom Router

Prepare training data

Training data maps prompts to the ideal models for each. Supported formats are JSON and CSV — host your file at any publicly accessible URL (GitHub, S3, CDN, etc.).

[
  {
    "problem": "Write a simple hello world function",
    "correct_models": ["openai/gpt-4o-mini", "anthropic/claude-3-5-haiku-20241022"]
  },
  {
    "problem": "Explain quantum computing in detail",
    "correct_models": ["openai/gpt-4o", "anthropic/claude-3-5-sonnet-20241022"]
  }
]

problem,correct_models
"Write a simple hello world function","openai/gpt-4o-mini,anthropic/claude-3-5-haiku-20241022"
"Explain quantum computing in detail","openai/gpt-4o,anthropic/claude-3-5-sonnet-20241022"

You can pass multiple file URLs to combine datasets from different sources.

Start training

Pass one or more data URLs to kick off a training job.

import time
from ironlabs import RouterTrainer

trainer = RouterTrainer()

data_urls = ["https://example.com/path/to/your/training_data.json"]

training_info = trainer.fit(data_urls)
job_id = training_info.get("training_job_id")
print(f"Training job started. Job ID: {job_id}")

const { RouterTrainer } = require('ironlabs');

const trainer = new RouterTrainer();

const dataUrls = ['https://example.com/path/to/your/training_data.json'];

const trainingJob = await trainer.fit(dataUrls);
console.log(`Training job started: ${trainingJob.training_job_id}`);
console.log(`Initial status: ${trainingJob.status}`);

curl -X POST https://irona-ai--train.modal.run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "Data_URLs": ["https://example.com/training-data.json"]
  }'

Response:

{
  "training_job_id": "abc123-def456-ghi789",
  "status": "queued",
  "version": "v1.0"
}

Check training status

Poll until the job reaches completed or failed. Training typically takes a few minutes.

while True:
    status_info = trainer.get_status()
    status = status_info.get("status")
    print(f"Current status: {status}")

    if status == "completed":
        model_id = status_info.get("model_id")
        print(f"Training completed! Model ID: {model_id}")
        break
    elif status == "failed":
        print("Training failed.")
        break

    time.sleep(10)

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

let status = trainingJob.status;

while (status !== 'completed' && status !== 'failed') {
  console.log(`Current status: ${status}, waiting...`);
  await sleep(10000);

  const statusResponse = await trainer.getStatus();
  status = statusResponse.status;

  if (statusResponse.model_id) {
    console.log(`Model ID: ${statusResponse.model_id}`);
  }
}

if (status === 'failed') {
  console.error('Training failed!');
  process.exit(1);
}

curl -X GET "https://irona-ai--taskstatus.modal.run?task_id=abc123-def456-ghi789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "training_job_id": "abc123-def456-ghi789",
  "status": "completed",
  "model_id": "model-xyz-top1_0.8542",
  "started_at": "2026-02-04T10:30:00Z",
  "completed_at": "2026-02-04T10:35:00Z",
  "training_config": {
    "timing": {
      "training_time_seconds": 45.2,
      "embedding_time_seconds": 120.5,
      "total_time_seconds": 300.0
    }
  }
}

Status	Description
`queued`	Job is waiting to start
`running`	Training is in progress
`completed`	Training finished successfully
`failed`	Training encountered an error

Get model details

Retrieve metadata and performance metrics for your trained model.

details = trainer.get_model_details()
print(f"Model details: {details}")

const modelDetails = await trainer.getModelDetails();

console.log(`
Model Information:
  ID: ${modelDetails.model_id}
  Version: ${modelDetails.version}
  Status: ${modelDetails.status}
  Embedding Model: ${modelDetails.embedding_model}
  Number of Classes: ${modelDetails.num_classes}
  Created: ${modelDetails.created_at}
`);

if (modelDetails.metrics) {
  console.log('Performance Metrics:');
  console.log(JSON.stringify(modelDetails.metrics, null, 2));
}

curl -X GET "https://irona-ai--models.modal.run?model_id=model-xyz-top1_0.8542" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "model_id": "model-xyz-top1_0.8542",
  "version": "v1.0",
  "status": "active",
  "embedding_model": "Qwen/Qwen3-Embedding-4B",
  "num_classes": 8,
  "created_at": "2026-02-04T10:35:00Z",
  "metrics": {
    "top1_hit_rate": 0.8542,
    "top3_hit_rate": 0.9521,
    "accuracy": 0.8542
  }
}

Run inference

Use your trained router to select the best model for new prompts.

inputs = [
    "Write a Python function to calculate fibonacci numbers",
    "How to implement a binary search tree in JavaScript?",
    "What is the time complexity of quicksort?"
]

predictions = trainer.predict(inputs)

for i, pred in enumerate(predictions.get("predictions", [])):
    print(f"Input: {inputs[i]}")
    print(f"Recommended Model: {pred.get('top_model')}")
    print(f"Confidence: {pred.get('top_prob'):.0%}")
    print("-" * 40)

const inputs = [
  'Write a Python function to calculate fibonacci numbers',
  'How to implement a binary search tree in JavaScript?',
  'What is the time complexity of quicksort?',
];

const result = await trainer.predict(inputs);

result.predictions.forEach((pred, i) => {
  console.log(`Input: ${inputs[i]}`);
  console.log(`Top Model: ${pred.top_model}`);
  console.log(`Confidence: ${(pred.top_prob * 100).toFixed(2)}%`);

  if (pred.models && pred.models.length > 1) {
    console.log('Top 3 Recommendations:');
    pred.models.slice(0, 3).forEach((m, idx) => {
      console.log(`  ${idx + 1}. ${m.model} - ${(m.confidence * 100).toFixed(2)}% (rank ${m.rank})`);
    });
  }
  console.log('---');
});

curl -X POST https://irona-ai--infer.modal.run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model-xyz-top1_0.8542",
    "inputs": [
      "Write a Python function to calculate fibonacci numbers",
      "Explain the theory of relativity"
    ]
  }'

Response:

{
  "predictions": [
    {
      "top_model": "openai/gpt-4o-mini",
      "top_prob": 0.92,
      "models": [
        { "model": "openai/gpt-4o-mini", "confidence": 0.92, "rank": 1 },
        { "model": "anthropic/claude-3-5-haiku-20241022", "confidence": 0.06, "rank": 2 }
      ]
    }
  ],
  "version": "v1.0"
}

Each prediction includes:

top_model — the recommended model for this input
top_prob — confidence score (0–1)
models — full ranked list with individual confidence scores

Complete example

View full end-to-end example

import time
from ironlabs import RouterTrainer

def main():
    trainer = RouterTrainer()

    # 1. Start training
    data_urls = ["https://example.com/path/to/your/training_data.json"]
    training_info = trainer.fit(data_urls)
    job_id = training_info.get("training_job_id")
    print(f"Training job started. Job ID: {job_id}")

    # 2. Poll until complete
    while True:
        status_info = trainer.get_status()
        status = status_info.get("status")
        print(f"Current status: {status}")

        if status == "completed":
            model_id = status_info.get("model_id")
            print(f"Training completed! Model ID: {model_id}")
            break
        elif status == "failed":
            print("Training failed.")
            return

        time.sleep(10)

    # 3. Inspect model
    details = trainer.get_model_details()
    print(f"Model details: {details}")

    # 4. Run inference
    test_inputs = [
        "Write a Python function to calculate fibonacci numbers",
        "How to implement a binary search tree in JavaScript?",
        "What is the time complexity of quicksort?"
    ]

    predictions = trainer.predict(test_inputs)

    for i, pred in enumerate(predictions.get("predictions", [])):
        print(f"Input: {test_inputs[i]}")
        print(f"Recommended Model: {pred.get('top_model')}")
        print(f"Confidence: {pred.get('top_prob'):.0%}")
        print("-" * 40)

if __name__ == "__main__":
    main()

const { RouterTrainer } = require('ironlabs');

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function main() {
  const trainer = new RouterTrainer();

  // 1. Start training
  const dataUrls = ['https://api.npoint.io/1181b4ec6c6333632b49'];
  const trainingJob = await trainer.fit(dataUrls);
  console.log(`Training job started: ${trainingJob.training_job_id}`);

  // 2. Poll until complete
  let status = trainingJob.status;
  while (status !== 'completed' && status !== 'failed') {
    console.log(`Status: ${status}, waiting...`);
    await sleep(10000);
    const statusResponse = await trainer.getStatus();
    status = statusResponse.status;
    if (statusResponse.model_id) {
      console.log(`Model ID: ${statusResponse.model_id}`);
    }
  }

  if (status === 'failed') {
    console.error('Training failed!');
    process.exit(1);
  }

  // 3. Inspect model
  const modelDetails = await trainer.getModelDetails();
  console.log(`Model: ${modelDetails.model_id} | Classes: ${modelDetails.num_classes}`);
  if (modelDetails.metrics) {
    console.log('Metrics:', JSON.stringify(modelDetails.metrics, null, 2));
  }

  // 4. Run inference
  const inputs = [
    'Write a Python function to calculate the factorial of a number',
    'Explain the concept of machine learning',
    'What is the difference between REST and GraphQL?',
  ];

  const result = await trainer.predict(inputs);

  result.predictions.forEach((pred, i) => {
    console.log(`\nInput: ${inputs[i]}`);
    console.log(`Top Model: ${pred.top_model} (${(pred.top_prob * 100).toFixed(2)}%)`);
    if (pred.models && pred.models.length > 1) {
      const alts = pred.models.slice(1, 3).map(m => m.model).join(', ');
      console.log(`Alternatives: ${alts}`);
    }
  });
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

Loading an existing model

Reuse a previously trained model without going through training again.

from ironlabs import RouterTrainer

trainer = RouterTrainer()
trainer.model_id = "model-xyz-top1_0.8542"

predictions = trainer.predict(["What is the time complexity of quicksort?"])
print(f"Recommended model: {predictions['predictions'][0]['top_model']}")

const { RouterTrainer } = require('ironlabs');

const trainer = new RouterTrainer();
trainer.setModelId('model-xyz-top1_0.8542');

const result = await trainer.predict(['What is the time complexity of quicksort?']);
console.log(`Recommended model: ${result.predictions[0].top_model}`);

Batch processing

The predict endpoint supports up to 500 inputs per request. For larger datasets, split into chunks.

from ironlabs import RouterTrainer

trainer = RouterTrainer()
trainer.model_id = "model-xyz-top1_0.8542"

large_dataset = [f"Test query {i}" for i in range(1200)]
BATCH_SIZE = 500

all_predictions = []
for i in range(0, len(large_dataset), BATCH_SIZE):
    batch = large_dataset[i:i + BATCH_SIZE]
    result = trainer.predict(batch)
    all_predictions.extend(result.get("predictions", []))
    print(f"Processed {min(i + BATCH_SIZE, len(large_dataset))}/{len(large_dataset)} inputs")

print(f"Total predictions: {len(all_predictions)}")

const { RouterTrainer } = require('ironlabs');

const trainer = new RouterTrainer();
trainer.setModelId('model-xyz-top1_0.8542');

const largeDataset = Array.from({ length: 1200 }, (_, i) => `Test query ${i + 1}`);
const BATCH_SIZE = 500;

const allPredictions = [];
for (let i = 0; i < largeDataset.length; i += BATCH_SIZE) {
  const batch = largeDataset.slice(i, i + BATCH_SIZE);
  const batchNum = Math.floor(i / BATCH_SIZE) + 1;
  const totalBatches = Math.ceil(largeDataset.length / BATCH_SIZE);
  console.log(`Processing batch ${batchNum}/${totalBatches}...`);

  const result = await trainer.predict(batch);
  allPredictions.push(...result.predictions);
  console.log(`  Processed ${Math.min(i + BATCH_SIZE, largeDataset.length)}/${largeDataset.length}`);
}

console.log(`Total predictions: ${allPredictions.length}`);

Supported data formats

Format	Description
JSON	Array of objects with `problem` and `correct_models` fields
CSV	Columns for `problem` and `correct_models` (comma-separated model names in a single cell)
Multiple files	Pass multiple URLs in `Data_URLs` to combine datasets

Model lifecycle

State	Description
Active	Available for inference
Archived	Automatically archived after 1 year of inactivity
Removed	Inactive models are cleaned up weekly to optimize storage

Get Started

LLM Routing

Custom Routers & Agent Optimization

Completions & Multimodal

API Reference

Integrations

Pricing

Changelog

Python SDK

Node.js SDK

When to use Custom Router

Prerequisites

Installation

Initialize the client

Training a Custom Router

Complete example

Loading an existing model

Batch processing

Supported data formats

Model lifecycle

Python SDK

Node.js SDK

​When to use Custom Router

​Prerequisites

​Installation

​Initialize the client

​Training a Custom Router

​Complete example

​Loading an existing model

​Batch processing

​Supported data formats

​Model lifecycle

When to use Custom Router

Prerequisites

Installation

Initialize the client

Training a Custom Router

Complete example

Loading an existing model

Batch processing

Supported data formats

Model lifecycle