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.