Skip to main content

Examples

This page shows practical patterns for working with datasets using the Python SDK.

Basic listing and inspection

from basalt import Basalt

basalt = Basalt(api_key="your-api-key")

response = basalt.datasets.list_sync()

print(f"Total datasets: {response.total}")

for dataset in response.datasets:
    print(f"\nSlug: {dataset.slug}")
    print(f"  Name: {dataset.name}")
    print(f"  Description: {dataset.description}")
    print(f"  Rows: {dataset.num_rows}")
    print(f"  Columns: {len(dataset.columns)}")

basalt.shutdown()

Adding rows

Add new test cases to an existing dataset.
from basalt import Basalt

basalt = Basalt(api_key="your-api-key")

row = basalt.datasets.add_row_sync(
    slug="customer-support-qa",
    values={
        "question": "How do I reset my password?",
        "context": "User account management",
    },
    name="test-case-001",
    ideal_output='Click on "Forgot Password" on the login page.',
    metadata={"category": "account", "priority": "high"},
)

print(f"Added row: {row.name}")

basalt.shutdown()

Async row addition

import asyncio
from basalt import Basalt

async def add_test_case():
    basalt = Basalt(api_key="your-api-key")

    row = await basalt.datasets.add_row(
        slug="qa-dataset",
        values={"input": "test input", "category": "support"},
        name="async-test-001",
        ideal_output="Expected response here",
    )

    print(f"Added: {row.name}")

    basalt.shutdown()

asyncio.run(add_test_case())

Bulk row addition

from basalt import Basalt

def add_multiple_test_cases(slug: str, test_cases: list):
    """Add multiple test cases to a dataset"""
    basalt = Basalt(api_key="your-api-key")

    for i, test_case in enumerate(test_cases):
        try:
            row = basalt.datasets.add_row_sync(
                slug=slug,
                values=test_case["values"],
                name=test_case.get("name", f"test-{i:03d}"),
                ideal_output=test_case.get("ideal_output"),
                metadata=test_case.get("metadata", {}),
            )

            print(f"✓ Added: {row.name}")

        except Exception as e:
            print(f"✗ Failed to add test case {i}: {e}")

    basalt.shutdown()

## Adding rows with files

You can upload files (images, documents, etc.) as part of a dataset row using the `FileAttachment` class.

```python
from basalt import Basalt, FileAttachment
from pathlib import Path

basalt = Basalt(api_key="your-api-key")

image_path = Path("path/to/image.png")
secondary_image_path = Path("path/to/thumbnail.png")
third_image_path = Path("path/to/detail.png")

row = basalt.datasets.add_row_sync(
    slug="image-dataset",
    values={
        "description": "Test image upload",
        "image": FileAttachment(
            source=image_path,
            content_type="image/png",
        ),
        "thumbnail":  FileAttachment(
            source=secondary_image_path,
            content_type="image/png",
        ),
        "detail_view":  FileAttachment(
            source=third_image_path,
            content_type="image/png",
        ),
    },
    name="Image upload example",
    metadata={
        "upload_method": "file_path",
        "source_file": str(image_path),
    },
)

print(f"Added row with files: {row.name}")

basalt.shutdown()
basalt.shutdown()

## Use case: Prompt testing against a dataset

Evaluate a prompt against all rows in a dataset by treating row values as variables.

```python
from basalt import Basalt
import openai

def evaluate_prompt_against_dataset(prompt_slug: str, dataset_slug: str):
    """Test a prompt against a dataset"""
    basalt = Basalt(api_key="your-api-key")
    openai_client = openai.OpenAI()

    # Get dataset
    dataset = basalt.datasets.get_sync(slug=dataset_slug)

    results = []

    for row in dataset.rows:
        # Get prompt with row values as variables
        prompt = basalt.prompts.get_sync(
            slug=prompt_slug,
            tag="latest",
            variables=row.values,
        )

        # Generate response
        response = openai_client.chat.completions.create(
            model=prompt.model.model,
            messages=[{"role": "user", "content": prompt.text}],
        )

        actual_output = response.choices[0].message.content

        results.append(
            {
                "test_case": row.name,
                "input": row.values,
                "expected": row.ideal_output,
                "actual": actual_output,
                "match": actual_output.strip() == (row.ideal_output or "").strip(),
            }
        )

        print(f"Test {row.name}: {actual_output}")

    basalt.shutdown()
    return results
This pattern is a foundation for building more advanced evaluation pipelines and experiments on top of your datasets.