Example Management API

/**
 * Create a single example
 * @param example - Example creation data
 * @returns Promise resolving to created example
 */
createExample(example: ExampleCreate): Promise<Example>;

interface ExampleCreate {
  /** Dataset ID (either dataset_id or dataset_name is required) */
  dataset_id?: string;
  /** Dataset name (either dataset_id or dataset_name is required) */
  dataset_name?: string;
  /** Input data (required) */
  inputs: Record<string, any>;
  /** Expected output data */
  outputs?: Record<string, any>;
  /** Example metadata */
  metadata?: Record<string, any>;
  /** Example ID (auto-generated if not provided) */
  id?: string;
  /** Source run ID */
  source_run_id?: string;
  /** Split identifier (e.g., "train", "test", "validation") */
  split?: string | string[];
}

type CreateExampleOptions = {
  /** Dataset ID */
  datasetId?: string;
  /** Dataset name */
  datasetName?: string;
  /** Creation timestamp */
  createdAt?: Date;
  /** Example ID */
  exampleId?: string;
  /** Example metadata */
  metadata?: Record<string, any>;
  /** Split assignment (train, test, validation, etc.) */
  split?: string | string[];
  /** Source run ID */
  sourceRunId?: string;
  /** Use source run I/O */
  useSourceRunIO?: boolean;
  /** Use source run attachments */
  useSourceRunAttachments?: string[];
  /** Attachments for the example */
  attachments?: Attachments;
};


interface Example {
  /** Example ID */
  id: string;
  /** Dataset ID */
  dataset_id: string;
  /** Input data */
  inputs: Record<string, any>;
  /** Output data */
  outputs?: Record<string, any>;
  /** Metadata */
  metadata?: Record<string, any>;
  /** Creation timestamp */
  created_at: string;
  /** Source run ID */
  source_run_id?: string;
}

import { Client } from "langsmith";

const client = new Client();

const example = await client.createExample({
  dataset_id: dataset.id,
  inputs: { question: "What is LangSmith?" },
  outputs: { answer: "LangSmith is a platform..." },
  metadata: { category: "product-info" }
});

/**
 * Create an LLM format example (for completion-style datasets)
 * Note: This method requires THREE separate parameters (input, generation, options), not a single object.
 * @param input - Prompt/input text (string)
 * @param generation - Expected completion/output text (string or undefined)
 * @param options - Additional options (CreateExampleOptions object)
 * @returns Created example
 */
createLLMExample(
  input: string,
  generation: string | undefined,
  options: CreateExampleOptions
): Promise<Example>;

import { Client } from "langsmith";

const client = new Client();

// Create LLM example - note the THREE separate arguments
const example = await client.createLLMExample(
  "Translate 'hello' to French",  // Arg 1: input string
  "bonjour",                       // Arg 2: generation string
  {                                // Arg 3: options object
    datasetName: "translation-dataset",
    metadata: { language: "french" }
  }
);

// Create LLM example without expected output
const inputOnly = await client.createLLMExample(
  "Complete this sentence: The sky is",  // Arg 1: input
  undefined,                              // Arg 2: no expected output
  {                                       // Arg 3: options
    datasetName: "completion-tests",
    metadata: { type: "open-ended" }
  }
);

/**
 * Create a chat format example (for chat-style datasets)
 * @param input - Array of chat messages (input) or LangChain-compatible messages
 * @param generations - Single chat message object (output) or LangChain message, or undefined
 * @param options - Additional options
 * @returns Created example
 */
createChatExample(
  input: KVMap[] | LangChainBaseMessage[],
  generations: KVMap | LangChainBaseMessage | undefined,
  options: CreateExampleOptions
): Promise<Example>;

import { Client } from "langsmith";

const client = new Client();

// Create chat example (note: generations is a single message object, not an array)
const example = await client.createChatExample(
  [
    { role: "user", content: "What is the capital of France?" }
  ],
  { role: "assistant", content: "The capital of France is Paris." }, // Single object
  {
    datasetName: "qa-chat-dataset",
    metadata: { category: "geography" }
  }
);

// Create chat example with system message
const chatExample = await client.createChatExample(
  [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" }
  ],
  { role: "assistant", content: "Hi! How can I help you today?" }, // Single object
  {
    datasetId: dataset.id,
    split: "train"
  }
);

// Create chat example with undefined generation (for evaluation datasets)
const testInput = await client.createChatExample(
  [
    { role: "user", content: "Explain quantum computing" }
  ],
  undefined, // No expected output
  {
    datasetName: "test-inputs",
    metadata: { difficulty: "advanced" }
  }
);

/**
 * Create multiple examples in bulk using separate arrays
 * @param params - Bulk creation parameters with parallel arrays
 * @returns Promise resolving to array of created examples
 */
createExamples(params: CreateExamplesParamsSeparateArrays): Promise<Example[]>;

interface CreateExamplesParamsSeparateArrays {
  /** Dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Array of input objects */
  inputs: Record<string, any>[];
  /** Array of output objects (parallel to inputs) */
  outputs?: Record<string, any>[];
  /** Array of metadata objects (parallel to inputs) */
  metadata?: Record<string, any>[];
  /** Array of example IDs (parallel to inputs) */
  ids?: string[];
  /** Array of split identifiers (parallel to inputs) */
  splits?: (string | string[])[];
  /** Array of source run IDs (parallel to inputs) */
  sourceRunIds?: string[];
}

/**
 * Create multiple examples in bulk using examples array
 * @param params - Bulk creation parameters with examples array
 * @returns Promise resolving to array of created examples
 */
createExamples(params: CreateExamplesParamsExamplesArray): Promise<Example[]>;

interface CreateExamplesParamsExamplesArray {
  /** Dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Array of complete example objects */
  examples: Array<{
    inputs: Record<string, any>;
    outputs?: Record<string, any>;
    metadata?: Record<string, any>;
    id?: string;
    source_run_id?: string;
    split?: string | string[];
  }>;
}

await client.createExamples({
  datasetName: "qa-dataset",
  inputs: [
    { question: "What is 2+2?" },
    { question: "What is 3+3?" }
  ],
  outputs: [
    { answer: "4" },
    { answer: "6" }
  ],
  metadata: [
    { category: "math", difficulty: "easy" },
    { category: "math", difficulty: "easy" }
  ]
});

await client.createExamples({
  datasetName: "qa-dataset",
  examples: [
    {
      inputs: { question: "What is 2+2?" },
      outputs: { answer: "4" },
      metadata: { category: "math", difficulty: "easy" }
    },
    {
      inputs: { question: "What is 3+3?" },
      outputs: { answer: "6" },
      metadata: { category: "math", difficulty: "easy" }
    }
  ]
});

// Style 2 with per-example configuration
await client.createExamples({
  datasetName: "training-data",
  examples: [
    {
      inputs: { text: "Example 1" },
      outputs: { label: "positive" },
      metadata: { source: "production" },
      split: "train",
      source_run_id: "run-123"
    },
    {
      inputs: { text: "Example 2" },
      outputs: { label: "negative" },
      metadata: { source: "manual" },
      split: ["train", "validation"], // Multiple splits
      source_run_id: "run-456"
    }
  ]
});

/**
 * Update an example
 * @param example - Example update data
 * @returns Promise resolving to updated example
 */
updateExample(example: ExampleUpdate): Promise<Example>;

/**
 * Bulk update multiple examples
 * @param update - Array of example updates
 * @returns Promise resolving to update response object
 */
updateExamples(update: ExampleUpdate[]): Promise<object>;

interface ExampleUpdate {
  /** Example ID (required) */
  id: string;
  /** Updated inputs */
  inputs?: Record<string, any>;
  /** Updated outputs */
  outputs?: Record<string, any>;
  /** Updated metadata */
  metadata?: Record<string, any>;
  /** Updated split (optional) */
  split?: string | string[];
  /** Dataset ID (optional) */
  dataset_id?: string;
  /** Attachments */
  attachments?: Attachments;
  /** Attachment operations */
  attachments_operations?: Record<string, any>;
}

