feat: interleaved thinking with tool calls (reasoning_content alias + Anthropic thinking blocks) (#10744)

* feat(schema): accept reasoning_content as inbound alias for reasoning

Interleaved-thinking clients (cogito, vLLM/DeepSeek-style) emit reasoning_content
on assistant turns. Accept it as an inbound alias so reasoning survives the
tool-result loop; canonical reasoning wins when both are present. Emission is
unchanged (still reasoning).

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(schema): pin interleaved reasoning+tool_calls round-trip

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* test(openai): pin reachedTokenBudget truncation detection

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(anthropic): add thinking and signature fields to content blocks

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(anthropic): parse inbound thinking blocks into reasoning

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(anthropic): emit thinking blocks with synthetic signature on tool turns

Extract buildAnthropicContentBlocks so non-streaming content assembly is
unit-testable, and prepend a thinking block (with an opaque synthetic
signature) before text/tool_use blocks when the request opts into thinking.

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* feat(anthropic): stream thinking_delta and signature_delta before tool_use

Extract anthropicStreamSequence so the streaming block order is unit-testable,
and emit content_block_start(thinking) -> thinking_delta -> signature_delta ->
content_block_stop before the tool_use block sequence when thinking is enabled.

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

* docs: add interleaved thinking with tool calls guide

Add a features guide describing interleaved thinking: an assistant turn
carrying reasoning and tool_calls together, the reasoning-round-trip
contract (including the reasoning_content inbound alias and Anthropic
thinking blocks with a synthetic signature), per-backend enablement
(reasoning_format for llama.cpp, reasoning_parser/tool_call_parser for
vLLM/SGLang plus the vLLM auto-config hook), a worked request/response
example, and known limitations. Cross-link from model-configuration,
text-generation, and openai-functions.

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>

---------

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
Co-authored-by: Ettore Di Giacinto <mudler@localai.io>

Author: localai-bot

core/http/endpoints/anthropic/messages.go

@@ -3,6 +3,7 @@ package anthropic
 import (
 	"encoding/json"
 	"fmt"
+	"strings"
 	"sync"
 	"time"
 
@@ -244,63 +245,59 @@ func handleAnthropicNonStream(c echo.Context, id string, input *schema.Anthropic
 			}
 		}
 
-		// No MCP tools to execute, build and return response
+		// No MCP tools to execute, build and return response.
+		// Reasoning surfaces as a thinking block only when the client opted in,
+		// matching Anthropic's extended-thinking gating.
+		reasoning := functions.ReasoningFromChatDeltas(chatDeltas)
+		thinkingEnabled := input.Thinking != nil && input.Thinking.Type == "enabled"
+
 		var contentBlocks []schema.AnthropicContentBlock
 		var stopReason string
 
 		if shouldUseFn && len(toolCalls) > 0 {
 			stopReason = "tool_use"
-			for _, tc := range toolCalls {
-				var inputArgs map[string]any
-				if err := json.Unmarshal([]byte(tc.Arguments), &inputArgs); err != nil {
-					xlog.Warn("Failed to parse tool call arguments as JSON", "error", err, "args", tc.Arguments)
-					inputArgs = map[string]any{"raw": tc.Arguments}
-				}
-				contentBlocks = append(contentBlocks, schema.AnthropicContentBlock{
-					Type:  "tool_use",
-					ID:    fmt.Sprintf("toolu_%s_%d", id, len(contentBlocks)),
-					Name:  tc.Name,
-					Input: inputArgs,
-				})
-			}
-			textContent := functions.ParseTextContent(result, cfg.FunctionsConfig)
-			if textContent != "" {
-				contentBlocks = append([]schema.AnthropicContentBlock{{Type: "text", Text: textContent}}, contentBlocks...)
-			}
+			contentBlocks = buildAnthropicContentBlocks(buildParams{
+				reasoning:       reasoning,
+				thinkingEnabled: thinkingEnabled,
+				text:            functions.ParseTextContent(result, cfg.FunctionsConfig),
+				toolCalls:       funcResultsToToolCalls(toolCalls),
+				id:              id,
+			})
 		} else if !shouldUseFn && cfg.FunctionsConfig.AutomaticToolParsingFallback && result != "" {
 			// Automatic tool parsing fallback: no tools in request but model emitted tool call markup
 			parsed := functions.ParseFunctionCall(result, cfg.FunctionsConfig)
 			if len(parsed) > 0 {
 				stopReason = "tool_use"
-				stripped := functions.StripToolCallMarkup(result)
-				if stripped != "" {
-					contentBlocks = append(contentBlocks, schema.AnthropicContentBlock{Type: "text", Text: stripped})
-				}
-				for i, fc := range parsed {
-					var inputArgs map[string]any
-					if err := json.Unmarshal([]byte(fc.Arguments), &inputArgs); err != nil {
-						inputArgs = map[string]any{"raw": fc.Arguments}
-					}
-					toolCallID := fc.ID
-					if toolCallID == "" {
-						toolCallID = fmt.Sprintf("toolu_%s_%d", id, i)
-					}
-					contentBlocks = append(contentBlocks, schema.AnthropicContentBlock{
-						Type:  "tool_use",
-						ID:    toolCallID,
-						Name:  fc.Name,
-						Input: inputArgs,
-					})
-				}
+				contentBlocks = buildAnthropicContentBlocks(buildParams{
+					reasoning:       reasoning,
+					thinkingEnabled: thinkingEnabled,
+					text:            functions.StripToolCallMarkup(result),
+					toolCalls:       funcResultsToToolCalls(parsed),
+					id:              id,
+				})
 			} else {
 				stopReason = "end_turn"
-				contentBlocks = []schema.AnthropicContentBlock{{Type: "text", Text: result}}
+				contentBlocks = buildAnthropicContentBlocks(buildParams{
+					reasoning:       reasoning,
+					thinkingEnabled: thinkingEnabled,
+					text:            result,
+					id:              id,
+				})
 			}
 		} else {
 			stopReason = "end_turn"
-			contentBlocks = []schema.AnthropicContentBlock{
-				{Type: "text", Text: result},
-			}
+			contentBlocks = buildAnthropicContentBlocks(buildParams{
+				reasoning:       reasoning,
+				thinkingEnabled: thinkingEnabled,
+				text:            result,
+				id:              id,
+			})
+		}
+
+		// Anthropic responses must carry at least one content block; keep the
+		// empty-text fallback the pre-refactor assembly guaranteed.
+		if len(contentBlocks) == 0 {
+			contentBlocks = []schema.AnthropicContentBlock{{Type: "text", Text: result}}
 		}
 
 		resp := &schema.AnthropicResponse{
@@ -356,6 +353,9 @@ func handleAnthropicStream(c echo.Context, id string, input *schema.AnthropicReq
 	}
 	hasMCPTools := mcpExecutor != nil && mcpExecutor.HasTools()
 
+	// Reasoning streams as a thinking block only when the client opted in.
+	thinkingEnabled := input.Thinking != nil && input.Thinking.Type == "enabled"
+
 	for mcpIteration := 0; mcpIteration <= mcpMaxIterations; mcpIteration++ {
 		// Re-template on MCP iterations
 		if mcpIteration > 0 {
@@ -510,7 +510,9 @@ func handleAnthropicStream(c echo.Context, id string, input *schema.AnthropicReq
 				})
 			}
 
-			// Emit tool_use blocks from ChatDeltas
+			// Emit tool_use blocks from ChatDeltas, preceded by a fully-closed
+			// thinking block when reasoning is present (Anthropic ordering:
+			// thinking is streamed and closed before any tool_use starts).
 			if len(deltaToolCalls) > 0 && len(collectedToolCalls) == 0 {
 				collectedToolCalls = deltaToolCalls
 
@@ -522,35 +524,23 @@ func handleAnthropicStream(c echo.Context, id string, input *schema.AnthropicReq
 					currentBlockIndex++
 					inToolCall = true
 				}
-				for i, tc := range deltaToolCalls {
-					toolCallID := tc.ID
-					if toolCallID == "" {
-						toolCallID = fmt.Sprintf("toolu_%s_%d", id, i)
+
+				seq := anthropicStreamSequence(streamInput{
+					reasoningDeltas: []string{functions.ReasoningFromChatDeltas(chatDeltas)},
+					thinkingEnabled: thinkingEnabled,
+					toolCalls:       funcResultsToToolCalls(deltaToolCalls),
+					startIndex:      currentBlockIndex,
+					id:              id,
+				})
+				for _, ev := range seq {
+					sendAnthropicSSE(c, ev)
+					// Each content block ends with exactly one content_block_stop,
+					// so advance the running index in lockstep with the sequencer.
+					if ev.Type == "content_block_stop" {
+						currentBlockIndex++
 					}
-					sendAnthropicSSE(c, schema.AnthropicStreamEvent{
-						Type:  "content_block_start",
-						Index: intPtr(currentBlockIndex),
-						ContentBlock: &schema.AnthropicContentBlock{
-							Type: "tool_use",
-							ID:   toolCallID,
-							Name: tc.Name,
-						},
-					})
-					sendAnthropicSSE(c, schema.AnthropicStreamEvent{
-						Type:  "content_block_delta",
-						Index: intPtr(currentBlockIndex),
-						Delta: &schema.AnthropicStreamDelta{
-							Type:        "input_json_delta",
-							PartialJSON: tc.Arguments,
-						},
-					})
-					sendAnthropicSSE(c, schema.AnthropicStreamEvent{
-						Type:  "content_block_stop",
-						Index: intPtr(currentBlockIndex),
-					})
-					currentBlockIndex++
-					toolCallsEmitted++
 				}
+				toolCallsEmitted += len(deltaToolCalls)
 			}
 		}
 
@@ -697,6 +687,139 @@ func handleAnthropicStream(c echo.Context, id string, input *schema.AnthropicReq
 	return nil
 }
 
+// buildParams carries the pieces of an assistant turn that become Anthropic
+// content blocks. It exists so the block-assembly logic is unit-testable in
+// isolation from the HTTP handler.
+type buildParams struct {
+	reasoning       string
+	thinkingEnabled bool
+	text            string
+	toolCalls       []schema.ToolCall
+	id              string
+}
+
+// syntheticThinkingSignature returns an opaque, non-cryptographic signature so
+// Anthropic SDK clients round-trip the thinking block. Local models have no
+// real signature; this marker is accepted-but-ignored on the way back in.
+func syntheticThinkingSignature() string { return "localai" }
+
+// buildAnthropicContentBlocks assembles the content blocks for a non-streaming
+// assistant turn. When thinking is enabled and reasoning is present, a thinking
+// block is prepended before text and tool_use blocks (Anthropic ordering).
+func buildAnthropicContentBlocks(p buildParams) []schema.AnthropicContentBlock {
+	var blocks []schema.AnthropicContentBlock
+	if p.thinkingEnabled && p.reasoning != "" {
+		blocks = append(blocks, schema.AnthropicContentBlock{
+			Type:      "thinking",
+			Thinking:  p.reasoning,
+			Signature: syntheticThinkingSignature(),
+		})
+	}
+	if p.text != "" {
+		blocks = append(blocks, schema.AnthropicContentBlock{Type: "text", Text: p.text})
+	}
+	for i, tc := range p.toolCalls {
+		var inputArgs map[string]any
+		if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &inputArgs); err != nil {
+			inputArgs = map[string]any{"raw": tc.FunctionCall.Arguments}
+		}
+		id := tc.ID
+		if id == "" {
+			id = fmt.Sprintf("toolu_%s_%d", p.id, i)
+		}
+		blocks = append(blocks, schema.AnthropicContentBlock{
+			Type: "tool_use", ID: id, Name: tc.FunctionCall.Name, Input: inputArgs,
+		})
+	}
+	return blocks
+}
+
+// funcResultsToToolCalls adapts the parser's FuncCallResults into schema
+// ToolCalls so the pure block builders operate on one tool-call shape.
+func funcResultsToToolCalls(results []functions.FuncCallResults) []schema.ToolCall {
+	out := make([]schema.ToolCall, len(results))
+	for i, r := range results {
+		out[i] = schema.ToolCall{
+			ID:           r.ID,
+			Type:         "function",
+			FunctionCall: schema.FunctionCall{Name: r.Name, Arguments: r.Arguments},
+		}
+	}
+	return out
+}
+
+// streamInput carries the reasoning deltas and tool calls for one streaming
+// assistant turn. startIndex and id let the pure sequencer be wired into the
+// live loop, which already owns a running block index.
+type streamInput struct {
+	reasoningDeltas []string
+	thinkingEnabled bool
+	toolCalls       []schema.ToolCall
+	startIndex      int
+	id              string
+}
+
+// anthropicStreamSequence produces the ordered stream events for a thinking
+// block followed by tool_use blocks. Per the Anthropic spec the thinking block
+// is fully streamed and closed (content_block_stop) before any tool_use block
+// starts. Kept pure so ordering is unit-testable without an HTTP stream.
+func anthropicStreamSequence(in streamInput) []schema.AnthropicStreamEvent {
+	var events []schema.AnthropicStreamEvent
+	idx := in.startIndex
+
+	if in.thinkingEnabled && strings.Join(in.reasoningDeltas, "") != "" {
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:         "content_block_start",
+			Index:        intPtr(idx),
+			ContentBlock: &schema.AnthropicContentBlock{Type: "thinking"},
+		})
+		for _, d := range in.reasoningDeltas {
+			if d == "" {
+				continue
+			}
+			events = append(events, schema.AnthropicStreamEvent{
+				Type:  "content_block_delta",
+				Index: intPtr(idx),
+				Delta: &schema.AnthropicStreamDelta{Type: "thinking_delta", Thinking: d},
+			})
+		}
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:  "content_block_delta",
+			Index: intPtr(idx),
+			Delta: &schema.AnthropicStreamDelta{Type: "signature_delta", Signature: syntheticThinkingSignature()},
+		})
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:  "content_block_stop",
+			Index: intPtr(idx),
+		})
+		idx++
+	}
+
+	for i, tc := range in.toolCalls {
+		toolID := tc.ID
+		if toolID == "" {
+			toolID = fmt.Sprintf("toolu_%s_%d", in.id, i)
+		}
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:         "content_block_start",
+			Index:        intPtr(idx),
+			ContentBlock: &schema.AnthropicContentBlock{Type: "tool_use", ID: toolID, Name: tc.FunctionCall.Name},
+		})
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:  "content_block_delta",
+			Index: intPtr(idx),
+			Delta: &schema.AnthropicStreamDelta{Type: "input_json_delta", PartialJSON: tc.FunctionCall.Arguments},
+		})
+		events = append(events, schema.AnthropicStreamEvent{
+			Type:  "content_block_stop",
+			Index: intPtr(idx),
+		})
+		idx++
+	}
+
+	return events
+}
+
 func convertFuncsToOpenAITools(funcs functions.Functions) []functions.Tool {
 	tools := make([]functions.Tool, len(funcs))
 	for i, f := range funcs {
@@ -767,6 +890,17 @@ func convertAnthropicToOpenAIMessages(input *schema.AnthropicRequest) []schema.M
 						if text, ok := blockMap["text"].(string); ok {
 							textContent += text
 						}
+					case "thinking":
+						// Anthropic interleaved thinking: preserve the model's reasoning so it
+						// survives the tool-result loop. Signature is Anthropic-cloud specific;
+						// for local models we read but do not validate it.
+						if thinking, ok := blockMap["thinking"].(string); ok && thinking != "" {
+							combined := thinking
+							if openAIMsg.Reasoning != nil {
+								combined = *openAIMsg.Reasoning + thinking
+							}
+							openAIMsg.Reasoning = &combined
+						}
 					case "image":
 						// Handle image content
 						if source, ok := blockMap["source"].(map[string]any); ok {