fix: correct Anthropic streaming response format and usage tracking #186

fbzhong · 2025-07-23T05:16:22Z

Add dedicated AnthropicUsage type with cache token fields
Fix streaming event sequence to match Anthropic API format
Include usage data in streaming responses
Properly handle message_start, content_block_start/stop events
Track usage updates through message_delta events

coderabbitai · 2025-07-23T05:16:29Z

Summary by CodeRabbit

New Features
- Added support for streaming options and usage details in requests and responses, including cache-related token counts.
- Introduced prompt and content filter results in responses for enhanced transparency.
- Added error indication fields to tool messages and tool result content.
- New methods for formatting responses as Server-Sent Events (SSE).
Improvements
- Enhanced streaming response handling for Anthropic and OpenAI integrations, providing more granular event information and consistent usage reporting.
- Improved content serialization and error handling in streaming flows.
Chores
- Updated internal dependencies to use local modules for development.

Walkthrough

The changes introduce a provider-specific AnthropicUsage struct to replace the generic usage type in Anthropic streaming events, enriching token usage tracking with cache-related fields. Streaming event handling is refactored to accumulate and convert usage data consistently. The streaming response builder is overhauled to emit more granular SSE events, and function signatures are updated accordingly.

Changes

File(s)	Change Summary
core/providers/anthropic.go	Replaced `schemas.LLMUsage` with `AnthropicUsage` in event/message structs; added conversion method; updated streaming handler logic for usage tracking.
transports/bifrost-http/integrations/anthropic/router.go	Updated `ResponseConverter` signature and call to `DeriveAnthropicStreamFromBifrostResponse` to include `streamIndex`.
transports/bifrost-http/integrations/anthropic/types.go	Extended `AnthropicUsage` struct with cache fields; refactored `DeriveAnthropicStreamFromBifrostResponse` to handle multiple events, new parameter, and granular SSE construction.
transports/bifrost-http/integrations/genai/router.go	Updated `ResponseConverter` signature to include `streamIndex` parameter.
transports/bifrost-http/integrations/litellm/router.go	Updated `streamResponseConverter` signature and call to `DeriveAnthropicStreamFromBifrostResponse` to include `streamIndex`.
transports/bifrost-http/integrations/openai/router.go	Updated `ResponseConverter` signatures in multiple route configs to include `streamIndex` parameter.
transports/bifrost-http/integrations/utils.go	Updated `StreamResponseConverter` type signature to include `streamIndex`; modified streaming handler to track and pass stream index.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Router
    participant Provider
    participant SSE

    Client->>Router: Send streaming request
    Router->>Provider: Forward request
    Provider-->>Router: Stream events (with AnthropicUsage)
    Router->>SSE: DeriveAnthropicStreamFromBifrostResponse(resp, streamIndex)
    SSE-->>Client: Emit SSE events (message_start, content_block_start, deltas, etc.)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~45 minutes

Possibly related PRs

feat: Add Anthropic integration in HTTP transport #65: Adds initial Anthropic integration including request/response conversion and tool choice handling; this PR refactors and extends that code.

Suggested reviewers

danpiths
akshaydeo

Poem

In burrows deep, I code and hop,
Token counts now never stop!
With caches tracked and deltas neat,
Streaming flows are quite a feat.
SSEs bounce down the lane—
Anthropic’s usage, crystal plain!
🐇✨

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai generate unit tests to generate unit tests for this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

🔭 Outside diff range comments (1)

transports/bifrost-http/integrations/anthropic/types.go (1)

524-689: Consider refactoring this complex function for better maintainability.

The function has grown quite complex with multiple responsibilities. Consider extracting helper functions for different event types.

For example:

createMessageStartEvent(bifrostResp)

createContentBlockEvents(choice, messageIndex)

createMessageDeltaEvent(choice, usage)

This would improve readability and make the logic easier to test and maintain.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 99a0a77 and 468f367.

📒 Files selected for processing (3)

core/providers/anthropic.go (12 hunks)
transports/bifrost-http/integrations/anthropic/router.go (1 hunks)
transports/bifrost-http/integrations/anthropic/types.go (7 hunks)

🧠 Learnings (4)

