Adaption

View saved version →

---
name: adaption-dataset
description: Import, process, and transform datasets using Adaption MCP. Use when importing 
  datasets, running adaptation, augmenting, translating, localizing, or combining datasets.
---

# Adaption Dataset Skill

Import, process, and transform datasets using the Adaption platform.

## When to use

- Import datasets from HuggingFace, Kaggle, or Google Sheets
- Run dataset adaptation pipeline
- Augment datasets with synthetic domain/general rows
- Translate or localize dataset content
- Combine multiple datasets
- Check processing status and download results

## Available MCP Tools

Use these tools via the Adaption MCP server:

| Tool | Description |
|------|-------------|
| `list_datasets` | List datasets visible to the authenticated Adaption organization |
| `get_dataset` | Get a concise public view of one dataset, including processing and column information |
| `get_dataset_status` | Poll dataset processing status and progress after async operations |
| `get_dataset_evaluation` | Get quality evaluation status and results for one dataset |
| `get_dataset_export_links` | Poll saved external export URLs for a dataset after export |
| `import_dataset` | Import a dataset from HuggingFace, Kaggle, or Google Sheets URL |
| `run_dataset_adaptation` | Estimate or launch adaptation for an imported dataset |
| `augment_dataset` | Create new dataset with source rows plus curated domain/general rows |
| `translate_dataset` | Create new dataset with sampled rows translated into target languages |
| `localize_dataset` | Create new dataset with rows localized for country/language pairs |
| `combine_datasets` | Combine compatible ready datasets into one new dataset |

## Example Workflows

### Import and adapt a HuggingFace dataset

1. Call `import_dataset` with a `source` object — all import options nest inside it:
   ```json
   {
     "source": {
       "url": "https://huggingface.co/datasets/squad",
       "files": ["plain_text/train-00000-of-00001.parquet"]
     }
   }
   ```
   `files` is required for HuggingFace and Kaggle imports and rejected for Google
   Sheets. Pass `processing_mode: "raw"` to import a trainable dataset without
   running Adaptive Data.
2. Poll `get_dataset_status` until processing completes
3. Call `run_dataset_adaptation` with `estimate: true` to preview cost
4. Call `run_dataset_adaptation` with column mapping to launch
5. Poll `get_dataset_status` until adaptation completes
6. Call `get_dataset_export_links` to download results

### Augment a dataset with synthetic data

1. Ensure source dataset status is `ready`
2. Call `augment_dataset` with:
   - `dataset_id`: Source dataset ID
   - `domain_rows`: More samples from the domain already present in the dataset
   - `general_rows`: Samples from other domains not present in it
   - `training_type`: `instruction_dataset` (default) or `preference_pairs`
   - `estimate: true` for cost preview
3. Launch with `estimate: false`
4. Poll `get_dataset_status` on the new dataset ID

Each row count tops out at 100,000 per strategy. Augmenting creates a new dataset
rather than modifying the source.

### Translate dataset to multiple languages

1. Call `translate_dataset` with:
   - `dataset_id`: Source dataset ID
   - `languages`: Array of target language codes
   - `sample_rate`: Share of rows to translate, between 0.01 and 1
   - `estimate: true` for cost preview
2. Poll `get_dataset_status` until translation completes

`localize_dataset` takes the same `sample_rate` but replaces `languages` with
`pairs`, an array of `{ "country": "RS", "language": "sr" }` objects.

### Combine multiple datasets

1. Ensure all source datasets have compatible schemas and status `ready`
2. Call `combine_datasets` with:
   - `dataset_ids`: 2 to 10 unique dataset IDs, each a UUID v4
   - `name`: Required name for the combined dataset
   - `idempotency_key`: Required — reusing the same key returns the same result
     instead of combining twice

All sources must belong to the same organization.

## Column Mapping

When calling `run_dataset_adaptation`, map dataset columns to roles. Full rules: https://docs.adaptionlabs.ai/adaptive-data/select-columns/

- `prompt` and `completion` are column names. At least one is required. If the other is missing, Adaptive Data generates it.
- `context` is a list of column names (background or metadata), not a single string.
- `image` is one column of image bytes, URLs, or paths. Do not put images in `context`.
- `chat` is one column of multi-turn message arrays. It replaces `prompt`, `completion`, and `context`.
- `universal_prompt` is a shared instruction string for every row, not a column name. Use it when the dataset has no prompt column. It requires `context` or `image` to vary each row, and is mutually exclusive with `prompt`.

```json
{
  "column_mapping": {
    "prompt": "question",
    "completion": "answer",
    "context": ["category", "source"]
  }
}
```

## Adaptation Options

Beyond `column_mapping`, `run_dataset_adaptation` accepts:

