Skip to content

feat: Upwards-recursively read .env.braintrust containing BRAINTRUST_API_KEY#466

Open
Luca Forstner (lforst) wants to merge 2 commits into
mainfrom
lforst/env-braintrust-api-key
Open

feat: Upwards-recursively read .env.braintrust containing BRAINTRUST_API_KEY#466
Luca Forstner (lforst) wants to merge 2 commits into
mainfrom
lforst/env-braintrust-api-key

Conversation

@lforst
Copy link
Copy Markdown
Member

@lforst Luca Forstner (lforst) commented May 26, 2026

Direct port of braintrustdata/braintrust-sdk-javascript#2049

Prompt used + some cleanup:

Implement `.env.braintrust` API key discovery for this Braintrust SDK.

Context:
The Braintrust instrumentation wizard will generate a file named `.env.braintrust` in the user’s current working directory. That file contains a dotenv-style `BRAINTRUST_API_KEY=...` entry. The goal is that after running the wizard, users can immediately run or verify local Braintrust instrumentation without manually exporting `BRAINTRUST_API_KEY`.

`.env.braintrust` is not a general dotenv loader. It is only a credential fallback for Braintrust SDK API-key lookup.

Required behavior:
- Preserve precedence:
  1. Explicit caller-provided API key wins.
  2. Nonblank `BRAINTRUST_API_KEY` from the process environment wins.
  3. Otherwise, read `BRAINTRUST_API_KEY` from `.env.braintrust`.
- Treat missing, empty, or whitespace-only environment values as unset.
- Look for `.env.braintrust` starting at the current working directory at lookup time, then walk upward.
- Cap lookup at cwd plus 64 parent directories.
- The nearest `.env.braintrust` wins.
- The nearest `.env.braintrust` is a boundary: if it exists but has no nonblank `BRAINTRUST_API_KEY`, do not check higher parents.
- If the nearest `.env.braintrust` cannot be read, return “not found” and do not check higher parents. Do not throw from credential discovery.
- Read only `BRAINTRUST_API_KEY`; do not load or expose other variables from the file.
- Do not mutate the process environment.
- Support normal dotenv syntax if the SDK/runtime has a standard parser: quotes, comments, and `export BRAINTRUST_API_KEY=...`.

Implementation guidance:
- Prefer lazy, nonblocking lookup.
- If possible, start candidate file reads in parallel, but preserve nearest-wins semantics: a higher parent may only win after all closer candidates are known absent.
- If a constructor/setup path is synchronous, do not add blocking file IO there.
- For telemetry/exporter integrations, make export/flush wait for API-key discovery when needed.

Look at the reference implementation PR: https://github.com/braintrustdata/braintrust-sdk-javascript/pull/2049

@lforst Luca Forstner (lforst) marked this pull request as ready for review May 26, 2026 17:53
@AbhiPrasad
Copy link
Copy Markdown
Member

gonna take this PR over w/ some of the env variable refactors I made.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants