LangSmith Schemas

import {
  Run,
  RunCreate,
  RunUpdate,
  Example,
  Dataset,
  Feedback,
  Prompt,
  AnnotationQueue,
  KVMap,
  RunType,
  DataType,
} from "langsmith/schemas";

/**
 * Base run structure shared by all run types
 */
interface BaseRun {
  /** Unique identifier for the run */
  id?: string;
  /** Name of the run */
  name: string;
  /** Type of run: llm, chain, tool, retriever, embedding, prompt, or parser */
  run_type: RunType;
  /** Start time in milliseconds since epoch */
  start_time: number;
  /** End time in milliseconds since epoch */
  end_time?: number;
  /** Additional metadata as key-value pairs */
  extra?: KVMap;
  /** Error message if run failed */
  error?: string;
  /** Serialized representation of the traced object */
  serialized?: object;
  /** Events that occurred during the run */
  events?: RunEvent[];
  /** Tags for categorizing the run */
  tags?: string[];
  /** Input data for the run */
  inputs?: KVMap;
  /** Output data from the run */
  outputs?: KVMap;
  /** Reference to an example for evaluation */
  reference_example_id?: string;
  /** Parent run identifier for hierarchical traces */
  parent_run_id?: string;
  /** Multiple parent run identifiers (for complex traces) */
  parent_run_ids?: string[];
  /** Attachments associated with the run */
  attachments?: Attachments;
  /** LLM invocation parameters */
  invocation_params?: InvocationParamsSchema;
  /** S3 URLs for large inputs (when inputs exceed size limit) */
  inputs_s3_urls?: Record<string, string>;
  /** S3 URLs for large outputs (when outputs exceed size limit) */
  outputs_s3_urls?: Record<string, string>;
}

/**
 * Complete run record as returned from the API
 * Includes all database fields and computed properties
 */
interface Run extends BaseRun {
  /** Unique run identifier (required) */
  id: string;
  /** Project identifier */
  session_id?: string;
  /** Child runs in the trace tree */
  child_runs?: Run[];
  /** Execution order in the trace tree */
  execution_order?: number;
  /** Dotted order string for distributed tracing */
  dotted_order?: string;
  /** Trace identifier for grouping related runs */
  trace_id?: string;
  /** Total cost in USD if applicable */
  total_cost?: number;
  /** Prompt cost in USD if applicable */
  prompt_cost?: number;
  /** Completion cost in USD if applicable */
  completion_cost?: number;
  /** Total tokens used */
  total_tokens?: number;
  /** Prompt tokens used */
  prompt_tokens?: number;
  /** Completion tokens used */
  completion_tokens?: number;
  /** Feedback entries for this run */
  feedback_stats?: Record<string, number>;
  /** Run status */
  status?: string;
  /** First token timestamp */
  first_token_time?: number;
  /** Manifest identifier */
  manifest_id?: string;
  /** Associated app path */
  app_path?: string;
  /** Usage metadata breakdown */
  usage_metadata?: UsageMetadata;
  /** Whether this run is included in a dataset */
  in_dataset?: boolean;
}

/**
 * Schema for creating a new run
 */
interface RunCreate extends BaseRun {
  /** Project name or identifier */
  project_name?: string;
  /** Revision identifier */
  revision_id?: string;
}

/**
 * Schema for updating an existing run
 */
interface RunUpdate {
  /** End time in milliseconds since epoch */
  end_time?: number;
  /** Error message */
  error?: string;
  /** Input data */
  inputs?: KVMap;
  /** Output data */
  outputs?: KVMap;
  /** Parent run identifier */
  parent_run_id?: string;
  /** Reference example identifier */
  reference_example_id?: string;
  /** Events to add */
  events?: RunEvent[];
  /** Tags */
  tags?: string[];
  /** Additional metadata */
  extra?: KVMap;
  /** Dotted order for distributed tracing */
  dotted_order?: string;
  /** Trace identifier */
  trace_id?: string;
  /** Attachments */
  attachments?: Attachments;
  /** Session identifier override */
  session_id?: string;
  /** Session name override */
  session_name?: string;
}

/**
 * Run type enumeration
 */
type RunType =
  | "llm"          // Language model call
  | "chain"        // Chain of operations
  | "tool"         // Tool/function call
  | "retriever"    // Document retriever
  | "embedding"    // Embedding generation
  | "prompt"       // Prompt formatting
  | "parser";      // Output parser

/**
 * Run event structure for tracking execution milestones
 */
interface RunEvent {
  /** Event name */
  name: string;
  /** Event timestamp in milliseconds since epoch */
  time: number;
  /** Additional event metadata */
  kwargs?: KVMap;
}

