Prefer version over environment in loaders

Author: joshuawootonn

js/src/logger.test.ts

@@ -10,6 +10,8 @@ import {
   initLogger,
   Prompt,
   BraintrustState,
+  loadPrompt,
+  loadParameters,
   wrapTraced,
   currentSpan,
   withParent,
@@ -464,6 +466,169 @@ test("init accepts dataset with id and version", () => {
   expect(datasetWithVersion.version).toBe("v2");
 });
 
+describe("loader version precedence", () => {
+  let state: BraintrustState;
+  let getJson: ReturnType<typeof vi.spyOn>;
+  const promptRow = {
+    id: "11111111-1111-4111-8111-111111111111",
+    _xact_id: "v1",
+    project_id: "22222222-2222-4222-8222-222222222222",
+    log_id: "p",
+    org_id: "33333333-3333-4333-8333-333333333333",
+    name: "Saved prompt",
+    slug: "saved-prompt",
+    description: null,
+    tags: null,
+    prompt_data: {
+      prompt: {
+        type: "chat",
+        messages: [{ role: "user", content: "Hello" }],
+      },
+      options: { model: "gpt-5-mini" },
+    },
+  } satisfies {
+    id: string;
+    _xact_id: string;
+    project_id: string;
+    log_id: "p";
+    org_id: string;
+    name: string;
+    slug: string;
+    description: null;
+    tags: null;
+    prompt_data: {
+      prompt: {
+        type: "chat";
+        messages: Array<{ role: "user"; content: string }>;
+      };
+      options: { model: string };
+    };
+  };
+  const parametersRow = {
+    id: "44444444-4444-4444-8444-444444444444",
+    _xact_id: "v1",
+    project_id: "55555555-5555-4555-8555-555555555555",
+    name: "Saved parameters",
+    slug: "saved-parameters",
+    description: null,
+    function_type: "parameters",
+    function_data: {
+      type: "parameters",
+      data: { prefix: "hello" },
+      __schema: {
+        type: "object",
+        properties: {
+          prefix: { type: "string", default: "hello" },
+        },
+        additionalProperties: true,
+      },
+    },
+  } satisfies {
+    id: string;
+    _xact_id: string;
+    project_id: string;
+    name: string;
+    slug: string;
+    description: null;
+    function_type: "parameters";
+    function_data: {
+      type: "parameters";
+      data: { prefix: string };
+      __schema: {
+        type: string;
+        properties: { prefix: { type: string; default: string } };
+        additionalProperties: boolean;
+      };
+    };
+  };
+
+  beforeEach(async () => {
+    state = await _exportsForTestingOnly.simulateLoginForTests();
+    vi.spyOn(state, "login").mockResolvedValue(state);
+    getJson = vi.spyOn(state.apiConn(), "get_json");
+  });
+
+  afterEach(() => {
+    _exportsForTestingOnly.simulateLogoutForTests();
+    vi.restoreAllMocks();
+  });
+
+  test("loadPrompt prefers version over environment for project lookup", async () => {
+    getJson.mockResolvedValue({ objects: [promptRow] });
+
+    await loadPrompt({
+      projectName: "test-project",
+      slug: "saved-prompt",
+      version: "v1",
+      environment: "production",
+      state,
+    });
+
+    expect(getJson).toHaveBeenCalledWith(
+      "v1/prompt",
+      expect.objectContaining({
+        project_name: "test-project",
+        slug: "saved-prompt",
+        version: "v1",
+      }),
+    );
+    expect(getJson.mock.calls[0][1]).not.toHaveProperty("environment");
+  });
+
+  test("loadPrompt prefers version over environment for id lookup", async () => {
+    getJson.mockResolvedValue(promptRow);
+
+    await loadPrompt({
+      id: promptRow.id,
+      version: "v1",
+      environment: "production",
+      state,
+    });
+
+    expect(getJson).toHaveBeenCalledWith(`v1/prompt/${promptRow.id}`, {
+      version: "v1",
+    });
+  });
+
+  test("loadParameters prefers version over environment for project lookup", async () => {
+    getJson.mockResolvedValue({ objects: [parametersRow] });
+
+    await loadParameters({
+      projectName: "test-project",
+      slug: "saved-parameters",
+      version: "v1",
+      environment: "production",
+      state,
+    });
+
+    expect(getJson).toHaveBeenCalledWith(
+      "v1/function",
+      expect.objectContaining({
+        project_name: "test-project",
+        slug: "saved-parameters",
+        version: "v1",
+        function_type: "parameters",
+      }),
+    );
+    expect(getJson.mock.calls[0][1]).not.toHaveProperty("environment");
+  });
+
+  test("loadParameters prefers version over environment for id lookup", async () => {
+    getJson.mockResolvedValue(parametersRow);
+
+    await loadParameters({
+      id: parametersRow.id,
+      version: "v1",
+      environment: "production",
+      state,
+    });
+
+    expect(getJson).toHaveBeenCalledWith(`v1/function/${parametersRow.id}`, {
+      version: "v1",
+    });
+  });
+});
+
 describe("prompt.build structured output templating", () => {
   test("applies nunjucks templating inside schema", () => {
     const prompt = new Prompt<false, false>(

js/src/logger.ts

@@ -4073,6 +4073,7 @@ export type LoadParametersByIdOptions = LoadParametersBaseOptions & {
 export type LoadParametersByIdWithEnvOptions = LoadParametersBaseOptions & {
   id: string;
   environment: string;
+  version?: string;
 };
 
 export type LoadParametersByProjectNameOptions = LoadParametersBaseOptions & {
@@ -4086,6 +4087,7 @@ export type LoadParametersByProjectNameWithEnvOptions =
     projectName: string;
     slug: string;
     environment: string;
+    version?: string;
   };
 
 export type LoadParametersByProjectIdOptions = LoadParametersBaseOptions & {
@@ -4099,6 +4101,7 @@ export type LoadParametersByProjectIdWithEnvOptions =
     projectId: string;
     slug: string;
     environment: string;
+    version?: string;
   };
 
 export type LoadParametersOptions =
@@ -4126,7 +4129,7 @@ type LoadParametersImplementationOptions = LoadParametersBaseOptions & {
  * @param options.projectId The id of the project to load the prompt from. This takes precedence over `projectName` if specified.
  * @param options.slug The slug of the prompt to load.
  * @param options.version An optional version of the prompt (to read). If not specified, the latest version will be used.
- * @param options.environment Fetch the version of the prompt assigned to the specified environment (e.g. "production", "staging"). Cannot be specified at the same time as `version`.
+ * @param options.environment Fetch the version of the prompt assigned to the specified environment (e.g. "production", "staging"). If both `version` and `environment` are provided, `version` takes precedence.
  * @param options.id The id of a specific prompt to load. If specified, this takes precedence over all other parameters (project and slug).
  * @param options.defaults (Optional) A dictionary of default values to use when rendering the prompt. Prompt values will override these defaults.
  * @param options.noTrace If true, do not include logging metadata for this prompt when build() is called.
@@ -4162,11 +4165,11 @@ export async function loadPrompt({
   forceLogin,
   state: stateArg,
 }: LoadPromptOptions) {
-  if (version && environment) {
-    throw new Error(
-      "Cannot specify both 'version' and 'environment' parameters. Please use only one (remove the other).",
-    );
-  }
+  const versionOrEnvironment = version
+    ? { version }
+    : environment
+      ? { environment }
+      : {};
   if (id) {
     // When loading by ID, we don't need project or slug
   } else if (isEmpty(projectName) && isEmpty(projectId)) {
@@ -4187,10 +4190,9 @@ export async function loadPrompt({
     });
     if (id) {
       // Load prompt by ID using the /v1/prompt/{id} endpoint
-      response = await state.apiConn().get_json(`v1/prompt/${id}`, {
-        ...(version && { version }),
-        ...(environment && { environment }),
-      });
+      response = await state
+        .apiConn()
+        .get_json(`v1/prompt/${id}`, versionOrEnvironment);
       // Wrap single prompt response in objects array to match list API format
       if (response) {
         response = { objects: [response] };
@@ -4200,13 +4202,12 @@ export async function loadPrompt({
         project_name: projectName,
         project_id: projectId,
         slug,
-        version,
-        ...(environment && { environment }),
+        ...versionOrEnvironment,
       });
     }
   } catch (e) {
     // If environment or version was specified, don't fall back to cache
-    if (environment || version) {
+    if (versionOrEnvironment) {
       throw new Error(`Prompt not found with specified parameters: ${e}`);
     }
 
@@ -4286,7 +4287,7 @@ export async function loadPrompt({
  * @param options.projectId The id of the project to load the parameters from. This takes precedence over `projectName` if specified.
  * @param options.slug The slug of the parameters to load.
  * @param options.version An optional version of the parameters (to read). If not specified, the latest version will be used.
- * @param options.environment Fetch the version of the parameters assigned to the specified environment (e.g. "production", "staging"). Cannot be specified at the same time as `version`.
+ * @param options.environment Fetch the version of the parameters assigned to the specified environment (e.g. "production", "staging"). If both `version` and `environment` are provided, `version` takes precedence.
  * @param options.id The id of specific parameters to load. If specified, this takes precedence over all other parameters (project and slug).
  * @param options.appUrl The URL of the Braintrust App. Defaults to https://www.braintrust.dev.
  * @param options.apiKey The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable.
@@ -4339,11 +4340,15 @@ export async function loadParameters<
 }: LoadParametersImplementationOptions): Promise<
   RemoteEvalParameters<true, true, InferParameters<S>>
 > {
-  if (version && environment) {
-    throw new Error(
-      "Cannot specify both 'version' and 'environment' parameters. Please use only one (remove the other).",
-    );
-  }
+  const effectiveEnvironment = version !== undefined ? undefined : environment;
+  const versionOrEnvironment =
+    version !== undefined
+      ? { version }
+      : effectiveEnvironment !== undefined
+        ? { environment: effectiveEnvironment }
+        : {};
+  const hasExplicitSelector =
+    version !== undefined || effectiveEnvironment !== undefined;
   if (id) {
     // When loading by ID, we don't need project or slug
   } else if (isEmpty(projectName) && isEmpty(projectId)) {
@@ -4364,8 +4369,7 @@ export async function loadParameters<
     });
     if (id) {
       response = await state.apiConn().get_json(`v1/function/${id}`, {
-        ...(version && { version }),
-        ...(environment && { environment }),
+        ...versionOrEnvironment,
       });
       if (response) {
         response = { objects: [response] };
@@ -4375,13 +4379,12 @@ export async function loadParameters<
         project_name: projectName,
         project_id: projectId,
         slug,
-        version,
         function_type: "parameters",
-        ...(environment && { environment }),
+        ...versionOrEnvironment,
       });
     }
   } catch (e) {
-    if (environment || version) {
+    if (hasExplicitSelector) {
       throw new Error(`Parameters not found with specified parameters: ${e}`);
     }