Documentation Index
Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
Use this file to discover all available pages before exploring further.
Optimization SDK
Start and manage automated prompt optimization jobs. The optimization engine 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',
},
},
},
});
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' }) |
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 |
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 wss://api.mutagent.io/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;
};
}
interface OptimizeJobResponse {
id: string;
promptId: number;
promptGroupId: string;
datasetId: number;
status: 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
config: Record<string, unknown>;
progress: number;
currentIteration: number;
maxIterations: number;
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 |
optimization.getOptimizationStates({ id }) | Retrieve state snapshots for each optimization iteration |
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 |