📓 Common learnings

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#65
File: transports/bifrost-http/integrations/anthropic/types.go:131-180
Timestamp: 2025-06-10T13:11:37.867Z
Learning: In Anthropic API integration for Bifrost, messages won't contain both image and tool_result content blocks in the same message, so defensive guards against multiple embedded message structs are unnecessary in the content processing loop.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#54
File: core/schemas/provider.go:148-148
Timestamp: 2025-06-04T03:57:50.981Z
Learning: Breaking changes in the Bifrost codebase are managed by first merging and tagging core schema changes, then updating dependent code references in subsequent steps after the core version is released.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#162
File: transports/bifrost-http/integrations/genai/types.go:0-0
Timestamp: 2025-07-16T07:13:29.496Z
Learning: Pratham-Mishra04 prefers to avoid redundant error handling across architectural layers in the Bifrost streaming implementation. When error handling (such as timeouts, context cancellation, and JSON marshaling failures) is already handled at the provider level, they prefer not to duplicate this logic at the transport integration layer to keep the code simple and avoid unnecessary complexity.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#54
File: core/providers/anthropic.go:325-331
Timestamp: 2025-06-04T08:59:29.641Z
Learning: In the Anthropic provider, when handling system messages, prefer to let the API provider validate content (including empty strings) rather than pre-filtering on the client side. Users should receive errors directly from the provider if content is not supported.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:526-550
Timestamp: 2025-06-04T09:29:46.287Z
Learning: In core/providers/anthropic.go, the content field in formattedMessages is always of type []interface{} because it's explicitly constructed that way upstream in the prepareAnthropicChatRequest function. Defensive type casting for multiple types is not needed since the type is guaranteed by the construction logic.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T10:04:30.181Z
Learning: In the Anthropic provider (core/providers/anthropic.go), parallel tool calls support including the DisableParallelToolUse flag will be implemented in later commits as it's a relatively new feature that's not commonly used yet. The development approach prioritizes core functionality first.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:0-0
Timestamp: 2025-06-04T05:44:09.141Z
Learning: For the Anthropic provider in core/providers/anthropic.go, it's acceptable to pass potentially malformed messages with invalid roles because Anthropic's API will return suitable error responses for role issues, eliminating the need for additional validation logging.

transports/bifrost-http/integrations/anthropic/router.go (7)

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/router.go:19-33
Timestamp: 2025-06-09T16:46:32.018Z
Learning: In the GenericRouter (transports/bifrost-http/integrations), ResponseFunc is not called if the BifrostResponse parameter is nil, providing built-in protection against nil response marshaling.

Learnt from: Pratham-Mishra04
PR: #67
File: transports/bifrost-http/integrations/anthropic/router.go:26-34
Timestamp: 2025-06-10T11:19:29.604Z
Learning: The Generic router in transports/bifrost-http/integrations/utils.go already handles nil pointers from RequestConverter functions. When a RequestConverter returns a nil *schemas.BifrostRequest, the Generic router automatically returns an HTTP 400 error, making additional nil checks in individual router implementations redundant.

Learnt from: Pratham-Mishra04
PR: #67
File: transports/bifrost-http/integrations/anthropic/router.go:26-34
Timestamp: 2025-06-10T11:19:29.604Z
Learning: The Generic router in transports/bifrost-http/integrations/utils.go already handles nil pointers from RequestConverter functions. When a RequestConverter returns a nil *schemas.BifrostRequest, the Generic router automatically returns an HTTP 400 error with "Invalid request" message, making additional nil checks in individual router implementations redundant.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:0-0
Timestamp: 2025-06-04T05:44:09.141Z
Learning: For the Anthropic provider in core/providers/anthropic.go, it's acceptable to pass potentially malformed messages with invalid roles because Anthropic's API will return suitable error responses for role issues, eliminating the need for additional validation logging.