/**
 * Base example structure
 */
interface BaseExample {
  /** Unique identifier */
  id?: string;
  /** Dataset identifier this example belongs to */
  dataset_id: string;
  /** Input data */
  inputs: KVMap;
  /** Expected output data (optional, for evaluation) */
  outputs?: KVMap;
  /** Additional metadata */
  metadata?: KVMap;
  /** Split assignment (train, test, validation, etc.) */
  split?: string | string[];
  /** Source run identifier */
  source_run_id?: string;
}

/**
 * Complete example record as returned from the API
 */
interface Example extends BaseExample {
  /** Unique identifier (required) */
  id: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp */
  modified_at?: string;
  /** Number of runs referencing this example */
  runs?: Run[];
}

/**
 * Schema for creating a new example
 */
interface ExampleCreate extends BaseExample {
  /** Optional explicit identifier */
  id?: string;
  /** Creation timestamp */
  created_at?: string;
  /** Attachments for the example */
  attachments?: Attachments;
}

/**
 * Schema for updating an existing example
 */
interface ExampleUpdate {
  /** Example identifier (required for updates) */
  example_id: string;
  /** Dataset identifier */
  dataset_id?: string;
  /** Updated input data */
  inputs?: KVMap;
  /** Updated output data */
  outputs?: KVMap;
  /** Updated metadata */
  metadata?: KVMap;
  /** Updated split assignment */
  split?: string | string[];
  /** Updated attachments */
  attachments?: Attachments;
}

/**
 * Example with attachments for upload
 */
interface ExampleUploadWithAttachments {
  /** Example identifier */
  id?: string;
  /** Input data */
  inputs: KVMap;
  /** Output data */
  outputs?: KVMap;
  /** Metadata */
  metadata?: KVMap;
  /** Split assignment */
  split?: string | string[];
  /** Attachments */
  attachments?: Attachments;
}

/**
 * Base dataset structure
 */
interface BaseDataset {
  /** Unique identifier */
  id?: string;
  /** Dataset name */
  name: string;
  /** Dataset description */
  description?: string;
  /** Dataset metadata */
  metadata?: KVMap;
  /** Data type: kv (key-value), llm, or chat */
  data_type?: DataType;
}

/**
 * Complete dataset record as returned from the API
 */
interface Dataset extends BaseDataset {
  /** Unique identifier (required) */
  id: string;
  /** Tenant identifier */
  tenant_id: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp */
  modified_at: string;
  /** Number of examples in dataset */
  example_count?: number;
  /** Session count */
  session_count?: number;
  /** Last session start time */
  last_session_start_time?: string;
}

/**
 * Dataset sharing configuration
 */
interface DatasetShareSchema {
  /** Unique identifier */
  id: string;
  /** Dataset identifier */
  dataset_id: string;
  /** Share token for public access */
  share_token: string;
  /** Share URL */
  url: string;
}

/**
 * Dataset version information
 */
interface DatasetVersion {
  /** Dataset identifier */
  dataset_id: string;
  /** Version number or tag */
  as_of: string | Date;
  /** Version metadata */
  metadata?: KVMap;
  /** Version description */
  description?: string;
  /** Tags for the version */
  tags?: string[];
}

/**
 * Dataset diff information for comparing versions
 */
interface DatasetDiffInfo {
  /** Examples added in new version */
  examples_added: string[];
  /** Examples removed in new version */
  examples_removed: string[];
  /** Examples modified in new version */
  examples_modified: string[];
}

/**
 * Data type enumeration
 */
type DataType =
  | "kv"      // Key-value data
  | "llm"     // LLM input/output format
  | "chat";   // Chat message format

/**
 * Upload examples response
 */
interface UploadExamplesResponse {
  /** Number of examples created */
  count: number;
  /** Example IDs */
  example_ids: string[];
}

/**
 * Update examples response
 */
interface UpdateExamplesResponse {
  /** Number of examples updated */
  count: number;
  /** Example IDs */
  example_ids: string[];
}

/**
 * Raw example format (before processing)
 */
interface RawExample {
  /** Input data */
  inputs: KVMap;
  /** Output data */
  outputs?: KVMap;
  /** Metadata */
  metadata?: KVMap;
  /** Dataset ID */
  dataset_id?: string;
  /** Example ID */
  id?: string;
}

/**
 * Base feedback structure
 */