// Update single example
await client.updateExample({
  id: example.id,
  outputs: { answer: "Updated answer" },
  metadata: { reviewed: true }
});

// Bulk update multiple examples
await client.updateExamples([
  {
    id: "ex1",
    metadata: { verified: true }
  },
  {
    id: "ex2",
    outputs: { answer: "New answer" }
  },
  {
    id: "ex3",
    split: "train"
  }
]);

/**
 * Read example details
 * @param exampleId - Example ID
 * @returns Promise resolving to example
 */
readExample(exampleId: string): Promise<Example>;

const example = await client.readExample(exampleId);
console.log(example.inputs, example.outputs);

/**
 * List examples with filtering
 * @param params - List parameters
 * @returns Async iterable of examples
 */
listExamples(params?: ListExamplesParams): AsyncIterable<Example>;

interface ListExamplesParams {
  /** Filter by dataset ID or name */
  datasetId?: string;
  datasetName?: string;
  /** Filter by example IDs */
  exampleIds?: string[];
  /** Limit results */
  limit?: number;
  /** Offset for pagination */
  offset?: number;
  /** Metadata filter */
  metadata?: Record<string, any>;
  /** Include run information */
  includeRuns?: boolean;
}

// List all examples in dataset
for await (const example of client.listExamples({
  datasetName: "qa-dataset",
  limit: 100
})) {
  console.log(example.inputs, example.outputs);
}

// Filter by metadata
for await (const example of client.listExamples({
  datasetId: dataset.id,
  metadata: { category: "math" }
})) {
  console.log(example.inputs);
}

/**
 * Delete an example
 * @param exampleId - Example ID to delete
 * @returns Promise resolving when deletion completes
 */
deleteExample(exampleId: string): Promise<void>;

/**
 * Delete multiple examples
 * @param exampleIds - Array of example IDs
 * @param options - Deletion options
 * @returns Promise resolving when deletion completes
 */
deleteExamples(
  exampleIds: string[],
  options?: { hardDelete?: boolean }
): Promise<void>;

// Delete single example
await client.deleteExample(exampleId);

// Delete multiple
await client.deleteExamples(["ex1", "ex2", "ex3"]);

/**
 * Upload examples using multipart (for large batches)
 * @param params - Multipart upload parameters
 * @returns Promise resolving to upload response
 */
uploadExamplesMultipart(params: {
  datasetId?: string;
  datasetName?: string;
  examples: Array<{
    inputs: Record<string, any>;
    outputs?: Record<string, any>;
    metadata?: Record<string, any>;
  }>;
}): Promise<UploadExamplesResponse>;

interface UploadExamplesResponse {
  /** Array of created example IDs */
  example_ids: string[];
  /** Number of examples uploaded */
  count: number;
}

/**
 * Update examples using multipart (for large batches)
 * @param params - Multipart update parameters
 * @returns Promise resolving to update response
 */
updateExamplesMultipart(params: {
  exampleIds: string[];
  patches: Array<{
    inputs?: Record<string, any>;
    outputs?: Record<string, any>;
    metadata?: Record<string, any>;
  }>;
}): Promise<UpdateExamplesResponse>;

interface UpdateExamplesResponse {
  /** Array of updated example IDs */
  example_ids: string[];
  /** Number of examples updated */
  count: number;
}

import { Client } from "langsmith";

const client = new Client();

// Upload many examples efficiently
const uploadResult = await client.uploadExamplesMultipart({
  datasetName: "large-dataset",
  examples: [
    {
      inputs: { question: "What is AI?" },
      outputs: { answer: "Artificial Intelligence is..." },
      metadata: { category: "tech" }
    },
    {
      inputs: { question: "What is ML?" },
      outputs: { answer: "Machine Learning is..." },
      metadata: { category: "tech" }
    },
    // ... many more examples
  ]
});