Learnt from: Pratham-Mishra04
PR: #63
File: transports/bifrost-http/integrations/openai/router.go:62-64
Timestamp: 2025-06-09T11:27:00.925Z
Learning: The lib.ConvertToBifrostContext function in the bifrost HTTP transport never returns nil and handles the conversion internally, so nil checks are not needed when calling this function.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:526-550
Timestamp: 2025-06-04T09:29:46.287Z
Learning: In core/providers/anthropic.go, the content field in formattedMessages is always of type []interface{} because it's explicitly constructed that way upstream in the prepareAnthropicChatRequest function. Defensive type casting for multiple types is not needed since the type is guaranteed by the construction logic.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/types.go:105-113
Timestamp: 2025-06-09T14:56:14.951Z
Learning: Streaming functionality is not yet supported in the Bifrost system, so Stream flags are intentionally not propagated from integration requests to BifrostRequest.

core/providers/anthropic.go (18)

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:526-550
Timestamp: 2025-06-04T09:29:46.287Z
Learning: In core/providers/anthropic.go, the content field in formattedMessages is always of type []interface{} because it's explicitly constructed that way upstream in the prepareAnthropicChatRequest function. Defensive type casting for multiple types is not needed since the type is guaranteed by the construction logic.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:0-0
Timestamp: 2025-06-04T05:44:09.141Z
Learning: For the Anthropic provider in core/providers/anthropic.go, it's acceptable to pass potentially malformed messages with invalid roles because Anthropic's API will return suitable error responses for role issues, eliminating the need for additional validation logging.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T09:36:27.956Z
Learning: In the Anthropic provider (core/providers/anthropic.go), the user has confirmed through practical experience that the tool_choice parameter should always use an object format with a "type" field (e.g., {"type": "auto"}, {"type": "tool", "name": "function_name"}), even though the official documentation examples sometimes show "auto" as a direct string. The current implementation correctly handles all tool choice types with the object format.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T10:04:30.181Z
Learning: In the Anthropic provider (core/providers/anthropic.go), parallel tool calls support including the DisableParallelToolUse flag will be implemented in later commits as it's a relatively new feature that's not commonly used yet. The development approach prioritizes core functionality first.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/types.go:326-376
Timestamp: 2025-06-09T16:56:44.395Z
Learning: In Anthropic's message format, tool_result content blocks are inputs sent TO the LLM (typically from user/system after tool execution), not outputs generated BY the LLM. LLM responses should only contain text and tool_use content types.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/types.go:131-180
Timestamp: 2025-06-10T13:03:26.997Z
Learning: In Anthropic API message format, tool_result content blocks are sent by users in response to assistant tool calls, while image content blocks are typically sent in initial user messages. These content types follow different conversation flows and wouldn't naturally appear together in a single message, making defensive guards against multiple embedded message types unnecessary.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/bedrock.go:53-55
Timestamp: 2025-06-04T05:16:54.784Z
Learning: AWS Bedrock's ContentBlock data type is a UNION, meaning only one field (text, toolUse, image, document, etc.) can be specified per content block. Unlike Anthropic's direct API, Bedrock cannot have both text and toolUse in a single content block - they must be separate blocks in the content array.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/bedrock.go:443-468
Timestamp: 2025-06-04T09:32:15.826Z
Learning: In core/providers/bedrock.go, for tool call result messages (ModelChatMessageRoleTool), the Content field represents the actual tool call output. A tool result message should only be created when msg.Content is non-nil, as there's no semantic meaning to a tool result without output content.

Learnt from: Pratham-Mishra04
PR: #64
File: transports/bifrost-http/integrations/genai/types.go:383-395
Timestamp: 2025-06-09T16:26:05.777Z
Learning: In the Bifrost schema (core/schemas/bifrost.go), only UserMessage and ToolMessage structs have ImageContent fields. AssistantMessage does not have an ImageContent field and cannot contain images. The schema design intentionally limits image content to user and tool messages only.

Learnt from: Pratham-Mishra04
PR: #83
File: core/schemas/bifrost.go:186-190
Timestamp: 2025-06-15T14:18:32.703Z
Learning: In core/schemas/bifrost.go, the ToolChoice UnmarshalJSON validation intentionally only checks for empty Type fields and lets providers handle validation of specific tool choice values. This architectural decision keeps schema validation focused on structure while allowing provider-specific semantic validation.

Learnt from: Pratham-Mishra04
PR: #80
File: plugins/maxim/main.go:249-264
Timestamp: 2025-06-14T06:17:54.426Z
Learning: In the BifrostError struct, the Error field is a struct (not a pointer), so accessing bifrostErr.Error.Message, bifrostErr.Error.Code, and bifrostErr.Error.Type is safe without nil checks on the Error field itself. The Code and Type fields are of type *string.

