### Install Adaption Library

Source: https://docs.adaptionlabs.ai/api

Install the Adaption Python library using pip. This is the first step to interacting with the API programmatically.

```bash
pip install adaption
```

--------------------------------

### Example Download Response (JSON)

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/download

This is an example of the data you might receive when downloading a dataset.

```json
"Example data"
```

--------------------------------

### Install Adaption with aiohttp Support

Source: https://docs.adaptionlabs.ai/api/python

Install the Adaption Python library with aiohttp support for improved concurrency performance.

```bash
pip install adaption[aiohttp]
```

--------------------------------

### Start Adaption Run

Source: https://docs.adaptionlabs.ai/introduction/getting-started

Start an adaptation run on a dataset, mapping columns to expected roles. Use estimate=True first to preview costs.

```python
run = client.datasets.run(
    dataset_id,
    column_mapping={
        "prompt": "instruction",  # required — your prompt column
        "completion": "response",  # optional — completion column
        # "chat": "conversation",  # optional — chat column
        # "context": ["source", "ref"],  # optional — context columns
    },
)
print(run.run_id)
print(run.estimated_credits_consumed)
```

--------------------------------

### Full example: Ingest, run on subset, wait, and export

Source: https://docs.adaptionlabs.ai/guides/processing-large-datasets

This example demonstrates the full workflow: ingesting or reusing a dataset, waiting for it to be ready, running a job on a bounded number of rows, waiting for completion, and then exporting the results.

```python
import os
import time


from adaption import Adaption, DatasetTimeout


client = Adaption(api_key=os.environ["ADAPTION_API_KEY"])
dataset_id = os.environ.get("ADAPTION_DATASET_ID")


if not dataset_id:
    result = client.datasets.upload_file("large_training_data.csv")
    dataset_id = result.dataset_id
    while True:
        status = client.datasets.get_status(dataset_id)
        if status.row_count is not None:
            break
        time.sleep(2)


run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    job_specification={"max_rows": 1_000},
)
print(f"Run started (up to 1,000 rows): {run.run_id}")


try:
    final = client.datasets.wait_for_completion(dataset_id, timeout=3600)
    print(f"Finished: {final.status}")
    if final.error:
        raise RuntimeError(final.error.message)
except DatasetTimeout:
    print("Timed out — poll datasets.get or get_status in your environment")


url = client.datasets.download(dataset_id)
print(f"Download: {url}")
```

--------------------------------

### Full Example: Uploading Data, Running with Traces, and Downloading Results

Source: https://docs.adaptionlabs.ai/guides/reasoning-traces

This example demonstrates the complete workflow: uploading a training file, running a dataset with reasoning traces enabled, waiting for completion, and downloading the results. It includes error handling for timeouts and dataset errors.

```python
import os
import time


from adaption import Adaption, DatasetTimeout


client = Adaption(api_key=os.environ["ADAPTION_API_KEY"])
dataset_id = os.environ.get("ADAPTION_DATASET_ID")


if not dataset_id:
    result = client.datasets.upload_file("training_data.csv")
    dataset_id = result.dataset_id
    while True:
        status = client.datasets.get_status(dataset_id)
        if status.row_count is not None:
            break
        time.sleep(2)


run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    recipe_specification={"recipes": {"reasoning_traces": True}},
)
print(f"Run started: {run.run_id}, ~{run.estimated_credits_consumed} credits")


try:
    final = client.datasets.wait_for_completion(dataset_id, timeout=3600)
    print(f"Finished: {final.status}")
    if final.error:
        raise RuntimeError(final.error.message)
except DatasetTimeout:
    print("Timed out — check status manually")


url = client.datasets.download(dataset_id)
print(f"Download: {url}")

```

--------------------------------

### Full example: Fetching evaluation and dataset details

Source: https://docs.adaptionlabs.ai/guides/evaluating-dataset-quality

An example demonstrating how to fetch both the detailed evaluation results and the dataset record after a completed run. This provides a comprehensive view of the dataset's status and quality metrics.

```python
import os


from adaption import Adaption


client = Adaption(api_key=os.environ["ADAPTION_API_KEY"])
dataset_id = os.environ["ADAPTION_DATASET_ID"]


evaluation = client.datasets.get_evaluation(dataset_id)
print(f"Evaluation status: {evaluation.status}")


dataset = client.datasets.get(dataset_id)
print(f"Dataset status: {dataset.status}")
if dataset.evaluation_summary:
    print(f"Summary: {dataset.evaluation_summary.model_dump(exclude_none=True)}")
```

--------------------------------

### Full Example: Adapt Data with Hallucination Mitigation

Source: https://docs.adaptionlabs.ai/guides/mitigating-hallucinations

This example demonstrates the full workflow: uploading data (or reusing an existing dataset), waiting for it to be ready, adapting the data with hallucination mitigation enabled, waiting for the adaptation to complete, and then downloading the results. It also includes estimating credit consumption before running.

