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

import * as traceloop from "@traceloop/node-server-sdk";

// Initialize with comprehensive configuration
traceloop.initialize({
  appName: "your-app-name",
  apiKey: process.env.TRACELOOP_API_KEY,
  disableBatch: true,
  traceloopSyncEnabled: true,
});

// Wait for initialization to complete
await traceloop.waitForInitialization();

// Get the client instance for dataset operations
const client = traceloop.getClient();

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

const client = traceloop.getClient();

// Option 1: Create dataset manually
const myDataset = await client.datasets.create({
  name: "Medical Questions",
  slug: "medical-questions",
  description: "Dataset with patients medical questions"
});

// Option 2: Create and import from CSV data
const csvData = `user_id,prompt,response,model,satisfaction_score
user_001,"What is React?","React is a JavaScript library...","gpt-3.5-turbo",4
user_002,"Explain Docker","Docker is a containerization platform...","gpt-3.5-turbo",5`;

await myDataset.fromCSV(csvData, { hasHeader: true });

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

// Get dataset by slug - current draft version
const myDataset = await client.datasets.get("medical-questions");

// Get specific version as CSV
const datasetCsv = await client.datasets.getVersionCSV("medical-questions", "v1");

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
)

// Define schema by adding multiple columns
const columnsToAdd = [
  {
    name: "User ID",
    slug: "user-id",
    type: "string" as const,
    description: "Unique identifier for the user"
  },
  {
    name: "Satisfaction score",
    slug: "satisfaction-score",
    type: "number" as const,
    description: "User satisfaction rating (1-5)"
  }
];

await myDataset.addColumn(columnsToAdd);
console.log("Schema defined with multiple columns");

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

// Add individual rows to dataset
const userId = "user_001";
const prompt = "Explain machine learning in simple terms";
const startTime = Date.now();

const rowData = {
  user_id: userId,
  prompt: prompt,
  response: `This is the model response`,
  model: "gpt-3.5-turbo",
  satisfaction_score: 1,
};

await myDataset.addRow(rowData);

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

// Publish dataset with version and description
const publishedVersion = await myDataset.publish();