Learnt from: Pratham-Mishra04
PR: #54
File: core/schemas/bifrost.go:46-49
Timestamp: 2025-06-04T09:22:18.123Z
Learning: In core/schemas/bifrost.go, the RequestInput struct uses ChatCompletionInput *[]BifrostMessage (pointer-to-slice) rather than []BifrostMessage to properly represent union type semantics. For text completion requests, ChatCompletionInput should be nil to indicate "no chat payload at all", while for chat completion requests it should be non-nil (even if empty slice). This distinguishes between different request types rather than just empty vs non-empty chat messages.

Learnt from: Pratham-Mishra04
PR: #81
File: tests/core-providers/scenarios/end_to_end_tool_calling.go:43-45
Timestamp: 2025-06-16T04:13:55.437Z
Learning: In the Bifrost codebase, errors returned from client methods like ChatCompletionRequest are of type BifrostError, not the standard error interface. For testing these errors, use require.Nilf instead of require.NoErrorf since BifrostError doesn't work with the standard error assertion methods.

Learnt from: Pratham-Mishra04
PR: #177
File: transports/bifrost-http/handlers/completions.go:248-264
Timestamp: 2025-07-22T12:14:08.805Z
Learning: In transports/bifrost-http/handlers/completions.go, for speech completion requests, the user prefers to let the provider handle ResponseFormat validation rather than validating supported audio formats ("mp3", "opus", "aac", "flac") at the HTTP transport layer. This follows the architectural pattern of delegating domain-specific validation to providers rather than duplicating validation logic in the transport layer.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/utils.go:169-173
Timestamp: 2025-06-09T17:33:52.234Z
Learning: The ChatCompletionRequest method in the Bifrost client follows a contract where the result parameter will never be nil if the error parameter is nil. This means when error checking passes (err == nil), the result is guaranteed to be valid and can be safely used without additional nil checks.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/router.go:19-33
Timestamp: 2025-06-09T16:46:32.018Z
Learning: In the GenericRouter (transports/bifrost-http/integrations), ResponseFunc is not called if the BifrostResponse parameter is nil, providing built-in protection against nil response marshaling.

Learnt from: Pratham-Mishra04
PR: #81
File: tests/core-providers/scenarios/complete_end_to_end.go:39-41
Timestamp: 2025-06-16T04:12:05.427Z
Learning: In the Bifrost system, error returns are of type BifrostError rather than the standard Go error interface. Therefore, use require.Nilf(t, err, ...) instead of require.NoError(t, err) when checking for errors in Bifrost function calls.

Learnt from: Pratham-Mishra04
PR: #81
File: tests/core-providers/scenarios/simple_chat.go:39-41
Timestamp: 2025-06-16T04:13:42.755Z
Learning: In the Bifrost codebase, errors returned from methods like ChatCompletionRequest are of type BifrostError (a custom error type) rather than the standard Go error interface. Therefore, require.Nilf should be used for error assertions instead of require.NoErrorf.

transports/bifrost-http/integrations/anthropic/types.go (27)

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:526-550
Timestamp: 2025-06-04T09:29:46.287Z
Learning: In core/providers/anthropic.go, the content field in formattedMessages is always of type []interface{} because it's explicitly constructed that way upstream in the prepareAnthropicChatRequest function. Defensive type casting for multiple types is not needed since the type is guaranteed by the construction logic.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/types.go:131-180
Timestamp: 2025-06-10T13:11:37.867Z
Learning: In Anthropic API integration for Bifrost, messages won't contain both image and tool_result content blocks in the same message, so defensive guards against multiple embedded message structs are unnecessary in the content processing loop.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T09:36:27.956Z
Learning: In the Anthropic provider (core/providers/anthropic.go), the user has confirmed through practical experience that the tool_choice parameter should always use an object format with a "type" field (e.g., {"type": "auto"}, {"type": "tool", "name": "function_name"}), even though the official documentation examples sometimes show "auto" as a direct string. The current implementation correctly handles all tool choice types with the object format.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/types.go:140-146
Timestamp: 2025-06-10T13:51:52.859Z
Learning: In Bifrost core v1.0.9, ImageContent.Type was a pointer type (*string accessed via bifrost.Ptr), but in v1.0.10 it was changed to a value type (ImageContentType). When reviewing code, check the core version being used to determine the correct assignment pattern.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:0-0
Timestamp: 2025-06-04T05:44:09.141Z
Learning: For the Anthropic provider in core/providers/anthropic.go, it's acceptable to pass potentially malformed messages with invalid roles because Anthropic's API will return suitable error responses for role issues, eliminating the need for additional validation logging.

