ctx.prompt

// Load a prompt from the registry
const prompt = await ctx.prompts.load('org/acme/invoice-extraction@v2');

// Render with variables
const rendered = prompt.render({
  vendor_name: 'Acme Supplies',
  document_type: 'purchase_order',
});

// Use in an LLM call with full telemetry metadata
const response = await ctx.llm.complete({
  prompt: rendered,
  temperature: 0.2,
  promptMetadata: prompt.toCallMetadata(),  // Links response back to the prompt version
});

// Compose multiple prompt layers
// Useful for: base persona + task-specific instructions + user preferences
const composed = await ctx.prompts.compose([
  'org/acme/base-analyst-persona',
  'org/acme/invoice-extraction-task',
  'org/acme/formal-output-format',
], {
  variables: {
    organization: 'Acme Corp',
    currency: 'USD',
  },
});

console.log(composed.estimatedTokens);  // Know the cost before calling
console.log(composed.layers);           // Each source prompt

const response = await ctx.llm.complete({
  prompt: composed.content,
  promptMetadata: composed.metadata,
});

// Discover available prompts in your namespace
const prompts = ctx.prompts.list({
  scope: 'org',        // 'org', 'suite', or 'system'
  namespace: 'acme',
});

for (const meta of prompts) {
  console.log(meta.id, meta.version, meta.estimatedTokens);
}

// Estimate tokens without loading content
const tokenCount = ctx.prompts.estimateTokens('org/acme/invoice-extraction@v2', {
  model: 'gpt-4o',
});
console.log(`Prompt will use ~${tokenCount} tokens`);

// Get the most current version of a prompt key
// (respects A/B test assignments, org overrides, etc.)
const effective = await ctx.prompts.getEffective('invoice-extraction');
if (effective) {
  const rendered = effective.render({ vendor: vendorName });
  // effective.meta.version tells you which version is active
}