v4 - #2406
Open
Luca Forstner (lforst) wants to merge 9 commits into
Open
Conversation
ref: [SDK-226](https://linear.app/braintrustdata/issue/SDK-226) Replace Zod-inferred public types with explicit TypeScript types to reduce declaration size and downstream compile cost.
ref [#1841](#1841) Removes Plugins and unsubscribe functionality. Reasoning: Plugins are a bit of an unnecessary API to be exposed because they just attach stuff and un-attach stuff. The user can very easily just manage this by themselves. Also, unsubscribe is literally called from nowhere in the SDK.
Ref [#1841](#1841) `flushAsync` grinded my gears a bit a) as a user b) as a maintainer. Why?: - As a user, it added a quite intransparent API that is hard to wrap your head around. - As a user, it added a generic type to otherwise very non-generic APIs that made the LSP types incredibly hard to navigate - As a maintainer, it required a generic type to be passed around to literally everywhere - As a maintainer, it required us to have a weird `flushAsync` option to every tracing API In reality, what you can do instead, and which is very simple to understand, is simply do `await flush()` or `await logger.flush()` right after a span is ended. Not hard, very few if no drawbacks.
ref [#1841](#1841) - Replaced the root `braintrust` export surface with an explicit allowlist, removing roughly 140 named exports—primarily internal helpers, implementation classes, schemas, constants, and low-level types. - Stopped named-exporting most SDK-owned request/result types. Retained types are primarily user extension points, including `StartSpanArgs`, `Span`, tracing context types, eval callbacks, reporters, template plugins, and durable-eval stores. - Removed package subpaths `braintrust/browser`, `braintrust/util`, and `braintrust/webpack-loader`; the util bundle is no longer built or published. - Kept the webpack loader private: `braintrust/next` now resolves its built loader directly instead of exposing it as a package entrypoint. - Removed public implementation/testing exports such as `_exportsForTestingOnly`, `_internalIso`, `_internalGetGlobalState`, `_internalSetInitialState`, `SpanImpl`, `NoopSpan`, `TestBackgroundLogger`, `ObjectFetcher`, and ID-generator classes. - Removed public runtime schemas and serialization internals, including prompt, stream-chunk, attachment-reference, logs-overflow, and propagation schemas/constants. - Removed lower-level project/building APIs such as `graph`, `Project`, `CodeFunction`, `CodePrompt`, `PromptBuilder`, `ScorerBuilder`, and `ToolBuilder`; the `projects` facade remains. - Removed miscellaneous convenience and implementation exports including `log`, `summarize`, `traceable`, `newId`, `permalink`, `deepCopyEvent`, template-registry internals, span fetchers, and logs-overflow helpers. - Removed deprecated APIs: - `BraintrustMiddleware` and `wrapAISDKModel` - `wrapMastraAgent` - `withExperiment` and `withDataset` - `toAIStreamResponse` - deprecated bundler aliases `esbuildPlugin`, `rollupPlugin`, `vitePlugin`, and `webpackPlugin` - deprecated `useDiagnosticChannelCompatShim` - `Experiment.close()`, `Dataset.close()`, and `Span.close()` - `EvalHooks.meta`, `EvalResultWithSummary.toString()`, and `Score.error` - Removed legacy aliases and call shapes: - `initExperiment` - string-first `init()` and `initDataset()` overloads - dataset `useOutput` mode and the `output` record alias - deprecated event `inputs` and `datasetRecordId` fields - `wrapOpenAIv4` - Changed `EvalResultWithSummary` from an exported runtime class to a plain `{ summary, results }` result shape. - Restricted public span parenting to opaque `PropagationContext`; serialized span-slug strings remain internal plumbing. The public type is still named `StartSpanArgs`. - Added `configureContextManager()` and `ContextManager.getCurrentSpanStore()` as the supported context integration mechanism, replacing global symbols and direct state mutation. - Moved instrumentation-only APIs off the root: - `configureInstrumentation`, `InstrumentationConfig`, and Eve/Flue instrumentation remain under `braintrust/instrumentation`. - `registerOtelFlush` now lives there as the narrow OTEL hook. - Simplified OTEL integration: - Uses `configureContextManager()` instead of internal globals. - No longer overrides ID generation or V4 span serialization. - Replaced `contextFromSpanExport(string)` with `contextFromSpan(span)`. - `parentFromHeaders()` now returns opaque W3C propagation context. - Environment and `.env.braintrust` handling is self-contained and Edge-safe. - Removed the OTEL-specific exported ID generator. - Migrated Temporal propagation from private serialized span headers to standard `traceparent`, `tracestate`, and `baggage`, covering client→workflow, child workflow, and same-/cross-worker activity parenting. - Reworked `@braintrust/browser` to install a browser `ContextManager` through the public configuration API instead of mutating core isomorph internals. - Updated OpenAI Agents and the Vercel adapter to avoid `braintrust/util` and the exported `BraintrustStreamChunk`; the adapter now derives its stream chunk type from `BraintrustStream`. - Canonicalized instrumentation config keys by removing typed aliases such as `vercel`, `google`, `cursor`, `bedrock`, and `awsBedrock`; environment spellings still map to canonical keys. - Updated smoke tests, integration tests, Deno/browser coverage, and e2e scenarios to use only the curated public surface; added explicit tests for the allowed root types and published package entrypoints.
Integrate main through 5353f61 while preserving the v4 public API reductions, explicit public types, engine requirement, and removal of legacy CLI, plugin, flush, Flue, and Eve interfaces. Port provider updates into the internal instrumentation consumers, retain the new OpenAI Batch helpers, and reconcile dataset and OTEL changes with the v4 APIs. Keep Eve 0.34 pinned coverage and update the latest provider lane with tracePolicy support and matching replay fixtures.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.