Help us shape the future of Go! Take the 2026 Go Developer Survey

braintrust

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 30, 2025 License: Apache-2.0 Imports: 10 Imported by: 17

README

Braintrust Go SDK

Go Reference Beta

Overview

This library provides tools for evaluating and tracing AI applications in Braintrust. Use it to:

  • Evaluate your AI models with custom test cases and scoring functions
  • Trace LLM calls and monitor AI application performance with OpenTelemetry
  • Integrate seamlessly with OpenAI, Anthropic, Google Gemini, LangChainGo, and other LLM providers

This SDK is currently in BETA status and APIs may change.

Installation

go get github.com/braintrustdata/braintrust-sdk-go

export BRAINTRUST_API_KEY="your-api-key"  # Get from https://www.braintrust.dev/app/settings

Quick Start

Braintrust uses OpenTelemetry for distributed tracing. Set up a TracerProvider and initialize the client:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
)

func main() {
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    client, err := braintrust.New(tp, braintrust.WithProject("my-project"))
    if err != nil {
        log.Fatal(err)
    }
    _ = client // Your client is ready to use
}

Usage

Evaluations

Run systematic evaluations with custom test cases and scoring functions:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    "github.com/braintrustdata/braintrust-sdk-go/eval"
)

func main() {
    ctx := context.Background()

    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(ctx)
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    client, err := braintrust.New(tp)
    if err != nil {
        log.Fatal(err)
    }

    // Create an evaluator with your task's input and output types
    evaluator := braintrust.NewEvaluator[string, string](client)

    // Run an evaluation
    _, err = evaluator.Run(ctx, eval.Opts[string, string]{
        Experiment: "greeting-experiment",
        Dataset: eval.NewDataset([]eval.Case[string, string]{
            {Input: "World", Expected: "Hello World"},
            {Input: "Alice", Expected: "Hello Alice"},
        }),
        Task: eval.T(func(ctx context.Context, input string) (string, error) {
            return "Hello " + input, nil
        }),
        Scorers: []eval.Scorer[string, string]{
            eval.NewScorer("exact_match", func(ctx context.Context, r eval.TaskResult[string, string]) (eval.Scores, error) {
                score := 0.0
                if r.Expected == r.Output {
                    score = 1.0
                }
                return eval.S(score), nil
            }),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
}
Tracing LLM Calls

Automatically trace LLM calls by adding middleware to your client:

OpenAI:

package main

import (
    "context"
    "log"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    traceopenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp)
    if err != nil {
        log.Fatal(err)
    }

    // Create OpenAI client with tracing middleware
    client := openai.NewClient(
        option.WithMiddleware(traceopenai.NewMiddleware()),
    )

    // Make API calls - they'll be automatically traced and logged to Braintrust
    _, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Hello!"),
        },
        Model: openai.ChatModelGPT4oMini,
    })
    if err != nil {
        log.Fatal(err)
    }
}

Anthropic:

package main

import (
    "context"
    "log"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    traceanthropic "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/anthropic"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create Anthropic client with tracing middleware
    client := anthropic.NewClient(
        option.WithMiddleware(traceanthropic.NewMiddleware()),
    )

    // Make API calls - they'll be automatically traced and logged to Braintrust
    _, err = client.Messages.New(context.Background(), anthropic.MessageNewParams{
        Model: anthropic.ModelClaude3_7SonnetLatest,
        Messages: []anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
        },
        MaxTokens: 1024,
    })
    if err != nil {
        log.Fatal(err)
    }
}
API Client

Manage Braintrust resources programmatically:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    functionsapi "github.com/braintrustdata/braintrust-sdk-go/api/functions"
)

