> ## Documentation Index
> Fetch the complete documentation index at: https://enrolla-nk-hub-guardrails.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK usage

> Access your managed datasets with the Traceloop SDK

## SDK Initialization

First, initialize the Traceloop SDK.

<CodeGroup>
  ```python Python theme={null}
  from traceloop.sdk import Traceloop

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

  ```js Typescript theme={null}
  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();
  ```
</CodeGroup>

<Note>
  **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`.
  [Generate one in Settings →](/settings/managing-api-keys)
</Note>

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

<CodeGroup>
  ```python Python theme={null}
  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",
  )
  ```

  ```js Typescript theme={null}
  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 });
  ```
</CodeGroup>

### Get a dataset

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

<CodeGroup>
  ```python Python theme={null}
  # 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"
  )
  ```

  ```js Typescript theme={null}
  // 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");

  ```
</CodeGroup>

### Adding a Column

<CodeGroup>
  ```python Python theme={null}
  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
  )
  ```

  ```js Typescript theme={null}
  // 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");
  ```
</CodeGroup>

### Adding Rows

Map the column slug to its relevant value

<CodeGroup>
  ```python Python theme={null}
  # 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])
  ```

  ```js Typescript theme={null}
  // 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);
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python Python theme={null}
  # Publish the current dataset state as a new version
  published_version = my_dataset.publish()
  ```

  ```js Typescript theme={null}
  // Publish dataset with version and description
  const publishedVersion = await myDataset.publish();
  ```
</CodeGroup>