This guide provides practical examples of using the Basalt SDK for common prompt management scenarios. These examples demonstrate how to use the get, list, and describe methods effectively in your applications.

​
Getting Prompts

​
Basic Prompt Retrieval

The simplest way to get a prompt is by its slug:

import { BasaltSDK } from '@basalt/sdk'

const basalt = new BasaltSDK({ apiKey: process.env.BASALT_API_KEY })

async function getBasicPrompt() {
  const { value, error } = await basalt.prompt.get('welcome-message')
  
  if (error) {
    console.error('Failed to get prompt:', error.message)
    return null
  }
  
  return value
}

​
Getting a Specific Version

When you need a specific version of a prompt:

async function getSpecificVersion() {
  const { value, error } = await basalt.prompt.get({
    slug: 'product-description',
    version: '2.1.0'
  })
  
  if (error) {
    console.error('Failed to get prompt version:', error.message)
    return null
  }
  
  console.log(`Using prompt version: ${value.model.version}`)
  return value
}

​
Using Environment-Specific Tags

Get prompts with different tags based on your environment:

async function getEnvironmentSpecificPrompt() {
  // Determine environment
  const environment = process.env.NODE_ENV === 'production' ? 'production' : 'staging'
  
  const { value, error } = await basalt.prompt.get({
    slug: 'checkout-flow',
    tag: environment
  })
  
  if (error) {
    console.error(`Failed to get ${environment} prompt:`, error.message)
    return null
  }
  
  console.log(`Using ${environment} prompt variant`)
  return value
}

​
Replacing Variables

Replace placeholder variables with actual values:

async function getPersonalizedPrompt(userName: string, companyName: string) {
  const { value, error } = await basalt.prompt.get({
    slug: 'personalized-email',
    variables: {
      userName,
      companyName,
      date: new Date().toLocaleDateString()
    }
  })
  
  if (error) {
    console.error('Failed to get personalized prompt:', error.message)
    return null
  }
  
  return value
}

​
Combining Multiple Parameters

Use multiple parameters together for precise control:

async function getComplexPrompt() {
  const { value, error } = await basalt.prompt.get({
    slug: 'product-recommendation',
    version: '3.0.0',
    variables: {
      productCategory: 'electronics',
      userPreferences: 'budget-friendly, high-quality',
      maxResults: 5
    },
    cache: false // Always get the latest version
  })
  
  if (error) {
    console.error('Failed to get complex prompt:', error.message)
    return null
  }
  
  return value
}

​
Listing Prompts

​
List All Prompts

Get a list of all available prompts:

async function listAllPrompts() {
  const { value, error } = await basalt.prompt.list()
  
  if (error) {
    console.error('Failed to list prompts:', error.message)
    return []
  }
  
  console.log(`Found ${value.length} prompts`)
  return value
}

​
List Prompts by Feature

Get prompts that belong to a specific feature:

async function listFeaturePrompts(featureSlug: string) {
  const { value, error } = await basalt.prompt.list({
    featureSlug
  })
  
  if (error) {
    console.error(`Failed to list prompts for feature ${featureSlug}:`, error.message)
    return []
  }
  
  console.log(`Found ${value.length} prompts for feature ${featureSlug}`)
  return value
}

​
Finding and Filtering Prompts

List prompts and then filter them programmatically:

async function findLivePrompts() {
  const { value, error } = await basalt.prompt.list()
  
  if (error) {
    console.error('Failed to list prompts:', error.message)
    return []
  }
  
  // Find only live prompts
  const livePrompts = value.filter(prompt => prompt.status === 'live')
  
  console.log(`Found ${livePrompts.length} live prompts out of ${value.length} total`)
  return livePrompts
}

​
Finding Prompts with Specific Tags

List prompts and filter by available tags:

async function findPromptsByTag(tagName: string) {
  const { value, error } = await basalt.prompt.list()
  
  if (error) {
    console.error('Failed to list prompts:', error.message)
    return []
  }
  
  // Find prompts that have the specified tag available
  const promptsWithTag = value.filter(prompt => 
    prompt.availableTags.includes(tagName)
  )
  
  console.log(`Found ${promptsWithTag.length} prompts with tag "${tagName}"`)
  return promptsWithTag
}

​
Describing Prompts

​
Get Basic Prompt Details

Get detailed information about a prompt:

async function getPromptDetails(promptSlug: string) {
  const { value, error } = await basalt.prompt.describe(promptSlug)
  
  if (error) {
    console.error(`Failed to describe prompt ${promptSlug}:`, error.message)
    return null
  }
  
  console.log(`Prompt: ${value.name}`)
  console.log(`Status: ${value.status}`)
  console.log(`Variables: ${value.variables.length}`)
  
  return value
}

​
Extract Variable Names and Types