func main() {
    ctx := context.Background()

    // Create tracer provider
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(ctx)

    // Initialize Braintrust
    client, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Get API client
    api := client.API()

    // Create a prompt
    prompt, err := api.Functions().Create(ctx, functionsapi.CreateParams{
        ProjectID: "your-project-id",
        Name:      "My Prompt",
        Slug:      "my-prompt",
        FunctionData: map[string]any{
            "type": "prompt",
        },
        PromptData: map[string]any{
            "prompt": map[string]any{
                "type": "chat",
                "messages": []map[string]any{
                    {
                        "role":    "system",
                        "content": "You are a helpful assistant.",
                    },
                    {
                        "role":    "user",
                        "content": "{{input}}",
                    },
                },
            },
            "options": map[string]any{
                "model": "gpt-4o-mini",
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = prompt // Prompt is ready to use
}

Google Gemini:

package main

import (
    "context"
    "log"
    "os"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"
    "google.golang.org/genai"

    "github.com/braintrustdata/braintrust-sdk-go"
    tracegenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genai"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create Gemini client with tracing
    client, err := genai.NewClient(context.Background(), &genai.ClientConfig{
        HTTPClient: tracegenai.Client(),
        APIKey:     os.Getenv("GOOGLE_API_KEY"),
        Backend:    genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Make API calls - they'll be automatically traced and logged to Braintrust
    _, err = client.Models.GenerateContent(context.Background(),
        "gemini-1.5-flash",
        genai.Text("Hello!"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
}

LangChainGo: The SDK provides comprehensive tracing for LangChainGo applications. See examples/langchaingo for examples.

Examples

Complete working examples are available in examples/:

Features

  • Evaluations - Systematic testing with custom scoring functions
  • Tracing - Automatic instrumentation for major LLM providers
  • Datasets - Manage and version evaluation datasets
  • Experiments - Track versions and configurations
  • Observability - Monitor AI applications in production

Documentation

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

Apache License 2.0. See LICENSE for details.

Documentation

Overview

Package braintrust provides the core Braintrust SDK for Go.

Braintrust is a platform for building reliable AI applications. This SDK provides tools for evaluation, experimentation, and observability of AI systems.

Main Packages

For AI model evaluations, see the eval package.

For distributed tracing and observability, see the trace package.

Configuration

The SDK reads configuration from environment variables. See [GetConfig] for a complete list of supported environment variables.

Learn More

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEvaluator 

func NewEvaluator[I, R any](client *Client) *eval.Evaluator[I, R]

NewEvaluator creates a new evaluator for running multiple evaluations with the same input and output types.

Example: 

client, _ := braintrust.New(tp)

// Create an evaluator for string → string evaluations
evaluator := braintrust.NewEvaluator[string, string](client)

// Run multiple evaluations
result1, _ := evaluator.Run(ctx, eval.Opts[string, string]{
    Experiment: "test-1",
    Dataset:    dataset1,
    Task:       task1,
    Scorers:    scorers,
})

result2, _ := evaluator.Run(ctx, eval.Opts[string, string]{
    Experiment: "test-2",
    Dataset:    dataset2,
    Task:       task2,
    Scorers:    scorers,
})

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main Braintrust SDK client

func New 

func New(tp *trace.TracerProvider, opts ...Option) (*Client, error)

New creates a new Braintrust client.

It will add a Braintrust exporter to the given tracer provider..

Configuration is loaded from environment variables first, then explicit options are applied (options take precedence).

Login happens asynchronously in the background by default.

Example: 

tp := trace.NewTracerProvider()
bt, err := braintrust.New(tp,
    braintrust.WithAPIKey("your-api-key"),
    braintrust.WithProject("my-project"),
)
if err != nil {
    log.Fatal(err)
}
defer tp.Shutdown(context.Background())

func (*Client) API 

func (c *Client) API() *api.API

API returns an API client for making direct calls to the Braintrust API. This provides low-level access to projects, datasets, experiments, and other resources.

Example: 

client, _ := braintrust.New(tp, braintrust.WithAPIKey("your-key"))

// Create a dataset
apiClient := client.API()
project, _ := apiClient.Projects().Create(ctx, "my-project")
dataset, _ := apiClient.Datasets().Create(ctx, api.DatasetRequest{
    ProjectID:   project.ID,
    Name:        "my-dataset",
    Description: "My test dataset",
})

func (c *Client) Permalink(span oteltrace.Span) string

Permalink returns a URL to the span in the Braintrust UI. If the permalink cannot be generated, it returns an empty string and logs a warning.

Example: 

client, _ := braintrust.New(tp, braintrust.WithAPIKey("your-key"))
tracer := client.Tracer("my-app")
ctx, span := tracer.Start(ctx, "my-operation")
defer span.End()

// Get the permalink
link := client.Permalink(span)
fmt.Println("View trace:", link)

func (*Client) String 

func (c *Client) String() string

String returns a string representation of the client

func (*Client) Tracer 

func (c *Client) Tracer(name string, opts ...oteltrace.TracerOption) oteltrace.Tracer

Tracer returns an OpenTelemetry Tracer with the given name. This is a convenience method equivalent to calling TracerProvider().Tracer(name, opts...).

Example: 

tracer := client.Tracer("my-app")
ctx, span := tracer.Start(ctx, "my-operation")
defer span.End()

func (*Client) TracerProvider 

func (c *Client) TracerProvider() *trace.TracerProvider

TracerProvider returns the OpenTelemetry TracerProvider used by this client. This can be used to create tracers or access the provider for advanced use cases.

type Option 

type Option func(*config.Config)

Option is a functional option for configuring a Braintrust client

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key (overrides BRAINTRUST_API_KEY)

func WithAPIURL 

func WithAPIURL(apiURL string) Option

WithAPIURL sets the API URL (overrides BRAINTRUST_API_URL)

func WithAppURL 

func WithAppURL(appURL string) Option

WithAppURL sets the app URL (overrides BRAINTRUST_APP_URL)

func WithBlockingLogin 

func WithBlockingLogin(enabled bool) Option

WithBlockingLogin blocks setup until login completes. Authentication normally happens asynchronously in the background.

This only enables printing links to spans. This is only useful for scripts, testing and examples. It is not recommended for production use.

func WithExporter 

func WithExporter(exporter trace.SpanExporter) Option

WithExporter injects a custom OpenTelemetry SpanExporter. If not provided, an OTLP HTTP exporter will be created automatically. This is solely for testing purposes.

func WithFilterAISpans 

func WithFilterAISpans(enabled bool) Option

WithFilterAISpans enables filtering to keep only AI-related spans When enabled, only spans with AI-related names or attributes will be sent

func WithLogger 

func WithLogger(l logger.Logger) Option

WithLogger sets a custom logger for the SDK If not provided, a default logger will be used

func WithOrgName 

func WithOrgName(orgName string) Option

WithOrgName sets the organization name (overrides BRAINTRUST_ORG_NAME)

func WithProject 

func WithProject(projectName string) Option

WithProject sets the default project name (overrides BRAINTRUST_DEFAULT_PROJECT)

func WithProjectID 

func WithProjectID(projectID string) Option

WithProjectID sets the default project ID (overrides BRAINTRUST_DEFAULT_PROJECT_ID)

func WithSpanFilterFuncs 

func WithSpanFilterFuncs(filterFuncs ...config.SpanFilterFunc) Option

WithSpanFilterFuncs adds custom span filter functions Filters are evaluated in order. Return >0 to keep, <0 to drop, 0 to continue

Source Files

View all Source files

Directories

Path Synopsis
api
Package api provides a client for interacting with the Braintrust API.
 Package api provides a client for interacting with the Braintrust API.
datasets
Package datasets provides operations for managing Braintrust datasets.
 Package datasets provides operations for managing Braintrust datasets.
experiments
Package experiments provides operations for managing Braintrust experiments.
 Package experiments provides operations for managing Braintrust experiments.
functions
Package functions provides operations for managing Braintrust functions (prompts, tools, scorers).
 Package functions provides operations for managing Braintrust functions (prompts, tools, scorers).
projects
Package projects provides operations for managing Braintrust projects.
 Package projects provides operations for managing Braintrust projects.
btx module
Package config provides configuration management for the Braintrust SDK.
 Package config provides configuration management for the Braintrust SDK.
Package eval provides tools for evaluating AI model outputs.
 Package eval provides tools for evaluating AI model outputs.
examples module
anthropic command
This example demonstrates basic Anthropic tracing with Braintrust.
 This example demonstrates basic Anthropic tracing with Braintrust.
attachments command
Package main demonstrates manual attachment usage in Braintrust traces.
 Package main demonstrates manual attachment usage in Braintrust traces.
dataset-api command
datasets command
distributed-tracing command
Package main demonstrates distributed tracing using W3C baggage propagation.
 Package main demonstrates distributed tracing using W3C baggage propagation.
evals command
genai command
This example demonstrates basic Google Gemini tracing with Braintrust.
 This example demonstrates basic Google Gemini tracing with Braintrust.
internal/anthropic command
Anthropic kitchen sink - tests all the Anthropic features with minimal code
 Anthropic kitchen sink - tests all the Anthropic features with minimal code
internal/email-evals command
This is a realistic eval example.
 This is a realistic eval example.
internal/eval-updates command
This example demonstrates using the Update option to append results to an existing experiment.
 This example demonstrates using the Update option to append results to an existing experiment.
internal/functions command
internal/kitchensink command
Package main demonstrates a comprehensive "kitchen sink" example that combines as much Braintrust SDK functionality as possible into a single executable.
 Package main demonstrates a comprehensive "kitchen sink" example that combines as much Braintrust SDK functionality as possible into a single executable.
internal/rewrite command
manual-llm-logging command
openai command
This example demonstrates basic OpenAI tracing with Braintrust.
 This example demonstrates basic OpenAI tracing with Braintrust.
otel command
prompts command
This example demonstrates using a Braintrust prompt in an evaluation.
 This example demonstrates using a Braintrust prompt in an evaluation.
sashabaranov-openai command
This example demonstrates OpenAI tracing with Braintrust using the sashabaranov/go-openai library.
 This example demonstrates OpenAI tracing with Braintrust using the sashabaranov/go-openai library.
scorers command
internal
auth
Package auth provides authentication functionality for the Braintrust SDK.
 Package auth provides authentication functionality for the Braintrust SDK.
https
Package https provides a unified HTTP client for making API requests with centralized auth, error handling, and debug logging.
 Package https provides a unified HTTP client for making API requests with centralized auth, error handling, and debug logging.
logger
Package logger provides internal logging utilities.
 Package logger provides internal logging utilities.
oteltest
Package oteltest provides testing utilities for OpenTelemetry tracing.
 Package oteltest provides testing utilities for OpenTelemetry tracing.
tests
Package tests provides test utilities for creating test sessions and other test helpers.
 Package tests provides test utilities for creating test sessions and other test helpers.
vcr
Package vcr provides utilities for recording and replaying HTTP interactions in tests using go-vcr.
 Package vcr provides utilities for recording and replaying HTTP interactions in tests using go-vcr.
Package logger provides logging interfaces and implementations for the Braintrust SDK.
 Package logger provides logging interfaces and implementations for the Braintrust SDK.
Package trace provides distributed tracing functionality for Braintrust experiments.
 Package trace provides distributed tracing functionality for Braintrust experiments.
attachment
Package attachment provides utilities for creating and managing attachments in Braintrust traces.
 Package attachment provides utilities for creating and managing attachments in Braintrust traces.
contrib/anthropic
Package anthropic provides OpenTelemetry middleware for tracing Anthropic API calls.
 Package anthropic provides OpenTelemetry middleware for tracing Anthropic API calls.
contrib/genai
Package genai provides OpenTelemetry tracing for Google Gemini API calls.
 Package genai provides OpenTelemetry tracing for Google Gemini API calls.
contrib/github.com/sashabaranov/go-openai
Package traceopenai provides OpenTelemetry tracing for github.com/sashabaranov/go-openai client.
 Package traceopenai provides OpenTelemetry tracing for github.com/sashabaranov/go-openai client.
contrib/langchaingo
Package langchaingo provides OpenTelemetry tracing for LangChainGo applications.
 Package langchaingo provides OpenTelemetry tracing for LangChainGo applications.
contrib/openai
Package openai provides OpenTelemetry middleware for tracing OpenAI API calls.
 Package openai provides OpenTelemetry middleware for tracing OpenAI API calls.
internal
Package internal provides shared middleware functionality for OpenTelemetry tracers.
 Package internal provides shared middleware functionality for OpenTelemetry tracers.
contrib/a2a module
contrib/adk module
contrib/all module
contrib/bedrockruntime module
contrib/cloudwego/eino module
contrib/genkit module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.