interface FeedbackBase {
  /** Unique identifier */
  id?: string;
  /** Run identifier this feedback is for */
  run_id?: string;
  /** Feedback key/name */
  key: string;
  /** Numeric or boolean score */
  score?: ScoreType;
  /** Freeform value (string, number, boolean, object) */
  value?: ValueType;
  /** Additional comment or explanation */
  comment?: string;
  /** Correction data */
  correction?: KVMap;
  /** Feedback configuration */
  feedback_config?: FeedbackConfig;
  /** Feedback source */
  feedback_source?: FeedbackSourceBase | APIFeedbackSource | ModelFeedbackSource;
  /** Feedback group identifier */
  feedback_group_id?: string;
  /** Comparative experiment identifier */
  comparative_experiment_id?: string;
}

/**
 * Complete feedback record as returned from the API
 */
interface Feedback extends FeedbackBase {
  /** Unique identifier (required) */
  id: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp */
  modified_at: string;
  /** Session identifier */
  session_id?: string;
}

/**
 * Schema for creating new feedback
 */
interface FeedbackCreate extends FeedbackBase {
  /** Optional explicit identifier */
  id?: string;
  /** Creation timestamp */
  created_at?: string;
}

/**
 * Schema for updating existing feedback
 */
interface FeedbackUpdate {
  /** Updated score */
  score?: ScoreType;
  /** Updated value */
  value?: ValueType;
  /** Updated comment */
  comment?: string;
  /** Updated correction */
  correction?: KVMap;
  /** Updated feedback configuration */
  feedback_config?: FeedbackConfig;
}

/**
 * Feedback configuration for evaluators
 */
interface FeedbackConfig {
  /** Evaluator type or name */
  type?: string;
  /** Evaluator-specific settings */
  [key: string]: any;
}

/**
 * Feedback category for classification
 */
interface FeedbackCategory {
  /** Category value */
  value: string;
  /** Category label */
  label?: string;
}

/**
 * Base feedback source
 */
interface FeedbackSourceBase {
  /** Source type */
  type: string;
  /** Additional metadata */
  metadata?: KVMap;
}

/**
 * API-generated feedback source
 */
interface APIFeedbackSource extends FeedbackSourceBase {
  type: "api";
}

/**
 * Model-generated feedback source
 */
interface ModelFeedbackSource extends FeedbackSourceBase {
  type: "model";
  /** Model name */
  model?: string;
}

/**
 * Feedback ingest token for presigned access
 */
interface FeedbackIngestToken {
  /** Unique identifier */
  id: string;
  /** Presigned URL for feedback submission */
  url: string;
  /** Expiration timestamp */
  expires_at: string;
  /** Feedback key this token is for */
  feedback_key: string;
  /** Associated run ID */
  run_id?: string;
}

/**
 * Score type for feedback
 */
type ScoreType = number | boolean | null;

/**
 * Value type for feedback
 */
type ValueType = number | boolean | string | object | null;

/**
 * Prompt commit information
 */
interface PromptCommit {
  /** Repository owner */
  owner: string;
  /** Repository name */
  repo: string;
  /** Commit hash or tag */
  commit_hash: string;
  /** Manifest data */
  manifest: KVMap;
  /** Examples associated with prompt */
  examples?: Example[];
  /** Commit message */
  message?: string;
  /** Parent commit hash */
  parent_commit?: string;
  /** Commit timestamp */
  created_at?: string;
  /** Commit author */
  author?: string;
}

/**
 * Prompt schema
 */
interface Prompt {
  /** Prompt ID */
  id: string;
  /** Tenant ID */
  tenant_id: string;
  /** Repository handle (owner/repo) */
  repo_handle: string;
  /** Full repository name */
  full_name: string;
  /** Repository owner (optional) */
  owner?: string;
  /** Description */
  description?: string;
  /** Readme content */
  readme?: string;
  /** Tags */
  tags: string[];
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
  /** Is public */
  is_public: boolean;
  /** Is archived */
  is_archived: boolean;
  /** Number of likes */
  num_likes: number;
  /** Number of downloads */
  num_downloads: number;
  /** Number of views */
  num_views: number;
  /** Whether authenticated user has liked */
  liked_by_auth_user: boolean;
  /** Last commit hash */
  last_commit_hash?: string;
  /** Number of commits */
  num_commits: number;
  /** Original repository ID if forked */
  original_repo_id?: string;
  /** Original repository full name if forked */
  original_repo_full_name?: string;
  /** Upstream repository ID */
  upstream_repo_id?: string;
  /** Upstream repository full name */
  upstream_repo_full_name?: string;
}

/**
 * Response for listing prompts
 */
interface ListPromptsResponse {
  /** List of prompts */
  repos: Prompt[];
  /** Total count */
  total: number;
}

/**
 * Response for listing commits
 */
interface ListCommitsResponse {
  /** List of commits */
  commits: PromptCommit[];
  /** Total count */
  total: number;
}

