Skip to main content
Version: 4.7.8

Metadata

You can attach custom context (we call this metadata) to your pipeline runs. If you want to associate a URL to an external service or a prompt variant to the run, you can use metadata to tag your generations.

Usage

Advanced example for generation

You can associate metadata with an entire generation by specifying the metadata key in .start() function.

typescript
import { init, Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
async function main() {
 
init({
apiKey: process.env.GENTRACE_API_KEY ?? ""
});
 
const plugin = await initPlugin({
apiKey: process.env.OPENAI_KEY
});
 
const PIPELINE_SLUG = "advanced-pipeline";
const pipeline = new Pipeline({
slug: PIPELINE_SLUG,
plugins: {
openai: plugin,
},
});
const GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const runner = pipeline.start({
metadata: {
// We support multiple key/value pairs within the metadata object
externalServiceUrl: {
// Every metadata object must have a "type" key
type: "url",
url: "https://external-service.example.com",
text: "External service"
},
gitSha: {
type: "string",
value: GIT_SHA
}
}
});
const openai = runner.openai;
const chatCompletionResponse = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
model: "gpt-3.5-turbo",
});
await runner.submit();
}
 
main();

Advanced example on step

You can also add metadata to the run by using the context object for a particular step.

typescript
import { init, Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
init({
apiKey: process.env.GENTRACE_API_KEY ?? ""
});
 
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 GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const chatCompletionResponse = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
model: "gpt-3.5-turbo",
gentrace: {
metadata: {
// We support multiple metadata keys within the metadata object
externalServiceUrl: {
// Every metadata object must have a "type" key
type: "url",
url: "https://external-service.example.com",
text: "External service"
},
gitSha: {
type: "string",
value: GIT_SHA
}
}
}
});
 
await runner.submit();

Behavior

All metadata is scoped to a pipeline run. If you're using the advanced SDK and have multiple interim steps in your pipeline, any metadata that you associate with a step is associated directly with the pipeline run, not the step.

Let's say you have the following pipeline.

typescript
import { init, Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
init({
apiKey: process.env.GENTRACE_API_KEY ?? ""
});
 
const plugin = await initPlugin({
apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
slug: "advanced-pipeline",
plugins: {
openai: plugin,
},
});
 
const GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const runner = pipeline.start({
// Assign metadata upon pipeline instantiation
metadata: {
gitSha: {
type: "string",
value: GIT_SHA
}
}
});
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
model: "gpt-3.5-turbo",
stream: true,
gentrace: {
// Create additional metadata when you're adding steps to your pipeline
metadata: {
// We support multiple metadata keys within the metadata object
externalServiceUrl: {
// Every metadata object must have a "type" key
type: "url",
url: "https://external-service.example.com",
text: "External service"
}
}
}
});

Both items will render in the runs page in the Gentrace UI similar to below.

Metadata keys will overwrite

When defining a metadata key with the same identifier in a pipeline run, please note that only the latest write will be applied to the metadata for the entire run.

typescript
// Omit SDK and pipeline run initialization
 
const first = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
model: "gpt-3.5-turbo",
stream: true,
gentrace: {
metadata: {
promptId: {
type: "string",
value: "MzY0MzQ0"
}
}
}
});
 
// ...
 
const second = await openai.chat.completions.create({
messages: [{ role: "user", content: "Hello! What's the capital of Georgia" }],
model: "gpt-3.5-turbo",
stream: true,
gentrace: {
// 🚧 This overwrites the first instantiation
metadata: {
promptId: {
type: "string",
value: "SGVsbG8g"
}
}
}
});

Types

The value object for each metadata value is a union type. We only support two value types at this time. We will add more upon request.

"type": "url"

If specified as a URL, you must specify url and text key/value pairs.

json
{
"type": "url",
"url": "https://external-service.example.com",
"text": "External service"
}

"type": "string"

If specified as a string, you must specify a value key/value pair.

json
{
"type": "string",
"value": "MzY0MzQ0"
}

"type": "boolean"

If specified as a boolean, you must specify a value key/value pair

json
{
"type": "boolean",
"value": true
}
Malformed metadata

If your metadata is not properly formatted with the specified type, our API will reject your request.