| Parameter | Description |
|-----------|-------------|
| `training_type` | `instruction_dataset` (default) or `preference_pairs`. Use `preference_pairs` to prepare a dataset for an alignment training run |
| `recipe_specification` | Toggles for `prompt_rephrase`, `deduplication`, and `reasoning_traces` under a `recipes` object |
| `brand_controls` | `length` (`minimal`, `concise`, `detailed`, `extensive`), `safety_categories`, `hallucination_mitigation`, and `blueprint` |
| `job_specification` | `max_rows` to cap the run, plus `idempotency_key` |
| `language_expansion` | Same `translate`/`localize` spec as dataset generation |
| `estimate` | Set `true` to preview cost without launching |

## Tips

- Use `estimate: true` parameter to preview costs before launching operations
- Poll `get_dataset_status` every 5-10 seconds during processing — it returns
  `progress_percentage` alongside the status
- Filter `list_datasets` with `status` (`pending`, `running`, `awaiting_input`,
  `succeeded`, `failed`) or a `query` string instead of paging through everything
- Launch responses carry a `next_action` naming the tool to call next — follow it
- Check `get_dataset_evaluation` for quality metrics after adaptation
- Use `idempotency_key` for safe retries on launch operations

View saved version →

---
name: adaption-invent
description: Generate synthetic datasets using Adaption's Invent-a-Dataset. Use when 
  creating post-training datasets from scratch out of natural language descriptions, 
  to add new capabilities to a language model — especially in a zero-data regime 
  with no seed data available.
---

# Adaption Invent Skill

Generate synthetic training datasets using Adaption's Invent-a-Dataset feature.

## When to use

- Generate synthetic training datasets from natural language descriptions
- Create domain-specific datasets for post-training language models without any
  seed data to start from