/**
 * Response for liking a prompt
 */
interface LikePromptResponse {
  /** Number of likes after operation */
  num_likes: number;
  /** Whether user has liked */
  liked_by_auth_user: boolean;
}

/**
 * Prompt sort field enumeration
 */
type PromptSortField =
  | "updated_at"
  | "num_likes"
  | "num_downloads"
  | "num_views"
  | "num_commits";

/**
 * Annotation queue schema
 */
interface AnnotationQueue {
  /** Unique identifier */
  id: string;
  /** Queue name */
  name: string;
  /** Queue description */
  description?: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp */
  updated_at: string;
  /** Queue metadata */
  metadata?: KVMap;
  /** Tenant identifier */
  tenant_id: string;
}

/**
 * Annotation queue with additional details
 */
interface AnnotationQueueWithDetails extends AnnotationQueue {
  /** Number of runs in queue */
  run_count?: number;
  /** Number of sessions in queue */
  session_count?: number;
  /** Last session start time */
  last_session_start_time?: string;
}

/**
 * Run with annotation queue information
 */
interface RunWithAnnotationQueueInfo extends Run {
  /** Queue run identifier */
  queue_run_id: string;
  /** Added to queue timestamp */
  added_at: string;
  /** Last reviewed timestamp */
  last_reviewed_time?: string;
  /** Number of reviews */
  review_count?: number;
  /** Annotation queue identifier */
  annotation_queue_id: string;
}

/**
 * Attachment metadata
 */
interface AttachmentInfo {
  /** MIME type */
  content_type: string;
  /** File size in bytes */
  size?: number;
  /** Original filename */
  filename?: string;
  /** Additional metadata */
  metadata?: KVMap;
}

/**
 * Attachment data
 */
interface AttachmentData extends AttachmentInfo {
  /** File content as base64 string or Buffer */
  content: string | Buffer;
}

/**
 * Attachment description for reference
 */
interface AttachmentDescription extends AttachmentInfo {
  /** Presigned URL for accessing attachment */
  presigned_url?: string;
  /** Attachment identifier */
  id?: string;
}

/**
 * Map of attachments by name
 */
type Attachments = Record<string, AttachmentData | AttachmentDescription>;

/**
 * Token usage metadata
 */
interface UsageMetadata {
  /** Input tokens used */
  input_tokens?: number;
  /** Output tokens used */
  output_tokens?: number;
  /** Total tokens used */
  total_tokens?: number;
  /** Detailed input token breakdown */
  input_token_details?: InputTokenDetails;
  /** Detailed output token breakdown */
  output_token_details?: OutputTokenDetails;
}

/**
 * Input token breakdown
 */
interface InputTokenDetails {
  /** Audio tokens */
  audio?: number;
  /** Cached tokens (reused from cache) */
  cache_read?: number;
  /** Tokens added to cache */
  cache_creation?: number;
  /** Other input token types */
  [key: string]: number | undefined;
}

/**
 * Output token breakdown
 */
interface OutputTokenDetails {
  /** Audio tokens */
  audio?: number;
  /** Reasoning tokens */
  reasoning?: number;
  /** Other output token types */
  [key: string]: number | undefined;
}

/**
 * Extracted usage metadata from various formats
 */
interface ExtractedUsageMetadata {
  /** Usage metadata in standard format */
  usage_metadata?: UsageMetadata;
  /** Total cost in USD */
  total_cost?: number;
  /** Input cost in USD */
  input_cost?: number;
  /** Output cost in USD */
  output_cost?: number;
}

/**
 * Project/session information
 */
interface TracerSession {
  /** Unique identifier */
  id: string;
  /** Start time */
  start_time?: string;
  /** End time */
  end_time?: string;
  /** Extra metadata */
  extra?: KVMap;
  /** Project name */
  name?: string;
  /** Description */
  description?: string;
  /** Tags */
  tags?: string[];
  /** Tenant identifier */
  tenant_id: string;
}

/**
 * Extended session with run statistics
 */
interface TracerSessionResult extends TracerSession {
  /** Number of runs in session */
  run_count?: number;
  /** Latency statistics */
  latency_p50?: number;
  latency_p99?: number;
  /** Total tokens used */
  total_tokens?: number;
  /** Prompt tokens used */
  prompt_tokens?: number;
  /** Completion tokens used */
  completion_tokens?: number;
  /** Feedback statistics */
  feedback_stats?: Record<string, number>;
  /** Run facets/breakdown */
  run_facets?: Array<{ run_type: string; count: number }>;
  /** Error rate */
  error_rate?: number;
  /** Streaming rate */
  streaming_rate?: number;
  /** Last run start time */
  last_run_start_time?: string;
}

