> ## Documentation Index
> Fetch the complete documentation index at: https://bifrost-backport-mcp-oauth2-server.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning

> Cross-provider reference for reasoning and thinking capabilities in AI models

## Overview

Reasoning (also called "thinking" in some providers) allows AI models to show their step-by-step thought process before providing a final answer. This feature is available across multiple providers with different implementations.

<Info>
  Bifrost normalizes all provider-specific reasoning formats to a consistent OpenAI-compatible structure using `reasoning` in requests and `reasoning_details` in responses.
</Info>

***

## Provider Support Matrix

| Provider | Request Field | Response Field | Min Budget | Effort Levels | Streaming |
| - | - | - | - | - | - |
| OpenAI | `reasoning` | `reasoning_details` | None | `minimal`, `low`, `medium`, `high` | ✅ |
| Anthropic | `thinking` | Content blocks | **1024 tokens** | `enabled` only | ✅ |
| Bedrock (Anthropic) | `thinking` | Content blocks | **1024 tokens** | `enabled` only | ✅ |
| Gemini 2.5+ | `thinking_config` | `thought` parts | 1024 | Budget-only | ✅ |
| Gemini 3.0+ | `thinking_config` | `thought` parts | 1024 | `minimal`, `low`, `medium`, `high` + Budget | ✅ |

***

## Request Configuration

### Chat Completions API

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "model": "provider/model-name",
      "messages": [...],
      "reasoning": {
        "effort": "high",
        "max_tokens": 4096
      }
    }
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
    	"github.com/maximhq/bifrost"
    	"github.com/maximhq/bifrost/core/schemas"
    )

    chatReq := &schemas.BifrostChatRequest{
    	Provider: schemas.OpenAI,
    	Model:    "gpt-4o",
    	Input: []schemas.ChatMessage{
    		{
    			Role: schemas.ChatMessageRoleUser,
    			Content: &schemas.ChatMessageContent{
    				ContentStr: schemas.Ptr("Explain quantum computing"),
    			},
    		},
    	},
    	Params: &schemas.ChatParameters{
    		MaxCompletionTokens: schemas.Ptr(4096),
    		Reasoning: &schemas.ChatReasoning{
    			Effort:    schemas.Ptr("high"),
    			MaxTokens: schemas.Ptr(4096),
    		},
    	},
    }
    ```
  </Tab>
</Tabs>

### Responses API

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "model": "provider/model-name",
      "input": [...],
      "reasoning": {
        "effort": "high",
        "max_tokens": 4096,
        "summary": "detailed"
      }
    }
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
    	"github.com/maximhq/bifrost/core/schemas"
    )

    responsesReq := &schemas.BifrostResponsesRequest{
    	Provider: schemas.Anthropic,
    	Model:    "claude-3-5-sonnet-20241022",
    	Input: []schemas.ResponsesMessage{
    		{
    			Role: schemas.Ptr(schemas.ResponsesInputMessageRoleUser),
    			Content: &schemas.ResponsesMessageContent{
    				ContentStr: schemas.Ptr("Explain quantum computing"),
    			},
    		},
    	},
    	Params: &schemas.ResponsesParameters{
    		MaxOutputTokens: schemas.Ptr(4096),
    		Reasoning: &schemas.ResponsesParametersReasoning{
    			Effort:    schemas.Ptr("high"),
    			MaxTokens: schemas.Ptr(4096),
    			Summary:   schemas.Ptr("detailed"),
    		},
    	},
    }
    ```
  </Tab>
</Tabs>

<Note>
  Responses API supports both `effort` + `max_tokens` (like Chat Completions) and adds the optional `summary` parameter for output summarization.
</Note>

### Parameter Reference

#### Chat Completions API Parameters

| Parameter | Type | Description |
| - | - | - |
| `effort` | `string` | Reasoning intensity level |
| `max_tokens` | `int` | Maximum tokens for reasoning (budget) |

#### Responses API Parameters

| Parameter | Type | Description |
| - | - | - |
| `effort` | `string` | Reasoning intensity level |
| `max_tokens` | `int` | Maximum tokens for reasoning (budget) |
| `summary` | `string` | Summary level: `brief`, `detailed`, or `json` |

<Note>
  **Responses API** accepts the same `effort` and `max_tokens` parameters as Chat Completions, but adds an optional `summary` parameter for reasoning output summarization.
</Note>

***

## Provider-Specific Conversions

### OpenAI

OpenAI uses effort-based reasoning only. Bifrost applies priority logic:

1. If `reasoning.effort` is provided → use it directly
2. Else if `reasoning.max_tokens` is provided → estimate effort from it
3. The `max_tokens` field is cleared before sending to OpenAI

**Conversion Examples**:

<Tabs>
  <Tab title="Effort (JSON)">
    ```json theme={null}
    // Bifrost Request (with effort)
    {
      "reasoning": {
        "effort": "high"
      }
    }

    // OpenAI Request Sent
    {
      "reasoning": {
        "effort": "high"
      }
    }
    ```
  </Tab>

  <Tab title="Effort (Go)">
    ```go theme={null}
    // Bifrost request with effort (native field)
    chatReq := &schemas.BifrostChatRequest{
    	Provider: schemas.OpenAI,
    	Model:    "gpt-4o",
    	Input:    messages,
    	Params: &schemas.ChatParameters{
    		MaxCompletionTokens: schemas.Ptr(4096),
    		Reasoning: &schemas.ChatReasoning{
    			Effort: schemas.Ptr("high"),
    		},
    	},
    }

    // OpenAI receives effort directly, max_tokens is cleared
    ```
  </Tab>

  <Tab title="Max Tokens (JSON)">
    ```json theme={null}
    // Bifrost Request (with max_tokens only)
    {
      "max_completion_tokens": 4096,
      "reasoning": {
        "max_tokens": 3000
      }
    }

    // Estimation: ratio = 3000/4096 ≈ 0.73 → "high"
    // OpenAI Request Sent
    {
      "reasoning": {
        "effort": "high"
      }
    }
    ```
  </Tab>

  <Tab title="Max Tokens (Go)">
    ```go theme={null}
    // Bifrost request with max_tokens only
    chatReq := &schemas.BifrostChatRequest{
    	Provider: schemas.OpenAI,
    	Model:    "gpt-4o",
    	Input:    messages,
    	Params: &schemas.ChatParameters{
    		MaxCompletionTokens: schemas.Ptr(4096),
    		Reasoning: &schemas.ChatReasoning{
    			MaxTokens: schemas.Ptr(3000),
    		},
    	},
    }

    // Bifrost estimates effort from max_tokens
    // ratio = 3000/4096 ≈ 0.73 → effort = "high"
    // OpenAI receives effort, max_tokens cleared
    ```
  </Tab>
</Tabs>

**Supported Effort Levels**: `minimal`, `low`, `medium`, `high`

<Note>
  When `minimal` is encountered, it's converted to `low` for non-OpenAI providers. OpenAI receives only: `low`, `medium`, `high`.
</Note>

***

### Anthropic

Anthropic uses a `thinking` parameter with different structure.

<Tabs>
  <Tab title="Request Conversion (JSON)">
    ```json theme={null}
    // Bifrost Request
    {
      "reasoning": {
        "effort": "high",
        "max_tokens": 4096
      }
    }

    // Anthropic Request
    {
      "thinking": {
        "type": "enabled",
        "budget_tokens": 4096
      }
    }
    ```
  </Tab>

  <Tab title="Request Conversion (Go)">
    ```go theme={null}
    // Using Bifrost Go SDK
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Anthropic,
      Model:    "claude-3-5-sonnet-20241022",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          MaxTokens: schemas.Ptr(4096), // Anthropic native field
        },
      },
    }

    // Bifrost converts to Anthropic format:
    // {
    //   "thinking": {
    //     "type": "enabled",
    //     "budget_tokens": 4096
    //   }
    // }
    ```
  </Tab>

  <Tab title="Response Conversion (JSON)">
    ```json theme={null}
    // Anthropic Response (content blocks)
    {
      "content": [
        {
          "type": "thinking",
          "thinking": "Let me analyze this step by step...",
          "signature": "EqoBCkgIAR..."
        },
        {
          "type": "text",
          "text": "The answer is 42."
        }
      ]
    }

    // Bifrost Response
    {
      "choices": [{
        "message": {
          "content": "The answer is 42.",
          "reasoning": "Let me analyze this step by step...",
          "reasoning_details": [{
            "index": 0,
            "type": "text",
            "text": "Let me analyze this step by step...",
            "signature": "EqoBCkgIAR..."
          }]
        }
      }]
    }
    ```
  </Tab>

  <Tab title="Response Conversion (Go)">
    ```go theme={null}
    // After calling Bifrost Chat Completions with reasoning
    resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), chatReq)
    if err != nil {
      log.Fatal(err)
    }

    // Extract reasoning from response
    choice := resp.Choices[0]
    message := choice.Message

    // Access combined reasoning text
    reasoningText := message.Reasoning

    // Access detailed reasoning blocks
    for i, details := range message.ReasoningDetails {
      fmt.Printf("Block %d: %s\n", i, details.Text)
      if details.Signature != "" {
        fmt.Printf("  Signature: %s\n", details.Signature)
      }
    }
    ```
  </Tab>
</Tabs>

**Conversion Rules**:

| Bifrost | Anthropic | Notes |
| - | - | - |
| `reasoning.effort` | `thinking.type` | Always mapped to `"enabled"` |
| `reasoning.max_tokens` | `thinking.budget_tokens` | Token budget for reasoning |

<Warning>
  **Critical Constraint**: Anthropic requires `reasoning.max_tokens >= 1024`. Requests with lower values will **fail with an error**.
</Warning>

**Dynamic Budget Handling**:

| Input Value | Converted To |
| - | - |
| `-1` (dynamic) | `1024` (minimum default) |
| `< 1024` | **Error** |
| `>= 1024` | Pass-through |

**Code Reference**: `core/providers/anthropic/chat.go:104-134`

***

### Bedrock (Anthropic Models)

Bedrock uses the same structure as Anthropic for Claude models.

