Create an AutoScientist run

autoscientist.create() -> AutoscientistRun

POST/api/v1/autoscientist

Starts an iterative AutoScientist loop on a dataset you own. The loop runs up to max_iterations training cycles, stopping early when target_win_rate is achieved. Omitted parameters are resolved to platform defaults for the selected model and returned in the response. Poll GET /autoscientist/{experiment_id} for status, then GET /autoscientist/{experiment_id}/download once it succeeds.

ParametersExpand Collapse

dataset_id: str

The dataset to train on. Must be a dataset you own that has finished processing.

model: Optional[str]

Base model id from GET /autoscientist/models. By default, AutoScientist selects a suitable model. The resolved model is returned in the response model field.

data_format: Optional[Literal["chat", "instruction"]]

How training rows are interpreted. Defaults to chat when omitted.

One of the following:

"chat"

"instruction"

column_mapping: Optional[ColumnMapping]

Which dataset columns feed training. When omitted, AutoScientist infers the mapping from the dataset. Required columns depend on the data format.

prompt: Optional[str]

Source column holding the prompt/instruction text.

completion: Optional[str]

Source column holding the target completion/response. Used for supervised (sft) training.

reasoning_trace: Optional[str]

Optional source column holding a reasoning trace to train on.

hyperparams: Optional[Hyperparams]

Hyperparameter overrides. Not advised. AutoScientist derives these values from the resolved model and the effective dataset size; any field supplied here replaces the derived value for that field. Call POST /autoscientist/recommend-hyperparams to inspect the derived values without launching a run.

n_epochs: Optional[float]

minimum1

maximum20

batch_size: Optional[Union[Literal["max"], int]]

Either the literal 'max' or an integer of 1 or more. No fixed upper bound: the ceiling depends on the model and hardware, and a larger value is rejected at launch. Defaults to 'max'.

One of the following:

Literal["max"]

int

learning_rate: Optional[float]

minimum1e-8

maximum0.01

lora_r: Optional[float]

minimum1

maximum64

lora_alpha: Optional[float]

Must be 1× or 2× lora_r. Only checked when you supply lora_r in the same request; otherwise it is validated against the platform default.

lora_dropout: Optional[float]

minimum0

maximum1

lora_trainable_modules: Optional[str]

'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').

lr_scheduler_type: Optional[Literal["linear", "cosine", "constant"]]

One of the following:

"linear"

"cosine"

"constant"

min_lr_ratio: Optional[float]

minimum0

maximum1

scheduler_num_cycles: Optional[float]

Number of cosine decay cycles across training. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.

minimum0

maximum4

warmup_ratio: Optional[float]

minimum0

maximum1

max_grad_norm: Optional[float]

minimum0

weight_decay: Optional[float]

minimum0

train_on_inputs: Optional[bool]

Whether training loss is computed over the prompt tokens as well as the completion. true trains on the full sequence, false trains only on the completion. Omit to let the platform decide per example, which is the default.

training_type: Optional[Literal["lora", "full"]]

Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary.

One of the following:

"lora"

"full"

augmentation_domain_rows: Optional[float]

Number of synthetic domain-targeted rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).

minimum0

maximum40000

augmentation_general_rows: Optional[float]

Number of synthetic general-diversity rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).

minimum0

maximum50000

idempotency_key: Optional[str]

Client-generated key for safe retries. Scoped to dataset_id: while a run started with this key is still in progress, repeating the request returns that run instead of starting a second one. Once the run reaches a terminal state (succeeded, failed or cancelled) the key no longer matches and the same request starts a new run.

voucher: Optional[str]

Optional discount voucher code.

max_iterations: Optional[float]

Maximum number of iterations to run. Defaults to the resolved model configuration (currently 3). The resolved value is returned in the response max_iterations field.

minimum1

maximum5

target_win_rate: Optional[float]

Target win rate for the AutoScientist loop (between 0 exclusive and 1 inclusive). Defaults to 0.7 for small models and 0.8 for larger models. The resolved value is returned in the response target_win_rate field.

minimum0

maximum1

exclusiveMinimum

exclusiveMaximum

ReturnsExpand Collapse

class AutoscientistRun: …

id: str

AutoScientist run id.

dataset_id: Optional[object]

Public id of the dataset the run trained on.

model: Optional[object]

Resolved base model id used, including an automatically selected model.

status: Literal["pending", "running", "succeeded", 2 more]

One of the following:

"pending"

