Dataset Management API

/**
 * Create a new dataset
 * @param name - Dataset name (required)
 * @param options - Dataset creation options
 * @returns Promise resolving to created dataset
 */
createDataset(
  name: string,
  options?: {
    /** Description */
    description?: string;
    /** Data type: "kv" | "llm" | "chat" */
    dataType?: DataType;
    /** Input keys schema */
    inputsSchema?: Record<string, any>;
    /** Output keys schema */
    outputsSchema?: Record<string, any>;
    /** Metadata */
    metadata?: Record<string, any>;
  }
): Promise<Dataset>;

interface Dataset {
  /** Dataset ID */
  id: string;
  /** Dataset name */
  name: string;
  /** Description */
  description?: string;
  /** Data type */
  data_type?: DataType;
  /** Tenant ID */
  tenant_id: string;
  /** Creation timestamp */
  created_at: string;
  /** Example count */
  example_count?: number;
}

import { Client } from "langsmith";

const client = new Client();

const dataset = await client.createDataset(
  "chatbot-evaluation-v1",
  {
    description: "QA pairs for chatbot",
    dataType: "chat",
    metadata: { version: "1.0" }
  }
);

/**
 * Read dataset details
 * @param params - Dataset identifier
 * @returns Promise resolving to dataset
 */
