Invent a dataset

Invent generates a model-ready dataset from scratch—no source dataset required. Describe your dataset with a prompt, optionally narrow with domains and subdomains, and the API creates a dataset for your task.

Use datasets.create instead when you want to import and adapt an existing dataset.

What you can build

• Instruction datasets pair prompts with generated completions for supervised fine-tuning.
• Preference pairs rank two completions against each other for preference-based training.

How it works

1. Describe your dataset. Use the dataset_prompt and optional domains and subdomains to guide the dataset invention process.
2. Estimate (optional). Price the exact request with estimate=True. Nothing is created or charged.
3. Generate. Call datasets.invent to create the dataset and start generation. The call returns immediately with status running.
4. Poll and download. Poll datasets.get until the status is succeeded, then download the rows.

Generate a dataset

A single call to datasets.invent creates the dataset and starts generating rows from your description and optional domain selections. The examples assume you have installed the Python SDK and set ADAPTION_API_KEY.

from adaption import Adaption

client = Adaption()

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    rows=1000,
    name="Clinical Q&A",
)

dataset_id = dataset.id
print(dataset_id, dataset.status)  # running

Describe the dataset

To invent a dataset, provide at least one of the following parameters:

Parameter	Notes
dataset_prompt	Description of the data to generate. If omitted, a description is generated from your domain selections. Maximum 10,000 characters.
domains	Domain codes to generate from. See Choose domains and subdomains.
subdomains	Qualified subdomain codes that narrow generation. See Choose domains and subdomains.

Request parameters

Parameter	Required	Notes
rows	Yes	Number of rows to generate. Subject to your plan’s per-launch row limit.
name	No	Display name for the invented dataset.
training_type	No	instruction_dataset (default) or preference_pairs. See Choose the output format.
translate	No	Translates a sample of the generated rows into other languages. See Expand across languages and locales.
localize	No	Localizes a sample of the generated rows to country and language pairs. See Expand across languages and locales.
estimate	No	Returns a credit estimate without creating or launching a dataset. Defaults to False.
idempotency_key	No	Makes retries safe. Repeating a request with the same key returns the original dataset instead of starting generation again. Maximum 255 characters.

Price a request first

Set estimate=True to price the exact request. Nothing is generated or charged:

estimate = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=["medical"],
    subdomains=[
        "medical.symptoms_diagnosis",
        "medical.preventive_care",
    ],
    rows=1000,
    estimate=True,
)

print(f"Estimated credits: {estimate.estimated_credits}")
print(f"Available credits: {estimate.available_credits}")

Choose domains and subdomains

Fetch the current codes accepted by datasets.invent rather than hardcoding them:

response = client.datasets.invent_domains()

for domain in response.domains:
    print(domain.code, domain.title)
    for subdomain in domain.subdomains:
        print("  ", subdomain.code, subdomain.title)

Domain and subdomain fields

Field	Description
code	The value to send in domains or subdomains. Domain codes are values such as medical; subdomain codes are qualified values such as medical.symptoms_diagnosis.
title	Human-readable name for the domain or subdomain.
subdomains	Subdomains available within a domain. An empty list means the domain has no subdomains.

Narrow with subdomains

Pass subdomain codes exactly as returned by invent_domains. subdomains is a flat list of qualified codes:

Here, the medical portion is narrowed to the selected subdomains. The legal portion draws from the full legal domain because no legal subdomains were provided.

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=["medical", "legal"],
    subdomains=[
        "medical.symptoms_diagnosis",
        "medical.preventive_care",
    ],
    rows=1000,
)

Combine multiple domains

Every code in domains contributes to the same generation run. For a domain without subdivisions, pass its domain code and omit subdomains for it.

Configure generation

Configure the output format, expand languages, and make retries safe.

Choose the output format

training_type defaults to instruction_dataset. Set it to preference_pairs for chosen and rejected completion pairs:

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=["medical"],
    rows=1000,
    training_type="preference_pairs",
)

Use instruction_dataset for standard supervised fine-tuning. Use preference_pairs for preference-based training such as DPO. The same formats are described in Configure Adaptive Data.