```python
import os
import time


from adaption import Adaption, DatasetTimeout


client = Adaption(api_key=os.environ["ADAPTION_API_KEY"])
dataset_id = os.environ.get("ADAPTION_DATASET_ID")


if not dataset_id:
    result = client.datasets.upload_file("training_data.csv")
    dataset_id = result.dataset_id
    while True:
        status = client.datasets.get_status(dataset_id)
        if status.row_count is not None:
            break
        time.sleep(2)


estimate = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    brand_controls={"hallucination_mitigation": True},
    estimate=True,
)
print(f"Estimated credits: {estimate.estimated_credits_consumed}")


run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    brand_controls={"hallucination_mitigation": True},
)
print(f"Run started: {run.run_id}")


try:
    final = client.datasets.wait_for_completion(dataset_id, timeout=3600)
    print(f"Finished: {final.status}")
    if final.error:
        raise RuntimeError(final.error.message)
except DatasetTimeout:
    print("Timed out — poll datasets.get or get_status in your environment")


url = client.datasets.download(dataset_id)
print(f"Download: {url}")

```

--------------------------------

### Initiate Upload Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/subresources/upload/methods/initiate

This is an example of the JSON response received after successfully initiating a dataset upload. It includes the `upload_url` for the next step of the upload process.

```json
{
  "upload_url": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."
}
```

--------------------------------

### End-to-End File Upload and Processing Example

Source: https://docs.adaptionlabs.ai/introduction/getting-started

This example demonstrates the complete workflow of uploading a file, waiting for its processing, initiating a run with column mapping, waiting for the run to complete, and finally downloading the processed data. It includes error handling for timeouts.

```python
import time


from adaption import Adaption, DatasetTimeout


client = Adaption(api_key="pt_live_...")


# 1. Upload
result = client.datasets.upload_file("training_data.csv")


# 2. Wait for file processing
while True:
    status = client.datasets.get_status(result.dataset_id)
    if status.row_count is not None:
        break
    time.sleep(2)


# 3. Adapt (start run)
run = client.datasets.run(
    result.dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
)
print(
    f"Run started: {run.run_id}, ~{run.estimated_minutes} min, "
    f"{run.estimated_credits_consumed} credits"
)


# 4. Wait for completion
try:
    final = client.datasets.wait_for_completion(result.dataset_id, timeout=1800)
    print(f"Finished: {final.status}")
except DatasetTimeout:
    print("Timed out — check status manually")


# 5. Download
url = client.datasets.download(result.dataset_id)
print(f"Download: {url}")

```

--------------------------------

### Start an augmentation run (or estimate cost)

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/run

Validates column mapping and recipe configuration, reserves credits, and starts the augmentation pipeline. Set estimate=true to validate and get a cost quote without starting a run.

```APIDOC
## datasets.run

### Description
Validates column mapping and recipe configuration, reserves credits, and starts the augmentation pipeline. Set estimate=true to validate and get a cost quote without starting a run.

### Method
POST

### Endpoint
/api/v1/datasets/{dataset_id}/run

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The ID of the dataset to run.

#### Query Parameters
- **estimate** (bool) - Optional - When true, validates the request and returns the estimated credit cost without starting a run.

#### Request Body
- **brand_controls** (Optional[BrandControls]) - Optional - Brand and quality controls for generated completions. Covers response length, content safety categories, web-search grounding, and a freeform blueprint system prompt.
- **blueprint** (Optional[str]) - Optional - Freeform brand/style instructions injected as a system prompt for every generated completion. Use this to enforce tone, language, persona, or any guideline that does not fit the structured length/safety/grounding controls.
- **hallucination_mitigation** (Optional[bool]) - Optional - Enable web-search grounding to reduce hallucinations in generated completions.
- **length** (Optional[Literal["minimal", "concise", "detailed", "extensive"]]) - Optional - Target response length. Controls verbosity of generated completions.
- **safety_categories** (Optional[SequenceNotStr[str]]) - Optional - Content safety categories to enforce. Completions violating any listed category are filtered from the output.
- **column_mapping** (Optional[ColumnMapping]) - Optional - Column role assignments for augmentation. Required for real runs, optional for estimate-only requests.
- **prompt** (str) - Required - Column to use as the prompt/instruction field
- **chat** (Optional[str]) - Optional - Column containing chat/conversation data (alternative to prompt+completion)
- **completion** (Optional[str]) - Optional - Column to use as the completion/response field
- **context** (Optional[SequenceNotStr[str]]) - Optional - Columns to include as context
- **job_specification** (Optional[JobSpecification]) - Optional - Job execution parameters
- **idempotency_key** (Optional[str]) - Optional - Client-generated idempotency key for safe retries. If a launch with the same key already exists, the original response is returned.
- **max_rows** (Optional[float]) - Optional - Maximum number of rows to process in this run
- **recipe_specification** (Optional[RecipeSpecification]) - Optional - Augmentation recipe configuration. Omitted recipes use backend defaults.
- **recipes** (Optional[RecipeSpecificationRecipes]) - Optional - Augmentation recipe toggles. Omitted recipes use backend defaults.
  - **deduplication** (Optional[bool]) - Optional - Remove near-duplicate rows
  - **prompt_rephrase** (Optional[bool]) - Optional - Rephrase prompts for variety and clarity
  - **reasoning_traces** (Optional[bool]) - Optional - Add reasoning traces (chain-of-thought) to completions
  - **version** (Optional[str]) - Optional - Recipe schema version. Allows recipe options to evolve across releases.

### Response
#### Success Response (200)
- **estimate** (bool) - Whether this was an estimate-only request (no run started)
- **estimated_credits_consumed** (float) - Estimated number of credits that will be consumed by this run
- **estimated_minutes** (float) - Estimated processing time in minutes
- **run_id** (Optional[str]) - Unique identifier for this pipeline run. Null for estimate-only requests.

### Response Example
```json
{
  "estimate": true,
  "estimatedCreditsConsumed": 0,
  "estimatedMinutes": 0,
  "run_id": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890"
}
```
```