console.log(`Uploaded ${uploadResult.count} examples`);
console.log("Example IDs:", uploadResult.example_ids);

// Bulk update examples efficiently
const updateResult = await client.updateExamplesMultipart({
  exampleIds: ["ex1", "ex2", "ex3"],
  patches: [
    { metadata: { verified: true } },
    { outputs: { answer: "Updated answer" } },
    { metadata: { reviewed: true } }
  ]
});

console.log(`Updated ${updateResult.count} examples`);

/**
 * Find similar examples using embeddings
 * @param inputs - Input to find similar examples for
 * @param datasetId - Dataset ID to search
 * @param limit - Maximum results
 * @param filter - Optional filter
 * @returns Promise resolving to similar examples
 */
similarExamples(
  inputs: Record<string, any>,
  datasetId: string,
  limit?: number,
  filter?: string
): Promise<Example[]>;

const similar = await client.similarExamples(
  { question: "What is AI?" },
  dataset.id,
  5
);

for (const example of similar) {
  console.log("Similar:", example.inputs);
}

await client.createExamples({
  datasetName: "multi-domain-qa",
  inputs: [
    { question: "What is photosynthesis?" },
    { question: "Explain quantum entanglement" }
  ],
  outputs: [
    { answer: "..." },
    { answer: "..." }
  ],
  metadata: [
    {
      domain: "biology",
      difficulty: "medium",
      verified: true
    },
    {
      domain: "physics",
      difficulty: "hard",
      verified: true
    }
  ]
});

// Fetch high-quality runs
const runs = [];
for await (const run of client.listRuns({
  projectName: "production",
  filter: 'eq(feedback.score, 1)'
})) {
  runs.push(run);
}

// Convert to examples
await client.createExamples({
  datasetId: dataset.id,
  inputs: runs.map(run => run.inputs),
  outputs: runs.map(run => run.outputs),
  sourceRunIds: runs.map(run => run.id)
});

// BAD: Missing dataset reference
await client.createExample({
  inputs: { question: "What is AI?" },
  outputs: { answer: "..." }
  // Error: dataset_id required
});

// GOOD: Always specify dataset
await client.createExample({
  dataset_id: datasetId,
  inputs: { question: "What is AI?" },
  outputs: { answer: "..." }
});

// BAD: Mismatched lengths
await client.createExamples({
  datasetName: "qa",
  inputs: [{ q: "A" }, { q: "B" }, { q: "C" }], // 3 items
  outputs: [{ a: "1" }, { a: "2" }] // Only 2 items - ERROR
});

// GOOD: Same length
await client.createExamples({
  datasetName: "qa",
  inputs: [{ q: "A" }, { q: "B" }],
  outputs: [{ a: "1" }, { a: "2" }] // Matches
});

// BETTER: Use examples array to avoid this issue
await client.createExamples({
  datasetName: "qa",
  examples: [
    { inputs: { q: "A" }, outputs: { a: "1" } },
    { inputs: { q: "B" }, outputs: { a: "2" } }
  ]
});

// BAD: Using objects instead of strings
await client.createLLMExample(
  { text: "Translate hello" }, // Should be string
  { translation: "bonjour" }, // Should be string
  { datasetName: "translations" }
);

// GOOD: Use strings for LLM format
await client.createLLMExample(
  "Translate 'hello' to French",
  "bonjour",
  { datasetName: "translations" }
);

// BAD: Using string instead of message array
await client.createChatExample(
  "What is AI?", // Should be message array
  "AI is...", // Should be message array
  { datasetName: "chat" }
);

// GOOD: Use message arrays
await client.createChatExample(
  [{ role: "user", content: "What is AI?" }],
  [{ role: "assistant", content: "AI is..." }],
  { datasetName: "chat" }
);

// BAD: Large attachments may fail
await client.createExamples({
  datasetId,
  examples: examplesWithLargeImages // May exceed size limit
});

// GOOD: Use multipart for large/binary data
await client.uploadExamplesMultipart({
  datasetId,
  examples: examplesWithLargeImages
});