- Estimate costs before generating data

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_invent_domains` | List valid domain and qualified subdomain codes for dataset generation |
| `generate_dataset` | Estimate or launch generation of a new invented dataset (launches consume credits) |

After generation starts, use dataset tools to track progress:
| Tool | Description |
|------|-------------|
| `get_dataset_status` | Poll processing status of the generated dataset |
| `get_dataset` | Get details of the generated dataset |

## Example Workflows

### Generate domain-specific training data

Steps 1 and 2 are optional — a `dataset_prompt` on its own is enough, and the
taxonomy is inferred from it. Supply the codes when you want more control over
what ends up in the dataset.

1. Optionally call `list_invent_domains` to explore available domains and subdomains
2. Optionally choose domain and subdomain codes matching your use case
3. Call `generate_dataset` with `estimate: true` to preview cost:
   ```json
   {
     "domains": ["technology"],
     "subdomains": ["technology.software_applications"],
     "rows": 1000,
     "estimate": true
   }
   ```
4. Review estimate, then launch with `estimate: false`
5. Poll `get_dataset_status` with returned dataset ID until complete
6. Generated dataset is ready for training — an invented dataset is already a
   type of adaptive dataset, so it does not need adaptation

### Generate with custom specifications

```json
{
  "name": "Customer Support QA",
  "training_type": "instruction_dataset",
  "domains": ["corporate_business"],
  "subdomains": ["corporate_business.customer_service"],
  "rows": 500,
  "dataset_prompt": "Generate realistic customer questions about technical software product support scenarios"
}
```

### Control the output through `dataset_prompt`

`dataset_prompt` also carries constraints on output format, tone, and structure,
which is how you pin the shape of the generated rows. Both examples below omit
the taxonomy entirely and let it be inferred:

```json
{
  "rows": 1000,
  "dataset_prompt": "Question-answer pairs focusing on legal advice, factual explanations, and comparative analysis across diverse topics such as copyright law, government types, and liability. Questions should offer four choices; answers are limited to A, B, C, or D with no additional text."
}
```

```json
{
  "rows": 500,
  "dataset_prompt": "Summaries of used car advertisements in Serbian, featuring detailed descriptions of vehicle conditions, service histories, and equipment packages. Each prompt is an ad summary, and each response is a JSON object containing vehicle_description, service_history, and equipment_packages."
}
```

### Generate with language expansion

`language_expansion` is either a `translate` or a `localize` spec, and `type` is
required. `sample_rate` (0.01-1) is the share of rows expanded. Credits are
billed on the post-expansion row count, so this quotes above `rows`.

```json
{
  "domains": ["academic_education"],
  "subdomains": ["academic_education.stem"],
  "rows": 1000,
  "language_expansion": {
    "type": "translate",
    "languages": ["es", "fr", "de"],
    "sample_rate": 0.2
  }
}
```

To localize for country/language pairs instead:

```json
{
  "language_expansion": {
    "type": "localize",
    "pairs": [{ "country": "RS", "language": "sr" }],
    "sample_rate": 0.2
  }
}
```

## Domains and Subdomains

Domain codes are flat lowercase strings such as `technology`, `medical`, `legal`,
`code`, `corporate_business`, `academic_education`, and `personal_finance`.
Subdomain codes are always qualified with their domain as `domain.subdomain`,
for example `medical.symptoms_diagnosis` — a bare code can belong to more than
one domain, so an unqualified value is rejected.

Call `list_invent_domains` for the full catalog with the exact codes. A subdomain
naming a domain that is not in your `domains` array is rejected rather than
silently added.

## Parameters

`rows` is always required, plus at least one of `dataset_prompt`, `domains`, or
`subdomains`. With both taxonomy fields omitted, `dataset_prompt` is required and
the taxonomy is inferred from it; if nothing can be inferred the request is
rejected rather than generating across every domain. Supplying `domains` or
`subdomains` disables that inference.

| Parameter | Description |
|-----------|-------------|
| `rows` | Required number of rows to generate, subject to your plan's per-launch cap |
| `dataset_prompt` | Free-text description of the data you want, up to 10,000 characters |
| `domains` | Optional array of domain codes |
| `subdomains` | Optional array of qualified `domain.subdomain` codes |
| `training_type` | Shape of the generated data: `instruction_dataset` (default) or `preference_pairs` |
| `name` | Optional name for the generated dataset, up to 255 characters |
| `language_expansion` | Optional `translate` or `localize` expansion config |
| `estimate` | Set `true` to preview cost without launching |
| `idempotency_key` | Optional key for safe retries |

`training_type` here is the shape of the DATA, not the training method:
`instruction_dataset` produces prompt/completion rows, `preference_pairs`
produces ranked completion pairs. The `training_type` inside `hyperparams` on a
training run is a different field meaning LoRA versus full fine-tuning.

Generate with `preference_pairs` when the dataset will feed an alignment training
run — see the `adaption-training` skill, where that run needs
`training_method: "alignment"`.

## Tips

- Start with smaller row counts (100-500) to validate quality
- Use a specific `dataset_prompt` for better results
- Once an invented dataset covers the target capability, expand it with more
  domain-specific or general samples via `augment_dataset` to increase size and
  diversity before training
- Use `estimate: true` to check credits before launching
- Launch responses carry a `next_action` naming the tool to call next — follow it
- Use `idempotency_key` for safe retries if generation fails

View saved version →

---
name: adaption-training
description: Launch and monitor AutoScientist training runs using Adaption MCP. Use when 
  fine-tuning models, checking training progress, or getting hyperparameter recommendations.
---

# Adaption Training Skill

Launch and monitor AutoScientist training runs on the Adaption platform.

## When to use

- List available base models for fine-tuning
- Get recommended hyperparameters for a dataset
- Launch AutoScientist training runs
- Monitor training progress and results
- List past training runs

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_training_models` | List base models currently available for AutoScientist training |
| `list_autoscientist_runs` | List AutoScientist runs, optionally filtered to one dataset |
| `get_autoscientist_run` | Poll one AutoScientist run, including iteration progress and any public failure message |
| `recommend_autoscientist_hyperparameters` | Resolve a suitable model and hyperparameters for a ready dataset without launching a run |
| `create_autoscientist_run` | Launch a new asynchronous AutoScientist training run (spends credits) |

## Example Workflows

### Fine-tune a model with AutoScientist

1. Ensure dataset status is `ready` (check with `get_dataset_status`)
2. Call `list_training_models` to see available base models
3. Call `recommend_autoscientist_hyperparameters` with:
   - `dataset_id`: Your ready dataset
   - `model`: Optional preferred base model
   - `augmentation_domain_rows` and `augmentation_general_rows`: the same values
     you plan to launch with, since they count toward the dataset size the
     recommendation is sized for
4. Review the returned `model` and `hyperparams`
5. Call `create_autoscientist_run` with:
   - `dataset_id`: Your ready dataset
   - `model`: Optional base model — the platform picks one when omitted
   - `column_mapping`: Optional, see below — inferred from the dataset when omitted
   - `hyperparams`: Optional training configuration, or use the recommended one
6. Poll `get_autoscientist_run` with `experiment_id` until complete

### Train on preference pairs

An alignment run trains on ranked completion pairs instead of prompt/completion
rows. The dataset must have been prepared for it:

1. Generate it with `training_type: "preference_pairs"` — see the
   `adaption-invent` skill — or adapt an existing dataset with that setting
2. Call `create_autoscientist_run` with `training_method: "alignment"`
3. Map `chosen` and `rejected` in `column_mapping` when the columns are not
   obvious from the dataset

