Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getbasalt.ai/llms.txt

Use this file to discover all available pages before exploring further.

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")

datasets = basalt.datasets.list_sync()

print(f"Total datasets: {len(datasets)}")

for dataset in 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.
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()

Use case: Prompt testing against a dataset

Evaluate a prompt against all rows in a dataset by treating row values as variables.
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.