docs and api tweaks (#5)

- small docs fixes
- api tweaks (e.g. don't let `API()` return nil)

Author: clutchski

.github/workflows/ci.yml

@@ -32,3 +32,11 @@ jobs:
           version: v2.1.6
       - name: Lint, vet, tests, etc.
         run: make ci
+
+  ci-passed:
+    name: ci-passed
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mark CI as passed
+        run: echo "All CI jobs passed successfully"

README.md

@@ -14,18 +14,118 @@ This library provides tools for **evaluating** and **tracing** AI applications i
 
 This SDK is currently in BETA status and APIs may change.
 
-## Installation
+## Setup
 
 ```bash
 go get github.com/braintrustdata/braintrust-sdk-go
+
+export BRAINTRUST_API_KEY="your-api-key"
 ```
 
-## Quick Start
+### Getting started
 
-### Set up your API key
+Braintrust uses [OpenTelemetry](https://opentelemetry.io/) for distributed tracing. Every application needs:
 
-```bash
-export BRAINTRUST_API_KEY="your-api-key"
+1. **TracerProvider**: Collects and exports traces from your application
+2. **API Key**: Authenticates your application with Braintrust. [Braintrust Settings](https://www.braintrust.dev/app/settings).
+3. **Braintrust Client**: Connects to Braintrust and registers your TracerProvider for automatic instrumentation
+
+### Setup
+
+```go
+package main
+
+import (
+    "context"
+    "log"
+
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/sdk/trace"
+
+    "github.com/braintrustdata/braintrust-sdk-go"
+)
+
+func main() {
+    // Setup a global OTel Tracer Provider.
+    tp := trace.NewTracerProvider()
+    defer tp.Shutdown(context.Background())
+    otel.SetTracerProvider(tp)
+
+    bt, err := braintrust.New(tp)
+    if err != nil {
+        log.Fatal(err)
+    }
+    _ = bt // Your client is ready for use
+}
+```
+
+### API Usage
+
+Use the API client to manage Braintrust resources like prompts, datasets, and projects:
+
+```go
+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
+}
 ```
 
 ### Evals
@@ -51,16 +151,13 @@ func main() {
     otel.SetTracerProvider(tp)
 
     // Initialize Braintrust
-    bt, err := braintrust.New(tp,
-        braintrust.WithProject("my-project"),
-        braintrust.WithBlockingLogin(true),
-    )
+    client, err := braintrust.New(tp)
     if err != nil {
         log.Fatal(err)
     }
 
-    // Create evaluator
-    evaluator := braintrust.NewEvaluator[string, string](bt)
+    // Create an evaluator with your task's input and output types.
+    evaluator := braintrust.NewEvaluator[string, string](client)
 
     // Run an evaluation
     _, err = evaluator.Run(context.Background(), eval.Opts[string, string]{
@@ -73,11 +170,12 @@ func main() {
             return "Hello " + input, nil
         }),
         Scorers: []eval.Scorer[string, string]{
-            eval.NewScorer("exact_match", func(ctx context.Context, taskResult eval.TaskResult[string, string]) (eval.Scores, error) {
-                if taskResult.Expected == taskResult.Output {
-                    return eval.S(1.0), nil
+            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(0.0), nil
+                return eval.S(score), nil
             }),
         },
     })
@@ -112,9 +210,7 @@ func main() {
     otel.SetTracerProvider(tp)
 
     // Initialize Braintrust
-    _, err := braintrust.New(tp,
-        braintrust.WithProject("my-project"),
-    )
+    _, err := braintrust.New(tp)
     if err != nil {
         log.Fatal(err)
     }
@@ -124,8 +220,16 @@ func main() {
         option.WithMiddleware(traceopenai.NewMiddleware()),
     )
 
-    // Your OpenAI API calls will now be automatically traced
-    _ = client // Use the client for your API calls
+    // 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)
+    }
 }
 ```
 
@@ -166,8 +270,17 @@ func main() {
         option.WithMiddleware(traceanthropic.NewMiddleware()),
     )
 
-    // Your Anthropic API calls will now be automatically traced
-    _ = client // Use the client for your API calls
+    // 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)
+    }
 }
 ```
 
@@ -213,8 +326,15 @@ func main() {
         log.Fatal(err)
     }
 
-    // Your Gemini API calls will now be automatically traced
-    _ = client // Use the client for your API calls
+    // 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)
+    }
 }
 ```
 

