--- title: "Start Auto-Align" method: POST path: "/api/v3/alignment-projects/{alignment_id}/auto-align" tags: ["Alignment Projects"] --- # Start Auto-Align `POST /api/v3/alignment-projects/{alignment_id}/auto-align` ## Request - Base URL: `https://api.nugen.in` - URL: `https://api.nugen.in/api/v3/alignment-projects/{alignment_id}/auto-align` - Auth: HTTP bearer Submit a target alignment score and let the system plan the run as a recursive self-improvement loop: each checkpoint is scored, and the score steers the next phase. The system analyses your data, base model and prior train-time alignment history to build a multi-phase alignment plan. Phases are sequenced and executed continuously. The system may apply gradient-free representation adjustments, supervised learning, reward-guided optimisation, or a combination, re-planning when the score trajectory demands it. Checkpoints are evaluated between phases, and the system revisits earlier phases if regressions surface. Every parameter defaults to `auto`. You can override any of them to constrain the search, and the system performs best when given room to explore. **Path Parameters:** - `alignment_id`: The alignment project to auto-align. Its base model, data and prior train-time alignment history warm-start the planning. **Request Body:** - `target_score` (required): Target quality on a 0-99 scale - `benchmark_id` (optional): Benchmark that measures the achieved score against the target. Defaults to the benchmark already on the project - `method`, `representations`, `sequencing` (optional): Constrain which optimisation families run and in what order - `max_compute_hours` (optional): Upper bound on GPU hours across all phases - `notify_on_phase_transition` (optional): Notify on each phase change - `config` (optional): Take control of any part of the run, for reinforcement learning or supervised (SFT) settings: loss, optimizer, LoRA adapter, reward, advantage, reference policy, environment, dataset, sampling, training, checkpointing, evaluation, rendering and logging. Pass only what you want to pin; anything omitted stays auto and redundant settings are discarded. Every field is listed in the `AutoAlignConfig` schema, with a full example **Returns:** - `auto_align_id`: Identifier of this request - `alignment_id`: The project it targets - `status`, `message` **Raises:** - `404`: If the alignment project is not found or does not belong to you **Notes:** - Auto-alignment is an Enterprise Edition capability. The request is recorded and our team follows up; raise a support ticket to enable it - Once enabled, poll `GET /alignment-projects/{alignment_id}/status` for progress, phase transitions and intermediate scores ## Path parameters - `alignment_id` string, required ## Request body - AlignmentProjectAutoAlignRequest: Target a score and let the system reach it through recursive self-improvement. Every field except target_score defaults to auto. The deep configuration blocks are accepted as given and stored verbatim, so a run can pin any detail without the public schema enumerating every knob. - `target_score` number, required: Target alignment quality on a 0-99 scale. The system applies recursive self-improvement across phases until this score is reached or the compute budget is consumed. Targets above 85 typically cause the system to explore multiple optimisation strategies in sequence. - `benchmark_id` string, nullable: Benchmark used to measure the achieved score against the target. Defaults to the benchmark already on the alignment project. - `method` string, nullable: Which optimisation families the system may use. On auto it selects and sequences them from the score trajectory, and may begin with one approach, move to another, and revisit earlier ones. - `representations` string, nullable: How internal model representations are handled before and during alignment. On auto the system profiles the base model and picks a strategy before any gradient-based phase begins. - `sequencing` string[], nullable: Explicit phase ordering. When null the system orders phases itself and may interleave or revisit them. When given, it follows the order and still controls the hyperparameters within each phase. - `max_compute_hours` number, nullable: Upper bound on GPU hours across all phases, allocated by expected marginal score gain. When null the run continues until the target. - `notify_on_phase_transition` boolean, nullable: Notify when the system moves between alignment phases. - `config` AutoAlignConfig: Settings that pin any part of an auto-align run. Anything left out stays on auto. - `base_model` string, nullable: Base model by Hugging Face id; defaults to the alignment project's - `loss` AutoAlignLoss: The training objective and its settings. - `type` string, nullable: Objective: cross_entropy for SFT, or ppo, cispo, dro for reinforcement learning - `ppo` object, nullable: PPO clip bounds, clip_low and clip_high - `cispo` object, nullable: CISPO settings, eps_max - `dro` object, nullable: DRO settings, beta - `kl_coef` number, nullable: KL penalty against the reference policy - `entropy_coef` number, nullable: Entropy bonus - `token_reduction` string, nullable: How token losses reduce: sum or mean - `is_ratio_level` string, nullable: Importance ratio level: token or sequence - `custom_loss_ref` string, nullable: Reference to a custom loss - `custom_weights_field` string, nullable: Dataset field holding per-token weights - `z_loss_coef` number, nullable: Z-loss coefficient - `optimizer` AutoAlignOptimizer: The optimiser and its learning rate schedule. - `type` string, nullable: Optimizer, e.g. adamw - `learning_rate` number, nullable: Peak learning rate - `beta1` number, nullable: Adam beta1 - `beta2` number, nullable: Adam beta2 - `eps` number, nullable: Adam epsilon - `weight_decay` number, nullable: Weight decay - `grad_clip_norm` number, nullable: Global gradient norm clip - `lr_schedule` string, nullable: Learning rate schedule, e.g. cosine or linear - `warmup_steps` integer, nullable: Warmup steps - `warmup_ratio` number, nullable: Warmup as a fraction of steps, instead of warmup_steps - `lr_multiplier` number, nullable: Multiplier on the learning rate - `reward` AutoAlignReward: How each rollout is scored. - `type` string, nullable: Reward source: llm_judge, verifier, rubric, preference_model or composite - `verifier_ref` string, nullable: Reference to a programmatic verifier - `llm_judge` object, nullable: Judge settings: judge_model and criteria - `rubric_ref` string, nullable: Reference to a scoring rubric - `preference_model_ref` string, nullable: Reference to a preference model - `composite` object, nullable: Weights per reward component - `clip` number[], nullable: Reward clip range, [low, high] - `normalize` string, nullable: Reward normalisation, e.g. per_group_zscore - `advantage` AutoAlignAdvantage: How rewards become advantages, including the estimator, baseline and discounting. - `estimator` string, nullable: Advantage estimator, e.g. gae or group_relative - `center` string, nullable: Baseline used to centre advantages, e.g. group_mean - `normalize_std` boolean, nullable: Divide advantages by their standard deviation - `skip_zero_advantage_groups` boolean, nullable: Skip groups whose advantages are all zero - `gamma` number, nullable: Discount factor - `gae_lambda` number, nullable: GAE lambda - `scope` string, nullable: Per token or per sequence - `reference_policy` AutoAlignReferencePolicy: The reference policy the KL penalty is measured against. - `enabled` boolean, nullable: Keep a reference policy for the KL penalty - `source` string, nullable: frozen_snapshot or ema - `snapshot_path` string, nullable: Snapshot to use as the reference - `ema_decay` number, nullable: EMA decay when source is ema - `kl_target` number, nullable: Target KL for adaptive control - `environment` AutoAlignEnvironment: The environment the rollouts run in, including turns, tools and sandboxing. - `type` string, nullable: single_turn or multi_turn - `env_ref` string, nullable: Reference to an environment - `max_turns` integer, nullable: Maximum turns per episode - `tools` string[], nullable: Tools available to the model - `num_agents` integer, nullable: Agents per episode - `rollout_strategy` string, nullable: Rollout strategy - `sandbox` object, nullable: Sandbox settings: enabled and backend - `retry_on_failure` boolean, nullable: Retry a failed rollout - `fail_fast` boolean, nullable: Stop the run on the first rollout failure - `dataset` AutoAlignDataset: The data the run trains on and how it is read. - `name` string, nullable: Dataset name; defaults to the alignment project's data - `split` string, nullable: Split to train on - `prompt_field` string, nullable: Field holding the prompt - `answer_field` string, nullable: Field holding the reference answer - `completion_field` string, nullable: Field holding a completion - `shuffle` boolean, nullable: Shuffle examples - `streaming` boolean, nullable: Stream instead of loading in memory - `format` string, nullable: chat or completion - `file_type` string, nullable: jsonl, json or parquet - `max_examples` integer, nullable: Cap on examples used - `synthetic` object, nullable: Synthetic training dataset: enabled, domain_description, label_list, num_examples - `sampling` AutoAlignSampling: How completions are sampled for each prompt. - `group_size` integer, nullable: Completions sampled per prompt - `prompt_groups_per_step` integer, nullable: Prompt groups per step - `max_tokens` integer, nullable: Maximum generated tokens - `max_prompt_tokens` integer, nullable: Maximum prompt tokens - `max_seq_len` integer, nullable: Maximum sequence length - `temperature` number, nullable: Sampling temperature - `top_p` number, nullable: Nucleus sampling - `top_k` integer, nullable: Top-k sampling - `min_p` number, nullable: Min-p sampling - `stop` string[], nullable: Stop sequences - `seed` integer, nullable: Sampling seed - `enable_thinking` boolean, nullable: Allow a thinking phase - `thinking_effort` string, nullable: low, medium or high - `prompt_caching` boolean, nullable: Cache shared prompt prefixes - `session_affinity_key` string, nullable: Field that keeps a trajectory on one worker - `training` AutoAlignTraining: Training steps, batch size, mode and stopping rules. - `steps` integer, nullable: Optimiser steps - `batch_size` integer, nullable: Batch size - `gradient_accumulation` integer, nullable: Gradient accumulation steps - `inner_optim_steps` integer, nullable: Optimiser steps per batch - `mode` string, nullable: sync or async - `rollout_training_overlap` boolean, nullable: Overlap rollouts with optimisation - `epochs` integer, nullable: Epochs - `max_steps` integer, nullable: Hard cap on steps - `seed` integer, nullable: Seed - `early_stopping` object, nullable: Early stopping: enabled, metric, patience - `adapter` AutoAlignAdapter: Adapter type and size for the run. - `mode` string, nullable: lora or full - `rank` integer, nullable: LoRA rank - `alpha` integer, nullable: LoRA alpha - `dropout` number, nullable: LoRA dropout - `train_attn` boolean, nullable: Adapt attention layers - `train_mlp` boolean, nullable: Adapt MLP layers - `train_unembed` boolean, nullable: Adapt the unembedding layer - `init_seed` integer, nullable: Adapter initialisation seed - `quantization_bits` integer, nullable: Base model quantisation, e.g. 4 - `checkpointing` AutoAlignCheckpointing: When checkpoints are saved during the run. - `save_every_steps` integer, nullable: Save a checkpoint every N steps - `mode` string, nullable: Checkpoint mode - `keep_last_n` integer, nullable: Checkpoints to keep - `resume_from` string, nullable: Checkpoint to resume from - `promote_final` boolean, nullable: Promote the final checkpoint to the aligned model - `evaluation` AutoAlignEvaluation: Evaluation during the run. - `eval_dataset` string, nullable: Evaluation dataset - `eval_every_steps` integer, nullable: Evaluate every N steps - `eval_group_size` integer, nullable: Samples per evaluation prompt - `eval_temperature` number, nullable: Evaluation temperature - `metrics` string[], nullable: Metrics to track - `benchmark_ref` string, nullable: Benchmark to evaluate against - `eval_batch_size` integer, nullable: Evaluation batch size - `rendering` AutoAlignRendering: How prompts and conversations are rendered for the model. - `renderer_name` string, nullable: Renderer - `chat_template` string, nullable: Chat template override - `add_special_tokens` boolean, nullable: Add special tokens - `max_seq_len` integer, nullable: Maximum rendered length - `truncation` string, nullable: left or right - `packing` boolean, nullable: Pack sequences - `batch_unit` string, nullable: tokens or examples - `logging` AutoAlignLogging: Where the run logs its progress. - `wandb_project` string, nullable: Weights and Biases project - `log_metrics` string[], nullable: Metrics to log - `wandb_key` string, password, nullable: Weights and Biases API key. Write only: never returned or logged ## Response `202` Auto-alignment request accepted and recorded. - AlignmentProjectAutoAlignResponse: Acknowledgement of an auto-alignment request. - `auto_align_id` string, required: Identifier of the auto-alignment request. - `alignment_id` string, required: Alignment project the request targets. - `status` 'RECEIVED', required: Request status. RECEIVED means the request was recorded. - `message` string, required: Human-readable outcome of the request. ## Other responses - `401`: Invalid API key - `403`: Authorization header missing or not a Bearer token - `404`: Resource not found - `422`: Validation Error --- [API](https://skmtc.dev/nugen/apis/nugen-intelligence-api.md) - [All operations](https://skmtc.dev/nugen/apis/nugen-intelligence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nugen/apis/nugen-intelligence-api/revisions/62baa7960a4a?raw)