How to use the Brainglue Chain API?

Learn how to use the Brainglue Chain API and how to bring AI workflows into production quickly.

Quick Recap on How Brainglue Works

Brainglue is an AI playground that allows you to build and configure LLM prompt chains that can use different configurations and language models to complete complex generative AI tasks, such as content creation, text classification, data analysis, and more. Every Brainglue Chain has a unique API endpoint that can be used to trigger the chain, which in turn will return the outputs of every prompt in the chain so they can be used in other contexts or applications.

One of the most essential features of Brainglue is the ability to define global variables that can be used in any of the prompts in the chain. When you run a chain, Brainglue will use the default values set in the playground. However, these variables are actually dynamic variables that can be overridden when invoking the chain via its unique API endpoint.

In this guide, we will explore how we can configure the variables of a chain and use them dynamically via the Chain API.

Endpoint Usage

Every chain in Brainglue comes out-of-box with an invocation endpoint that allows you to trigger the chain and run its underlying LLM prompts from any client or application capable of interacting with a RESTful API.

You can find the endpoint URL at the top of the chain in the trigger module:

API Trigger

API trigger endpoints are secured with a chain secret that should be passed with every request.

To pass the secret, use any of the following:

• Pass bg_secret as a request header with your chain secret as the value.

• Pass bg_secret as a query parameter with your chain secret as the value.

• Pass bg_secret as a body parameter with your chain secret as the value.

As you can see, the Brainglue Chain API is extremely forgiving and allows you to set the authentication secret in multiple ways. This same principle applies to the way you can override the variables in a chain.

Chain Variables

As said before, in Brainglue, you can define global variables that can be used in the context of an LLM prompt.

Let's look at the "Synonym Poem Generator" chain example used when you create a Brainglue account.

This particular chain generates a poem about a given word by first generating a list of synonyms for that word and then using that list to write a poem and its title. In this chain, we have a chain variable with the key word and a default value of happy

Variables

By default, this chain will run and use the default value of happy any prompt in the chain that references the variable @word. In the case of this chain, the first prompt references the @word variable to generate a list of 10 synonyms, and a subsequent prompt uses that list to write a poem.

Prompt Module

Now, every time that we invoke this chain via the API, Brainglue will run the chain with whatever default value was set; in this case, the word happy.

However, the API allows us to override that value by simply passing a query parameter or body parameter with the name/key of the variable. So, for example, we could invoke this same API and generate a poem with the synonyms of the word wise, by simply passing a query parameter or body parameter word with a value of wise:

NodeJS Request with Body Params

const axios = require('axios');

const url = 'https://run.brainglue.ai/clm00000000000000000';
const headers = {
  'bg_secret': '{{your_chain_secret}}'
};
const data = {
  word: 'wise'
};