An alignment run trains in two stages, supervised first and preference second,
and reports the first stage until the second begins — so it stays `running`
through the handoff rather than reporting the supervised result as final.

### Augment before training

AutoScientist can augment your dataset before training starts. This is useful for
increasing dataset size or adding data closer to the target capability, since many
models need larger volumes before showing a reasonable performance lift.

Use `augmentation_domain_rows` for more samples from the domain already present in
your dataset, and `augmentation_general_rows` for samples from other domains that
are not in it.

```json
{
  "dataset_id": "...",
  "augmentation_domain_rows": 1000,
  "augmentation_general_rows": 500
}
```

### Check training history

1. Call `list_autoscientist_runs` to see all runs
2. Filter by dataset: `list_autoscientist_runs` with `dataset_id`
3. Get details: `get_autoscientist_run` with `experiment_id`

## Run Options

`create_autoscientist_run` takes these alongside `dataset_id`:

| Parameter | Description |
|-----------|-------------|
| `model` | Base model name from `list_training_models`. The platform picks one when omitted |
| `training_method` | `instruction` or `alignment`. Derived from the dataset when omitted |
| `data_format` | `chat` or `instruction`, defaulting to `chat`. Applies to raw datasets only — for an adapted dataset the platform resolves the encoding and this is ignored |
| `column_mapping` | Which dataset columns feed training, see below |
| `hyperparams` | Training configuration, see below |
| `augmentation_domain_rows` | Extra rows from the dataset's own domain |
| `augmentation_general_rows` | Extra rows from other domains |
| `max_iterations` | How many iterations AutoScientist may run, up to 5 |
| `target_win_rate` | Win rate to stop at, between 0.5 and 1 |
| `idempotency_key` | Key for safe retries |

## Column Mapping

A training run accepts a different set of roles than dataset adaptation does, and
unknown keys are dropped silently instead of rejected — so `context`, `chat`, or
`image` sent here are ignored without an error.

| Role | Use |
|------|-----|
| `prompt` | Column holding the instruction text |
| `completion` | Column holding the target response |
| `reasoning_trace` | Column holding a reasoning trace, when the dataset has one |
| `chosen` | Preferred completion, alignment runs only |
| `rejected` | Rejected completion, alignment runs only |

Omit `column_mapping` entirely and AutoScientist infers it from the dataset.

## Training Configuration

`hyperparams` is validated strictly, so an unknown key fails the whole request.
Every field is optional — omit what you do not want to pin and AutoScientist
fills it in from the recommendation.

```json
{
  "hyperparams": {
    "training_type": "lora",
    "n_epochs": 3,
    "learning_rate": 2e-5,
    "batch_size": "max",
    "lora_r": 16,
    "lora_alpha": 32,
    "lr_scheduler_type": "cosine",
    "warmup_ratio": 0.1
  }
}
```

| Parameter | Accepted values |
|-----------|-----------------|
| `training_type` | `lora` or `full` — LoRA versus full fine-tuning |
| `n_epochs` | 1-20 |
| `learning_rate` | 1e-8 to 1e-2 |
| `batch_size` | `"max"` or a positive integer |
| `lora_r` | 1-64 |
| `lora_alpha` | Must equal `lora_r` or twice `lora_r` |
| `lora_dropout` | 0-1 |
| `lora_trainable_modules` | `"all-linear"` or a comma-separated module list |
| `lr_scheduler_type` | `linear`, `cosine`, or `constant` |
| `min_lr_ratio` | 0-1 |
| `scheduler_num_cycles` | 0-4 |
| `warmup_ratio` | 0-1 |
| `max_grad_norm` | Non-negative |
| `weight_decay` | Non-negative |
| `train_on_inputs` | Boolean |
| `dpo_beta` | 0.05-0.9, alignment runs only |
| `dpo_normalize_logratios_by_length` | Boolean, alignment runs only |
| `rpo_alpha`, `simpo_gamma` | Alignment runs only, and both cannot be positive at once |

## Training Status

The `get_autoscientist_run` response reports progress as a count of finished
iterations plus the metrics of the best one — there are no per-iteration metrics:

- `status`, `created_at`, and `completed_at`
- `iterations_completed` against `max_iterations`
- `best_win_rate` against `target_win_rate`
- `best_hyperparams` — the configuration that produced the best iteration
- `download_available` once a successful run has a trained model
- `error` with the public failure message when the run failed

## Tips

- Use `recommend_autoscientist_hyperparameters` before launching to optimize configuration
- Training runs consume credits — verify dataset is ready first
- Poll `get_autoscientist_run` every 30-60 seconds during training
- Launch responses carry a `next_action` naming the tool to call next — follow it
- Use `augmentation_domain_rows` for domain-specific enrichment and
  `augmentation_general_rows` for general or domain-diverse enrichment