PromptCloud SDK

Welcome to the PromptCloud SDK! This SDK facilitates interactions with the PromptCloud API, offering dynamic prompt creation, customization, and real-time completions. Leverage the CompletionBuilder to craft intricate AI interactions with ease.

Table of Contents

• Installation
• Initialization
• Core Features
  • Prompts
  • The CompletionBuilder
    • Build
    • Completion
    • Stream Completion
  • Examples
• API Reference
• Error Handling
• Support and Contributions

Installation

To add the PromptCloud SDK to your project:

npm i promptcloud

Initialization

Start by setting up the client with your organization's API key:

import { PromptCloud } from 'promptcloud';

const cloud = PromptCloud.getClient({ apiKey: process.env.PROMPTCLOUD_API_KEY });

Core Features

Prompts

The PromptCloud client you initialize will connect you with the PromptCloud dashboard. This means you will be able to fetch your prompts through the SDK and use them in your code. To list what prompts are available in your organization:

const prompts: Prompt[] = await cloud.listPrompts();

To fetch a specific prompt by name:

const prompt: Prompt = await cloud.getPrompt("SpeechGenerator");

Prompts can have placeholder variables that need to be filled in. These variables are denoted in your prompt in a {{}} double curly bracket syntax. You can fill these variables in your prompt by doing the following:

const hydratedPrompt: Prompt = await cloud
  .getPrompt("SpeechGenerator")
  .hydrate({
    name: 'Elon Musk',
    topic: 'SpaceX'
  });

If you're unsure what placeholders a prompt has or want to display them, you can use:

const vars = await cloud
  .getPrompt("SpeechGenerator")
  .getPlaceholders();

The CompletionBuilder

The CompletionBuilder offers a fluid interface to create, customize, and get completions. You can access the builder from your instance of the PromptCloud client, as shown below:

const props = cloud.builder...;

The above snippet shows how you can access the static builder property on your client. The builder acts as a query builder, where you can chain methods to construct an OpenAI completion. Methods can be chained together to build a query, and should be done in the order you want them to execute in. For example, if I want to add a prompt from the dashboard, and add a message manually to the query:

const props = await cloud
  .builder
  .prompt("SpeechGenerator")
  .message({ role: 'system', content: 'Limit your response to 2 sentences' })
  .build();

The resulting props from this example query will a messages array with the SpeechGenerator prompt first, then the manual message following it. These methods can be chained together as much as you see fit, and will build the completion parameters in the order in which you write the query:

...
  .builder
  .prompt("Prompt1")
  .message(...)
  .messages(...)
  .prompt("Prompt2")
  .prompt("Prompt3")
  .message(...)

CompletionBuilder queries can end in one of the following 3 primary actions:

build()

Returns the parameters object that you need to get an OpenAI chat completion yourself

const props = await cloud
  .builder
  .prompt("SpeechGenerator")
  .hydrate({ name: 'Elon Musk', topic: 'AI' })
  .build();

/*
props = {
  messages: [
    { role: 'system', content: 'Generate a speech given by Elon Musk on the following topic: AI' }
  ]
}
*/

const completion = await openai.chat.completions.create(props);

completion()

Works off of build() and performs the completion step for you

const completion = await cloud
  .builder
  .prompt("SpeechGenerator")
  .hydrate({ name: 'Elon Musk', topic: 'AI' })
  .completion();

streamCompletion()

Works off of build() and returns a generator object with the completion stream

const stream = await cloud
  .builder
  .prompt("SpeechGenerator")
  .hydrate({ name: 'Elon Musk', topic: 'AI' })
  .streamCompletion();

for await (const chunk of stream) {
  console.log(chunk);
}

There are many helpful methods that can be chained together in these builder operations, from fetching a PromptCloud prompt, to adding messages, to adding function calls (and many more).

• Selecting a Model:

builder.model('gpt-3.5-turbo');

• Fetching a Prompt:

builder
  .prompt("SpeechGenerator");