<Tabs>
  <Tab title="Request (JSON)">
    ```json theme={null}
    // Bifrost Request
    {
      "reasoning": {
        "effort": "high",
        "max_tokens": 4096
      }
    }

    // Bedrock Request (for Anthropic/Claude models)
    {
      "additionalModelRequestFields": {
        "reasoning_config": {
          "type": "enabled",
          "budget_tokens": 4096
        }
      }
    }
    ```
  </Tab>

  <Tab title="Request (Go)">
    ```go theme={null}
    // Using Bifrost Go SDK with Bedrock provider
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Bedrock,
      Model:    "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          MaxTokens: schemas.Ptr(4096), // Bedrock Anthropic native field
        },
      },
    }

    // Bifrost converts to Bedrock format with reasoning_config
    ```
  </Tab>
</Tabs>

<Note>
  The same 1024 minimum token budget constraint applies to Bedrock Anthropic models. Attempts to set `max_tokens` below 1024 will result in an error.
</Note>

**Code Reference**: `core/providers/bedrock/utils.go:34-47`

***

### Bedrock (Nova Models)

Bedrock Nova models use an effort-based approach similar to OpenAI.

<Tabs>
  <Tab title="Request Conversion (JSON)">
    ```json theme={null}
    // Bifrost Request
    {
      "reasoning": {
        "effort": "high",
        "max_tokens": 4096
      }
    }

    // Bedrock Request (for Nova models)
    {
      "additionalModelRequestFields": {
        "reasoningConfig": {
          "type": "enabled",
          "maxReasoningEffort": "high"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Request Conversion (Go)">
    ```go theme={null}
    // Using Bifrost Go SDK with Bedrock Nova
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Bedrock,
      Model:    "us.amazon.nova-pro-v1:0",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          Effort: schemas.Ptr("high"), // Nova native field
        },
      },
    }

    // Bifrost converts to Bedrock Nova format:
    // reasoningConfig: {
    //   type: "enabled",
    //   maxReasoningEffort: "high"
    // }
    ```
  </Tab>

  <Tab title="Effort Levels">
    | Bifrost Effort | Nova Effort | Configuration |
    | - | - | - |
    | `minimal`, `low` | `"low"` | Normal parameters allowed |
    | `medium` | `"medium"` | Normal parameters allowed |
    | `high` | `"high"` | Clears `maxTokens`, `temperature`, `topP` |
  </Tab>
</Tabs>

**Key Differences from Anthropic**:

* No minimum token budget constraint
* Uses effort levels instead of token budgets
* High effort mode automatically clears conflicting parameters

**Code Reference**: `core/providers/bedrock/utils.go:48-89`

***

### Gemini

Gemini uses `thinking_config` with dual support for both token budgets and effort levels, depending on the model version.

#### Model Version Support

| Gemini Version | `thinkingBudget` | `thinkingLevel` | Notes |
| - | - | - | - |
| **2.5+** | ✅ | ❌ | Budget-only models |
| **3.0+** | ✅ | ✅ | Support both budget and level |

<Warning>
  **Important**: Only ONE parameter (`thinkingBudget` or `thinkingLevel`) should be sent to Gemini at a time. When both `reasoning.max_tokens` and `reasoning.effort` are provided in a Bifrost request, `max_tokens` takes priority and is converted to `thinkingBudget`.
</Warning>

#### Priority Rules

When both `reasoning.max_tokens` and `reasoning.effort` are present:

```
1. If max_tokens is provided → USE thinkingBudget (ignores effort)
2. Else if effort is provided:
   - Gemini 3.0+ → USE thinkingLevel (more native)
   - Gemini 2.5 → CONVERT effort to thinkingBudget
