packages/docs/rest/training.md
The training API enables fine-tuning workflows: browse collected trajectories, build datasets, launch training jobs, and manage fine-tuned models. The training service must be available and the agent runtime initialized for most operations.
Get the training service status.
Response
{
"runningJobs": 0,
"queuedJobs": 0,
"completedJobs": 0,
"failedJobs": 0,
"modelCount": 0,
"datasetCount": 0,
"runtimeAvailable": true
}
List trajectories available for training with pagination.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of results to return (default: 100) |
offset | integer | No | Number of results to skip (default: 0) |
Response
{
"available": true,
"total": 142,
"trajectories": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"source": "chat",
"status": "completed",
"llmCallCount": 5,
"startTime": 1718000000000,
"endTime": 1718000010000
}
]
}
Get detailed trajectory data for a specific trajectory, including LLM calls and provider accesses.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Trajectory ID |
Response
{
"trajectory": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"llmCalls": [],
"providerAccesses": []
}
}
List all built training datasets.
Response
{
"datasets": [
{
"id": "dataset-2024-06-10",
"createdAt": 1718000000000,
"trajectoryCount": 50,
"exampleCount": 250
}
]
}
Build a new training dataset from available trajectories.
Request
{
"limit": 100,
"minLlmCallsPerTrajectory": 2
}
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Maximum number of trajectories to include |
minLlmCallsPerTrajectory | integer | No | Minimum LLM calls a trajectory must have to be included |
Response (201 Created)
{
"dataset": {
"id": "dataset-2024-06-10",
"createdAt": 1718000000000,
"trajectoryCount": 87,
"exampleCount": 435
}
}
List all training jobs.
Response
{
"jobs": [
{
"id": "job-001",
"status": "completed",
"datasetId": "dataset-2024-06-10",
"backend": "mlx",
"model": "eliza-1-2b",
"createdAt": 1718000000000,
"completedAt": 1718003600000
}
]
}
Start a new training job.
Request
{
"datasetId": "dataset-2024-06-10",
"backend": "mlx",
"model": "eliza-1-2b",
"iterations": 100,
"batchSize": 4,
"learningRate": 1e-5
}
| Parameter | Type | Required | Description |
|---|---|---|---|
datasetId | string | No | Dataset ID to train on (uses latest if omitted) |
maxTrajectories | integer | No | Cap on trajectories to use |
backend | string | No | Training backend: "native" (default, prompt optimization via MIPRO/GEPA), "mlx", "cuda", or "cpu" |
model | string | No | Base model to fine-tune |
iterations | integer | No | Number of training iterations |
batchSize | integer | No | Batch size |
learningRate | float | No | Learning rate |
Response (201 Created)
{
"job": {
"id": "job-002",
"status": "running",
"datasetId": "dataset-2024-06-10",
"backend": "mlx",
"createdAt": 1718005000000
}
}
Get the status of a specific training job.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Training job ID |
Response
{
"job": {
"id": "job-002",
"status": "running",
"progress": 0.45,
"currentIteration": 45,
"totalIterations": 100,
"loss": 0.234
}
}
Cancel a running training job.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Training job ID |
Response
{
"job": {
"id": "job-002",
"status": "cancelled"
}
}
List all fine-tuned models.
Response
{
"models": [
{
"id": "model-001",
"jobId": "job-001",
"name": "eliza-1-2b-v1",
"createdAt": 1718003600000,
"active": false
}
]
}
Import a fine-tuned model into Ollama for local inference.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Model ID |
Request
{
"modelName": "eliza-v1",
"baseModel": "eliza-1-2b",
"ollamaUrl": "http://localhost:11434"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
modelName | string | No | Name to register in Ollama |
baseModel | string | No | Base model identifier in Ollama |
ollamaUrl | string | No | Ollama URL — must be a loopback host (localhost, 127.0.0.1, or ::1) |
Response
{
"model": {
"id": "model-001",
"ollamaName": "eliza-v1",
"importedAt": 1718005000000
}
}
Activate a fine-tuned model so the agent uses it for inference.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Model ID |
Request
{
"providerModel": "eliza-v1"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
providerModel | string | No | Provider-specific model identifier (e.g., Ollama model name) |
Response
{
"ok": true,
"activeModel": "eliza-v1"
}
Run a benchmark against a fine-tuned model to evaluate performance.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Model ID |
Response
{
"modelId": "model-001",
"scores": {
"coherence": 0.87,
"consistency": 0.91,
"helpfulness": 0.84
},
"completedAt": 1718006000000
}
Get the auto-training configuration (thresholds, cooldown).
Response
{
"threshold": 100,
"cooldownHours": 12,
"enabled": true
}
Update the auto-training configuration.
Request
{
"threshold": 200,
"cooldownHours": 24
}
| Parameter | Type | Required | Description |
|---|---|---|---|
threshold | integer | No | Number of trajectories per task before auto-training triggers |
cooldownHours | number | No | Minimum hours between auto-training runs |
enabled | boolean | No | Enable or disable auto-training |
Response
{
"ok": true,
"config": {
"threshold": 200,
"cooldownHours": 24,
"enabled": true
}
}
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Request body is malformed or missing required fields |
| 401 | UNAUTHORIZED | Missing or invalid authentication token |
| 404 | NOT_FOUND | Requested resource does not exist |
| 500 | TRAINING_FAILED | Training job failed to start or complete |
| 503 | SERVICE_UNAVAILABLE | Training service is not available |
| 500 | INTERNAL_ERROR | Unexpected server error |