braintrust 0.0.91 → 0.0.93

package/dist/index.js

@@ -3693,7 +3693,7 @@ var DefaultAsyncLocalStorage = class {
   }
 };
 var iso = {
-  getRepoStatus: async () => void 0,
+  getRepoStatus: async (_settings) => void 0,
   getPastNAncestors: async () => [],
   getEnv: (_name) => void 0,
   getCallerLocation: () => void 0,
@@ -7681,9 +7681,7 @@ async function getBaseBranchAncestor(remote = void 0) {
   if (git === null) {
     throw new Error("Not in a git repo");
   }
-  const { remote: remoteName, branch: baseBranch } = await getBaseBranch(
-    remote
-  );
+  const { remote: remoteName, branch: baseBranch } = await getBaseBranch(remote);
   const isDirty = (await git.diffSummary()).files.length > 0;
   const head = isDirty ? "HEAD" : "HEAD^";
   try {
@@ -7732,7 +7730,21 @@ function truncateToByteLimit(s, byteLimit = 65536) {
   const truncated = encoded.subarray(0, byteLimit);
   return new TextDecoder().decode(truncated);
 }
-async function getRepoStatus() {
+async function getRepoStatus(settings) {
+  if (settings && settings.collect === "none") {
+    return void 0;
+  }
+  const repo = await repoStatus();
+  if (!repo || !settings || settings.collect === "all") {
+    return repo;
+  }
+  let sanitized = {};
+  settings.fields?.forEach((field) => {
+    sanitized = { ...sanitized, [field]: repo[field] };
+  });
+  return sanitized;
+}
+async function repoStatus() {
   const git = await currentRepo();
   if (git === null) {
     return void 0;
@@ -7944,6 +7956,24 @@ var SpanTypeAttribute = /* @__PURE__ */ ((SpanTypeAttribute2) => {
   SpanTypeAttribute2["TOOL"] = "tool";
   return SpanTypeAttribute2;
 })(SpanTypeAttribute || {});
+function mergeGitMetadataSettings(s1, s2) {
+  var _a2;
+  if (s1.collect === "all") {
+    return s2;
+  } else if (s2.collect === "all") {
+    return s1;
+  } else if (s1.collect === "none") {
+    return s1;
+  } else if (s2.collect === "none") {
+    return s2;
+  }
+  const fields = ((_a2 = s1.fields) != null ? _a2 : []).filter((f) => {
+    var _a22;
+    return ((_a22 = s2.fields) != null ? _a22 : []).includes(f);
+  });
+  const collect = fields.length > 0 ? "some" : "none";
+  return { collect, fields };
+}
 
 // src/util.ts
 var GLOBAL_PROJECT = "Global";
@@ -7998,7 +8028,7 @@ var NoopSpan = class {
 var NOOP_SPAN = new NoopSpan();
 var BraintrustState = class {
   constructor() {
-    this.apiUrl = null;
+    this.appUrl = null;
     this.loginToken = null;
     this.orgId = null;
     this.orgName = null;
@@ -8014,21 +8044,22 @@ var BraintrustState = class {
     globalThis.__inherited_braintrust_state = this;
   }
   resetLoginInfo() {
-    this.apiUrl = null;
+    this.appUrl = null;
     this.loginToken = null;
     this.orgId = null;
     this.orgName = null;
     this.logUrl = null;
     this.loggedIn = false;
+    this.gitMetadataSettings = void 0;
     this._apiConn = null;
     this._logConn = null;
   }
   apiConn() {
     if (!this._apiConn) {
-      if (!this.apiUrl) {
-        throw new Error("Must initialize apiUrl before requesting apiConn");
+      if (!this.appUrl) {
+        throw new Error("Must initialize appUrl before requesting apiConn");
       }
-      this._apiConn = new HTTPConnection(this.apiUrl);
+      this._apiConn = new HTTPConnection(this.appUrl);
     }
     return this._apiConn;
   }
@@ -8248,12 +8279,12 @@ var Logger = class {
    * Log a single event. The event will be batched and uploaded behind the scenes if `logOptions.asyncFlush` is true.
    *
    * @param event The event to log.
-   * @param event.input: The arguments that uniquely define a user input (an arbitrary, JSON serializable object).
-   * @param event.output: The output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
-   * @param event.expected: The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
-   * @param event.scores: A dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare logs.
+   * @param event.input: (Optional) the arguments that uniquely define a user input (an arbitrary, JSON serializable object).
+   * @param event.output: (Optional) the output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
+   * @param event.expected: (Optional) the ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
+   * @param event.scores: (Optional) a dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare logs.
    * @param event.metadata: (Optional) a dictionary with additional data about the test example, model outputs, or just about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
-   * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end", "caller_functionname", "caller_filename", "caller_lineno".
+   * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
    * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
    * :returns: The `id` of the logged event.
    */
@@ -8307,7 +8338,9 @@ var Logger = class {
     };
   }
   /**
-   * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current.
+   * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+   * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+   * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
    *
    * See `traced` for full details.
    */
@@ -8458,16 +8491,17 @@ function init(project, options = {}) {
     baseExperiment,
     isPublic,
     update,
-    apiUrl,
+    appUrl,
     apiKey,
     orgName,
-    metadata
+    metadata,
+    gitMetadataSettings
   } = options || {};
   const lazyMetadata = (async () => {
     await login({
       orgName,
       apiKey,
-      apiUrl
+      appUrl
     });
     const args = {
       project_name: project,
@@ -8482,9 +8516,20 @@ function init(project, options = {}) {
     if (update) {
       args["update"] = update;
     }
-    const repoStatus = await isomorph_default.getRepoStatus();
-    if (repoStatus) {
-      args["repo_info"] = repoStatus;
+    let mergedGitMetadataSettings = {
+      ..._state.gitMetadataSettings || {
+        collect: "all"
+      }
+    };
+    if (gitMetadataSettings) {
+      mergedGitMetadataSettings = mergeGitMetadataSettings(
+        mergedGitMetadataSettings,
+        gitMetadataSettings
+      );
+    }
+    const repoStatus2 = await isomorph_default.getRepoStatus(gitMetadataSettings);
+    if (repoStatus2) {
+      args["repo_info"] = repoStatus2;
     }
     if (baseExperiment) {
       args["base_experiment"] = baseExperiment;
@@ -8549,12 +8594,12 @@ function withLogger(callback, options = {}) {
   return callback(logger);
 }
 function initDataset(project, options = {}) {
-  const { dataset, description, version, apiUrl, apiKey, orgName } = options || {};
+  const { dataset, description, version, appUrl, apiKey, orgName } = options || {};
   const lazyMetadata = (async () => {
     await login({
       orgName,
       apiKey,
-      apiUrl
+      appUrl
     });
     const args = {
       org_id: _state.orgId,
@@ -8590,7 +8635,7 @@ function initLogger(options = {}) {
     projectName,
     projectId,
     asyncFlush,
-    apiUrl,
+    appUrl,
     apiKey,
     orgName,
     forceLogin
@@ -8599,7 +8644,7 @@ function initLogger(options = {}) {
     await login({
       orgName,
       apiKey,
-      apiUrl,
+      appUrl,
       forceLogin
     });
     const org_id = _state.orgId;
@@ -8645,7 +8690,7 @@ function initLogger(options = {}) {
 }
 async function login(options = {}) {
   const {
-    apiUrl = isomorph_default.getEnv("BRAINTRUST_API_URL") || "https://www.braintrustdata.com",
+    appUrl = isomorph_default.getEnv("BRAINTRUST_APP_URL") || "https://www.braintrustdata.com",
     apiKey = isomorph_default.getEnv("BRAINTRUST_API_KEY"),
     orgName = isomorph_default.getEnv("BRAINTRUST_ORG_NAME")
   } = options || {};
@@ -8654,11 +8699,11 @@ async function login(options = {}) {
     return;
   }
   _state.resetLoginInfo();
-  _state.apiUrl = apiUrl;
+  _state.appUrl = appUrl;
   let conn = null;
   if (apiKey !== void 0) {
     const resp = await checkResponse(
-      await fetch(_urljoin(_state.apiUrl, `/api/apikey/login`), {
+      await fetch(_urljoin(_state.appUrl, `/api/apikey/login`), {
         method: "POST",
         headers: {
           "Content-Type": "application/json"
@@ -8775,7 +8820,8 @@ function _check_org_info(org_info, org_name) {
     if (org_name === void 0 || org.name === org_name) {
       _state.orgId = org.id;
       _state.orgName = org.name;
-      _state.logUrl = isomorph_default.getEnv("BRAINTRUST_LOG_URL") ?? org.api_url;
+      _state.logUrl = isomorph_default.getEnv("BRAINTRUST_API_URL") ?? org.api_url;
+      _state.gitMetadataSettings = org.git_metadata || void 0;
       break;
     }
   }
@@ -8844,6 +8890,9 @@ function validateAndSanitizeExperimentLogFullArgs(event, hasDataset) {
       "Exactly one of input or inputs (deprecated) must be specified. Prefer input."
     );
   }
+  if (!event.output) {
+    throw new Error("output must be specified");
+  }
   if (!event.scores) {
     throw new Error("scores must be specified");
   }
@@ -8891,10 +8940,10 @@ var Experiment = class {
    * @param event The event to log.
    * @param event.input: The arguments that uniquely define a test case (an arbitrary, JSON serializable object). Later on, Braintrust will use the `input` to know whether two test cases are the same between experiments, so they should not contain experiment-specific state. A simple rule of thumb is that if you run the same experiment twice, the `input` should be identical.
    * @param event.output: The output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
-   * @param event.expected: The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate your experiments while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
+   * @param event.expected: (Optional) The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate your experiments while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
    * @param event.scores: A dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare experiments.
    * @param event.metadata: (Optional) a dictionary with additional data about the test example, model outputs, or just about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
-   * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end", "caller_functionname", "caller_filename", "caller_lineno".
+   * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
    * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
    * @param event.dataset_record_id: (Optional) the id of the dataset record that this event is associated with. This field is required if and only if the experiment is associated with a dataset.
    * @param event.inputs: (Deprecated) the same as `input` (will be removed in a future version).
@@ -8933,7 +8982,9 @@ var Experiment = class {
     };
   }
   /**
-   * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current.
+   * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+   * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+   * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
    *
    * See `traced` for full details.
    */
@@ -8958,7 +9009,7 @@ var Experiment = class {
     let { summarizeScores = true, comparisonExperimentId = void 0 } = options || {};
     await this.bgLogger.flush();
     const state = await this.getState();
-    const projectUrl = `${state.apiUrl}/app/${encodeURIComponent(
+    const projectUrl = `${state.appUrl}/app/${encodeURIComponent(
       state.orgName
     )}/p/${encodeURIComponent((await this.project).name)}`;
     const experimentUrl = `${projectUrl}/${encodeURIComponent(
@@ -9054,9 +9105,9 @@ var SpanImpl = class _SpanImpl {
     })();
     this.internalData = {
       metrics: {
-        start: args.startTime ?? getCurrentUnixTimestamp(),
-        ...callerLocation
+        start: args.startTime ?? getCurrentUnixTimestamp()
       },
+      context: { ...callerLocation },
       span_attributes: { ...args.spanAttributes, name },
       created: (/* @__PURE__ */ new Date()).toISOString()
     };
@@ -9243,7 +9294,7 @@ var Dataset = class {
     let { summarizeData = true } = options || {};
     await this.bgLogger.flush();
     const state = await this.getState();
-    const projectUrl = `${state.apiUrl}/app/${encodeURIComponent(
+    const projectUrl = `${state.appUrl}/app/${encodeURIComponent(
       state.orgName
     )}/p/${encodeURIComponent((await this.project).name)}`;
     const datasetUrl = `${projectUrl}/d/${encodeURIComponent(await this.name)}`;

package/dist/isomorph.d.ts

@@ -1,13 +1,4 @@
-export interface RepoStatus {
-    commit?: string;
-    branch?: string;
-    tag?: string;
-    dirty: boolean;
-    author_name?: string;
-    author_email?: string;
-    commit_message?: string;
-    commit_time?: string;
-}
+import { GitMetadataSettings, RepoStatus } from "@braintrust/core";
 export interface CallerLocation {
     caller_functionname: string;
     caller_filename: string;
@@ -19,7 +10,7 @@ export interface IsoAsyncLocalStorage<T> {
     getStore(): T | undefined;
 }
 export interface Common {
-    getRepoStatus: () => Promise<RepoStatus | undefined>;
+    getRepoStatus: (settings?: GitMetadataSettings) => Promise<RepoStatus | undefined>;
     getPastNAncestors: () => Promise<string[]>;
     getEnv: (name: string) => string | undefined;
     getCallerLocation: () => CallerLocation | undefined;

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { IS_MERGE_FIELD, PARENT_ID_FIELD, Source, AUDIT_SOURCE_FIELD, AUDIT_METADATA_FIELD } from "@braintrust/core";
+import { IS_MERGE_FIELD, PARENT_ID_FIELD, Source, AUDIT_SOURCE_FIELD, AUDIT_METADATA_FIELD, GitMetadataSettings } from "@braintrust/core";
 import { IsoAsyncLocalStorage } from "./isomorph";
 export type Metadata = Record<string, unknown>;
 export type SetCurrentArg = {
@@ -64,7 +64,9 @@ export interface Span {
      */
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
     /**
-     * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current. Be sure to end the span with `span.end()` when it has finished.
+     * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+     * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+     * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
      *
      * See `traced` for full details.
      *
@@ -111,12 +113,13 @@ declare class BraintrustState {
     currentExperiment: Experiment | undefined;
     currentLogger: Logger<false> | undefined;
     currentSpan: IsoAsyncLocalStorage<Span>;
-    apiUrl: string | null;
+    appUrl: string | null;
     loginToken: string | null;
     orgId: string | null;
     orgName: string | null;
     logUrl: string | null;
     loggedIn: boolean;
+    gitMetadataSettings?: GitMetadataSettings;
     private _apiConn;
     private _logConn;
     constructor();
@@ -176,12 +179,12 @@ export declare class Logger<IsAsyncFlush extends boolean> {
      * Log a single event. The event will be batched and uploaded behind the scenes if `logOptions.asyncFlush` is true.
      *
      * @param event The event to log.
-     * @param event.input: The arguments that uniquely define a user input (an arbitrary, JSON serializable object).
-     * @param event.output: The output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
-     * @param event.expected: The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
-     * @param event.scores: A dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare logs.
+     * @param event.input: (Optional) the arguments that uniquely define a user input (an arbitrary, JSON serializable object).
+     * @param event.output: (Optional) the output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
+     * @param event.expected: (Optional) the ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
+     * @param event.scores: (Optional) a dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare logs.
      * @param event.metadata: (Optional) a dictionary with additional data about the test example, model outputs, or just about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
-     * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end", "caller_functionname", "caller_filename", "caller_lineno".
+     * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
      * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
      * :returns: The `id` of the logged event.
      */
@@ -194,7 +197,9 @@ export declare class Logger<IsAsyncFlush extends boolean> {
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): PromiseUnless<IsAsyncFlush, R>;
     private lazyParentIds;
     /**
-     * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current.
+     * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+     * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+     * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
      *
      * See `traced` for full details.
      */
@@ -232,7 +237,7 @@ export type OtherExperimentLogFields = {
     datasetRecordId: string;
 };
 export type ExperimentLogPartialArgs = Partial<OtherExperimentLogFields> & Partial<InputField | InputsField>;
-export type ExperimentLogFullArgs = Partial<Omit<OtherExperimentLogFields, "scores">> & Required<Pick<OtherExperimentLogFields, "scores">> & Partial<InputField | InputsField> & Partial<IdField>;
+export type ExperimentLogFullArgs = Partial<Omit<OtherExperimentLogFields, "output" | "scores">> & Required<Pick<OtherExperimentLogFields, "output" | "scores">> & Partial<InputField | InputsField> & Partial<IdField>;
 export type LogFeedbackFullArgs = IdField & Partial<Omit<OtherExperimentLogFields, "output" | "metrics" | "datasetRecordId"> & {
     comment: string;
     source: Source;
@@ -259,6 +264,7 @@ type ExperimentEvent = Partial<InputField> & Partial<OtherExperimentLogFields> &
     created: string;
     span_parents: string[];
     span_attributes: Record<string, unknown>;
+    context: Record<string, unknown>;
     [PARENT_ID_FIELD]: string;
     [AUDIT_SOURCE_FIELD]: Source;
     [AUDIT_METADATA_FIELD]?: Record<string, unknown>;
@@ -311,10 +317,11 @@ export type InitOptions = {
     update?: boolean;
     baseExperiment?: string;
     isPublic?: boolean;
-    apiUrl?: string;
+    appUrl?: string;
     apiKey?: string;
     orgName?: string;
     metadata?: Metadata;
+    gitMetadataSettings?: GitMetadataSettings;
     setCurrent?: boolean;
 };
 /**
@@ -330,7 +337,7 @@ export type InitOptions = {
  * @param options.baseExperiment An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this
  * experiment. Otherwise, it will pick an experiment by finding the closest ancestor on the default (e.g. main) branch.
  * @param options.isPublic An optional parameter to control whether the experiment is publicly visible to anybody with the link or privately visible to only members of the organization. Defaults to private.
- * @param options.apiUrl The URL of the Braintrust API. Defaults to https://www.braintrustdata.com.
+ * @param options.appUrl The URL of the Braintrust App. Defaults to https://www.braintrustdata.com.
  * @param options.apiKey The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. If no API
  * key is specified, will prompt the user to login.
  * @param options.orgName (Optional) The name of a specific organization to connect to. This is useful if you belong to multiple.
@@ -338,6 +345,7 @@ export type InitOptions = {
  * about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the
  * `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any
  * JSON-serializable type, but its keys must be strings.
+ * @param options.gitMetadataSettings (Optional) Settings for collecting git metadata. By default, will collect all git metadata fields allowed in org-level settings.
  * @param setCurrent If true (the default), set the global current-experiment to the newly-created one.
  * @returns The newly created Experiment.
  */
@@ -354,7 +362,7 @@ type InitDatasetOptions = {
     dataset?: string;
     description?: string;
     version?: string;
-    apiUrl?: string;
+    appUrl?: string;
     apiKey?: string;
     orgName?: string;
 };
@@ -365,7 +373,7 @@ type InitDatasetOptions = {
  * @param options Additional options for configuring init().
  * @param options.dataset The name of the dataset to create. If not specified, a name will be generated automatically.
  * @param options.description An optional description of the dataset.
- * @param options.apiUrl The URL of the Braintrust API. Defaults to https://www.braintrustdata.com.
+ * @param options.appUrl The URL of the Braintrust App. Defaults to https://www.braintrustdata.com.
  * @param options.apiKey The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. If no API
  * key is specified, will prompt the user to login.
  * @param options.orgName (Optional) The name of a specific organization to connect to. This is useful if you belong to multiple.
@@ -382,7 +390,7 @@ type AsyncFlushArg<IsAsyncFlush> = {
 type InitLoggerOptions<IsAsyncFlush> = {
     projectName?: string;
     projectId?: string;
-    apiUrl?: string;
+    appUrl?: string;
     apiKey?: string;
     orgName?: string;
     forceLogin?: boolean;
@@ -395,7 +403,7 @@ type InitLoggerOptions<IsAsyncFlush> = {
  * @param options.projectName The name of the project to log into. If unspecified, will default to the Global project.
  * @param options.projectId The id of the project to log into. This takes precedence over projectName if specified.
  * @param options.asyncFlush If true, will log asynchronously in the background. Otherwise, will log synchronously. (false by default, to support serverless environments)
- * @param options.apiUrl The URL of the Braintrust API. Defaults to https://www.braintrustdata.com.
+ * @param options.appUrl The URL of the Braintrust App. Defaults to https://www.braintrustdata.com.
  * @param options.apiKey The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. If no API
  * key is specified, will prompt the user to login.
  * @param options.orgName (Optional) The name of a specific organization to connect to. This is useful if you belong to multiple.
@@ -409,14 +417,14 @@ export declare function initLogger<IsAsyncFlush extends boolean = false>(options
  * https://www.braintrustdata.com/app/token. This method is called automatically by `init()`.
  *
  * @param options Options for configuring login().
- * @param options.apiUrl The URL of the Braintrust API. Defaults to https://www.braintrustdata.com.
+ * @param options.appUrl The URL of the Braintrust App. Defaults to https://www.braintrustdata.com.
  * @param options.apiKey The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. If no API
  * key is specified, will prompt the user to login.
  * @param options.orgName (Optional) The name of a specific organization to connect to. This is useful if you belong to multiple.
  * @param options.forceLogin Login again, even if you have already logged in (by default, this function will exit quickly if you have already logged in)
  */
 export declare function login(options?: {
-    apiUrl?: string;
+    appUrl?: string;
     apiKey?: string;
     orgName?: string;
     forceLogin?: boolean;
@@ -470,7 +478,11 @@ export declare function getSpanParentObject<IsAsyncFlush extends boolean>(option
  */
 export declare function traced<IsAsyncFlush extends boolean = false, R = void>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg & AsyncFlushArg<IsAsyncFlush>): PromiseUnless<IsAsyncFlush, R>;
 /**
- * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current. See `traced` for full details.
+ * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+ * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+ * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
+ *
+ * See `traced` for full details.
  */
 export declare function startSpan<IsAsyncFlush extends boolean = false>(args?: StartSpanArgs & AsyncFlushArg<IsAsyncFlush>): Span;
 /**
@@ -502,10 +514,10 @@ export declare class Experiment {
      * @param event The event to log.
      * @param event.input: The arguments that uniquely define a test case (an arbitrary, JSON serializable object). Later on, Braintrust will use the `input` to know whether two test cases are the same between experiments, so they should not contain experiment-specific state. A simple rule of thumb is that if you run the same experiment twice, the `input` should be identical.
      * @param event.output: The output of your application, including post-processing (an arbitrary, JSON serializable object), that allows you to determine whether the result is correct or not. For example, in an app that generates SQL queries, the `output` should be the _result_ of the SQL query generated by the model, not the query itself, because there may be multiple valid queries that answer a single question.
-     * @param event.expected: The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate your experiments while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
+     * @param event.expected: (Optional) The ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not. Braintrust currently does not compare `output` to `expected` for you, since there are so many different ways to do that correctly. Instead, these values are just used to help you navigate your experiments while digging into analyses. However, we may later use these values to re-score outputs or fine-tune your models.
      * @param event.scores: A dictionary of numeric values (between 0 and 1) to log. The scores should give you a variety of signals that help you determine how accurate the outputs are compared to what you expect and diagnose failures. For example, a summarization app might have one score that tells you how accurate the summary is, and another that measures the word similarity between the generated and grouth truth summary. The word similarity score could help you determine whether the summarization was covering similar concepts or not. You can use these scores to help you sort, filter, and compare experiments.
      * @param event.metadata: (Optional) a dictionary with additional data about the test example, model outputs, or just about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
-     * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end", "caller_functionname", "caller_filename", "caller_lineno".
+     * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
      * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
      * @param event.dataset_record_id: (Optional) the id of the dataset record that this event is associated with. This field is required if and only if the experiment is associated with a dataset.
      * @param event.inputs: (Deprecated) the same as `input` (will be removed in a future version).
@@ -520,7 +532,9 @@ export declare class Experiment {
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
     private lazyParentIds;
     /**
-     * Lower-level alternative to `traced`, which does not automatically end the span or mark it as current.
+     * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
+     * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
+     * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
      *
      * See `traced` for full details.
      */