Skip to main content
Version: 4.5.0

Metadata

You can attach run-level metadata with our SDKs to attach related information to your generative output.

Usage

You can add run-level context using both our simple and advanced SDKs.

Supported keys

Some keys only work on certain types of AI generations. For example, user IDs can only be associated to an entire generation, whereas metadata can be assigned directly on particular steps within a generation. Visit the detailed page for each context type to learn more about its semantics.

Simple SDK

Every simple invocation allows you to specify a gentrace parameter, where you can supply specific context key/value pairs. Here's an example from our OpenAI simple plugin.

typescript
import { init } from "@gentrace/core";
import { OpenAI } from "@gentrace/openai";
 
init({
apiKey: process.env.GENTRACE_API_KEY,
});
 
const openai = new OpenAI({
apiKey: process.env.OPENAI_KEY,
});
 
await openai.chat.completions.create({
messages: [
{
role: "user",
contentTemplate: "Hello! My name is {{ name }}. Write a brief essay about Maine.",
contentInputs: { name: "Vivek" },
},
],
model: "gpt-3.5-turbo",
pipelineSlug: "simple-pipeline",
stream: true,
 
// Context is specified with the `gentrace` key. In this case, the user ID will be
// associated with this generation.
gentrace: {
userId: "TWFuIGlzIGRpc3Rpbmd1aXNoZW",
},
});

Advanced SDK

You can specify context when you initialize a PipelineRun instance with the pipeline.start() function.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const plugin = await initPlugin({
apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
slug: "advanced-pipeline",
plugins: {
openai: plugin,
},
});
 
// Context is specified directly as an object. This context is associated with all
// steps in the generative pipeline.
const runner = pipeline.start({
userId: "TWFuIGlzIGRpc3Rpbmd1aXNoZW",
});
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello!" }],
model: "gpt-3.5-turbo",
stream: true,
});
 

You can also associate context with any individual step with the gentrace parameter.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const plugin = await initPlugin({
apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
slug: "advanced-pipeline",
plugins: {
openai: plugin,
},
});
 
const runner = pipeline.start();
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello!" }],
model: "gpt-3.5-turbo",
stream: true,
// Context is applied directly to this AI step
gentrace: {
userId: "TWFuIGlzIGRpc3Rpbmd1aXNoZW"
}
});

Certain step methods like measure() and checkpoint() require that context is explicitly passed in a context key.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const plugin = await initPlugin({
apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
slug: "advanced-pipeline",
plugins: {
openai: plugin,
},
});
 
const runner = pipeline.start();
 
const outputs = await runner.measure(
(pageDescription) => {
// ... Omitted logic for creating HTML from provided inputs
return {
koalaHtml: htmlOutput
};
},
["Create HTML for a site about koalas"],
{
context: {
render: {
type: "html",
key: "koalaHtml",
},
},
},
);
 
await runner.submit();