axios.post(url, data, { headers })
  .then((response) => {
    console.log('Response:', response.data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

NodeJS Request with Query Params

const axios = require('axios');

const url = 'https://run.brainglue.ai/clm00000000000000000';
const headers = {
  'bg_secret': '{{your_chain_secret}}'
};
const params = {
  word: 'wise'
};

axios.get(url, { headers, params })
  .then((response) => {
    console.log('Response:', response.data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

Python Request with Body Parameters

import requests
import json

url = 'https://run.brainglue.ai/clm30gco7000193uy9c0iy6ft'
headers = {
    'bg_secret': '{{your_chain_secret}}'
}
data = {
    'word': 'wise'
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print('Response:', json.dumps(response.json(), indent=4))
else:
    print('Error:', response.status_code, response.text)

Python Request with Query Parameters

import requests
import json

url = 'https://run.brainglue.ai/clm30gco7000193uy9c0iy6ft'
headers = {
    'bg_secret': '{{your_chain_secret}}'
}
params = {
    'word': 'wise'
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    print('Response:', json.dumps(response.json(), indent=4))
else:
    print('Error:', response.status_code, response.text)

Streamed or Buffered Responses

By default, the Brainglue Chains API uses the preferred mechanism of response for LLMs, which is streaming its response.

In the context of HTTP requests, a streamed response is sent back in chunks as they are generated and become available, allowing the client to start processing data immediately without waiting for the entire response. In contrast, a buffered response is fully received and stored in memory before it's passed along to the client for processing. Streamed responses improve the perceived experience of LLMs by allowing them to stream tokens as they are produced by the model.

We default to streamed transmission because we believe most solutions that leverage AI will benefit from having generated tokens as soon as possible.

However, we acknowledge that not all architectures or implementations need or can use a streamed response, so we also provide a buffered response by doing one of the following:

• Pass bg_stream as a request header with your false as the value.

• Pass bg_stream as a query parameter with your false as the value.

• Pass bg_stream as a body parameter with your false as the value.

Once again, our goal here is to give you maximum flexibility when interacting with your chains and allow you to move rapidly to productized solutions.

Please acknowledge the following limits when deciding on a response type:

• Streamed responses have a hard timeout of 15 minutes.

• Buffered responses have a hard timeout of 3 minutes.

API Responses

Once you invoke the chain endpoint, you will start receiving response chunks that you can pipe into other processes or parts of your implementation. The standard streamed response looks like this:

{"part":"nt80iqwiw","promptIndex":0,"data":""}
{"part":"nt80iqwiw","promptIndex":0,"data":"Heavy"}
{"part":"nt80iqwiw","promptIndex":0,"data":" heart"}
{"part":"nt80iqwiw","promptIndex":0,"data":" cries"}
{"part":"nt80iqwiw","promptIndex":0,"data":" out"}
{"part":"nt80iqwiw","promptIndex":0,"data":"\n"}
{"part":"nt80iqwiw","promptIndex":0,"data":"T"}
{"part":"nt80iqwiw","promptIndex":0,"data":"ears"}
{"part":"nt80iqwiw","promptIndex":0,"data":" flow"}
{"part":"nt80iqwiw","promptIndex":0,"data":" like"}
{"part":"nt80iqwiw","promptIndex":0,"data":" a"}
{"part":"nt80iqwiw","promptIndex":0,"data":" river"}
{"part":"nt80iqwiw","promptIndex":0,"data":"'s"}
{"part":"nt80iqwiw","promptIndex":0,"data":" stream"}
{"part":"nt80iqwiw","promptIndex":0,"data":"\n"}
{"part":"nt80iqwiw","promptIndex":0,"data":"Sad"}
{"part":"nt80iqwiw","promptIndex":0,"data":"ness"}
{"part":"nt80iqwiw","promptIndex":0,"data":" consumes"}
{"part":"nt80iqwiw","promptIndex":0,"data":" me"}
{"part":"rjkqim15g","promptIndex":1,"data":""}
{"part":"rjkqim15g","promptIndex":1,"data":"Light"}
{"part":"rjkqim15g","promptIndex":1,"data":" heart"}
{"part":"rjkqim15g","promptIndex":1,"data":" sings"}
{"part":"rjkqim15g","promptIndex":1,"data":" with"}
{"part":"rjkqim15g","promptIndex":1,"data":" joy"}
{"part":"rjkqim15g","promptIndex":1,"data":"\n"}
{"part":"rjkqim15g","promptIndex":1,"data":"La"}
{"part":"rjkqim15g","promptIndex":1,"data":"ughter"}
{"part":"rjkqim15g","promptIndex":1,"data":" dances"}
{"part":"rjkqim15g","promptIndex":1,"data":" like"}
{"part":"rjkqim15g","promptIndex":1,"data":" a"}
{"part":"rjkqim15g","promptIndex":1,"data":" bro"}
{"part":"rjkqim15g","promptIndex":1,"data":"ok"}
{"part":"rjkqim15g","promptIndex":1,"data":"\n"}
{"part":"rjkqim15g","promptIndex":1,"data":"H"}
{"part":"rjkqim15g","promptIndex":1,"data":"appiness"}
{"part":"rjkqim15g","promptIndex":1,"data":" frees"}
{"part":"rjkqim15g","promptIndex":1,"data":" me"}
{"part":"used_variables","data":[{"key":"word","value":"sad","origin":"default_value"}]}

Every chunk is an object that contains the following keys:

• part contains the identifier of the prompt that generated this output. Generally, you don't need to use this key for processing on your end, and you can safely rely on the key promptIndex described below.

• promptIndex contains the index of the prompt in the chain that generated this output. You can use this key to process a respond on your end. Chunks are delivered in order of generation, so you can process chunks safely in the order in which they arrive.

• data contains the actual streamed tokens that can be used to assemble the model's response.

Also, you might have noticed the last chunk is a little bit different. Brainglue will also return a chunk (or a key in a buffered response) telling you what global variables were used and where did they originated from (a default value or an API parameter).

Processing Streamed Responses

If you're wondering how to process the chunks on your end, here is a simple JavaScript implementation on how to do it. The objective here is to create a new object where for each promptIndex, the data strings are concatenated together. Here's how you can do that:

1. Define an empty object that will store the results.

2. Iterate through the streamed response chunks.

3. For each chunk, if the promptIndex does not exist in the result object, create it and initialize it with the data value of the chunk.

4. If the promptIndex already exists in the result object, simply append the data value of the chunk to the existing value.

5. Return the result object.

Here's a JavaScript function that implements the above steps:

function processChunks(chunks) {
  let result = {};

  chunks.forEach(chunk => {
    const promptIndex = chunk.promptIndex;

    // Check if the promptIndex key already exists
    if (result[promptIndex] !== undefined) {
      result[promptIndex] += chunk.data;
    } else {
      result[promptIndex] = chunk.data;
    }
  });

  return result;
}

// Example usage:
const chunks = [
  {"part":"nt80iqwiw","promptIndex":0,"data":"Heavy"},
  // ... other chunks ...
  {"part":"rjkqim15g","promptIndex":1,"data":"Happiness frees me"}
];

const processedData = processChunks(chunks);
console.log(processedData);

When you run the above function with the provided example data, it should give you:

{
  0: "Heavy heart cries out\nTears flow like a river's stream\nSadness consumes me",
  1: "Light heart sings with joy\nLaughter dances like a brook\nHappiness frees me"
}

This will give you the concatenated strings for each promptIndex key in the chunks array.