Runs

A Run is an interface to manage the execution of one or more prompts on the same pipeline. Every time your pipeline is ran a new Run instance will be created and for each execution a unique Run identifier is set. Runs are useful as they allow you to track each generation call with details for each prompt and also track the pipeline execution as a whole.

Run instances can also be used to call generate and automatically track prompt generation information. run.generate() will automatically pull the prompt and call the underlaying AI model to get the generation result:

import { Promptd } from '@promptd-js/client';
import { OpenAIChatApi } from 'llm-api';
 
const promptdApiKey = 'xxx'; // Grab this in your Promptd project settings page.
const promptd = new Promptd({ apiKey: promptdApiKey });
 
// We're using Open AI's GPT4 model in this example, but we're LLM-agnostic:
const openAiKey = 'yyy'; // Grab this in your Open AI account.
const ai = new OpenAIChatApi({ apiKey: openAiKey },{ model: 'gpt-4-turbo' });
 
export const createPodcast = async(title: string) => {
  // Set execution status to Running
  const run = await promptd.startRun({
    name: `Script create Podcast for ${new Date().toLocaleDateString()}`
  });
 
  try {
    // Introduction prompt execution
    const writeIntroductionTemplate = promptd.template('write-introduction');
    const intro = await run.generate(
      writeIntroductionTemplate,
      { title },
      { ai },
    );
 
    // Comment about introduction prompt execution
    await run.comment('Podcast introduction created');
 
    // Body prompt execution
    const body = await run.generate(
      'write-body',
      {
        title,
        intro: intro.data.message,
      },
      { ai },
    );
 
    // Comment about body prompt execution
    await run.comment('Podcast body created');
 
    // Conclusion prompt execution
    const WriteConclusionTemplate = promptd.template('write-conclusion');
    const conclusion = await conclusionPrompt.generate(
      WriteConclusionTemplate,
      {
        title,
        intro: intro.data.message,
        body: body.data.message,
      },
      { ai },
    );
 
    // Comment about conclusion prompt execution
    await run.comment('Podcast conclusion created');
 
    const podcast = concatenateEpisode(
      intro.data.message,
      body.data.message,
      conclusion.data.message,
    );
    generatePodcastAudio(podcast);
 
    // Comment about podcast audio
    await run.comment('Podcast audio created');
 
    // Set execution status to Completed
    await run.end(podcast);
  } catch (error) {
    // Set execution status to Failed
    await run.error(error as Error);
  }
};

Note that in the example above we use the method run.generate() in two ways:

Passing object template as first parameter, like in introduction prompt execution
Passing prompt slug as first parameter, like in body prompt execution

📝 How to use

To start tracking the execution use the startRun() method at the beginning of the pipeline and end() to mark its conclusion. You can also handle error statuses using method error():

// Set execution status to Running
const run = await promptd.startRun({name: 'Script say hello'});
 
try {
  // prompts execution
 
  // Set execution status to Completed
  await run.end(result);
} catch (error) {
  // Set execution status to Failed
  await run.error(error as Error);
}

Calling startRun() will update the run status to Running, end() will update the status to Completed and save the result, and error() will update the status to Failed and save the error. After end() or error() are called, the run is considered closed and won't accept any additional method calls.

Optionally, it is possible to add comments for the execution using method comment():

// Set execution status to Running
const run = await promptd.startRun({name: 'Script say hello'});
 
try {
  // promptA execution
 
  // Optionally, add comment for the execution
  await run.comment('Some important comment');
 
  // promptB execution
 
  // Set execution status to Completed
  await run.end(result);
} catch (error) {
  // Set execution status to Failed
  await run.error(error as Error);
}

You can check all the Run's information on your Promptd's dashboard.

Full listing

import { Promptd } from '@promptd-js/client';
import { OpenAIChatApi } from 'llm-api';
 
const promptdApiKey = 'xxx'; // Grab this in your Promptd project settings page.
const promptd = new Promptd({ apiKey: promptdApiKey });
 
// We're using Open AI's GPT4 model in this example, but we're LLM-agnostic:
const openAiKey = 'yyy'; // Grab this in your Open AI account.
const ai = new OpenAIChatApi({ apiKey: openAiKey },{ model: 'gpt-4-turbo' });
 
export const createPodcast = async(title: string) => {
  // Set execution status to Running
  const run = await promptd.startRun({
    name: `Script create Podcast for ${new Date().toLocaleDateString()}`
  });
 
  try {
    // Introduction prompt execution
    const writeIntroductionTemplate = promptd.template('write-introduction');
    const introPrompt = writeIntroductionTemplate.render({ title });
    const intro = await introPrompt.generate({}, ai);
 
    // Comment about introduction prompt execution
    await run.comment('Podcast introduction created');
 
    // Body prompt execution
    const writeBodyTemplate = promptd.template('write-body');
    const bodyPrompt = writeBodyTemplate.render({
      title,
      intro: intro.data.message,
    });
    const body = await bodyPrompt.generate({}, ai);
 
    // Comment about body prompt execution
    await run.comment('Podcast body created');
 
    // Conclusion prompt execution
    const WriteConclusionTemplate = promptd.template('write-conclusion');
    const conclusionPrompt = WriteConclusionTemplate.render({
      title,
      intro: intro.data.message,
      body: body.data.message,
    });
    const conclusion = await conclusionPrompt.generate({}, ai);
 
    // Comment about conclusion prompt execution
    await run.comment('Podcast conclusion created');
 
    const podcast = concatenateEpisode(
      intro.data.message,
      body.data.message,
      conclusion.data.message,
    );
    generatePodcastAudio(podcast);
 
    // Comment about podcast audio
    await run.comment('Podcast audio created');
 
    // Set execution status to Completed
    await run.end(podcast);
  } catch (error) {
    // Set execution status to Failed
    await run.error(error as Error);
  }
};

Template Analytics and Tracking