Examples

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
}

from basalt import BasaltSDK

basalt = BasaltSDK(api_key=os.environ.get('BASALT_API_KEY'))

def get_basic_prompt():
    error, prompt, generation = await basalt.prompt.get('welcome-message')
    
    if error:
        print(f"Failed to get prompt: {error.message}")
        return None
    
    return prompt

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
}

def get_specific_version():
    error, prompt, generation = await basalt.prompt.get(
        slug='product-description',
        version='2.1.0'
    )
    
    if error:
        print(f"Failed to get prompt version: {error.message}")
        return None
    
    print(f"Using prompt version: {prompt.model.version}")
    return prompt

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
}

def get_environment_specific_prompt():
    # Determine environment
    environment = os.environ.get('ENVIRONMENT', 'staging')
    is_prod = environment == 'production'
    
    tag = 'production' if is_prod else 'staging'
    
    error, prompt, generation = await basalt.prompt.get(
        slug='checkout-flow',
        tag=tag
    )
    
    if error:
        print(f"Failed to get {tag} prompt: {error.message}")
        return None
    
    print(f"Using {tag} prompt variant")
    return prompt

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
}

def get_personalized_prompt(user_name, company_name):
    from datetime import datetime
    
    error, prompt, generation = await basalt.prompt.get(
        slug='personalized-email',
        variables={
            'userName': user_name,
            'companyName': company_name,
            'date': datetime.now().strftime('%Y-%m-%d')
        }
    )
    
    if error:
        print(f"Failed to get personalized prompt: {error.message}")
        return None
    
    return prompt

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
}

def get_complex_prompt():
    error, prompt, generation = 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:
        print(f"Failed to get complex prompt: {error.message}")
        return None
    
    return prompt

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
}

def list_all_prompts():
    error, prompts = await basalt.prompt.list()
    
    if error:
        print(f"Failed to list prompts: {error.message}")
        return []
    
    print(f"Found {len(prompts)} prompts")
    return prompts

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
}

def list_feature_prompts(feature_slug):
    error, prompts = await basalt.prompt.list(
        feature_slug=feature_slug
    )
    
    if error:
        print(f"Failed to list prompts for feature {feature_slug}: {error.message}")
        return []
    
    print(f"Found {len(prompts)} prompts for feature {feature_slug}")
    return prompts

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
}

def find_live_prompts():
    error, prompts = await basalt.prompt.list()
    
    if error:
        print(f"Failed to list prompts: {error.message}")
        return []
    
    # Find only live prompts
    live_prompts = [prompt for prompt in prompts if prompt.status == 'live']
    
    print(f"Found {len(live_prompts)} live prompts out of {len(prompts)} total")
    return live_prompts

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
}

def find_prompts_by_tag(tag_name):
    error, prompts = await basalt.prompt.list()
    
    if error:
        print(f"Failed to list prompts: {error.message}")
        return []
    
    # Find prompts that have the specified tag available
    prompts_with_tag = [
        prompt for prompt in prompts 
        if tag_name in prompt.availableTags
    ]
    
    print(f"Found {len(prompts_with_tag)} prompts with tag \"{tag_name}\"")
    return prompts_with_tag

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
}

def get_prompt_details(prompt_slug):
    error, details = await basalt.prompt.describe(prompt_slug)
    
    if error:
        print(f"Failed to describe prompt {prompt_slug}: {error.message}")
        return None
    
    print(f"Prompt: {details.name}")
    print(f"Status: {details.status}")
    print(f"Variables: {len(details.variables)}")
    
    return details

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
}

def get_prompt_variables(prompt_slug):
    error, details = await basalt.prompt.describe(prompt_slug)
    
    if error:
        print(f"Failed to describe prompt {prompt_slug}: {error.message}")
        return []
    
    # Map variables to a simpler format
    variables = [{
        'name': variable.label,
        'type': variable.type,
        'description': variable.description or 'No description provided'
    } for variable in details.variables]
    
    print(f"Prompt \"{details.name}\" has {len(variables)} variables:")
    for v in variables:
        print(f"- {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
}

def check_available_versions(prompt_slug):
    error, details = await basalt.prompt.describe(prompt_slug)
    
    if error:
        print(f"Failed to describe prompt {prompt_slug}: {error.message}")
        return []
    
    print(f"Prompt \"{details.name}\" has {len(details.availableVersions)} versions:")
    print(f"- Current version: {details.version}")
    print("- Available versions:")
    for v in details.availableVersions:
        is_current = " (current)" if v == details.version else ""
        print(f"  - {v}{is_current}")
    
    return details.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
}