Expand across languages and locales

translate and localize add rows in other languages, the same way as translating and localizing an existing dataset:

• translate adds a translated variant of each sampled row for every target language.
• localize adds a variant for every country and language pair, using locale-specific wording rather than direct translation alone.

Pass either one, or both in the same request. Each takes its own sample_rate: the fraction of invented rows expanded for each target, between 0.01 and 1. Credits are billed on the expanded output row count.

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=["medical"],
    rows=1000,
    translate={
        "languages": ["es", "fr"],
        "sample_rate": 0.25,
    },
    localize={
        "pairs": [{"country": "ES", "language": "ca"}],
        "sample_rate": 0.1,
    },
)

This request delivers and bills about 1,000 × (1 + 0.25 × 2 + 0.1 × 1) = 1,600 rows.

Unsupported language codes and country/language pairs return a 400 response before anything is created.

language_expansion is deprecated. It holds one mode at a time and cannot be combined with translate or localize. Requests that already use it keep working.

Make retries safe

Provide an idempotency key when a network failure might cause your application to retry the request:

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=["medical"],
    rows=1000,
    idempotency_key="clinical-qa-2026-09-02",
)

Repeating the same request with this key returns the original dataset instead of starting another generation run.

Put it together

domains = ["medical"]
subdomains = ["medical.symptoms_diagnosis"]

estimate = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=domains,
    subdomains=subdomains,
    rows=1000,
    estimate=True,
)
print(f"Estimated credits: {estimate.estimated_credits}")

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    name="Clinical Q&A",
    domains=domains,
    subdomains=subdomains,
    rows=1000,
    training_type="instruction_dataset",
    idempotency_key="clinical-qa-2026-09-02",
)
dataset_id = dataset.id
print(dataset_id, dataset.status)  # running

Check status and download

Poll datasets.get with the invented dataset ID until generation reports succeeded or failed.

Poll until generation finishes

import time

while True:
    record = client.datasets.get(dataset_id)
    if record.status == "succeeded":
        break
    if record.status == "failed":
        error = record.error_data
        message = (error and error.message) or "unknown error"
        raise RuntimeError(f"Dataset generation failed: {message}")
    time.sleep(5)

print(f"Generated {record.row_count} rows")

Download the rows

Download the completed dataset as JSON Lines, JSON, CSV, or Parquet:

client.datasets.download(
    dataset_id,
    file_format="jsonl",
).write_to_file("clinical-qa.jsonl")

See datasets.download for all response and streaming options.

Complete example

import time

from adaption import Adaption

client = Adaption()

domains = ["medical"]
subdomains = ["medical.symptoms_diagnosis"]

estimate = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    domains=domains,
    subdomains=subdomains,
    rows=1000,
    estimate=True,
)
print(f"Estimated credits: {estimate.estimated_credits}")

dataset = client.datasets.invent(
    dataset_prompt=(
        "A dataset of medical question-answer pairs covering diagnoses, treatments, "
        "drug explanations, and healthcare roles. Each entry includes a prompt and a "
        "detailed, expert-generated response."
    ),
    name="Clinical Q&A",
    domains=domains,
    subdomains=subdomains,
    rows=1000,
    training_type="instruction_dataset",
    idempotency_key="clinical-qa-2026-09-02",
)
dataset_id = dataset.id
print(dataset_id, dataset.status)  # running

assert dataset_id is not None

while True:
    record = client.datasets.get(dataset_id)
    if record.status == "succeeded":
        break
    if record.status == "failed":
        error = record.error_data
        message = (error and error.message) or "unknown error"
        raise RuntimeError(f"Dataset generation failed: {message}")
    time.sleep(5)

print(f"Generated {record.row_count} rows")

client.datasets.download(
    dataset_id,
    file_format="jsonl",
).write_to_file("clinical-qa.jsonl")

To train on the generated dataset, pass its ID to autoscientist.create:

run = client.autoscientist.create(dataset_id=dataset_id)
print(run.id, run.status)