Learnt from: Pratham-Mishra04
PR: #54
File: core/schemas/bifrost.go:46-49
Timestamp: 2025-06-04T09:22:18.123Z
Learning: In core/schemas/bifrost.go, the RequestInput struct uses ChatCompletionInput *[]BifrostMessage (pointer-to-slice) rather than []BifrostMessage to properly represent union type semantics. For text completion requests, ChatCompletionInput should be nil to indicate "no chat payload at all", while for chat completion requests it should be non-nil (even if empty slice). This distinguishes between different request types rather than just empty vs non-empty chat messages.

Learnt from: Pratham-Mishra04
PR: #169
File: docs/usage/http-transport/openapi.json:1352-1358
Timestamp: 2025-07-17T08:56:59.907Z
Learning: In the Bifrost project, the fallback format has been updated from object structure {"provider": "...", "model": "..."} to a simpler string format "provider/model" (e.g., "anthropic/claude-3-sonnet-20240229"). The current OpenAPI schema correctly reflects this new format.

Learnt from: Pratham-Mishra04
PR: #144
File: transports/bifrost-http/handlers/providers.go:45-49
Timestamp: 2025-07-08T16:50:27.699Z
Learning: In the Bifrost project, breaking API changes are acceptable when features are not yet public. This applies to scenarios like changing struct fields from pointer to non-pointer types in request/response structures for unreleased features.

Learnt from: Pratham-Mishra04
PR: #55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T10:04:30.181Z
Learning: In the Anthropic provider (core/providers/anthropic.go), parallel tool calls support including the DisableParallelToolUse flag will be implemented in later commits as it's a relatively new feature that's not commonly used yet. The development approach prioritizes core functionality first.

Learnt from: connyay
PR: #92
File: core/providers/utils.go:60-64
Timestamp: 2025-06-17T14:04:21.104Z
Learning: The bifrost codebase uses string alias types (like type ContextKey string) for context keys consistently across multiple packages including plugins/maxim/main.go and transports/bifrost-http/tracking/plugin.go. This pattern should be maintained for consistency rather than switching to the canonical struct{} approach.

Learnt from: Pratham-Mishra04
PR: #94
File: core/schemas/bifrost.go:20-23
Timestamp: 2025-06-18T15:16:23.127Z
Learning: In the Bifrost project, BifrostConfig struct is never marshaled/unmarshaled, so serialization tags (json, yaml) are not needed for its fields.

Learnt from: Pratham-Mishra04
PR: #83
File: core/schemas/bifrost.go:186-190
Timestamp: 2025-06-15T14:18:32.703Z
Learning: In core/schemas/bifrost.go, the ToolChoice UnmarshalJSON validation intentionally only checks for empty Type fields and lets providers handle validation of specific tool choice values. This architectural decision keeps schema validation focused on structure while allowing provider-specific semantic validation.

Learnt from: Pratham-Mishra04
PR: #80
File: plugins/maxim/main.go:249-264
Timestamp: 2025-06-14T06:17:54.426Z
Learning: In the BifrostError struct, the Error field is a struct (not a pointer), so accessing bifrostErr.Error.Message, bifrostErr.Error.Code, and bifrostErr.Error.Type is safe without nil checks on the Error field itself. The Code and Type fields are of type *string.

Learnt from: Pratham-Mishra04
PR: #152
File: transports/bifrost-http/plugins/logging/utils.go:94-111
Timestamp: 2025-07-10T13:44:23.297Z
Learning: Pratham-Mishra04 prefers not to add error handling for JSON marshaling operations in the Bifrost logging plugin (transports/bifrost-http/plugins/logging/utils.go) because logging is not critical functionality and the structured schema data being marshaled is unlikely to fail. They accept the risk of not handling json.Marshal errors in logging contexts to keep the code simple.