"running"

"succeeded"

"failed"

"cancelled"

created_at: datetime

formatdate-time

completed_at: Optional[object]

iterations_completed: float

Number of completed iterations.

max_iterations: float

Resolved maximum number of iterations, including the model-specific default.

target_win_rate: float

Resolved target win rate for the AutoScientist loop, including the model-specific default.

best_win_rate: Optional[object]

Best win rate achieved so far.

best_hyperparams: Optional[BestHyperparams]

Hyperparameters that produced the best iteration so far, and the ones the downloadable artifact was trained with. Null until an iteration completes.

n_epochs: Optional[float]

minimum1

maximum20

batch_size: Optional[Union[Literal["max"], int, null]]

Either the literal 'max' or an integer of 1 or more. No fixed upper bound: the ceiling depends on the model and hardware, and a larger value is rejected at launch. Defaults to 'max'.

One of the following:

Literal["max"]

int

learning_rate: Optional[float]

minimum1e-8

maximum0.01

lora_r: Optional[float]

minimum1

maximum64

lora_alpha: Optional[float]

Must be 1× or 2× lora_r. Only checked when you supply lora_r in the same request; otherwise it is validated against the platform default.

lora_dropout: Optional[float]

minimum0

maximum1

lora_trainable_modules: Optional[str]

'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').

lr_scheduler_type: Optional[Literal["linear", "cosine", "constant"]]

One of the following:

"linear"

"cosine"

"constant"

min_lr_ratio: Optional[float]

minimum0

maximum1

scheduler_num_cycles: Optional[float]

Number of cosine decay cycles across training. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.

minimum0

maximum4

warmup_ratio: Optional[float]

minimum0

maximum1

max_grad_norm: Optional[float]

minimum0

weight_decay: Optional[float]

minimum0

train_on_inputs: Optional[bool]

training_type: Optional[Literal["lora", "full"]]

Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary.

One of the following:

"lora"

"full"

column_mapping: Optional[ColumnMapping]

Column mapping the run trained with, echoing what was sent on create. Null when the mapping was left to the platform to infer.

prompt: Optional[str]

Source column holding the prompt/instruction text.

completion: Optional[str]

Source column holding the target completion/response. Used for supervised (sft) training.

reasoning_trace: Optional[str]

Optional source column holding a reasoning trace to train on.

download_available: bool

True when the best trained artifact can be downloaded.

error: Optional[object]

Why the run failed. Null unless status is failed.

Create an AutoScientist run

import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
autoscientist_run = client.autoscientist.create(
    dataset_id="dataset_id",
)
print(autoscientist_run.id)

{
  "id": "id",
  "dataset_id": {},
  "model": {},
  "status": "pending",
  "created_at": "2019-12-27T18:11:19.117Z",
  "completed_at": {},
  "iterations_completed": 0,
  "max_iterations": 0,
  "target_win_rate": 0,
  "best_win_rate": {},
  "best_hyperparams": {
    "n_epochs": 1,
    "batch_size": "max",
    "learning_rate": 0.00005,
    "lora_r": 8,
    "lora_alpha": 0,
    "lora_dropout": 0,
    "lora_trainable_modules": "q_proj,v_proj",
    "lr_scheduler_type": "linear",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "weight_decay": 0,
    "train_on_inputs": false,
    "training_type": "lora"
  },
  "column_mapping": {
    "prompt": "prompt",
    "completion": "completion",
    "reasoning_trace": "reasoning_trace"
  },
  "download_available": true,
  "error": {}
}

Returns Examples

{
  "id": "id",
  "dataset_id": {},
  "model": {},
  "status": "pending",
  "created_at": "2019-12-27T18:11:19.117Z",
  "completed_at": {},
  "iterations_completed": 0,
  "max_iterations": 0,
  "target_win_rate": 0,
  "best_win_rate": {},
  "best_hyperparams": {
    "n_epochs": 1,
    "batch_size": "max",
    "learning_rate": 0.00005,
    "lora_r": 8,
    "lora_alpha": 0,
    "lora_dropout": 0,
    "lora_trainable_modules": "q_proj,v_proj",
    "lr_scheduler_type": "linear",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "weight_decay": 0,
    "train_on_inputs": false,
    "training_type": "lora"
  },
  "column_mapping": {
    "prompt": "prompt",
    "completion": "completion",
    "reasoning_trace": "reasoning_trace"
  },
  "download_available": true,
  "error": {}
}