--------------------------------

### Dataset Creation Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/create

This is an example of a successful response when creating a dataset. It includes the dataset ID, its current status, and upload instructions if the source type was 'file'.

```json
{
  "dataset_id": "dataset_id",
  "status": "status",
  "upload_instructions": {
    "method": "PUT",
    "s3_key": "s3_key",
    "url": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."
  }
}
```

--------------------------------

### Nested Parameters Example

Source: https://docs.adaptionlabs.ai/api/python

Example demonstrating the use of nested parameters, which are represented as dictionaries.

```APIDOC
## Nested Parameters Example

### Description
Shows how to pass nested parameters, which are typed as `TypedDict`, to an API method.

### Method
`client.datasets.run(dataset_id: str, brand_controls: dict)`

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The ID of the dataset.
#### Request Body
- **brand_controls** (dict) - Required - A dictionary representing brand controls.

### Request Example
```python
from adaption import Adaption

client = Adaption()

response = client.datasets.run(
    dataset_id="dataset_id",
    brand_controls={},
)
print(response.brand_controls)
```

### Response
#### Success Response (200)
- **brand_controls** (dict) - The brand controls returned in the response.
```

--------------------------------

### Running a Dataset with Nested Parameters

Source: https://docs.adaptionlabs.ai/api/python

Example of calling the `run` method on a dataset, passing nested parameters as a dictionary. The `brand_controls` parameter is shown as an example.

```python
from adaption import Adaption

client = Adaption()

response = client.datasets.run(
    dataset_id="dataset_id",
    brand_controls={},
)
print(response.brand_controls)
```

--------------------------------

### Dataset Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/get

This is an example of the JSON structure returned when a dataset is successfully retrieved.

```json
{
  "configured_column_mapping": {
    "chat": "chat",
    "completion": "completion",
    "context": [
      "string"
    ],
    "prompt": "prompt"
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": "dataset_id",
  "error": {
    "message": "message"
  },
  "evaluation_summary": {
    "grade_after": "grade_after",
    "grade_before": "grade_before",
    "improvement_percent": 0,
    "score_after": 0,
    "score_before": 0
  },
  "name": "name",
  "progress": {
    "percent": 0,
    "processed_rows": 0,
    "total_rows": 0
  },
  "row_count": 0,
  "run_id": "run_id",
  "status": "pending",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```

--------------------------------

### Start Augmentation Run (cURL)

Source: https://docs.adaptionlabs.ai/api/resources/datasets/methods/run

Use this cURL command to start an augmentation run or estimate its cost. Replace $DATASET_ID and $ADAPTION_API_KEY with your actual values. Set estimate=true in the request body for cost estimation.

```bash
curl https://api.adaptionlabs.ai/api/v1/datasets/$DATASET_ID/run \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{}'
```

--------------------------------

### Dataset Publish Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/publish

This is an example of the response received after successfully queuing a dataset for publishing. It includes a unique publish ID, the job status, and an optional message.

```json
{
  "publish_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "message"
}
```

--------------------------------

### Asynchronous Client Usage

Source: https://docs.adaptionlabs.ai/api/python

Example of how to instantiate and use the asynchronous Adaption client to retrieve a dataset.

```APIDOC
## Asynchronous Client Usage

### Description
Instantiate the asynchronous `AsyncAdaption` client and use `await` to fetch a specific dataset by its ID.

### Method
`await client.datasets.get(dataset_id: str)`

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.

### Request Example
```python
import os
import asyncio
from adaption import AsyncAdaption

client = AsyncAdaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)

async def main() -> None:
  dataset = await client.datasets.get(
      "REPLACE_ME",
  )
  print(dataset.dataset_id)

asyncio.run(main())
```

### Response
#### Success Response (200)
- **dataset_id** (str) - The unique identifier of the dataset.
```

--------------------------------

### Determine installed version

Source: https://docs.adaptionlabs.ai/api/python

Check the installed version of the adaption package at runtime.

```python
import adaption
print(adaption.__version__)
```

--------------------------------

### Complete Upload Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/subresources/upload/methods/complete