Learnt from: Pratham-Mishra04
PR: #81
File: tests/core-providers/scenarios/end_to_end_tool_calling.go:43-45
Timestamp: 2025-06-16T04:13:55.437Z
Learning: In the Bifrost codebase, errors returned from client methods like ChatCompletionRequest are of type BifrostError, not the standard error interface. For testing these errors, use require.Nilf instead of require.NoErrorf since BifrostError doesn't work with the standard error assertion methods.

Learnt from: Pratham-Mishra04
PR: #152
File: transports/bifrost-http/plugins/logging/utils.go:378-399
Timestamp: 2025-07-10T13:44:14.518Z
Learning: In the Bifrost logging plugin (transports/bifrost-http/plugins/logging/utils.go), Pratham-Mishra04 prefers not to add error handling for JSON unmarshaling operations, considering logging not very critical and being confident that JSON marshalling won't fail in practice.

Learnt from: Pratham-Mishra04
PR: #152
File: transports/bifrost-http/plugins/logging/utils.go:16-18
Timestamp: 2025-07-10T13:44:39.237Z
Learning: In the Bifrost logging plugin (transports/bifrost-http/plugins/logging/utils.go), Pratham-Mishra04 prefers to ignore JSON marshaling errors when storing log entries because logging is not critical for their use case and they are certain the marshaling operations won't fail.

Learnt from: Pratham-Mishra04
PR: #83
File: core/providers/mistral.go:168-170
Timestamp: 2025-06-15T14:24:49.882Z
Learning: In the Bifrost codebase, performance is prioritized over defensive copying for HTTP service operations. Specifically, shallow slice assignments in provider response handling are acceptable due to object pool reset patterns and JSON unmarshaling behavior that minimize practical data corruption risks.

Learnt from: Pratham-Mishra04
PR: #63
File: transports/bifrost-http/integrations/openai/types.go:223-231
Timestamp: 2025-06-10T11:06:06.670Z
Learning: The OpenAI name field on messages cannot be preserved when converting to Bifrost format because the schemas.BifrostMessage struct in bifrost/core does not support a Name field. This is a known limitation of the Bifrost core schema design.

Learnt from: Pratham-Mishra04
PR: #81
File: tests/core-providers/scenarios/simple_chat.go:39-41
Timestamp: 2025-06-16T04:13:42.755Z
Learning: In the Bifrost codebase, errors returned from methods like ChatCompletionRequest are of type BifrostError (a custom error type) rather than the standard Go error interface. Therefore, require.Nilf should be used for error assertions instead of require.NoErrorf.

Learnt from: Pratham-Mishra04
PR: #88
File: core/providers/mistral.go:170-176
Timestamp: 2025-06-16T06:56:55.290Z
Learning: When JSON unmarshaling into pooled structs, slice fields like Choices []schemas.BifrostResponseChoice get fresh heap memory allocations from json.Unmarshal(). The slice data is not part of the pooled struct's memory, so defensive copying is unnecessary. Resetting pooled structs with *resp = ResponseType{} only clears slice headers, not the underlying data.

Learnt from: Pratham-Mishra04
PR: #64
File: transports/bifrost-http/integrations/genai/types.go:383-395
Timestamp: 2025-06-09T16:26:05.777Z
Learning: In the Bifrost schema (core/schemas/bifrost.go), only UserMessage and ToolMessage structs have ImageContent fields. AssistantMessage does not have an ImageContent field and cannot contain images. The schema design intentionally limits image content to user and tool messages only.

Learnt from: Pratham-Mishra04
PR: #75
File: transports/bifrost-http/integrations/genai/types.go:161-178
Timestamp: 2025-06-14T08:45:19.119Z
Learning: In the Bifrost project, when users pass empty messages (no content blocks and no content string), the system should error rather than trying to handle them gracefully. This is an intentional design decision - empty messages that would result in invalid JSON serialization are expected to cause errors to fail fast on invalid user input.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/anthropic/router.go:19-33
Timestamp: 2025-06-09T16:46:32.018Z
Learning: In the GenericRouter (transports/bifrost-http/integrations), ResponseFunc is not called if the BifrostResponse parameter is nil, providing built-in protection against nil response marshaling.

