Skip to main content

​
API Reference

This page documents the main Python SDK methods and objects for working with datasets.

​
Dataset methods

​
list_sync

basalt.datasets.list_sync()
Lists all datasets accessible to your API key. Returns: An object with:
  • total (int): Total number of datasets.
  • datasets (list): List of dataset metadata objects.
Each dataset object includes slug, name, description, num_rows, and columns.

​
list (async)

await basalt.datasets.list()
Async variant of list_sync, suitable for use in async applications. Returns: Same as list_sync: an object with total and datasets.

​
get_sync

basalt.datasets.get_sync(slug: str)
Retrieves a dataset by slug, including its rows and columns. Parameters:
  • slug (str, required): Dataset identifier.
Returns: A Dataset object (see below).

​
add_row_sync

basalt.datasets.add_row_sync(
    slug: str,
    values: dict,
    name: str | None = None,
    ideal_output: str | None = None,
    metadata: dict | None = None,
)
Adds a single row to a dataset. Parameters:
  • slug (str, required): Dataset identifier.
  • values (dict, required): Column name → value mapping. Values can be strings, numbers, or FileAttachment objects for file uploads.
  • name (str, optional): Row identifier; auto-generated if omitted.
  • ideal_output (str, optional): Expected output for evaluation.
  • metadata (dict, optional): Arbitrary metadata for this row.
Returns: A DatasetRow object representing the newly created row.

​
add_row (async)

await basalt.datasets.add_row(
    slug: str,
    values: dict,
    name: str | None = None,
    ideal_output: str | None = None,
    metadata: dict | None = None,
)
Async variant of add_row_sync, for use in async workflows. Returns: Same as add_row_sync: a DatasetRow object.

​
Dataset objects

​
Dataset

Represents a complete dataset, including schema and rows.
  • slug (str): Unique identifier.
  • name (str): Human-readable name.
  • description (str): Description of the dataset.
  • num_rows (int): Number of rows.
  • columns (list[DatasetColumn]): List of column definitions.
  • rows (list[DatasetRow]): List of rows in the dataset.

​
DatasetColumn

Describes a single column in the dataset schema.
  • name (str): Column name.
  • type (str): Data type (for example "string", "number").
  • description (str): Column description.

​
DatasetRow

Represents a single test case / row.
  • name (str): Row identifier.
  • values (dict): Column name → value mapping.
  • ideal_output (str | None): Expected output, when available.
  • metadata (dict | None): Additional metadata for this row.

​
FileAttachment

Used to upload files as part of a dataset row. 
from basalt import FileAttachment

attachment = FileAttachment(
    source=Path("path/to/file"),
    content_type="image/png"
)
  • source (Path | str): Path to the file to upload.
  • content_type (str): MIME type of the file (e.g., "image/png", "application/pdf").
Refer to the Python SDK documentation for lower-level details and additional helpers.