Skip to main content

Optimization SDK

Start and manage automated prompt optimization jobs. The optimization engine (MetaTuner) iteratively mutates prompt text, evaluates candidates against a dataset, and converges on the highest-scoring variant.

Start Optimization

Create and start a new optimization job for a prompt. The id parameter is the numeric prompt ID, and the body contains the dataset and configuration.
import { Mutagent } from '@mutagent/sdk';

const client = new Mutagent({ apiKey: process.env.MUTAGENT_API_KEY });

const job = await client.optimization.optimizePrompt({
  id: 42,  // Prompt ID
  body: {
    datasetId: 7,
    config: {
      maxIterations: 10,
      targetScore: 0.9,
      patience: 3,
      model: 'claude-sonnet-4-6',
      tuningParams: {
        evaluationModel: 'claude-sonnet-4-6',
      },
    },
    executionMode: 'worker_loop',
  },
});

console.log('Job started:', job);

Config Options

FieldTypeDefaultDescription
maxIterationsnumber10Maximum optimization cycles (1-100)
targetScorenumberStop early when this score is reached (0-1)
patiencenumberStop after N iterations with no improvement (1-50)
dryRunbooleanfalseValidate configuration without starting execution
modelstringTarget LLM model for prompt generation
tuningParamsobjectAdvanced tuning parameters (e.g., { evaluationModel: 'claude-sonnet-4-6' })

Execution Modes

ModeDescription
worker_loopDefault. Runs optimization in a server-side worker loop
bun_workerRuns in an isolated Bun worker thread

Get Job Status

Get detailed status of an optimization job, including the latest iteration state and recent events.
const status = await client.optimization.getOptimization({
  id: 'job-uuid-here',
});

console.log('Status:', status);

Response Fields

FieldTypeDescription
idstringJob UUID
promptIdnumberSource prompt ID
promptGroupIdstringPrompt group UUID
datasetIdnumberDataset used for evaluation
statusstringqueued, running, paused, completed, failed, or cancelled
executionModestringworker_loop or bun_worker
progressnumberCompletion percentage (0-100)
currentIterationnumberCurrent iteration number
maxIterationsnumberTotal iterations configured
currentScorenumber | nullScore of the current iteration
bestScorenumber | nullBest score achieved so far
bestIterationnumber | nullIteration that achieved best score
resultPromptIdnumber | nullID of the optimized prompt version
errorstring | nullError message if job failed

List Optimization Jobs

Get a paginated list of optimization jobs with optional filters.
const page = await client.optimization.listOptimizations({
  status: 'running',
  limit: 20,
  offset: 0,
});

for await (const job of page) {
  console.log(job.id, '-', job.status, `(${job.progress}%)`);
}

Query Parameters

ParameterTypeDescription
promptGroupIdstringFilter by prompt group UUID
statusstringFilter by status (queued, running, paused, completed, failed, cancelled)
limitnumberResults per page (1-100, default 20)
offsetnumberNumber of results to skip

Get Score Progression

Retrieve the score history across iterations for a job. Useful for charting optimization progress.
const progress = await client.optimization.getOptimizationProgress({
  id: 'job-uuid-here',
});

console.log('Progression:', progress);
The response contains a progression array with { iteration, score } entries for each completed iteration.

Pause Job

Pause a running optimization job. The job can be resumed later from where it left off.
await client.optimization.pauseOptimization({
  id: 'job-uuid-here',
});

console.log('Job paused');

Resume Job

Resume a previously paused optimization job.
await client.optimization.resumeOptimization({
  id: 'job-uuid-here',
});

console.log('Job resumed');

Cancel Job

Cancel an optimization job. This action cannot be undone.
await client.optimization.cancelOptimization({
  id: 'job-uuid-here',
});

console.log('Job cancelled');

Poll for Completion

async function waitForOptimization(jobId: string) {
  while (true) {
    const status = await client.optimization.getOptimization({
      id: jobId,
    });

    // Access status fields from the response
    console.log(`Job status: ${JSON.stringify(status)}`);

    // Check for terminal states
    const statusStr = JSON.stringify(status);
    if (statusStr.includes('"completed"')) {
      console.log('Optimization complete');
      return status;
    }
    if (statusStr.includes('"failed"') || statusStr.includes('"cancelled"')) {
      throw new Error('Job ended without completing');
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

const result = await waitForOptimization('job-uuid-here');
For real-time updates, connect to the WebSocket endpoint at ws://your-server/ws/optimization and subscribe to a job ID. The server streams events as each iteration completes.

Type Definitions

interface OptimizeConfig {
  maxIterations?: number;      // Max optimization cycles (default: 10)
  targetScore?: number;        // Stop when score reached (0-1)
  patience?: number;           // Stop after N iterations with no improvement
  dryRun?: boolean;            // Validate config without running
  model?: string;              // Target LLM model
  tuningParams?: {             // Advanced tuning parameters
    evaluationModel?: string;  // Model used for evaluation scoring
    [key: string]: unknown;
  };
}

enum ExecutionMode {
  WorkerLoop = 'worker_loop',
  BunWorker = 'bun_worker',
}

interface OptimizeJobResponse {
  id: string;
  promptId: number;
  promptGroupId: string;
  datasetId: number;
  status: 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
  executionMode: 'worker_loop' | 'bun_worker';
  config: Record<string, unknown>;
  progress: number;
  currentIteration: number;
  maxIterations: number;
  currentStage: string | null;
  currentScore: number | null;
  bestScore: number | null;
  bestIteration: number | null;
  resultPromptId: number | null;
  error: string | null;
  createdAt: string;
  startedAt: string | null;
  completedAt: string | null;
}

interface ScoreProgression {
  iteration: number;
  score: number | null;
}

Method Reference

MethodDescription
optimization.optimizePrompt({ id, body })Start optimization job
optimization.getOptimization({ id })Get job status
optimization.listOptimizations({ ...filters })List all jobs with pagination
optimization.getOptimizationProgress({ id })Get score progression
optimization.pauseOptimization({ id })Pause job
optimization.resumeOptimization({ id })Resume job
optimization.cancelOptimization({ id })Cancel job

REST API Reference

The SDK methods map to these HTTP endpoints:
SDK MethodHTTP Endpoint
optimizePromptPOST /api/prompt/:id/optimize
getOptimizationGET /api/optimization/:id
listOptimizationsGET /api/optimization
getOptimizationProgressGET /api/optimization/:id/progress
pauseOptimizationPOST /api/optimization/:id/pause
resumeOptimizationPOST /api/optimization/:id/resume
cancelOptimizationPOST /api/optimization/:id/cancel