• Hydrating a prompt with Data:

builder
  .prompt("SpeechGenerator")
  .hydrate({ name: 'Elon Musk', topic: 'AI' })

• Adding Messages:

builder.message({ role: 'system', content: 'You are a helpful assistant' });

• Batch Adding Messages:

builder.messages([
  { role: 'system', content: 'You are a helpful assistant' },
  { role: 'user', content: 'Hey, how are you?' }
  ]);

• Setting Token Limits:

builder.maxTokens(150);

... and many more such as frequencyPenalty, logitBias, n, presencePenalty, stop, stream, temperature, topP, user.

Examples

Say you're creating an assistant application with the PromptCloud SDK, and you have a standard system prompt that gives the assistant its character / speaking style - BotPrompt. To get a completion for a user's message to the bot:

async function reply(message) {
  const completion = await cloud
    .builder
    .prompt(`BotPrompt`)
    .hydrate({
      userFirstName: `Richard Hendrix`,
      userAge: 26,
      currentDate: new Date().toIsoString()
    });
    .message(message)
    .completion();

  return completion.choices[0].message;
}

Now, if you wanted to not only reply to the user's message, but you wanted to give the context of previous messages between the user & assistant, you could add .messages() to the chain:

let conversationHistory = [...];

async function reply(message) {
  const completion = await cloud
    .builder
    .prompt(`BotPrompt`)
    .hydrate({
      userFirstName: `Richard Hendrix`,
      userAge: 26,
      currentDate: new Date().toIsoString()
    });
    .messages(conversationHistory)
    .message(message)
    .completion();

  return completion.choices[0].message;
}

If you wanted to stream the response back to the user, you could make the following change:

let conversationHistory = [...];

async function reply(message) {
  const stream = await cloud
    .builder
    .prompt(`BotPrompt`)
    .hydrate({
      userFirstName: `Richard Hendrix`,
      userAge: 26,
      currentDate: new Date().toIsoString()
    });
    .messages(conversationHistory)
    .message(message)
    .streamCompletion();

  for await (const chunk of stream) {
    console.log(chunk.choices[0].delta);
  }
}

API Reference

• PromptCloud:

  • getClient(props: PromptCloudOptions): Retrieve the SDK client.
  • getPrompt(name: string): Fetch a named prompt.
  • listPrompts(): Get a list of all available prompts.

• CompletionBuilder:

  • prompt(promptName: string): Choose a named prompt.
  • hydrate(variables: Json): Customize the prompt with variables.
  • message(message: ChatCompletionMessageParam): Add a message to the chat sequence.
  • messages(messages: ChatCompletionMessageParam[]): Add multiple messages to the chat sequence.
  • function(schema: ChatCompletionCreateParams.Function): add a function schema object to use in an OpenAI function call
  • functionCall(call: 'auto' | 'none' | ChatCompletionCreateParams.FunctionCallOption): dictates whether the function call should be automatic or pre-determined
  • model(model: CompletionModel) which version of the OpenAI model to use in the completion
  • async build(settings?: CompletionOptionalSettings): Promise<ChatCompletionCreateParams> build the completion creation parameter object. Optional - provide config settings (top_p, n, etc) that you didn't set in the query builder
  • async completion(settings?: ChatCompletionOptionalSettings): Get a completion based on the built query. Optional - provide config settings (top_p, n, etc) that you didn't set in the query builder
  • async streamCompletion(settings?: CompletionOptionalSettings): Get a completion stream generator object. Optional - provide config settings (top_p, n, etc) that you didn't set in the query builder

Error Handling

Stay informed with clear error indications. Enable logging for in-depth logs. Watch out for specific error classes like PromptCloudError, OrganizationNotSetError, and PromptNotFoundError to streamline error handling.

Support and Contributions

For issues or suggestions, please visit our GitHub repository. Your contributions are valued, and we encourage you to submit a pull request for enhancements.

We hope you enjoy using the PromptCloud SDK! We're looking forward to seeing what you build with it.