This is an example of a successful response when completing a dataset upload. It returns the unique identifier for the created dataset.

```json
{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### API Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/subresources/upload/methods/complete_by_id

This is an example of a successful response when completing a file upload. It includes the dataset ID and its current processing status.

```json
{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}
```

--------------------------------

### Async Client with aiohttp Backend

Source: https://docs.adaptionlabs.ai/api/python

Instantiate the asynchronous Adaption client using aiohttp as the HTTP backend. This requires installing `aiohttp` and using `DefaultAioHttpClient()`.

```python
import os
import asyncio
from adaption import DefaultAioHttpClient
from adaption import AsyncAdaption

async def main() -> None:
  async with AsyncAdaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
    http_client=DefaultAioHttpClient(),
) as client:
    dataset = await client.datasets.get(
        "REPLACE_ME",
    )
    print(dataset.dataset_id)

asyncio.run(main())
```

--------------------------------

### Synchronous Client Usage

Source: https://docs.adaptionlabs.ai/api/python

Example of how to instantiate and use the synchronous Adaption client to retrieve a dataset.

```APIDOC
## Synchronous Client Usage

### Description
Instantiate the synchronous `Adaption` client and use it to fetch a specific dataset by its ID.

### Method
`client.datasets.get(dataset_id: str)`

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.

### Request Example
```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)

dataset = client.datasets.get(
    "REPLACE_ME",
)
print(dataset.dataset_id)
```

### Response
#### Success Response (200)
- **dataset_id** (str) - The unique identifier of the dataset.
```

--------------------------------

### Asynchronous Client with aiohttp

Source: https://docs.adaptionlabs.ai/api/python

Example of using the asynchronous Adaption client with aiohttp as the HTTP backend.

```APIDOC
## Asynchronous Client with aiohttp

### Description
Instantiate the asynchronous `AsyncAdaption` client using `DefaultAioHttpClient` for improved concurrency performance.

### Method
`async with AsyncAdaption(http_client=DefaultAioHttpClient()) as client:`
  `await client.datasets.get(dataset_id: str)`

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.

### Request Example
```python
import os
import asyncio
from adaption import DefaultAioHttpClient
from adaption import AsyncAdaption

async def main() -> None:
  async with AsyncAdaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
    http_client=DefaultAioHttpClient(),
) as client:
    dataset = await client.datasets.get(
        "REPLACE_ME",
    )
    print(dataset.dataset_id)

asyncio.run(main())
```

### Response
#### Success Response (200)
- **dataset_id** (str) - The unique identifier of the dataset.
```

--------------------------------

### Start an Augmentation Run

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/run

Initiates a dataset augmentation run. Ensure the ADAPTION_API_KEY environment variable is set. The `dataset_id` is required.

```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.run(
    dataset_id="dataset_id",
)
print(response.run_id)
```

--------------------------------

### Dataset Status Response Example

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/get_status

This is an example of a successful response when retrieving the status of a dataset. It includes dataset ID, error details (if any), progress information, row count, and the current status.

```json
{
  "dataset_id": "dataset_id",
  "error": {
    "message": "message"
  },
  "progress": {
    "percent": 0,
    "processed_rows": 0,
    "total_rows": 0
  },
  "row_count": 0,
  "status": "pending"
}
```

--------------------------------

### Asynchronous Operations with Adaption AI

Source: https://docs.adaptionlabs.ai/introduction/getting-started

This example shows how to use the asynchronous client for file uploads, waiting for completion, and listing datasets. It utilizes `async for` for iterating over datasets.

```python
from adaption import AsyncAdaption


client = AsyncAdaption(api_key="pt_live_...")


result = await client.datasets.upload_file("data.csv")
status = await client.datasets.wait_for_completion(result.dataset_id)
async for dataset in client.datasets.list():
    print(dataset.dataset_id)

```

--------------------------------

### Start augmentation run

Source: https://docs.adaptionlabs.ai/api

Initiates an augmentation run for a dataset or estimates the cost.

```APIDOC
## POST /api/v1/datasets/{dataset_id}/run

### Description
Starts an augmentation run for a dataset or estimates the cost.

### Method
POST

### Endpoint
/api/v1/datasets/{dataset_id}/run

#### Path Parameters
- **dataset_id** (string) - Required - The unique identifier of the dataset.
```

--------------------------------

### Asynchronous Pagination

Source: https://docs.adaptionlabs.ai/api/python

Example of using the auto-paginating iterator for listing datasets asynchronously.

```APIDOC
## Asynchronous Pagination

### Description
Iterate through all datasets asynchronously using the auto-paginating iterator provided by `client.datasets.list()`.

### Method
`async for dataset in client.datasets.list():`

### Response
#### Success Response (200)
- **datasets** (list) - A list of dataset objects.