/**
 * LLM invocation parameters
 */
interface InvocationParamsSchema {
  /** Model name */
  model?: string;
  /** Sampling temperature */
  temperature?: number;
  /** Nucleus sampling parameter */
  top_p?: number;
  /** Maximum tokens to generate */
  max_tokens?: number;
  /** Stop sequences */
  stop?: string | string[];
  /** Frequency penalty */
  frequency_penalty?: number;
  /** Presence penalty */
  presence_penalty?: number;
  /** Number of completions to generate */
  n?: number;
  /** Log probabilities to return */
  logprobs?: number;
  /** Top log probabilities to return */
  top_logprobs?: number;
  /** Additional provider-specific parameters */
  [key: string]: any;
}

/**
 * Retriever output format
 */
interface RetrieverOutput {
  /** Retrieved documents */
  documents?: Array<{
    /** Document content */
    page_content: string;
    /** Document metadata */
    metadata?: KVMap;
    /** Document identifier */
    id?: string;
  }>;
  /** Raw retriever output */
  raw_output?: any;
}

/**
 * Comparison evaluation result
 */
interface ComparisonEvaluationResult {
  /** Result key */
  key: string;
  /** Scores for each experiment */
  scores: Record<string, number | boolean | null>;
  /** Optional comment */
  comment?: string;
  /** Source run identifier */
  source_run_id?: string;
  /** Target run identifier */
  target_run_id?: string;
}

/**
 * Comparative experiment schema
 */
interface ComparativeExperiment {
  /** Unique identifier */
  id: string;
  /** Experiment name */
  name: string;
  /** Description */
  description?: string;
  /** Creation timestamp */
  created_at: string;
  /** Last modification timestamp */
  modified_at: string;
  /** Experiment identifiers being compared */
  experiment_ids: string[];
  /** Reference dataset identifier */
  reference_dataset_id?: string;
  /** Extra metadata */
  extra?: KVMap;
  /** Feedback statistics */
  feedback_stats?: Record<string, number>;
}

/**
 * LangSmith platform settings
 */
interface LangSmithSettings {
  /** Tenant identifier */
  tenant_id: string;
  /** Organization identifier */
  organization_id?: string;
  /** Feature flags */
  flags?: Record<string, boolean>;
  /** Tenant settings */
  settings?: KVMap;
  /** Configured integrations */
  integrations?: Array<{
    /** Integration name */
    name: string;
    /** Integration configuration */
    config: KVMap;
  }>;
}

/**
 * Time delta for expressing durations
 */
interface TimeDelta {
  /** Days component */
  days?: number;
  /** Seconds component */
  seconds?: number;
  /** Microseconds component */
  microseconds?: number;
}

/**
 * LangChain message format
 */
interface LangChainBaseMessage {
  /** Message role (e.g., "human", "ai", "system") */
  role: string;
  /** Message content */
  content: string;
  /** Additional message data */
  additional_kwargs?: KVMap;
}

/**
 * Key-value map for flexible metadata and data storage
 */
type KVMap = Record<string, any>;

/**
 * Run type enumeration
 */
type RunType =
  | "llm"
  | "chain"
  | "tool"
  | "retriever"
  | "embedding"
  | "prompt"
  | "parser";

/**
 * Score type for feedback and evaluation
 */
type ScoreType = number | boolean | null;

/**
 * Value type for flexible data storage
 */
type ValueType = number | boolean | string | object | null;

/**
 * Data type enumeration
 */
type DataType = "kv" | "llm" | "chat";

import { RunCreate } from "langsmith/schemas";

const run: RunCreate = {
  name: "my-chain",
  run_type: "chain",
  start_time: Date.now(),
  inputs: { query: "What is LangSmith?" },
  project_name: "my-project",
};

import { ExampleCreate } from "langsmith/schemas";

const example: ExampleCreate = {
  dataset_id: "dataset-uuid",
  inputs: { question: "What is LangSmith?" },
  outputs: { answer: "LangSmith is a platform..." },
  metadata: { difficulty: "easy" },
};

import { FeedbackCreate } from "langsmith/schemas";

const feedback: FeedbackCreate = {
  run_id: "run-uuid",
  key: "user-rating",
  score: 0.9,
  comment: "Great response!",
};

import { UsageMetadata } from "langsmith/schemas";

const usage: UsageMetadata = {
  input_tokens: 50,
  output_tokens: 100,
  total_tokens: 150,
  input_token_details: {
    cache_read: 30,
    cache_creation: 20,
  },
  output_token_details: {
    reasoning: 40,
  },
};