readDataset(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<Dataset>;

// Read by name
const dataset = await client.readDataset({
  datasetName: "chatbot-evaluation-v1"
});

// Read by ID
const dataset = await client.readDataset({
  datasetId: "550e8400-e29b-41d4-a716-446655440000"
});

/**
 * List datasets
 * @param params - List parameters
 * @returns Promise resolving to array of datasets
 */
listDatasets(params?: ListDatasetsParams): Promise<Dataset[]>;

interface ListDatasetsParams {
  /** Limit results */
  limit?: number;
  /** Offset for pagination */
  offset?: number;
  /** Filter by data type */
  dataType?: DataType;
}

const datasets = await client.listDatasets({ limit: 50 });

for (const dataset of datasets) {
  console.log(dataset.name, dataset.example_count);
}

/**
 * Update dataset details
 * NOTE: Metadata cannot be updated after creation. Only name and description can be modified.
 * @param props - Dataset identifier and updates
 * @returns Promise resolving to updated dataset
 */
updateDataset(props: {
  datasetId?: string;
  datasetName?: string;
  name?: string;
  description?: string;
}): Promise<Dataset>;

await client.updateDataset({
  datasetName: "chatbot-evaluation-v1",
  description: "Updated description"
});

// Note: Metadata is immutable and can only be set during creation
// This will NOT work:
// await client.updateDataset({
//   datasetName: "chatbot-evaluation-v1",
//   metadata: { version: "2.0" }  // NOT SUPPORTED
// });

/**
 * Delete a dataset
 * @param params - Dataset identifier
 * @returns Promise resolving when deletion completes
 */
deleteDataset(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<void>;

await client.deleteDataset({
  datasetName: "old-dataset"
});

/**
 * Check if dataset exists
 * @param params - Dataset identifier
 * @returns Promise resolving to boolean
 */
hasDataset(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<boolean>;

/**
 * Update dataset tags
 * @param params - Dataset and tag update parameters
 * @returns Promise resolving to updated dataset
 */
updateDatasetTag(params: {
  datasetId?: string;
  datasetName?: string;
  tag: string;
}): Promise<Dataset>;

// Update dataset tag
await client.updateDatasetTag({
  datasetName: "qa-dataset",
  tag: "production"
});

// Tag with dataset ID
await client.updateDatasetTag({
  datasetId: "dataset-123",
  tag: "v1.0.0"
});

const exists = await client.hasDataset({
  datasetName: "my-dataset"
});

if (!exists) {
  await client.createDataset({
    datasetName: "my-dataset"
  });
}

/**
 * Share a dataset publicly
 * @param params - Share parameters
 * @returns Dataset share schema with share token
 */
shareDataset(params: ShareDatasetParams): Promise<DatasetShareSchema>;

interface ShareDatasetParams {
  /** Dataset ID to share */
  datasetId: string;
}

/**
 * Unshare a dataset
 * @param params - Unshare parameters
 */
unshareDataset(params: UnshareDatasetParams): Promise<void>;

interface UnshareDatasetParams {
  /** Dataset ID to unshare */
  datasetId: string;
}

/**
 * Read a shared dataset using share token
 * @param shareToken - Share token string
 * @returns Dataset object
 */
readSharedDataset(shareToken: string): Promise<Dataset>;

/**
 * Read schema information from a shared dataset
 * @param shareToken - Share token string
 * @returns Dataset schema
 */
readDatasetSharedSchema(shareToken: string): Promise<{
  inputs_schema?: Record<string, any>;
  outputs_schema?: Record<string, any>;
}>;

/**
 * List examples from a shared dataset
 * @param shareToken - Share token string
 * @param params - Optional list parameters
 * @returns Async iterable of examples
 */
listSharedExamples(
  shareToken: string,
  params?: { limit?: number; offset?: number }
): AsyncIterable<Example>;

interface DatasetShareSchema {
  /** Dataset ID */
  dataset_id: string;
  /** Share token for public access */
  share_token: string;
  /** Public share URL */
  url: string;
}

import { Client } from "langsmith";

const client = new Client();

// Share a dataset
const shareInfo = await client.shareDataset({
  datasetId: "dataset-123",
});
console.log("Share URL:", shareInfo.url);
console.log("Share token:", shareInfo.share_token);

// Read shared dataset (no auth required)
const sharedDataset = await client.readSharedDataset(
  "share_token_abc123xyz"
);

// Read schema from shared dataset
const schema = await client.readDatasetSharedSchema("share_token_abc123");
console.log("Input schema:", schema.inputs_schema);
console.log("Output schema:", schema.outputs_schema);

// List examples from shared dataset
for await (const example of client.listSharedExamples("share_token_abc123", {
  limit: 100,
})) {
  console.log(example.inputs, example.outputs);
}

// Unshare dataset
await client.unshareDataset({
  datasetId: "dataset-123",
});

/**
 * Create a new dataset version snapshot
 * @param params - Version creation parameters
 * @returns Created dataset version
 */
createDatasetVersion(
  params: CreateDatasetVersionParams
): Promise<DatasetVersion>;

interface CreateDatasetVersionParams {
  /** Dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Version name/tag */
  name?: string;
  /** Version description */
  description?: string;
  /** Version tags */
  tags?: string[];
  /** Example IDs to include in this version (optional, includes all if not specified) */
  exampleIds?: string[];
}

/**
 * Update an existing dataset version
 * @param params - Version update parameters
 * @returns Updated dataset version
 */
updateDatasetVersion(
  params: UpdateDatasetVersionParams
): Promise<DatasetVersion>;

interface UpdateDatasetVersionParams {
  /** Dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Version ID or name to update */
  versionId?: string;
  versionName?: string;
  /** New version name */
  name?: string;
  /** New description */
  description?: string;
  /** New tags */
  tags?: string[];
}

/**
 * Read a specific dataset version
 * @param params - Version identifier
 * @returns Promise resolving to dataset version
 */
readDatasetVersion(params: {
  datasetId?: string;
  datasetName?: string;
  versionId?: string;
  versionName?: string;
}): Promise<DatasetVersion>;

/**
 * Compare two dataset versions
 * @param params - Diff parameters
 * @returns Dataset diff information
 */
diffDatasetVersions(
  params: DiffDatasetVersionsParams
): Promise<DatasetDiffInfo>;

interface DiffDatasetVersionsParams {
  /** Dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Source version ID or name */
  fromVersion: string;
  /** Target version ID or name */
  toVersion: string;
}

interface DatasetVersion {
  /** Version ID */
  id: string;
  /** Dataset ID */
  dataset_id: string;
  /** Version name/tag */
  name?: string;
  /** Version description */
  description?: string;
  /** Creation timestamp */
  created_at: string;
  /** Version tags */
  tags?: string[];
  /** Example IDs included in this version */
  example_ids?: string[];
}

interface DatasetDiffInfo {
  /** Examples added in target version */
  examples_added: Example[];
  /** Examples removed in target version */
  examples_removed: Example[];
  /** Examples modified between versions */
  examples_modified: Array<{
    /** Example in source version */
    before: Example;
    /** Example in target version */
    after: Example;
  }>;
}

import { Client } from "langsmith";

const client = new Client();

// Create a version snapshot
const version = await client.createDatasetVersion({
  datasetName: "qa-dataset",
  name: "v1.0.0",
  description: "Initial release version",
  tags: ["production", "release"],
});

// Update version metadata
await client.updateDatasetVersion({
  datasetId: "dataset-123",
  versionName: "v1.0.0",
  description: "Production release - validated and approved",
  tags: ["production", "release", "validated"],
});

// Read a specific version
const specificVersion = await client.readDatasetVersion({
  datasetName: "qa-dataset",
  versionName: "v1.0.0",
});

// Compare two versions
const diff = await client.diffDatasetVersions({
  datasetName: "qa-dataset",
  fromVersion: "v1.0.0",
  toVersion: "v1.1.0",
});

console.log("Examples added:", diff.examples_added.length);
console.log("Examples removed:", diff.examples_removed.length);
console.log("Examples modified:", diff.examples_modified.length);

/**
 * Index a dataset for search
 * @param params - Dataset identifier
 * @returns Promise resolving when indexing completes
 */
indexDataset(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<void>;

/**
 * Find similar examples using embeddings
 * @param inputs - Input to find similar examples for
 * @param datasetId - Dataset ID to search within
 * @param limit - Maximum number of results to return
 * @param options - Optional filter parameters
 * @returns Promise resolving to array of similar examples with scores
 */
similarExamples(
  inputs: Record<string, any>,
  datasetId: string,
  limit: number,
  options?: { filter?: string }
): Promise<Array<Example & { score?: number }>>;

/**
 * Upload CSV file as a dataset
 * @param params - CSV upload parameters
 * @returns Promise resolving to created dataset
 */
uploadCsv(params: {
  csvFile: Blob | string;
  fileName: string;
  inputKeys: string[];
  outputKeys: string[];
  name?: string;
  description?: string;
  dataType?: DataType;
}): Promise<Dataset>;

/**
 * List dataset splits (train/test/val)
 * @param params - Dataset identifier
 * @returns Promise resolving to array of split names
 */
listDatasetSplits(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<string[]>;

/**
 * Update dataset splits assignments
 * @param params - Split update parameters
 * @returns Promise resolving when update completes
 */
updateDatasetSplits(params: {
  datasetId?: string;
  datasetName?: string;
  splits: Record<string, string[]>; // { 'train': ['ex1', 'ex2'], 'test': ['ex3'] }
}): Promise<void>;

/**
 * Clone a publicly shared dataset to your tenant
 * @param tokenOrUrl - Share token or full share URL
 * @param options - Optional clone options
 * @returns Promise resolving when clone completes
 */
clonePublicDataset(
  tokenOrUrl: string,
  options?: CloneDatasetParams
): Promise<void>;

interface CloneDatasetParams {
  /** Source API URL */
  sourceApiUrl?: string;
  /** Target dataset name */
  datasetName?: string;
  /** Target dataset description */
  targetDatasetDescription?: string;
  /** Source dataset ID */
  sourceDatasetId?: string;
  /** Source dataset name */
  sourceDatasetName?: string;
  /** Target dataset ID */
  targetDatasetId?: string;
  /** Include examples */
  includeExamples?: boolean;
  /** Tags to filter */
  tags?: string[];
}

/**
 * Export dataset in OpenAI fine-tuning format (JSONL)
 * @param params - Export parameters
 * @returns Array of formatted training examples
 */
readDatasetOpenaiFinetuning(params: {
  datasetId?: string;
  datasetName?: string;
}): Promise<Array<Record<string, any>>>;

import { Client } from "langsmith";
import { readFileSync, writeFile } from "fs/promises";

const client = new Client();

// Index a dataset for similarity search
await client.indexDataset({
  datasetName: "qa-dataset",
});

// Find similar examples
const similar = await client.similarExamples(
  { question: "What is the capital of France?" },
  "dataset-123",
  5,
  { filter: "metadata.category == 'geography'" }
);

console.log("Similar examples:", similar);

// Upload CSV as dataset
const csvContent = readFileSync("dataset.csv", "utf-8");
const dataset = await client.uploadCsv({
  csvFile: csvContent,
  fileName: "dataset.csv",
  inputKeys: ["question"],
  outputKeys: ["answer"],
  name: "uploaded-dataset",
  description: "Dataset imported from CSV",
  dataType: "kv",
});

// List and update dataset splits
const splits = await client.listDatasetSplits({
  datasetName: "ml-dataset",
});
console.log("Current splits:", splits);

await client.updateDatasetSplits({
  datasetName: "ml-dataset",
  splits: {
    train: ["ex1", "ex2", "ex3"],
    test: ["ex4", "ex5"],
    validation: ["ex6"],
  },
});

// Clone a publicly shared dataset
await client.clonePublicDataset(
  "https://smith.langchain.com/public/abc123/d",
  { datasetName: "cloned-public-dataset" }
);

// Or use just the share token
await client.clonePublicDataset("share_token_abc123");

// Export dataset for OpenAI fine-tuning
const finetuningData = await client.readDatasetOpenaiFinetuning({
  datasetName: "chat-training-data",
});

// Save to JSONL file
const jsonl = finetuningData.map((item) => JSON.stringify(item)).join("\n");
await writeFile("training_data.jsonl", jsonl);

// Each item follows OpenAI's format:
// {
//   "messages": [
//     { "role": "system", "content": "..." },
//     { "role": "user", "content": "..." },
//     { "role": "assistant", "content": "..." }
//   ]
// }

import { Client } from "langsmith";

const client = new Client();

// 1. Create dataset
const dataset = await client.createDataset({
  datasetName: "customer-feedback-v1",
  description: "Customer feedback classification dataset",
  dataType: "kv",
});

// 2. Add examples in batches
const feedbackData = [
  {
    inputs: { text: "Great product, very satisfied!" },
    outputs: { sentiment: "positive" },
  },
  {
    inputs: { text: "Terrible experience, would not recommend." },
    outputs: { sentiment: "negative" },
  },
  // ... more examples
];

await client.createExamples({
  datasetId: dataset.id,
  inputs: feedbackData.map((d) => d.inputs),
  outputs: feedbackData.map((d) => d.outputs),
});

// 3. Create version snapshot
const v1 = await client.createDatasetVersion({
  datasetId: dataset.id,
  name: "v1.0",
  description: "Initial dataset version",
});

// 4. Update examples
await client.updateExamples({
  exampleIds: ["ex1", "ex2"],
  metadata: [{ reviewed: true }, { reviewed: true }],
});

// 5. Create new version
const v2 = await client.createDatasetVersion({
  datasetId: dataset.id,
  name: "v1.1",
  description: "Updated with reviewed examples",
});

// 6. Compare versions
const diff = await client.diffDatasetVersions({
  datasetId: dataset.id,
  fromVersion: "v1.0",
  toVersion: "v1.1",
});

console.log(`Modified examples: ${diff.examples_modified.length}`);

// 7. Share dataset
const shareInfo = await client.shareDataset({
  datasetId: dataset.id,
});
console.log(`Share at: ${shareInfo.url}`);

import { Client } from "langsmith";

const client = new Client();

// Create dataset for storing examples
const dataset = await client.createDataset({
  datasetName: "production-traces-2024",
  description: "High-quality production runs converted to examples",
});

// Fetch runs with specific criteria
const runs = [];
for await (const run of client.listRuns({
  projectName: "production-chat",
  filter: 'eq(feedback.score, 1) and eq(feedback.key, "quality")',
  limit: 100,
})) {
  runs.push(run);
}

// Convert runs to examples
await client.createExamples({
  datasetId: dataset.id,
  inputs: runs.map((run) => run.inputs),
  outputs: runs.map((run) => run.outputs),
  metadata: runs.map((run) => ({
    source: "production",
    originalRunId: run.id,
    feedback: run.feedback_stats,
  })),
  sourceRunIds: runs.map((run) => run.id),
});

console.log(`Created ${runs.length} examples from production runs`);

import { Client } from "langsmith";

const client = new Client();

const dataset = await client.createDataset({
  datasetName: "ml-training-data",
  dataType: "kv",
});

// Add examples with different splits
const allData = loadYourData(); // Your data loading function

// Split data 70/15/15
const trainSize = Math.floor(allData.length * 0.7);
const valSize = Math.floor(allData.length * 0.15);

const trainData = allData.slice(0, trainSize);
const valData = allData.slice(trainSize, trainSize + valSize);
const testData = allData.slice(trainSize + valSize);

// Create examples with split labels
await client.createExamples({
  datasetId: dataset.id,
  inputs: trainData.map((d) => d.inputs),
  outputs: trainData.map((d) => d.outputs),
  splits: trainData.map(() => "train"),
});

await client.createExamples({
  datasetId: dataset.id,
  inputs: valData.map((d) => d.inputs),
  outputs: valData.map((d) => d.outputs),
  splits: valData.map(() => "validation"),
});

await client.createExamples({
  datasetId: dataset.id,
  inputs: testData.map((d) => d.inputs),
  outputs: testData.map((d) => d.outputs),
  splits: testData.map(() => "test"),
});

// Query specific splits
for await (const example of client.listExamples({
  datasetId: dataset.id,
  splits: ["train"],
})) {
  // Train model on training examples
}

// Or use updateDatasetSplits for batch updates
await client.updateDatasetSplits({
  datasetId: dataset.id,
  splits: {
    train: ["ex1", "ex2", "ex3"],
    test: ["ex4", "ex5"],
    validation: ["ex6"],
  },
});

import { Client } from "langsmith";

const client = new Client();

// Create examples with rich metadata
await client.createExamples({
  datasetName: "multi-domain-qa",
  inputs: [
    { question: "What is photosynthesis?" },
    { question: "Explain quantum entanglement" },
  ],
  outputs: [{ answer: "..." }, { answer: "..." }],
  metadata: [
    {
      domain: "biology",
      difficulty: "medium",
      source: "textbook",
      verified: true,
      tags: ["science", "education"],
    },
    {
      domain: "physics",
      difficulty: "hard",
      source: "research_paper",
      verified: true,
      tags: ["science", "quantum"],
    },
  ],
});

// Query examples by metadata
for await (const example of client.listExamples({
  datasetName: "multi-domain-qa",
  metadata: { domain: "biology", verified: true },
})) {
  console.log(example.inputs.question);
}

// Clone dataset with metadata filtering
const biologyDataset = await client.cloneDataset({
  sourceDatasetName: "multi-domain-qa",
  targetDatasetName: "biology-qa-only",
  tags: ["biology"],
});

// Create versioned datasets
datasetName: "qa-eval-v1.0.0"
datasetName: "qa-eval-v1.1.0"

// Include version in metadata
metadata: {
  version: "1.0.0",
  created_by: "data-team"
}

// Good
"customer-support-qa"
"translation-test-set"
"regression-tests-2024"

// Avoid
"dataset1"
"test"
"data"

// BAD: May create duplicate
await client.createDataset({ datasetName: "my-dataset" });

// GOOD: Check first
const exists = await client.hasDataset({ datasetName: "my-dataset" });
if (!exists) {
  await client.createDataset({ datasetName: "my-dataset" });
}

// BETTER: Use upsert
await client.createDataset({
  datasetName: "my-dataset",
  upsert: true
});

// BAD: Wrong type for chat data
await client.createDataset({
  datasetName: "chat-dataset",
  dataType: "kv" // Should be "chat"
});

// GOOD: Match data structure
await client.createDataset({
  datasetName: "chat-dataset",
  dataType: "chat" // Correct for chat messages
});

// BAD: Will fail if not indexed
const similar = await client.similarExamples(
  { question: "What is AI?" },
  datasetId
);

// GOOD: Index first (only needed once)
await client.indexDataset({ datasetId });
const similar = await client.similarExamples(
  { question: "What is AI?" },
  datasetId
);

// Misunderstanding: Tags don't create versions
await client.updateDatasetTag({
  datasetId,
  tag: "v2",
  asOf: new Date() // Points tag to current version
});

// Correct understanding:
// 1. Add examples (auto-creates new version)
await client.createExamples({...});

// 2. Tag that version
await client.updateDatasetTag({
  datasetId,
  tag: "v2",
  asOf: new Date()
});