### Request Example
```python
import asyncio
from adaption import AsyncAdaption

client = AsyncAdaption()

async def main() -> None:
    all_datasets = []
    # Iterate through items across all pages, issuing requests as needed.
    async for dataset in client.datasets.list():
        all_datasets.append(dataset)
    print(all_datasets)

asyncio.run(main())
```
```

--------------------------------

### Manual Pagination Control

Source: https://docs.adaptionlabs.ai/api/python

Demonstrates granular control over pagination using `.has_next_page()`, `.next_page_info()`, and `.get_next_page()` methods. This example shows fetching the next page and its contents.

```python
first_page = await client.datasets.list()
if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.datasets)}")

# Remove `await` for non-async usage.
```

--------------------------------

### Manual Pagination Control

Source: https://docs.adaptionlabs.ai/api/python

Example of using methods like `.has_next_page()`, `.next_page_info()`, and `.get_next_page()` for granular control over pagination.

```APIDOC
## Manual Pagination Control

### Description
Demonstrates how to manually control pagination by checking for the next page, retrieving its information, and fetching it.

### Methods
- `first_page.has_next_page()`: Returns `True` if there is a next page.
- `first_page.next_page_info()`: Returns information needed to fetch the next page.
- `await first_page.get_next_page()`: Fetches the next page of results.

### Request Example
```python
# Assuming 'client' is an instance of Adaption or AsyncAdaption
first_page = await client.datasets.list() # Use `await` for async, omit for sync

if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page() # Use `await` for async, omit for sync
    print(f"number of items we just fetched: {len(next_page.datasets)}")

# Example of working directly with returned data:
print(f"next page cursor: {first_page.next_cursor}") # => "next page cursor: ..."
for dataset in first_page.datasets:
    print(dataset.dataset_id)
```
```

--------------------------------

### Synchronous Pagination

Source: https://docs.adaptionlabs.ai/api/python

Example of using the auto-paginating iterator for listing datasets synchronously.

```APIDOC
## Synchronous Pagination

### Description
Iterate through all datasets using the auto-paginating iterator provided by `client.datasets.list()`.

### Method
`client.datasets.list()`

### Response
#### Success Response (200)
- **datasets** (list) - A list of dataset objects.

### Request Example
```python
from adaption import Adaption

client = Adaption()

all_datasets = []
# Automatically fetches more pages as needed.
for dataset in client.datasets.list():
    # Do something with dataset here
    all_datasets.append(dataset)
print(all_datasets)
```
```

--------------------------------

### Run Dataset Augmentation

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets

Starts an augmentation run for a dataset or estimates the cost.

```APIDOC
## Run Dataset Augmentation

### Description
Starts an augmentation run for a dataset or estimates the cost.

### Method
POST