api/client.go

@@ -2,8 +2,6 @@
 package api
 
 import (
-	"fmt"
-
 	"github.com/braintrustdata/braintrust-sdk-go/api/datasets"
 	"github.com/braintrustdata/braintrust-sdk-go/api/experiments"
 	"github.com/braintrustdata/braintrust-sdk-go/api/functions"
@@ -43,11 +41,8 @@ func WithLogger(log logger.Logger) Option {
 }
 
 // NewClient creates a new Braintrust API client with the given API key and options.
-func NewClient(apiKey string, opts ...Option) (*API, error) {
-	if apiKey == "" {
-		return nil, fmt.Errorf("apiKey is required")
-	}
-
+// The apiKey must be non-empty (validated at config level).
+func NewClient(apiKey string, opts ...Option) *API {
 	options := &options{
 		apiURL: "https://api.braintrust.dev", // default
 		logger: nil,
@@ -57,14 +52,11 @@ func NewClient(apiKey string, opts ...Option) (*API, error) {
 		opt(options)
 	}
 
-	client, err := https.NewClient(apiKey, options.apiURL, options.logger)
-	if err != nil {
-		return nil, err
-	}
+	client := https.NewClient(apiKey, options.apiURL, options.logger)
 
 	return &API{
 		client: client,
-	}, nil
+	}
 }
 
 // Projects returns a client for project operations

client.go

@@ -23,10 +23,9 @@ type Client struct {
 	tracerProvider *trace.TracerProvider
 }
 
-// New creates a new Braintrust client with the provided TracerProvider.
+// New creates a new Braintrust client.
 //
-// The TracerProvider is required and should be managed by the caller.
-// The client will NOT shut down the provider - you must do this yourself.
+// 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).
@@ -53,6 +52,11 @@ func New(tp *trace.TracerProvider, opts ...Option) (*Client, error) {
 		opt(cfg)
 	}
 
+	// Validate configuration before proceeding
+	if err := cfg.IsValid(); err != nil {
+		return nil, fmt.Errorf("invalid configuration: %w", err)
+	}
+
 	// Setup default logger if none provided
 	log := cfg.Logger
 	if log == nil {
@@ -192,22 +196,22 @@ func (c *Client) Tracer(name string, opts ...oteltrace.TracerOption) oteltrace.T
 //
 // Example:
 //
-//	client, _ := braintrust.New(tp, braintrust.WithProject("my-project"))
+//	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",
-//	    Cases:      cases1,
+//	    Dataset:    dataset1,
 //	    Task:       task1,
 //	    Scorers:    scorers,
 //	})
 //
 //	result2, _ := evaluator.Run(ctx, eval.Opts[string, string]{
 //	    Experiment: "test-2",
-//	    Cases:      cases2,
+//	    Dataset:    dataset2,
 //	    Task:       task2,
 //	    Scorers:    scorers,
 //	})
@@ -224,7 +228,7 @@ func NewEvaluator[I, R any](client *Client) *eval.Evaluator[I, R] {
 //
 //	// Create a dataset
 //	apiClient := client.API()
-//	project, _ := apiClient.Projects().Register(ctx, "my-project")
+//	project, _ := apiClient.Projects().Create(ctx, "my-project")
 //	dataset, _ := apiClient.Datasets().Create(ctx, api.DatasetRequest{
 //	    ProjectID:   project.ID,
 //	    Name:        "my-dataset",
@@ -234,17 +238,11 @@ func (c *Client) API() *api.API {
 	// Get endpoints from session (prefers logged-in info, falls back to config)
 	endpoints := c.session.Endpoints()
 
-	client, err := api.NewClient(
+	return api.NewClient(
 		endpoints.APIKey,
 		api.WithAPIURL(endpoints.APIURL),
 		api.WithLogger(c.logger),
 	)
-	if err != nil {
-		// Log error but return nil - this shouldn't happen with valid session
-		c.logger.Error("failed to create API client", "error", err)
-		return nil
-	}
-	return client
 }
 
 // Permalink returns a URL to the span in the Braintrust UI.