Learnt from: Pratham-Mishra04
PR: #177
File: transports/bifrost-http/handlers/completions.go:248-264
Timestamp: 2025-07-22T12:14:08.805Z
Learning: In transports/bifrost-http/handlers/completions.go, for speech completion requests, the user prefers to let the provider handle ResponseFormat validation rather than validating supported audio formats ("mp3", "opus", "aac", "flac") at the HTTP transport layer. This follows the architectural pattern of delegating domain-specific validation to providers rather than duplicating validation logic in the transport layer.

Learnt from: Pratham-Mishra04
PR: #65
File: transports/bifrost-http/integrations/utils.go:169-173
Timestamp: 2025-06-09T17:33:52.234Z
Learning: The ChatCompletionRequest method in the Bifrost client follows a contract where the result parameter will never be nil if the error parameter is nil. This means when error checking passes (err == nil), the result is guaranteed to be valid and can be safely used without additional nil checks.

Learnt from: Pratham-Mishra04
PR: #94
File: core/bifrost.go:823-845
Timestamp: 2025-06-18T15:15:51.323Z
Learning: In the Bifrost project, the team prioritizes maintaining consistent error handling patterns over exposing detailed error context. All errors should be wrapped in the standard BifrostError structure rather than creating specific error types or exposing richer error details like exit codes or stderr output.

🧬 Code Graph Analysis (1)

transports/bifrost-http/integrations/anthropic/router.go (1)

transports/bifrost-http/integrations/anthropic/types.go (1)

DeriveAnthropicStreamFromBifrostResponse (524-689)

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#65
File: transports/bifrost-http/integrations/anthropic/types.go:131-180
Timestamp: 2025-06-10T13:11:37.867Z
Learning: In Anthropic API integration for Bifrost, messages won't contain both image and tool_result content blocks in the same message, so defensive guards against multiple embedded message structs are unnecessary in the content processing loop.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#54
File: core/schemas/provider.go:148-148
Timestamp: 2025-06-04T03:57:50.981Z
Learning: Breaking changes in the Bifrost codebase are managed by first merging and tagging core schema changes, then updating dependent code references in subsequent steps after the core version is released.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#162
File: transports/bifrost-http/integrations/genai/types.go:0-0
Timestamp: 2025-07-16T07:13:29.496Z
Learning: Pratham-Mishra04 prefers to avoid redundant error handling across architectural layers in the Bifrost streaming implementation. When error handling (such as timeouts, context cancellation, and JSON marshaling failures) is already handled at the provider level, they prefer not to duplicate this logic at the transport integration layer to keep the code simple and avoid unnecessary complexity.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#54
File: core/providers/anthropic.go:325-331
Timestamp: 2025-06-04T08:59:29.641Z
Learning: In the Anthropic provider, when handling system messages, prefer to let the API provider validate content (including empty strings) rather than pre-filtering on the client side. Users should receive errors directly from the provider if content is not supported.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:526-550
Timestamp: 2025-06-04T09:29:46.287Z
Learning: In core/providers/anthropic.go, the content field in formattedMessages is always of type []interface{} because it's explicitly constructed that way upstream in the prepareAnthropicChatRequest function. Defensive type casting for multiple types is not needed since the type is guaranteed by the construction logic.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:483-494
Timestamp: 2025-06-04T10:04:30.181Z
Learning: In the Anthropic provider (core/providers/anthropic.go), parallel tool calls support including the DisableParallelToolUse flag will be implemented in later commits as it's a relatively new feature that's not commonly used yet. The development approach prioritizes core functionality first.

Learnt from: Pratham-Mishra04
PR: maximhq/bifrost#55
File: core/providers/anthropic.go:0-0
Timestamp: 2025-06-04T05:44:09.141Z
Learning: For the Anthropic provider in core/providers/anthropic.go, it's acceptable to pass potentially malformed messages with invalid roles because Anthropic's API will return suitable error responses for role issues, eliminating the need for additional validation logging.