From 32238486aafe1ad7cb88eb55eeb11bcc146cebfb Mon Sep 17 00:00:00 2001 From: roroghost17 Date: Tue, 25 Aug 2026 16:06:04 +0530 Subject: [PATCH] docs: updated migration guide for 2.0.0 with the cost split function --- docs/enterprise/migration-guides/v2.0.0.mdx | 9 +- docs/migration-guides/v2.0.0.mdx | 99 ++++++++++++++++++++- 2 files changed, 104 insertions(+), 4 deletions(-) diff --git a/docs/enterprise/migration-guides/v2.0.0.mdx b/docs/enterprise/migration-guides/v2.0.0.mdx index c8644ab5b77..9cbe075e92c 100644 --- a/docs/enterprise/migration-guides/v2.0.0.mdx +++ b/docs/enterprise/migration-guides/v2.0.0.mdx @@ -3,7 +3,7 @@ title: "Migrating to Enterprise v2.0.0" description: "Breaking changes and migration instructions for the Enterprise v2.0.0 release" --- -Enterprise v2.0.0 is built on top of OSS `2.0.0-prerelease3` and inherits both breaking changes from that release. This page summarizes the inherited changes, the Enterprise license requirement, the plugin transport-hook change, and how the changes interact with SCIM-based authentication. +Enterprise v2.0.0 is built on the OSS v2.0.0 base and inherits its breaking changes. This page summarizes the inherited changes, the Enterprise license requirement, the plugin transport-hook change, and how the changes interact with SCIM-based authentication. **A provisioned Bifrost Enterprise license is required for v2.0.0.** Before migrating, contact the Bifrost team to obtain your `license.bif` file. Set the entire contents of this file as the value of the `BIFROST_LICENSE` environment variable on every node running Bifrost. Complete this configuration before upgrading to avoid interrupting your deployment. @@ -11,14 +11,17 @@ Enterprise v2.0.0 is built on top of OSS `2.0.0-prerelease3` and inherits both b --- -## Inherited OSS `2.0.0-prerelease3` Breaking Changes +## Inherited OSS v2.0.0 Breaking Changes -Enterprise v2.0.0 ships with the OSS `2.0.0-prerelease3` base, so both breaking changes from that release apply. See the [OSS v2.0.0 Migration Guide](/migration-guides/v2.0.0) for full before/after examples. +Enterprise v2.0.0 ships on the OSS v2.0.0 base, so all five OSS breaking changes apply. See the [OSS v2.0.0 Migration Guide](/migration-guides/v2.0.0) for full before/after examples and the migration checklist. | OSS # | Change | What you must do | |-------|--------|------------------| | 1 | **Custom plugin downloads are now SSRF-protected** | If any custom plugin `.so` (whether defined in `config.json` or via the admin API) is hosted on an internal/private-network URL, add that host to `server.plugin_download_private_allowlist`, or switch to a local file path | | 2 | **Custom plugin creation/update now requires admin authentication** | If dashboard auth is disabled or unconfigured, enable it before creating or updating a plugin with a custom `path` through the admin API. **OIDC SSO or SCIM provisioning already counts as configured dashboard auth**, so most Enterprise deployments need no action here (see [User Provisioning](/enterprise/user-provisioning)). Plugins defined directly in `config.json` are unaffected by this specific check (see the SCIM note below for how this check behaves under SCIM specifically) | +| 3 | **Governance APIs moved to the `/api/governance` namespace** | Move API clients, scripts, Postman collections, and UI callers to the canonical `/api/governance/*` paths, and switch Team/User list endpoints to `limit`/`offset` pagination. Legacy paths remain deprecated aliases for one GA release | +| 4 | **`HTTPTransportPreHook` now runs after authentication** | If a custom plugin injects a credential from `HTTPTransportPreHook`, rename that function to `HTTPTransportPreAuthHook`. See [Plugin Transport Hooks](#plugin-transport-hooks-new-pre-auth-phase) below for the SCIM/identity-provider specifics | +| 5 | **Request cost is now a per-category breakdown** | If any integration parses the `cost` / `token_usage.cost` object, remap the flat fields to the nested input/output/additional shape. Custom log store wrappers implementing `framework/logstore.LogStore` must update `BulkUpdateCost` to take `map[string]CostUpdate` | --- diff --git a/docs/migration-guides/v2.0.0.mdx b/docs/migration-guides/v2.0.0.mdx index 8f95290017b..74e2329fa89 100644 --- a/docs/migration-guides/v2.0.0.mdx +++ b/docs/migration-guides/v2.0.0.mdx @@ -3,7 +3,7 @@ title: "Migrating to v2.0.0" description: "Breaking changes and migration instructions for the v2.0.0 release" --- -v2.0.0 hardens custom plugin loading against server-side request forgery (SSRF), closes a path that let an unauthenticated caller register a custom native plugin when dashboard auth is disabled or unconfigured, moves all governance APIs under a single `/api/governance` namespace, and moves the plugin `HTTPTransportPreHook` phase to run after the transport authenticates the request. This page covers the four breaking changes in this release and how to migrate. +v2.0.0 hardens custom plugin loading against server-side request forgery (SSRF), closes a path that let an unauthenticated caller register a custom native plugin when dashboard auth is disabled or unconfigured, moves all governance APIs under a single `/api/governance` namespace, moves the plugin `HTTPTransportPreHook` phase to run after the transport authenticates the request, and restructures the request `cost` object into a per-category input/output/additional breakdown. This page covers the five breaking changes in this release and how to migrate. **Running Bifrost Enterprise?** This page covers the OSS behavior only. See the [Enterprise v2.0.0 Migration Guide](/enterprise/migration-guides/v2.0.0) for how these changes interact with SCIM-based authentication. @@ -242,6 +242,95 @@ See the [Plugin Migration Guide](/plugins/migration-guide) for the full hook con --- +## Breaking Change 5: Request Cost Is Now a Per-Category Breakdown + +The `BifrostCost` object (returned as `cost` on inference responses and as `token_usage.cost` on log entries) was restructured from a flat list of token-category costs into three buckets (input, output, additional), each with an optional nested details object, that reconcile to `total_cost`. + +**What changed:** the flat fields (`input_tokens_cost`, `output_tokens_cost`, `reasoning_tokens_cost`, `citation_tokens_cost`, `search_queries_cost`, `request_cost`) were replaced by `input_cost`, `output_cost`, and `additional_cost` aggregates plus `input_cost_details`, `output_cost_details`, and `additional_cost_details`. When the category split is populated, `input_cost + output_cost + additional_cost == total_cost`. A cost parsed from the legacy bare-number shape is the exception: `UnmarshalJSON` sets only `total_cost` and leaves the category fields zero, so treat `total_cost` as authoritative and check the category fields before relying on the equality. + +**Who is affected:** any client that parses the `cost` object from an inference response or the logs API, any Go code that reads `schemas.BifrostCost`, and any custom `framework/logstore` implementation. + +**How to fix it:** remap the fields you read using the table below. + +### JSON field mapping + +| v1.x (`cost`) | 2.0.0 (`cost`) | +|---|---| +| `input_tokens_cost` | `input_cost` (text portion in `input_cost_details.text_cost`) | +| `output_tokens_cost` | `output_cost` (text portion in `output_cost_details.text_cost`) | +| `reasoning_tokens_cost` | `output_cost_details.reasoning_cost` (rolled up in `output_cost`) | +| `citation_tokens_cost` | `output_cost_details.citation_cost` (rolled up in `output_cost`) | +| `search_queries_cost` | `output_cost_details.search_queries_cost` (rolled up in `output_cost`) | +| `request_cost` | `input_cost_details.request_cost` (rolled up in `input_cost`) | +| `total_cost` | `total_cost` (unchanged) | +| (none) | `additional_cost` + `additional_cost_details` (`guardrail_cost`, `mcp_cost`, `semantic_cache_cost`), new in 2.0.0 | + +`input_cost_details` also breaks out `audio_cost`, `image_cost`, `cached_read_cost`, and `cached_write_cost`; `output_cost_details` also breaks out `audio_cost` and `image_cost`. Every details field is omitted when zero. + + +**Reading historical data still works.** `BifrostCost` accepts the legacy flat shape (and a bare float total) when deserializing, so cost objects stored by v1.x, and providers that still emit the flat shape, parse without error. Only newly emitted responses use the nested shape, so update any consumer that reads cost fields by name. + + +**Before** (v1.x response `cost`): +```json +{ + "input_tokens_cost": 0.0021, + "output_tokens_cost": 0.0075, + "reasoning_tokens_cost": 0.0004, + "total_cost": 0.0096 +} +``` + +**After** (2.0.0 response `cost`): +```json +{ + "input_cost": 0.0021, + "input_cost_details": { "text_cost": 0.0021 }, + "output_cost": 0.0075, + "output_cost_details": { "text_cost": 0.0071, "reasoning_cost": 0.0004 }, + "total_cost": 0.0096 +} +``` + +### Go consumers of `schemas.BifrostCost` + +The struct fields were renamed to match the JSON above, and the former top-level breakouts now live on the details structs: + +**Before:** +```go +cost := resp.Cost +input := cost.InputTokensCost +reasoning := cost.ReasoningTokensCost +``` + +**After:** +```go +cost := resp.Cost +input := cost.InputCost +var reasoning float64 +if cost.OutputCostDetails != nil { + reasoning = cost.OutputCostDetails.ReasoningCost +} +``` + +### Custom log store implementations: `BulkUpdateCost` + +`LogStore.BulkUpdateCost` now takes the per-category split instead of a bare total, so a cost recompute keeps the denormalized `input_cost`/`output_cost`/`additional_cost` columns reconciled with the `cost` column. + +**Before:** +```go +BulkUpdateCost(ctx context.Context, updates map[string]float64) error +``` + +**After:** +```go +BulkUpdateCost(ctx context.Context, updates map[string]CostUpdate) error +``` + +`CostUpdate` carries `Total`, `Input`, `Output`, and `Additional`. A `BulkUpdateCost` implementation reads these fields and writes them to the row (see `framework/logstore/clickhousestore.go`); it does not construct them. Construction happens in the caller that builds the update map: it turns a `*schemas.BifrostCost` into a `CostUpdate` with `logstore.CostUpdateFromBreakdown(breakdown)` (which attributes an unsplit total to the input side for opaque-total providers), or builds `CostUpdate{Total: t, Input: t}` directly when only a total is available. + +--- + ## Migration Checklist @@ -276,4 +365,12 @@ Any role or API key that reads `/api/governance/users/{user_id}/virtual-keys` wi Legacy governance paths remain executable aliases for one complete GA release and return a `Deprecation` header. They are planned for removal in the following major release. + + +Any client parsing `cost` / `token_usage.cost`, or Go code reading `schemas.BifrostCost`, must move from the flat fields (`input_tokens_cost`, `reasoning_tokens_cost`, ...) to the nested input/output/additional shape (see the [JSON field mapping](#json-field-mapping)). + + + +If you implement `framework/logstore.LogStore`, change `BulkUpdateCost` to take `map[string]CostUpdate` and read each value's `Total`, `Input`, `Output`, and `Additional`. `CostUpdateFromBreakdown` belongs in the caller that builds the update map, not the implementation. +