SDK usage

Access your managed datasets with the Traceloop SDK

SDK Initialization

First, initialize the Traceloop SDK.

Python

from traceloop.sdk import Traceloop

# Initialize with dataset sync enabled
client = Traceloop.init()

Prerequisites: You need an API key set as the environment variable TRACELOOP_API_KEY. Generate one in Settings →

The SDK fetches your datasets from Traceloop servers. Changes made to a draft dataset version are immediately available in the UI.

Dataset Operations

Create a dataset

You can create datasets in different ways depending on your data source:

• Python: Import from CSV file or pandas DataFrame
• TypeScript: Import from CSV data or create manually

Python

import pandas as pd
from traceloop.sdk import Traceloop

client = Traceloop.init()

# Create dataset from CSV file
dataset_csv = client.datasets.from_csv(
    file_path="path/to/your/data.csv",
    slug="medical-questions",
    name="Medical Questions",
    description="Dataset with patients medical questions"
)

# Create dataset from pandas DataFrame
data = {
    "product": ["Laptop", "Mouse", "Keyboard", "Monitor"],
    "price": [999.99, 29.99, 79.99, 299.99],
    "in_stock": [True, True, False, True],
    "category": ["Electronics", "Accessories", "Accessories", "Electronics"],
}
df = pd.DataFrame(data)

# Create dataset from DataFrame
dataset_df = client.datasets.from_dataframe(
    df=df,
    slug="product-inventory",
    name="Product Inventory",
    description="Sample product inventory data",
)

Get a dataset

The dataset can be retrieved using its slug, which is available on the dataset page in the UI

Python

# Get dataset by slug - current draft version
my_dataset = client.datasets.get_by_slug("medical-questions")

# Get specific version as CSV
dataset_csv = client.datasets.get_version_csv(
    slug="medical-questions", 
    version="v2"
)

Adding a Column

Python

from traceloop.sdk.dataset import ColumnType

# Add a new column to your dataset
new_column = my_dataset.add_column(
    slug="confidence_score",
    name="Confidence Score", 
    col_type=ColumnType.NUMBER
)

Adding Rows

Map the column slug to its relevant value

Python

# Add new rows to your dataset
row_data = {
    "product": "TV Screen",
    "price": 1500.0,
    "in_stock": True,
    "category": "Electronics"
}

my_dataset.add_rows([row_data])

Dataset Versions

Publish a dataset

Dataset versions and history can be viewed in the UI. Versioning allows you to run the same evaluations and experiments across different datasets, making valuable comparisons possible.

Python

# Publish the current dataset state as a new version
published_version = my_dataset.publish()