Skip to main content
Version: 4.7.28

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.