adaption-ai

Adaption AI SDK Skill

Build dataset augmentation pipelines with Adaption's Adaptive Data platform. This skill covers the full lifecycle: ingest → adapt → wait → evaluate → export.

Quick Reference

pip install adaption

from adaption import Adaption
client = Adaption(api_key="pt_live_...")  # or set ADAPTION_API_KEY env var

Async client: from adaption import AsyncAdaption

Core Lifecycle

1. Ingest — Upload local file, import from HuggingFace, or import from Kaggle
2. Adapt — Start an augmentation run with column mapping + optional controls
3. Wait — Poll for completion with exponential backoff
4. Evaluate — Fetch quality metrics (score_before/after, improvement %)
5. Export — Download augmented dataset via presigned URL

Ingest Methods

Local file upload

Supported formats: .csv, .json, .jsonl, .parquet

result = client.datasets.upload_file("training_data.csv")
result = client.datasets.upload_file("data.csv", name="my-dataset")  # custom name
dataset_id = result.dataset_id

Hugging Face import (async on server — poll before running)

resp = client.datasets.create_from_huggingface(
    url="https://huggingface.co/datasets/org/repo",
    files=["train.csv"],
)

Kaggle import (requires Kaggle API creds registered in Adaption settings)

resp = client.datasets.create_from_kaggle(
    url="https://www.kaggle.com/datasets/org/dataset-name",
    files=["data.csv"],
)

Running Adaptation Jobs

datasets.run() — the central method

Required: dataset_id, column_mapping with at least "prompt" key.

run = client.datasets.run(
    dataset_id,
    column_mapping={
        "prompt": "instruction",       # required
        "completion": "response",      # optional
        # "chat": "conversation",      # optional — alternative to prompt+completion
        # "context": ["source", "ref"],# optional — list of context columns
    },
    # --- Optional controls (see references/ for details) ---
    brand_controls={...},
    recipe_specification={...},
    job_specification={...},
    estimate=True,  # dry-run: get cost quote without starting
)

Response fields: run.run_id, run.estimated_credits_consumed, run.estimated_minutes

Brand Controls (brand_controls)

Recipe Specification (recipe_specification)

recipe_specification={
    "recipes": {
        "reasoning_traces": True,          # chain-of-thought in completions
        "deduplication": True,             # remove near-duplicates
        "preference_pairs": True,          # DPO chosen/rejected pairs
        "prompt_rephrase": True,           # rephrase prompts for variety
        "prompt_metadata_injection": True, # inject context into prompts
    },
    "version": "...",  # optional schema version
}

Job Specification (job_specification)

job_specification={
    "max_rows": 500,           # subsample for pilots
    "idempotency_key": "...",  # safe retries
}

Wait, Evaluate, Export

from adaption import DatasetTimeout

# Wait (exponential backoff 2s→30s, default timeout 1hr)
try:
    status = client.datasets.wait_for_completion(dataset_id, timeout=600)
except DatasetTimeout as e:
    print(f"Still running after {e.timeout}s")

# Evaluate quality
ev = client.datasets.get_evaluation(dataset_id)
# ev.status: pending | running | succeeded | failed | skipped
# ev.quality.score_before, ev.quality.score_after, ev.quality.improvement_percent

# Download
url = client.datasets.download(dataset_id)  # presigned S3 URL

When to read more

Key Patterns

• Always estimate first on large datasets: estimate=True before real run
• Poll after HF/Kaggle import: ingestion is async; wait for row_count is not None
• Evaluation lags adaptation: run may show succeeded before eval finishes — poll get_evaluation separately
• Combine controls freely: brand_controls + recipe_specification + job_specification all compose on one datasets.run() call

Anti-Patterns to Avoid

• Running a real job without estimating first — on large datasets, always call with estimate=True and check estimated_credits_consumed before spending budget
• Reading results right after HF/Kaggle import — ingestion is async; wait until row_count is not None before running a job, or you'll process an empty dataset
• Treating run completion as evaluation completion — the run can show succeeded while the evaluation is still running; poll get_evaluation separately
• Retrying without an `idempotency_key` — naive retries on network errors create duplicate jobs; set job_specification.idempotency_key
• Missing the `prompt` key in `column_mapping` — it is required; jobs fail with confusing errors when the mapping is incomplete

When to Use / Not Use

Use this skill when:

• Generating synthetic training data or augmenting existing datasets for fine-tuning
• Building DPO preference pairs, reasoning traces, or grounded (hallucination-mitigated) training data
• Working with the Adaption Python SDK (pip install adaption) or the adaptionlabs.ai API

Do NOT use this skill when:

• The data only needs simple cleaning/formatting — a local pipeline is cheaper
• The work must stay fully on-premises with no external platform dependency
• You are not using Adaption's platform — use the generic dataset pipelines of the framework you're already on