### Endpoint
/api/v1/datasets/{dataset_id}/run

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.
#### Request Body
- **kwargs** (DatasetRunParams) - Required - Parameters for running the augmentation.
```

--------------------------------

### Example API Response for Listing Datasets

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/list

This JSON structure represents a successful response when listing datasets, including dataset details and a cursor for pagination.

```json
{
  "datasets": [
    {
      "created_at": "2019-12-27T18:11:19.117Z",
      "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "description": "description",
      "name": "My training data",
      "row_count": 1000
    }
  ],
  "next_cursor": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Sample Evaluation Results Response

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/get_evaluation

This is an example of a successful response when retrieving dataset evaluation results. It shows structured quality metrics and the status of the evaluation pipeline.

```json
{
  "dataset_id": "dataset_id",
  "quality": {
    "grade_after": "A",
    "grade_before": "C",
    "improvement_percent": 37.1,
    "percentile_after": 92.3,
    "score_after": 8.5,
    "score_before": 6.2
  },
  "raw_results": {
    "foo": "bar"
  },
  "status": "succeeded"
}
```

--------------------------------

### Combine max_rows with estimate=True

Source: https://docs.adaptionlabs.ai/guides/processing-large-datasets

Get a cost and duration quote for a subset of rows by calling `datasets.run` with `estimate=True` before the actual run.

```python
quote = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    job_specification={"max_rows": 500},
    estimate=True,
)
print(f"Subset estimate: {quote.estimated_credits_consumed} credits")
```

```python
run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    job_specification={"max_rows": 500},
)
```

--------------------------------

### Import Data from Hugging Face

Source: https://docs.adaptionlabs.ai/introduction/getting-started

Import data from a Hugging Face dataset URL. The import runs asynchronously; poll status or use wait_for_completion before starting an adaptation run.

```python
response = client.datasets.create_from_huggingface(
    url="https://huggingface.co/datasets/org/repo",
    files=["train.csv"],
)
print(response.dataset_id)
```

--------------------------------

### Wait for Dataset or Run Completion

Source: https://docs.adaptionlabs.ai/resources/faq

Use `datasets.wait_for_completion` with an optional timeout for long jobs, or handle `DatasetTimeout` exceptions. Manual polling via `get_status` or `get` is also an option.

```python
datasets.wait_for_completion(dataset_id, timeout=...)
```

--------------------------------

### Get Dataset Status in Python

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/get_status

Use the Adaption client to fetch the processing status of a dataset by providing its ID. Ensure your API key is set as an environment variable.

```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.get_status(
    "dataset_id",
)
print(response.dataset_id)
```

--------------------------------

### Estimate Augmentation Run Cost

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/run

Estimates the cost of an augmentation run without starting it. Set `estimate=true` to get a cost quote. The response includes estimated credits and minutes.

```json
{
  "estimate": true,
  "estimatedCreditsConsumed": 0,
  "estimatedMinutes": 0,
  "run_id": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890"
}
```

--------------------------------

### Quick view on dataset evaluation summary

Source: https://docs.adaptionlabs.ai/guides/evaluating-dataset-quality

Get a compact evaluation summary directly from the dataset record. Useful for dashboards or listing datasets without a second request. This summary is populated when available.

```python
dataset = client.datasets.get(dataset_id)
if dataset.evaluation_summary:
    print(dataset.evaluation_summary.score_after, dataset.evaluation_summary.improvement_percent)
```

--------------------------------

### Estimate Dataset Run Credits and Duration

Source: https://docs.adaptionlabs.ai/resources/faq

Use `estimate=True` to validate a request and get estimated credits and duration without starting a full run. This is useful for budgeting jobs and gating CI.

```python
datasets.run(..., estimate=True)
```

--------------------------------

### Full script with brand controls

Source: https://docs.adaptionlabs.ai/guides/safety-and-length-constraints

This script demonstrates setting up the Adaption client, uploading a dataset if needed, running a dataset with combined brand controls, and waiting for completion.

```python
import os
import time


from adaption import Adaption, DatasetTimeout


client = Adaption(api_key=os.environ["ADAPTION_API_KEY"])
dataset_id = os.environ.get("ADAPTION_DATASET_ID")


if not dataset_id:
    result = client.datasets.upload_file("training_data.csv")
    dataset_id = result.dataset_id
    while True:
        status = client.datasets.get_status(dataset_id)
        if status.row_count is not None:
            break
        time.sleep(2)


run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    brand_controls={
        "length": "concise",
        "safety_categories": ["harassment", "hate"],
        "blueprint": "Answer in British English with a warm, concise tone.",
    },
)
print(f"Run started: {run.run_id}")


try:
    final = client.datasets.wait_for_completion(dataset_id, timeout=3600)
    print(f"Finished: {final.status}")
    if final.error:
        raise RuntimeError(final.error.message)
except DatasetTimeout:
    print("Timed out")


url = client.datasets.download(dataset_id)
print(f"Download: {url}")

```

--------------------------------

### Initialize Adaption Client with API Key (Python)

Source: https://docs.adaptionlabs.ai/introduction/create-api-keys

Pass the API key explicitly when initializing the Adaption client. Ensure the key is kept secure.

```python
from adaption import Adaption


client = Adaption(api_key="pt_live_...")
```

--------------------------------

### Get Dataset by ID

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/get

Fetches a dataset by its ID using the `datasets.get` method. This method corresponds to a GET request to the `/api/v1/datasets/{dataset_id}` endpoint.

```APIDOC
## GET /api/v1/datasets/{dataset_id}

### Description
Get a dataset by ID.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - Unique dataset identifier

### Response
#### Success Response (200)
- **configured_column_mapping** (Optional[ConfiguredColumnMapping]) - User-configured column mapping. Null if not yet configured.
- **chat** (Optional[str])
- **completion** (Optional[str])
- **context** (List[str])
- **prompt** (Optional[str])
- **created_at** (datetime) - Timestamp when the dataset was created
- **dataset_id** (str) - Unique dataset identifier
- **error** (Optional[Error]) - Error details if the dataset failed. Null otherwise.
  - **message** (str) - Error message
- **evaluation_summary** (Optional[EvaluationSummary]) - Compact evaluation summary. Null if evaluation has not completed.
  - **grade_after** (Optional[str]) - Letter grade (A-E) after augmentation
  - **grade_before** (Optional[str]) - Letter grade (A-E) before augmentation
  - **improvement_percent** (Optional[float]) - Relative improvement percentage
  - **score_after** (Optional[float]) - Quality score after augmentation
  - **score_before** (Optional[float]) - Quality score before augmentation
- **name** (Optional[str]) - Human-readable name for the dataset
- **progress** (Optional[Progress]) - Processing progress. Null when no run is active.
  - **percent** (Optional[int]) - Progress percentage (0-100)
  - **processed_rows** (Optional[int]) - Number of rows processed so far
  - **total_rows** (Optional[int]) - Total rows to process (samples_to_process or row_count)
- **row_count** (Optional[int]) - Total number of rows in the dataset
- **run_id** (Optional[str]) - ID of the currently active run
- **status** (Literal["pending", "running", "succeeded", "failed"]) - Lifecycle status: pending, running, succeeded, or failed
- **updated_at** (datetime) - Timestamp of the last update

### Response Example
```json
{
  "configured_column_mapping": {
    "chat": "chat",
    "completion": "completion",
    "context": [
      "string"
    ],
    "prompt": "prompt"
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": "dataset_id",
  "error": {
    "message": "message"
  },
  "evaluation_summary": {
    "grade_after": "grade_after",
    "grade_before": "grade_before",
    "improvement_percent": 0,
    "score_after": 0,
    "score_before": 0
  },
  "name": "name",
  "progress": {
    "percent": 0,
    "processed_rows": 0,
    "total_rows": 0
  },
  "row_count": 0,
  "run_id": "run_id",
  "status": "pending",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```
```

--------------------------------

### Initiate Dataset Upload - Python

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/subresources/upload/methods/initiate

Use this snippet to initiate a dataset upload. Ensure you have your ADAPTION_API_KEY set as an environment variable. The response contains a `upload_url` which you should use for the actual file upload.

```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.upload.initiate(
    file_format="csv",
    name="my-training-data",
)
print(response.upload_url)
```

--------------------------------

### Initialize Adaption Client

Source: https://docs.adaptionlabs.ai/introduction/getting-started

Initialize the Adaption client with your API key. Alternatively, set the ADAPTION_API_KEY environment variable.

```python
from adaption import Adaption


client = Adaption(api_key="pt_live_...")
# Or set the ADAPTION_API_KEY environment variable and omit the argument
```

--------------------------------

### Initialize Adaption Client using Environment Variable (Python)

Source: https://docs.adaptionlabs.ai/introduction/create-api-keys

Construct the Adaption client without arguments to automatically read the ADAPTION_API_KEY environment variable. This simplifies authentication for scripts and applications.

```python
from adaption import Adaption


client = Adaption()  # reads ADAPTION_API_KEY
```

--------------------------------

### List Datasets in Python

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/list

Initializes the Adaption client and calls the datasets.list method to fetch the first page of datasets. Accesses and prints the dataset_id of the first dataset in the response.

```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
page = client.datasets.list()
page = page.datasets[0]
print(page.dataset_id)
```

--------------------------------

### Apply Blueprint for Global Preferences in SDK

Source: https://docs.adaptionlabs.ai/guides/applying-preferences

Inject a freeform string as a system prompt for qualitative preferences like tone, persona, or language that apply to the whole run. This is configured within brand_controls.

```python
run = client.datasets.run(
    dataset_id,
    column_mapping={"prompt": "instruction", "completion": "response"},
    brand_controls={
        "blueprint": (
            "You are a customer-success assistant for Acme. "
            "Answer in British English, stay warm but concise, "
            "and never recommend third-party tools."
        ),
    },
)
```

--------------------------------

### Get Dataset Evaluation

Source: https://docs.adaptionlabs.ai/api/resources/datasets

Retrieve the evaluation results for a dataset.

```APIDOC
## GET /api/v1/datasets/{dataset_id}/evaluation

### Description
Get evaluation results for a dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/evaluation

### Parameters
#### Path Parameters
- **dataset_id** (string) - Required - Unique dataset identifier
```

--------------------------------

### Get evaluation results

Source: https://docs.adaptionlabs.ai/api

Retrieves the evaluation results for a specified dataset.

```APIDOC
## GET /api/v1/datasets/{dataset_id}/evaluation

### Description
Gets the evaluation results for a dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/evaluation

#### Path Parameters
- **dataset_id** (string) - Required - The unique identifier of the dataset.
```

--------------------------------

### Get Dataset Status

Source: https://docs.adaptionlabs.ai/api/resources/datasets

Check the processing status of a specific dataset.

```APIDOC
## GET /api/v1/datasets/{dataset_id}/status

### Description
Get the processing status of a dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/status

### Parameters
#### Path Parameters
- **dataset_id** (string) - Required - Unique dataset identifier
```

--------------------------------

### Get Dataset Evaluation Results

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets

Retrieves the evaluation results for a dataset.

```APIDOC
## Get Dataset Evaluation Results

### Description
Retrieves the evaluation results for a dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/evaluation

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.
```

--------------------------------

### Request Reasoning Traces in Completions

Source: https://docs.adaptionlabs.ai/resources/faq

Include `recipe_specification={\"recipes\": {\"reasoning_traces\": True}}` to obtain adapted completions that contain explicit reasoning, beneficial for auditing and training.

```python
recipe_specification={\"recipes\": {\"reasoning_traces\": True}}
```

--------------------------------

### Create Dataset

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/create

This method allows you to create a dataset from different sources. For file uploads, it provides upload instructions. For HuggingFace and Kaggle, it initiates an asynchronous import process.

```APIDOC
## POST /api/v1/datasets

### Description
Unified ingest endpoint. Discriminated by source.type: "file" returns upload instructions for a presigned S3 PUT, "huggingface" and "kaggle" start an async import.

### Method
POST

### Endpoint
/api/v1/datasets

### Parameters
#### Request Body
- **source** (Source) - Required - Dataset source configuration. Discriminated by `type`: file, huggingface, or kaggle.
  - **file_format** (Literal["csv", "json", "jsonl", "parquet"]) - Required - Format of the file being uploaded
  - **name** (str) - Required - Human-readable name for the dataset
  - **type** (Literal["file"]) - Required - Source type
  - **files** (SequenceNotStr[str]) - Required - File paths to download from the repository
  - **type** (Literal["huggingface"]) - Required - Source type
  - **url** (str) - Required - HuggingFace dataset repository URL
  - **files** (SequenceNotStr[str]) - Required - File paths to download from the dataset
  - **type** (Literal["kaggle"]) - Required - Source type
  - **url** (str) - Required - Kaggle dataset URL

### Response
#### Success Response (200)
- **dataset_id** (str) - ID of the newly created dataset
- **status** (str) - Current dataset status
- **upload_instructions** (Optional[UploadInstructions]) - Upload instructions for file sources. PUT your file to the provided URL.
  - **method** (str) - HTTP method to use
  - **s3_key** (str) - S3 object key — pass this back in the complete request if needed for verification
  - **url** (str) - Pre-signed URL for uploading the file

### Request Example
```json
{
  "source": {
    "file_format": "csv",
    "name": "my-training-data",
    "type": "file"
  }
}
```

### Response Example
```json
{
  "dataset_id": "dataset_id",
  "status": "status",
  "upload_instructions": {
    "method": "PUT",
    "s3_key": "s3_key",
    "url": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."
  }
}
```
```

--------------------------------

### Create Dataset from File Upload (Python)

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets/methods/create

Use this snippet to create a new dataset by uploading a file. Specify the file format, dataset name, and source type as 'file'. The response will include upload instructions for a presigned S3 PUT URL.

```python
import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
dataset = client.datasets.create(
    source={
        "file_format": "csv",
        "name": "my-training-data",
        "type": "file",
    },
)
print(dataset.dataset_id)
```

--------------------------------

### List Datasets (cURL)

Source: https://docs.adaptionlabs.ai/api/resources/datasets/methods/list

Use this cURL command to list datasets. Ensure you replace $ADAPTION_API_KEY with your actual API key.

```bash
curl https://api.adaptionlabs.ai/api/v1/datasets \
    -H "Authorization: Bearer $ADAPTION_API_KEY"
```

--------------------------------

### Initiate Dataset Upload Request

Source: https://docs.adaptionlabs.ai/api/resources/datasets/subresources/upload/methods/initiate

Use this cURL command to send a POST request to initiate a dataset upload. Ensure you replace `$ADAPTION_API_KEY` with your actual API key and adjust the JSON body for your specific file format and dataset name.

```bash
curl https://api.adaptionlabs.ai/api/v1/datasets/upload/initiate \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{ \
          "file_format": "csv", \
          "name": "my-training-data" \
        }'
```

--------------------------------

### Get Dataset Status

Source: https://docs.adaptionlabs.ai/api/resources/datasets/methods/get_status

Retrieves the processing status of a dataset using its ID.

```APIDOC
## GET /api/v1/datasets/{dataset_id}/status

### Description
Get the processing status of a dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/status

### Parameters
#### Path Parameters
- **dataset_id** (string) - Required - The ID of the dataset.

#### Returns
- **dataset_id** (string) - Dataset ID.
- **error** (object) - Error details if the dataset failed. Null otherwise.
  - **message** (string) - Error message.
- **progress** (object) - Processing progress. Null when no run is active.
  - **percent** (number) - Progress percentage (0-100).
  - **processed_rows** (number) - Number of rows processed so far.
  - **total_rows** (number) - Total rows to process (samples_to_process or row_count).
- **row_count** (number) - Number of rows in the dataset.
- **status** (string) - Current processing status. One of the following: "pending", "running", "succeeded", "failed".

### Request Example
```curl
https://api.adaptionlabs.ai/api/v1/datasets/$DATASET_ID/status \
    -H "Authorization: Bearer $ADAPTION_API_KEY"
```

### Response Example (200)
```json
{
  "dataset_id": "dataset_id",
  "error": {
    "message": "message"
  },
  "progress": {
    "percent": 0,
    "processed_rows": 0,
    "total_rows": 0
  },
  "row_count": 0,
  "status": "pending"
}
```
```

--------------------------------

### Get Dataset Processing Status

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets

Checks the processing status of a given dataset.

```APIDOC
## Get Dataset Processing Status

### Description
Checks the processing status of a given dataset.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}/status

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.
```

--------------------------------

### Enable Logging in Python

Source: https://docs.adaptionlabs.ai/api/python

Enable library logging by setting the ADAPTION_LOG environment variable to 'info' or 'debug'.

```bash
$ export ADAPTION_LOG=info
```

--------------------------------

### Get Dataset by ID

Source: https://docs.adaptionlabs.ai/api/python/resources/datasets

Retrieves a specific dataset using its unique identifier.

```APIDOC
## Get Dataset by ID

### Description
Retrieves a specific dataset using its unique identifier.

### Method
GET

### Endpoint
/api/v1/datasets/{dataset_id}

### Parameters
#### Path Parameters
- **dataset_id** (str) - Required - The unique identifier of the dataset.
```