Get information about a prompt’s variables:

async function getPromptVariables(promptSlug: string) {
  const { value, error } = await basalt.prompt.describe(promptSlug)
  
  if (error) {
    console.error(`Failed to describe prompt ${promptSlug}:`, error.message)
    return []
  }
  
  // Map variables to a simpler format
  const variables = value.variables.map(variable => ({
    name: variable.label,
    type: variable.type,
    description: variable.description || 'No description provided'
  }))
  
  console.log(`Prompt "${value.name}" has ${variables.length} variables:`)
  variables.forEach(v => {
    console.log(`- ${v.name} (${v.type}): ${v.description}`)
  })
  
  return variables
}

​
Check Available Versions

Get information about available versions of a prompt:

async function checkAvailableVersions(promptSlug: string) {
  const { value, error } = await basalt.prompt.describe(promptSlug)
  
  if (error) {
    console.error(`Failed to describe prompt ${promptSlug}:`, error.message)
    return []
  }
  
  console.log(`Prompt "${value.name}" has ${value.availableVersions.length} versions:`)
  console.log(`- Current version: ${value.version}`)
  console.log('- Available versions:')
  value.availableVersions.forEach(v => {
    const isCurrent = v === value.version ? ' (current)' : ''
    console.log(`  - ${v}${isCurrent}`)
  })
  
  return value.availableVersions
}

​
Practical Application Examples

​
Building a Prompt Selection UI

Use list and describe to build a prompt selection interface:

async function buildPromptSelectionData() {
  // Step 1: Get all prompts
  const { value: prompts, error: listError } = await basalt.prompt.list()
  
  if (listError) {
    console.error('Failed to list prompts:', listError.message)
    return null
  }
  
  // Step 2: Collect detailed info about each prompt
  const promptDetails = []
  
  for (const prompt of prompts) {
    const { value: details, error: describeError } = await basalt.prompt.describe(prompt.slug)
    
    if (describeError) {
      console.warn(`Couldn't get details for ${prompt.slug}:`, describeError.message)
      continue
    }
    
    promptDetails.push({
      slug: details.slug,
      name: details.name,
      description: details.description || 'No description',
      status: details.status,
      variables: details.variables,
      currentVersion: details.version,
      versions: details.availableVersions,
      tags: details.availableTags
    })
  }
  
  return promptDetails
}

​
Implementing a Prompt-Based Workflow

Chain multiple prompts together for a workflow:

async function runSupportWorkflow(userQuery: string) {
  // Step 1: Use classifier prompt to determine intent
  const { value: classifierPrompt, error: classifierError } = await basalt.prompt.get({
    slug: 'support-query-classifier',
    variables: {
      query: userQuery
    }
  })
  
  if (classifierError) {
    console.error('Failed to get classifier prompt:', classifierError.message)
    return null
  }
  
  // Use the classifier prompt with your LLM provider...
  const classificationResult = await yourLLMProvider.complete(classifierPrompt.text)
  const intent = parseClassificationResult(classificationResult)
  
  // Step 2: Based on the intent, get the appropriate response prompt
  const responseSlug = `support-response-${intent}`
  
  const { value: responsePrompt, error: responseError } = await basalt.prompt.get({
    slug: responseSlug,
    variables: {
      query: userQuery,
      // Additional context based on intent
      ...getContextForIntent(intent)
    }
  })
  
  if (responseError) {
    console.error(`Failed to get response prompt ${responseSlug}:`, responseError.message)
    return null
  }
  
  // Use the response prompt with your LLM provider...
  const finalResponse = await yourLLMProvider.complete(responsePrompt.text)
  
  return {
    intent,
    response: finalResponse
  }
}

​
Feature Flag Integration

Use prompt tags as feature flags:

async function getFeatureFlaggedPrompt(promptSlug: string) {
  // Get user segment (e.g., from user profile)
  const userSegment = await getUserSegment()
  
  // Map user segment to prompt tag
  let promptTag
  
  switch (userSegment) {
    case 'beta-tester':
      promptTag = 'beta'
      break
    case 'premium':
      promptTag = 'premium'
      break
    default:
      promptTag = 'standard'
  }
  
  // Get the appropriate prompt variant using tags
  const { value, error } = await basalt.prompt.get({
    slug: promptSlug,
    tag: promptTag
  })
  
  if (error) {
    // Fall back to standard prompt if specific tag doesn't exist
    if (error.name === 'NotFoundError' && promptTag !== 'standard') {
      console.warn(`Tag ${promptTag} not found for ${promptSlug}, falling back to standard`)
      return getFeatureFlaggedPrompt('standard')
    }
    
    console.error(`Failed to get prompt ${promptSlug} with tag ${promptTag}:`, error.message)
    return null
  }
  
  return value
}