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
| Field | Type | Default | Description |
|---|
maxIterations | number | 10 | Maximum optimization cycles (1-100) |
targetScore | number | — | Stop early when this score is reached (0-1) |
patience | number | — | Stop after N iterations with no improvement (1-50) |
dryRun | boolean | false | Validate configuration without starting execution |
model | string | — | Target LLM model for prompt generation |
tuningParams | object | — | Advanced tuning parameters (e.g., { evaluationModel: 'claude-sonnet-4-6' }) |
Execution Modes
| Mode | Description |
|---|
worker_loop | Default. Runs optimization in a server-side worker loop |
bun_worker | Runs 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
| Field | Type | Description |
|---|
id | string | Job UUID |
promptId | number | Source prompt ID |
promptGroupId | string | Prompt group UUID |
datasetId | number | Dataset used for evaluation |
status | string | queued, running, paused, completed, failed, or cancelled |
executionMode | string | worker_loop or bun_worker |
progress | number | Completion percentage (0-100) |
currentIteration | number | Current iteration number |
maxIterations | number | Total iterations configured |
currentScore | number | null | Score of the current iteration |
bestScore | number | null | Best score achieved so far |
bestIteration | number | null | Iteration that achieved best score |
resultPromptId | number | null | ID of the optimized prompt version |
error | string | null | Error 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
| Parameter | Type | Description |
|---|
promptGroupId | string | Filter by prompt group UUID |
status | string | Filter by status (queued, running, paused, completed, failed, cancelled) |
limit | number | Results per page (1-100, default 20) |
offset | number | Number 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
| Method | Description |
|---|
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 Method | HTTP Endpoint |
|---|
optimizePrompt | POST /api/prompt/:id/optimize |
getOptimization | GET /api/optimization/:id |
listOptimizations | GET /api/optimization |
getOptimizationProgress | GET /api/optimization/:id/progress |
pauseOptimization | POST /api/optimization/:id/pause |
resumeOptimization | POST /api/optimization/:id/resume |
cancelOptimization | POST /api/optimization/:id/cancel |