async def build_prompt_selection_data():
    # Step 1: Get all prompts
    error, prompts = await basalt.prompt.list()
    
    if error:
        print(f"Failed to list prompts: {error.message}")
        return None
    
    # Step 2: Collect detailed info about each prompt
    prompt_details = []
    
    for prompt in prompts:
        desc_error, details = await basalt.prompt.describe(prompt.slug)
        
        if desc_error:
            print(f"Couldn't get details for {prompt.slug}: {desc_error.message}")
            continue
        
        prompt_details.append({
            'slug': details.slug,
            'name': details.name,
            'description': details.description or 'No description',
            'status': details.status,
            'variables': details.variables,
            'currentVersion': details.version,
            'versions': details.availableVersions,
            'tags': details.availableTags
        })
    
    return prompt_details

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
  }
}

async def run_support_workflow(user_query):
    # Step 1: Use classifier prompt to determine intent
    error, classifier_prompt = await basalt.prompt.get(
        slug='support-query-classifier',
        variables={
            'query': user_query
        }
    )
    
    if error:
        print(f"Failed to get classifier prompt: {error.message}")
        return None
    
    # Use the classifier prompt with your LLM provider...
    classification_result = await your_llm_provider.complete(classifier_prompt.text)
    intent = parse_classification_result(classification_result)
    
    # Step 2: Based on the intent, get the appropriate response prompt
    response_slug = f"support-response-{intent}"
    
    error, response_prompt = await basalt.prompt.get(
        slug=response_slug,
        variables={
            'query': user_query,
            # Additional context based on intent
            **get_context_for_intent(intent)
        }
    )
    
    if error:
        print(f"Failed to get response prompt {response_slug}: {error.message}")
        return None
    
    # Use the response prompt with your LLM provider...
    final_response = await your_llm_provider.complete(response_prompt.text)
    
    return {
        'intent': intent,
        'response': final_response
    }

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
}

async def get_feature_flagged_prompt(prompt_slug):
    # Get user segment (e.g., from user profile)
    user_segment = await get_user_segment()
    
    # Map user segment to prompt tag
    if user_segment == 'beta-tester':
        prompt_tag = 'beta'
    elif user_segment == 'premium':
        prompt_tag = 'premium'
    else:
        prompt_tag = 'standard'
    
    # Get the appropriate prompt variant using tags
    error, prompt, generation = await basalt.prompt.get(
        slug=prompt_slug,
        tag=prompt_tag
    )
    
    if error:
        # Fall back to standard prompt if specific tag doesn't exist
        if error.name == 'NotFoundError' and prompt_tag != 'standard':
            print(f"Tag {prompt_tag} not found for {prompt_slug}, falling back to standard")
            return await get_feature_flagged_prompt('standard')
        
        print(f"Failed to get prompt {prompt_slug} with tag {prompt_tag}: {error.message}")
        return None
    
    return prompt

Start Here

Guides

Learn more

Getting Prompts

Basic Prompt Retrieval

Getting a Specific Version

Using Environment-Specific Tags

Replacing Variables

Combining Multiple Parameters

Listing Prompts

List All Prompts

List Prompts by Feature

Finding and Filtering Prompts

Finding Prompts with Specific Tags

Describing Prompts

Get Basic Prompt Details

Extract Variable Names and Types

Check Available Versions

Practical Application Examples

Building a Prompt Selection UI

Implementing a Prompt-Based Workflow

Feature Flag Integration

​Getting Prompts

​Basic Prompt Retrieval

​Getting a Specific Version

​Using Environment-Specific Tags

​Replacing Variables

​Combining Multiple Parameters

​Listing Prompts

​List All Prompts

​List Prompts by Feature

​Finding and Filtering Prompts

​Finding Prompts with Specific Tags

​Describing Prompts

​Get Basic Prompt Details

​Extract Variable Names and Types

​Check Available Versions

​Practical Application Examples

​Building a Prompt Selection UI

​Implementing a Prompt-Based Workflow

​Feature Flag Integration

Getting Prompts

Basic Prompt Retrieval

Getting a Specific Version

Using Environment-Specific Tags

Replacing Variables

Combining Multiple Parameters

Listing Prompts

List All Prompts

List Prompts by Feature

Finding and Filtering Prompts

Finding Prompts with Specific Tags

Describing Prompts

Get Basic Prompt Details

Extract Variable Names and Types

Check Available Versions

Practical Application Examples

Building a Prompt Selection UI

Implementing a Prompt-Based Workflow

Feature Flag Integration