3. Else → disable reasoning
```

<Tabs>
  <Tab title="Budget Priority (JSON)">
    ```json theme={null}
    // Bifrost Request - Both fields provided
    {
      "model": "gemini-3.0-flash",
      "reasoning": {
        "effort": "high",        // Ignored
        "max_tokens": 4096      // Takes priority
      }
    }

    // Gemini 3.0+ Request - Only budget sent
    {
      "generation_config": {
        "thinking_config": {
          "include_thoughts": true,
          "thinking_budget": 4096
        }
      }
    }
    ```
  </Tab>

  <Tab title="Effort to Level (Gemini 3.0+)">
    ```json theme={null}
    // Bifrost Request - Effort only
    {
      "model": "gemini-3.0-flash",
      "reasoning": {
        "effort": "high"
      }
    }

    // Gemini 3.0+ Request - Converted to level
    {
      "generation_config": {
        "thinking_config": {
          "include_thoughts": true,
          "thinking_level": "high"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Effort to Budget (Gemini 2.5)">
    ```json theme={null}
    // Bifrost Request - Effort only
    {
      "model": "gemini-2.5-flash",
      "max_completion_tokens": 4096,
      "reasoning": {
        "effort": "high"
      }
    }

    // Gemini 2.5 Request - Converted to budget
    // Calculation: 1024 + (0.80 × (4096 - 1024)) = 3482
    {
      "generation_config": {
        "thinking_config": {
          "include_thoughts": true,
          "thinking_budget": 3482
        }
      }
    }
    ```
  </Tab>
</Tabs>

#### Model-Specific Level Conversions

Gemini Pro models have stricter constraints on thinking levels:

| Bifrost Effort | Non-Pro Models | Pro Models | Notes |
| - | - | - | - |
| `"none"` | Empty string | Empty string | Disables thinking |
| `"minimal"` | `"minimal"` | `"low"` | Pro doesn't support minimal |
| `"low"` | `"low"` | `"low"` | Supported on all |
| `"medium"` | `"medium"` | `"high"` | Pro doesn't support medium |
| `"high"` | `"high"` | `"high"` | Supported on all |

**Example**:

```go theme={null}
// For "gemini-3.0-flash-thinking-exp" (non-Pro)
effort: "medium" → thinkingLevel: "medium"

// For "gemini-3.0-pro" (Pro model)
effort: "medium" → thinkingLevel: "high"  // Converted up
```

#### Special Values

| Value | Field | Behavior | Use Case |
| - | - | - | - |
| `0` | `max_tokens` | `thinking_budget: 0`, `include_thoughts: false` | Explicitly disable reasoning |
| `-1` | `max_tokens` | `thinking_budget: -1` | **Dynamic budget** (Gemini decides) |
| `"none"` | `effort` | `thinking_budget: 0`, `include_thoughts: false` | Disable reasoning |

<Tabs>
  <Tab title="Dynamic Budget (JSON)">
    ```json theme={null}
    // Bifrost Request - Dynamic budget
    {
      "reasoning": {
        "max_tokens": -1
      }
    }

    // Gemini Request - Sent as-is
    {
      "generation_config": {
        "thinking_config": {
          "include_thoughts": true,
          "thinking_budget": -1
        }
      }
    }
    ```
  </Tab>

  <Tab title="Disable Reasoning (JSON)">
    ```json theme={null}
    // Bifrost Request - Method 1
    {
      "reasoning": {
        "max_tokens": 0
      }
    }

    // Bifrost Request - Method 2
    {
      "reasoning": {
        "effort": "none"
      }
    }

    // Gemini Request - Both become
    {
      "generation_config": {
        "thinking_config": {
          "include_thoughts": false,
          "thinking_budget": 0
        }
      }
    }
    ```
  </Tab>

  <Tab title="Go SDK Examples">
    ```go theme={null}
    // Using Bifrost Go SDK with Gemini
    // Example 1: Dynamic budget
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Gemini,
      Model:    "gemini-2.0-flash-thinking-exp-1219",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          MaxTokens: schemas.Ptr(-1), // Let Gemini decide
        },
      },
    }

    // Example 2: Effort-based for Gemini 3.0+
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Gemini,
      Model:    "gemini-3.0-flash",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          Effort: schemas.Ptr("high"), // Converts to thinkingLevel
        },
      },
    }

    // Example 3: Budget-based (all versions)
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Gemini,
      Model:    "gemini-2.5-flash",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          MaxTokens: schemas.Ptr(3000), // Direct budget
        },
      },
    }
    ```
  </Tab>
</Tabs>

#### Response Conversion

<Tabs>
  <Tab title="Response (JSON)">
    ```json theme={null}
    // Gemini Response
    {
      "candidates": [{
        "content": {
          "parts": [
            {
              "thought": true,
              "text": "Analyzing the problem..."
            },
            {
              "text": "The answer is 42."
            }
          ]
        }
      }]
    }

    // Bifrost Response
    {
      "choices": [{
        "message": {
          "content": "The answer is 42.",
          "reasoning": "Analyzing the problem...",
          "reasoning_details": [{
            "index": 0,
            "type": "text",
            "text": "Analyzing the problem..."
          }]
        }
      }]
    }
    ```
  </Tab>

  <Tab title="Response (Go)">
    ```go theme={null}
    // After calling Bifrost Chat Completions with Gemini
    resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), chatReq)
    if err != nil {
      log.Fatal(err)
    }

    // Extract reasoning from response
    choice := resp.Choices[0]
    message := choice.Message

    // Access combined reasoning text
    fmt.Printf("Reasoning: %s\n", message.Reasoning)

    // Access detailed reasoning blocks
    for i, details := range message.ReasoningDetails {
      if details.Type == "text" {
        fmt.Printf("Thinking block %d:\n%s\n", i, details.Text)
      }
    }

    // Access final answer
    fmt.Printf("Answer:\n%s\n", message.Content)
    ```
  </Tab>
</Tabs>

#### Conversion Summary

**Bifrost → Gemini (Request)**:

| Input | Gemini 2.5 | Gemini 3.0+ | Note |
| - | - | - | - |
| `max_tokens: 4096` | `thinking_budget: 4096` | `thinking_budget: 4096` | Direct pass-through |
| `max_tokens: -1` | `thinking_budget: -1` | `thinking_budget: -1` | Dynamic budget |
| `max_tokens: 0` | `thinking_budget: 0` | `thinking_budget: 0` | Disabled |
| `effort: "high"` only | `thinking_budget: 3482`\* | `thinking_level: "high"` | Estimated or native |
| `effort: "medium"` only | `thinking_budget: 2330`\* | `thinking_level: "medium"` or `"high"`\*\* | Estimated or native |
| Both `effort` + `max_tokens` | Uses `max_tokens` | Uses `max_tokens` | Priority rule |

\* Assumes `max_completion_tokens: 8192` (default), uses estimation formula\
\*\* Pro models convert `"medium"` to `"high"`

**Gemini → Bifrost (Response)**:

| Gemini Field | Bifrost Field | Conversion |
| - | - | - |
| `thinking_budget` | `reasoning.max_tokens` | Direct mapping |
| `thinking_level` | `reasoning.effort` | Level → effort mapping |
| `thought: true` parts | `reasoning_details[]` | Array of reasoning blocks |

**Code References**:

* `core/providers/gemini/utils.go` (Chat Completions)
* `core/providers/gemini/responses.go` (Responses API)
* `core/providers/gemini/types.go` (Constants)

***

## Two Reasoning Methods: Effort vs. Max Tokens

Bifrost supports two distinct reasoning models across different providers:

### Reasoning Model Types

| Model | Providers | Request Field | Native Format |
| - | - | - | - |
| **Effort-Based** | OpenAI, AWS Bedrock Nova | `reasoning.effort` | `reasoning_effort` (Chat) / `effort` (Responses) |
| **Max-Tokens-Based** | Anthropic, Cohere, Gemini | `reasoning.max_tokens` | `thinking.budget_tokens` |

**Important**: Both effort and max\_tokens can be specified in a single request. Bifrost uses a **priority hierarchy** to determine which field is used.

### Priority Logic: Native vs. Estimated

When both `effort` and `max_tokens` are present in a request, Bifrost prioritizes the **native compatible field** for the target provider:

#### **For Max-Tokens-Based Providers** (Anthropic, Cohere, Gemini)

```
1. If reasoning.max_tokens is provided → USE IT (native field)
2. Else if reasoning.effort is provided → ESTIMATE max_tokens from effort
3. Else → disable reasoning
```

**Example** (Cohere):

```json theme={null}
// Request with both fields
{
  "reasoning": {
    "effort": "high",
    "max_tokens": 2000
  }
}
```

**Result**: Uses `max_tokens: 2000` directly, ignores `effort`

#### **For Effort-Based Providers** (OpenAI, AWS Bedrock Nova)

```
1. If reasoning.effort is provided → USE IT (native field)
2. Else if reasoning.max_tokens is provided → ESTIMATE effort from max_tokens
3. Else → disable reasoning
```

**Example** (OpenAI Chat Completions):

```json theme={null}
// Request with both fields
{
  "reasoning": {
    "effort": "high",
    "max_tokens": 2000
  }
}
```

**Result**: Uses `effort: "high"` directly, strips `max_tokens` from JSON

<Accordion title="Why Priority Matters">
  **Reason 1: Accuracy** - Native fields provide direct control without estimation loss

  **Reason 2: Consistency** - Using native fields ensures the exact user intent is preserved

  **Reason 3: Performance** - Avoids unnecessary conversions when native field is already provided
</Accordion>

***

## Estimator Functions

Bifrost provides two estimator functions to convert between reasoning methods. These are used when the native field is not available.

### Function 1: Effort → Max Tokens

**Function**: `GetBudgetTokensFromReasoningEffort()`

**File**: `core/providers/utils/utils.go:1350-1387`

**Signature**:

```go theme={null}
func GetBudgetTokensFromReasoningEffort(
    effort string,           // "minimal", "low", "medium", "high"
    minBudgetTokens int,     // Provider-specific minimum (e.g., 1024 for Anthropic)
    maxTokens int,           // Total completion tokens available
) (int, error)
```

**Algorithm**:

```
1. Define ratio for effort level:
   - "minimal"  → 2.5%  (0.025)
   - "low"      → 15%   (0.15)
   - "medium"   → 42.5% (0.425)
   - "high"     → 80%   (0.80)

2. Calculate budget:
   budget = minBudgetTokens + (ratio × (maxTokens - minBudgetTokens))

3. Clamp to valid range:
   if budget < minBudgetTokens → budget = minBudgetTokens
   if budget > maxTokens → budget = maxTokens
```

**Conversion Examples** (with `minBudgetTokens=1024`, `maxTokens=4096`):

| Effort | Ratio | Calculation | Result |
| - | - | - | - |
| `minimal` | 2.5% | 1024 + 0.025 × 3072 | 1101 → 1024\* |
| `low` | 15% | 1024 + 0.15 × 3072 | 1485 |
| `medium` | 42.5% | 1024 + 0.425 × 3072 | 2330 |
| `high` | 80% | 1024 + 0.80 × 3072 | 3482 |

<Note>
  \*When result is below minimum, clamped to minBudgetTokens (for Anthropic minimum of 1024)
</Note>

**Error Handling**:

```go theme={null}
if minBudgetTokens > maxTokens {
    return 0, fmt.Errorf("max_tokens must be > minBudgetTokens")
}
```

**Code Example**:

```go theme={null}
// Cohere: Convert effort to token budget
budgetTokens, err := providerUtils.GetBudgetTokensFromReasoningEffort(
    "high",                    // effort
    1,                         // Cohere min
    4096,                      // max completion tokens
)
// Returns: 3277 tokens
```

### Function 2: Max Tokens → Effort

**Function**: `GetReasoningEffortFromBudgetTokens()`

**File**: `core/providers/utils/utils.go:1308-1345`

**Signature**:

```go theme={null}
func GetReasoningEffortFromBudgetTokens(
    budgetTokens int,        // Reasoning token budget
    minBudgetTokens int,     // Provider-specific minimum
    maxTokens int,           // Total completion tokens available
) string                     // Returns: "low", "medium", "high"
```

**Algorithm**:

```
1. Normalize budget to valid range:
   if budget < min → budget = min
   if budget > max → budget = max

2. Calculate ratio:
   ratio = (budgetTokens - minBudgetTokens) / (maxTokens - minBudgetTokens)

3. Map ratio to effort level:
   if ratio ≤ 0.25  → "low"
   if ratio ≤ 0.60  → "medium"
   if ratio > 0.60  → "high"
```

**Conversion Examples** (with `minBudgetTokens=1024`, `maxTokens=4096`):

| Budget Tokens | Ratio | Effort |
| - | - | - |
| 1024 | 0% | `low` |
| 1101 | 2.5% | `low` |
| 1500 | 15.6% | `low` |
| 1900 | 28.6% | `medium` |
| 2500 | 48.1% | `medium` |
| 3000 | 64.5% | `high` |
| 3400 | 77.6% | `high` |

**Defensive Defaults**:

```go theme={null}
if budgetTokens <= 0 {
    return "none"
}
if maxTokens <= 0 {
    return "medium"  // Safe default
}
if maxTokens <= minBudgetTokens {
    return "high"    // Can't calculate ratio
}
```

**Code Example**:

```go theme={null}
// Convert Anthropic budget back to effort for display
effort := providerUtils.GetReasoningEffortFromBudgetTokens(
    3000,   // budget tokens from Anthropic response
    1024,   // Anthropic minimum
    4096,   // max tokens
)
// Returns: "high"
```

***

## Provider-Specific Constants

Different providers have different constraints on reasoning budget:

### Min Budget Constants

| Provider | File | MinBudgetTokens | Reason |
| - | - | - | - |
| Anthropic | `core/providers/anthropic/types.go` | **1024** | Anthropic API requirement |
| Bedrock Anthropic | `core/providers/bedrock/types.go` | **1024** | Same as Anthropic |
| Bedrock Nova | `core/providers/bedrock/types.go` | 1 | More flexible |
| Cohere | `core/providers/cohere/types.go` | 1 | Flexible |
| Gemini | `core/providers/gemini/types.go` | 1024 | Default minimum for conversions |

### Default Completion Tokens (for ratio calculation)

When `max_completion_tokens` is not provided, these defaults are used for ratio calculations:

| Provider | Default | File |
| - | - | - |
| OpenAI, Anthropic, Cohere, Bedrock | 4096 | `core/providers/*/types.go` |
| Gemini | 8192 | `core/providers/gemini/types.go` |

***

## Effort-to-Token Conversion Examples

### Example 1: Estimate tokens from effort (Anthropic)

<Tabs>
  <Tab title="JSON">
    **Input**:

    ```json theme={null}
    {
      "model": "anthropic/claude-3-5-sonnet",
      "max_completion_tokens": 2000,
      "reasoning": {
        "effort": "high"
      }
    }
    ```

    **Conversion Process**:

    1. `effort = "high"` → `ratio = 0.80`
    2. `minBudgetTokens = 1024` (Anthropic)
    3. `maxCompletionTokens = 2000`
    4. `budget = 1024 + (0.80 × (2000 - 1024))`
    5. `budget = 1024 + (0.80 × 976)`
    6. `budget = 1024 + 780`
    7. **Result: 1804 tokens**

    **Anthropic Request Generated**:

    ```json theme={null}
    {
      "thinking": {
        "type": "enabled",
        "budget_tokens": 1804
      }
    }
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    import (
      "github.com/maximhq/bifrost/core/providers/utils"
      "github.com/maximhq/bifrost/core/schemas"
    )

    // Using Bifrost Go SDK
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Anthropic,
      Model:    "claude-3-5-sonnet-20241022",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(2000),
        Reasoning: &schemas.ChatReasoning{
          Effort: schemas.Ptr("high"), // Effort provided, max_tokens not set
        },
      },
    }

    // Bifrost automatically converts effort to budget tokens:
    // 1. Get ratio for "high": 0.80
    // 2. Calculate: 1024 + (0.80 × (2000 - 1024)) = 1804
    // 3. Send to Anthropic with budget_tokens: 1804

    // Alternatively, manually call the estimator function:
    budgetTokens, _ := utils.GetBudgetTokensFromReasoningEffort(
      "high",     // effort
      1024,       // Anthropic minimum
      2000,       // max completion tokens
    )
    // Returns: 1804
    ```
  </Tab>
</Tabs>

### Example 2: Estimate effort from tokens (Bedrock Nova)

<Tabs>
  <Tab title="JSON">
    **Input**:

    ```json theme={null}
    {
      "model": "bedrock/us.amazon.nova-pro-v1:0",
      "max_completion_tokens": 4096,
      "reasoning": {
        "max_tokens": 2000
      }
    }
    ```

    **Conversion Process**:

    1. `budgetTokens = 2000`
    2. `minBudgetTokens = 1` (Nova)
    3. `maxCompletionTokens = 4096`
    4. `ratio = (2000 - 1) / (4096 - 1)`
    5. `ratio = 1999 / 4095`
    6. `ratio = 0.488` (48.8%)
    7. Since `0.25 < 0.488 ≤ 0.60` → **Result: "medium"**

    **Bedrock Nova Request Generated**:

    ```json theme={null}
    {
      "reasoningConfig": {
        "type": "enabled",
        "maxReasoningEffort": "medium"
      }
    }
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    import (
      "github.com/maximhq/bifrost/core/providers/utils"
      "github.com/maximhq/bifrost/core/schemas"
    )

    // Using Bifrost Go SDK with max_tokens (not effort)
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Bedrock,
      Model:    "us.amazon.nova-pro-v1:0",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          MaxTokens: schemas.Ptr(2000), // Max tokens provided, effort not set
        },
      },
    }

    // Bifrost automatically estimates effort from max_tokens:
    // 1. Calculate ratio: (2000 - 1) / (4096 - 1) = 0.488
    // 2. Since 0.25 < 0.488 ≤ 0.60 → "medium"
    // 3. Send to Bedrock Nova with effort: "medium"

    // Alternatively, manually call the estimator function:
    effort := utils.GetReasoningEffortFromBudgetTokens(
      2000,  // budget tokens
      1,     // Nova minimum
      4096,  // max completion tokens
    )
    // Returns: "medium"
    ```
  </Tab>
</Tabs>

### Example 3: Both fields provided (priority used)

<Tabs>
  <Tab title="JSON">
    **Input**:

    ```json theme={null}
    {
      "model": "anthropic/claude-3-5-sonnet",
      "max_completion_tokens": 4096,
      "reasoning": {
        "effort": "medium",
        "max_tokens": 2500
      }
    }
    ```

    **Logic for Max-Tokens-Based Provider**:

    1. Check: Is `max_tokens` provided? → **YES**
    2. Use `max_tokens` directly (ignore `effort`)
    3. Validate: `2500 >= 1024`? → **YES**

    **Anthropic Request Generated**:

    ```json theme={null}
    {
      "thinking": {
        "type": "enabled",
        "budget_tokens": 2500
      }
    }
    ```

    **Note**: The `effort: "medium"` is completely ignored because `max_tokens` takes priority.
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    import "github.com/maximhq/bifrost/core/schemas"

    // Using Bifrost Go SDK with BOTH effort and max_tokens
    chatReq := &schemas.BifrostChatRequest{
      Provider: schemas.Anthropic,
      Model:    "claude-3-5-sonnet-20241022",
      Input:    messages,
      Params: &schemas.ChatParameters{
        MaxCompletionTokens: schemas.Ptr(4096),
        Reasoning: &schemas.ChatReasoning{
          Effort:    schemas.Ptr("medium"),   // Provided but ignored
          MaxTokens: schemas.Ptr(2500),       // This takes priority
        },
      },
    }

    // Bifrost Priority Logic:
    // 1. For max-tokens-based providers (Anthropic):
    //    → Check if max_tokens is provided? YES
    //    → Use it directly: 2500
    //    → Ignore effort: "medium"
    //    → Validate: 2500 >= 1024? YES ✓
    // 2. Send to Anthropic with budget_tokens: 2500

    // Result: effort is completely ignored, max_tokens is used
    ```
  </Tab>
</Tabs>

***

## Response Format

### Bifrost Standard Response

All providers return reasoning in a normalized `reasoning_details` array:

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Final response text",
      "reasoning_details": [
        {
          "index": 0,
          "type": "text",
          "text": "Step-by-step reasoning content...",
          "signature": "optional_signature_for_verification"
        }
      ]
    }
  }]
}
```

### Reasoning Details Fields

| Field | Type | Description | Present In |
| - | - | - | - |
| `index` | `int` | Position in reasoning sequence | All |
| `type` | `string` | Content type (`text`, `encrypted`, `summary`) | All |
| `text` | `string` | Reasoning content | Chat Completions |
| `summary` | `string` | Reasoning summary | Responses API |
| `signature` | `string` | Cryptographic signature for verification | Anthropic, Bedrock |

### Type Mappings

| Reasoning Type | When Used | Source |
| - | - | - |
| `reasoning.text` | Direct thinking/reasoning content | Anthropic, Gemini, Bedrock |
| `reasoning.encrypted` | Signature-verified reasoning | Anthropic, Bedrock Nova |
| `reasoning.summary` | Summarized reasoning (Responses API) | All providers |

<Note>
  **OpenAI Implementation**: OpenAI (both Chat Completions and Responses API) is effort-based, following the standard priority logic: if `effort` is provided, it's used directly; if only `max_tokens` is provided, effort is estimated from it. The `max_tokens` field is then cleared before JSON serialization via `MarshalJSON` (`core/providers/openai/types.go:383-453`), since OpenAI's APIs don't accept it.
</Note>

***

## Streaming

### Stream Event Types

| Provider | Reasoning Event | Signature Event |
| - | - | - |
| OpenAI | `reasoning` (top-level) | N/A |
| Anthropic | `thinking_delta` | `signature_delta` |
| Bedrock | `thinking_delta` | `signature_delta` |
| Gemini | `thought` (in content) | `thought_signature` |

### Anthropic Streaming Example

```
// Stream events
event: content_block_start
data: {"type": "content_block_start", "content_block": {"type": "thinking"}}

event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "thinking_delta", "thinking": "Let me"}}

event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "thinking_delta", "thinking": " analyze..."}}

event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "signature_delta", "signature": "EqoB..."}}

event: content_block_stop
data: {"type": "content_block_stop"}
```

### Bifrost Stream Response

```json theme={null}
// Thinking delta
{
  "choices": [{
    "delta": {
      "reasoning_details": [{
        "index": 0,
        "type": "text",
        "text": "Let me analyze..."
      }]
    }
  }]
}

// Signature delta
{
  "choices": [{
    "delta": {
      "reasoning_details": [{
        "index": 0,
        "signature": "EqoB..."
      }]
    }
  }]
}
```

***

## Caveats Summary

<Accordion title="Minimum Budget (Anthropic/Bedrock)">
  **Severity**: High
  **Behavior**: `reasoning.max_tokens` must be >= 1024
  **Impact**: Requests with lower values fail with error
  **Workaround**: Always set max\_tokens >= 1024 for Anthropic/Bedrock
</Accordion>

<Accordion title="Dynamic Budget Not Supported">
  **Severity**: Medium
  **Behavior**: `reasoning.max_tokens = -1` converted to `1024`
  **Impact**: Dynamic budgeting not available on Anthropic/Bedrock
  **Workaround**: Set explicit token budget
</Accordion>

<Accordion title="Effort Level Normalization">
  **Severity**: Low
  **Behavior**: OpenAI's `minimal` converted to `low` when routing to other providers
  **Impact**: Slightly different reasoning behavior
</Accordion>

<Accordion title="Signature Field Provider-Specific">
  **Severity**: Low
  **Behavior**: `signature` field only present in Anthropic/Bedrock responses
  **Impact**: Signature-based verification only available for these providers
</Accordion>

<Accordion title="Thinking Type Always Enabled">
  **Severity**: Low
  **Behavior**: Anthropic's `thinking.type` always set to `"enabled"` regardless of effort
  **Impact**: Cannot disable thinking once reasoning param is present
</Accordion>

<Accordion title="Gemini: Only One Parameter Sent">
  **Severity**: Medium
  **Behavior**: When both `effort` and `max_tokens` are provided, only `thinkingBudget` is sent to Gemini (effort is dropped)
  **Impact**: Effort value is completely ignored when max\_tokens is present
  **Workaround**: Provide only the parameter you want to use
</Accordion>

<Accordion title="Gemini: Model Version Differences">
  **Severity**: Medium
  **Behavior**: Gemini 2.5 only supports `thinkingBudget`, while 3.0+ supports both `thinkingBudget` and `thinkingLevel`
  **Impact**: Effort-only requests on 2.5 are converted to budget; on 3.0+ they use native levels
  **Note**: Bifrost automatically detects version and uses appropriate conversion
</Accordion>

<Accordion title="Gemini Pro: Limited Level Support">
  **Severity**: Low
  **Behavior**: Pro models only support "low" and "high" thinking levels
  **Impact**: `"minimal"` → `"low"`, `"medium"` → `"high"` for Pro models
  **Note**: Non-Pro models support all four levels: minimal, low, medium, high
</Accordion>

***

## Complete Provider Comparison

### Reasoning Model

| Provider | Model Type | Budget Type | Min Budget | Signature Support |
| - | - | - | - | - |
| OpenAI | Effort-based | Effort-based | None | ❌ |
| Anthropic | Thinking blocks | Token budget | **1024** | ✅ |
| Bedrock (Anthropic) | Reasoning config | Token budget | **1024** | ✅ |
| Bedrock (Nova) | Reasoning config | Effort-based | None | ❌ |
| Gemini 2.5+ | Thinking config | Token budget | 1024 | ✅ |
| Gemini 3.0+ | Thinking config | Dual (budget + level) | 1024 | ✅ |

### Parameter Support

| Provider | `effort` | `max_tokens` | `summary` | Streaming |
| - | - | - | - | - |
| OpenAI | ✅ (4 levels) | ✅ | ❌ | ✅ |
| Anthropic | ❌ (binary) | ✅ | ✅ | ✅ |
| Bedrock (Anthropic) | ❌ (binary) | ✅ | ✅ | ✅ |
| Bedrock (Nova) | ✅ (3 levels) | ⚠️ (ignored) | ❌ | ✅ |
| Gemini 2.5+ | ⚠️ (converts to budget) | ✅ | ❌ | ✅ |
| Gemini 3.0+ | ✅ (4 levels) | ✅ | ❌ | ✅ |

***

## Troubleshooting

### Anthropic: "reasoning.max\_tokens must be >= 1024"

**Cause**: Attempting to use reasoning with `max_tokens < 1024`

**Solution**: Ensure `reasoning.max_tokens >= 1024` for Anthropic/Bedrock Anthropic models

```json theme={null}
// ❌ Invalid
{"reasoning": {"effort": "high", "max_tokens": 500}}

// ✅ Valid
{"reasoning": {"effort": "high", "max_tokens": 1024}}
```

### OpenAI: Model doesn't support reasoning

**Cause**: Using an older model that doesn't support reasoning (e.g., `gpt-4-turbo`)

**Solution**: Use models with reasoning support: `gpt-4o`, `gpt-4o-mini` (o1 series with native reasoning)

### Bedrock Nova: `max_tokens` parameter being ignored

**Expected Behavior**: Bedrock Nova uses effort-based reasoning only

**Solution**: Provide `effort` parameter instead of `max_tokens` for Nova models

```json theme={null}
// ✅ Correct for Nova
{"reasoning": {"effort": "high"}}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.