Project Management API

/**
 * Create a new project
 * @param params - Project creation parameters
 * @returns Promise resolving to the created project
 */
createProject(params: CreateProjectParams): Promise<TracerSession>;

interface CreateProjectParams {
  /** Project name (required) */
  projectName: string;
  /** Project description */
  description?: string;
  /** Project metadata (will be stored in the 'extra' property of the returned TracerSession) */
  metadata?: Record<string, any>;
  /** Whether to upsert if exists */
  upsert?: boolean;
  /** Reference dataset ID */
  referenceDatasetId?: string;
}

interface TracerSession {
  /** Project ID */
  id: string;
  /** Project name */
  name: string;
  /** Description */
  description?: string;
  /** Additional metadata (stored in 'extra' property) */
  extra?: Record<string, any>;
  /** Creation timestamp */
  created_at: string;
  /** Update timestamp */
  updated_at?: string;
  /** Tenant ID */
  tenant_id: string;
}

import { Client } from "langsmith";

const client = new Client();

// Create project
const project = await client.createProject({
  projectName: "my-chatbot-v1",
  description: "Production chatbot deployment",
  metadata: { version: "1.0.0", env: "production" }
});

// Create or update
await client.createProject({
  projectName: "dev-project",
  upsert: true
});

/**
 * Read project details
 * @param params - Project identifier
 * @returns Promise resolving to project details
 */
readProject(params: {
  projectId?: string;
  projectName?: string;
}): Promise<TracerSession>;

// Read by name
const project = await client.readProject({
  projectName: "my-chatbot-v1"
});

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

/**
 * List projects with optional filtering
 * @param params - List parameters
 * @returns AsyncIterable of projects (stream)
 */
listProjects(params?: ListProjectsParams): AsyncIterable<TracerSessionResult>;

interface ListProjectsParams {
  /** Filter by project IDs */
  projectIds?: string[];
  /** Filter by exact project name */
  name?: string;
  /** Filter by project name substring */
  nameContains?: string;
  /** Filter by reference dataset ID */
  referenceDatasetId?: string;
  /** Filter by reference dataset name */
  referenceDatasetName?: string;
  /** Include statistics */
  includeStats?: boolean;
  /** Dataset version */
  datasetVersion?: string;
  /** Include reference-free projects */
  referenceFree?: boolean;
  /** Metadata filters */
  metadata?: Record<string, any>;
}

type TracerSessionResult = TracerSession;

// List all projects (stream)
for await (const project of client.listProjects()) {
  console.log(project.name);
}

// Filter by reference dataset
const projects = [];
for await (const project of client.listProjects({
  referenceDatasetName: "qa-eval"
})) {
  projects.push(project);
}

// Filter by name substring
for await (const project of client.listProjects({
  nameContains: "prod"
})) {
  console.log(project.name, project.id);
}

/**
 * Update project details
 * @param projectId - Project ID to update
 * @param params - Update parameters
 * @returns Promise resolving to updated project
 */
updateProject(
  projectId: string,
  params: UpdateProjectParams
): Promise<TracerSession>;

interface UpdateProjectParams {
  /** New project name */
  name?: string;
  /** New description */
  description?: string;
  /** New metadata */
  metadata?: Record<string, any>;
  /** End time timestamp */
  endTime?: Date | string;
}

await client.updateProject(project.id, {
  description: "Updated description",
  metadata: { version: "1.0.1" }
});

// End a project
await client.updateProject(project.id, {
  endTime: new Date()
});

/**
 * Delete a project
 * @param params - Project identifier
 * @returns Promise resolving when deletion completes
 */
deleteProject(params: {
  projectId?: string;
  projectName?: string;
}): Promise<void>;

// Delete by name
await client.deleteProject({
  projectName: "my-chatbot-v1"
});

// Delete by ID
await client.deleteProject({
  projectId: projectId
});

/**
 * Check if a project exists
 * @param params - Project identifier
 * @returns Promise resolving to boolean
 */
hasProject(params: {
  projectId?: string;
  projectName?: string;
}): Promise<boolean>;

const exists = await client.hasProject({
  projectName: "my-project"
});

if (exists) {
  console.log("Project exists");
} else {
  await client.createProject({
    projectName: "my-project"
  });
}

/**
 * Get URL for viewing project in LangSmith UI
 * @param params - Project identifier
 * @returns Promise resolving to project URL string
 */
getProjectUrl(params: {
  projectId?: string;
  projectName?: string;
}): Promise<string>;

const url = await client.getProjectUrl({
  projectName: "my-project"
});

console.log("View project:", url);

// Good: Descriptive and hierarchical
"production-chatbot"
"staging-chatbot-v2"
"experiment-gpt4-baseline"

// Avoid: Generic or unclear
"project1"
"test"
"default"

await client.createProject({
  projectName: "production-app",
  metadata: {
    environment: "production",
    version: "2.1.0",
    deployment: "us-west-2",
    team: "ai-platform"
  }
});

// Create for experiment
const project = await client.createProject({
  projectName: "experiment-2024-01-15"
});

// Run traces to project
// ... your application code ...

// Mark as completed
await client.updateProject(project.id, {
  endTime: new Date(),
  metadata: {
    status: "completed",
    results: "documented in wiki"
  }
});