Merge branch 'main' into fix/local

Author: zhuangjie1125

components/model/claude/claude.go

@@ -434,6 +434,17 @@ func (cm *ChatModel) BindForcedTools(tools []*schema.ToolInfo) error {
 	return nil
 }
 
+// newCacheControlParam creates a CacheControlEphemeralParam from the given CacheControl.
+// If ctrl is nil or ctrl.TTL is empty, the returned param will have no TTL set,
+// which means the API will use its default TTL (5 minutes).
+func newCacheControlParam(ctrl *CacheControl) anthropic.CacheControlEphemeralParam {
+	p := anthropic.NewCacheControlEphemeralParam()
+	if ctrl != nil && ctrl.TTL != "" {
+		p.TTL = ctrl.TTL
+	}
+	return p
+}
+
 func toAnthropicToolParam(tools []*schema.ToolInfo) ([]anthropic.ToolUnionParam, error) {
 	if len(tools) == 0 {
 		return nil, nil
@@ -461,7 +472,7 @@ func toAnthropicToolParam(tools []*schema.ToolInfo) ([]anthropic.ToolUnionParam,
 		}
 
 		if isBreakpointTool(tool) {
-			toolParam.CacheControl = anthropic.NewCacheControlEphemeralParam()
+			toolParam.CacheControl = newCacheControlParam(getToolBreakpointCacheControl(tool))
 		}
 
 		result = append(result, anthropic.ToolUnionParam{OfTool: toolParam})
@@ -565,14 +576,14 @@ func (cm *ChatModel) populateInput(params *anthropic.MessageNewParams, system []
 		block := anthropic.TextBlockParam{Text: m.Content}
 		if isBreakpointMessage(m) {
 			hasSetSysBreakPoint = true
-			block.CacheControl = anthropic.NewCacheControlEphemeralParam()
+			block.CacheControl = newCacheControlParam(getMessageBreakpointCacheControl(m))
 		}
 		params.System = append(params.System, block)
 	}
 
 	// if no breakpoint has been set, a breakpoint will be set for the last system message
-	if len(params.System) > 0 && !hasSetSysBreakPoint && fromOrDefault(specOptions.EnableAutoCache, false) {
-		params.System[len(params.System)-1].CacheControl = anthropic.NewCacheControlEphemeralParam()
+	if len(params.System) > 0 && !hasSetSysBreakPoint && specOptions.AutoCacheControl != nil {
+		params.System[len(params.System)-1].CacheControl = newCacheControlParam(specOptions.AutoCacheControl)
 	}
 
 	msgParams := make([]anthropic.MessageParam, 0, len(msgs))
@@ -591,10 +602,10 @@ func (cm *ChatModel) populateInput(params *anthropic.MessageNewParams, system []
 		msgParams = append(msgParams, msgParam)
 	}
 
-	if !hasSetMsgBreakPoint && fromOrDefault(specOptions.EnableAutoCache, false) {
+	if !hasSetMsgBreakPoint && specOptions.AutoCacheControl != nil {
 		lastMsgParam := msgParams[len(msgParams)-1]
 		lastBlock := lastMsgParam.Content[len(lastMsgParam.Content)-1]
-		populateContentBlockBreakPoint(lastBlock)
+		populateContentBlockBreakPoint(lastBlock, specOptions.AutoCacheControl)
 	}
 
 	params.Messages = msgParams
@@ -612,7 +623,7 @@ func (cm *ChatModel) populateTools(params *anthropic.MessageNewParams, commonOpt
 		}
 	}
 
-	if len(tools) > 0 && fromOrDefault(specOptions.EnableAutoCache, false) {
+	if len(tools) > 0 && specOptions.AutoCacheControl != nil {
 		hasBreakpoint := false
 		for _, tool := range tools {
 			if ctrl := tool.GetCacheControl(); ctrl != nil && ctrl.Type != "" {
@@ -622,7 +633,7 @@ func (cm *ChatModel) populateTools(params *anthropic.MessageNewParams, commonOpt
 		}
 		// if no breakpoint has been set, a breakpoint will be set for the last tool
 		if !hasBreakpoint {
-			tools[len(tools)-1].OfTool.CacheControl = anthropic.NewCacheControlEphemeralParam()
+			tools[len(tools)-1].OfTool.CacheControl = newCacheControlParam(specOptions.AutoCacheControl)
 		}
 	}
 
@@ -903,7 +914,7 @@ func convSchemaMessage(message *schema.Message) (mp anthropic.MessageParam, err
 	}
 
 	if len(messageParams) > 0 && isBreakpointMessage(message) {
-		populateContentBlockBreakPoint(messageParams[len(messageParams)-1])
+		populateContentBlockBreakPoint(messageParams[len(messageParams)-1], getMessageBreakpointCacheControl(message))
 	}
 
 	switch message.Role {
@@ -974,21 +985,22 @@ func convToolMultiContent(callID string, parts []schema.MessageInputPart) (anthr
 	return result, nil
 }
 
-func populateContentBlockBreakPoint(block anthropic.ContentBlockParamUnion) {
+func populateContentBlockBreakPoint(block anthropic.ContentBlockParamUnion, cacheCtrl *CacheControl) {
+	ctrl := newCacheControlParam(cacheCtrl)
 	if block.OfText != nil {
-		block.OfText.CacheControl = anthropic.NewCacheControlEphemeralParam()
+		block.OfText.CacheControl = ctrl
 		return
 	}
 	if block.OfImage != nil {
-		block.OfImage.CacheControl = anthropic.NewCacheControlEphemeralParam()
+		block.OfImage.CacheControl = ctrl
 		return
 	}
 	if block.OfToolResult != nil {
-		block.OfToolResult.CacheControl = anthropic.NewCacheControlEphemeralParam()
+		block.OfToolResult.CacheControl = ctrl
 		return
 	}
 	if block.OfToolUse != nil {
-		block.OfToolUse.CacheControl = anthropic.NewCacheControlEphemeralParam()
+		block.OfToolUse.CacheControl = ctrl
 		return
 	}
 }

components/model/claude/claude_test.go

@@ -345,19 +345,19 @@ func TestWithTools(t *testing.T) {
 
 func TestPopulateContentBlockBreakPoint(t *testing.T) {
 	block := anthropic.NewTextBlock("input")
-	populateContentBlockBreakPoint(block)
+	populateContentBlockBreakPoint(block, nil)
 	assert.NotEmpty(t, block.OfText.CacheControl.Type)
 
 	block = anthropic.NewImageBlock[anthropic.URLImageSourceParam](anthropic.URLImageSourceParam{})
-	populateContentBlockBreakPoint(block)
+	populateContentBlockBreakPoint(block, nil)
 	assert.NotEmpty(t, block.OfImage.CacheControl.Type)
 
 	block = anthropic.NewToolResultBlock("userID", "input", false)
-	populateContentBlockBreakPoint(block)
+	populateContentBlockBreakPoint(block, nil)
 	assert.NotEmpty(t, block.OfToolResult.CacheControl.Type)
 
 	block = anthropic.NewToolUseBlock("123", "input", "test_tool")
-	populateContentBlockBreakPoint(block)
+	populateContentBlockBreakPoint(block, nil)
 	assert.NotEmpty(t, block.OfToolUse.CacheControl.Type)
 }
 
@@ -762,3 +762,87 @@ func TestPopulateToolChoice(t *testing.T) {
 		assert.Equal(t, "tool choice=unsupported not support", err.Error())
 	})
 }
+
+func TestCacheTTL(t *testing.T) {
+	t.Run("SetMessageBreakpoint without TTL", func(t *testing.T) {
+		msg := schema.UserMessage("hello")
+		bp := SetMessageBreakpoint(msg)
+		assert.True(t, isBreakpointMessage(bp))
+		ctrl := getMessageBreakpointCacheControl(bp)
+		assert.Nil(t, ctrl)
+	})
+
+	t.Run("SetMessageCacheControl with TTL", func(t *testing.T) {
+		msg := schema.UserMessage("hello")
+		bp := SetMessageCacheControl(msg, &CacheControl{TTL: CacheTTL1h})
+		assert.True(t, isBreakpointMessage(bp))
+		ctrl := getMessageBreakpointCacheControl(bp)
+		assert.Equal(t, CacheTTL1h, ctrl.TTL)
+	})
+
+	t.Run("SetToolInfoBreakpoint without TTL", func(t *testing.T) {
+		tool := &schema.ToolInfo{Name: "test"}
+		bp := SetToolInfoBreakpoint(tool)
+		assert.True(t, isBreakpointTool(bp))
+		ctrl := getToolBreakpointCacheControl(bp)
+		assert.Nil(t, ctrl)
+	})
+
+	t.Run("SetToolInfoCacheControl with TTL", func(t *testing.T) {
+		tool := &schema.ToolInfo{Name: "test"}
+		bp := SetToolInfoCacheControl(tool, &CacheControl{TTL: CacheTTL5m})
+		assert.True(t, isBreakpointTool(bp))
+		ctrl := getToolBreakpointCacheControl(bp)
+		assert.Equal(t, CacheTTL5m, ctrl.TTL)
+	})
+
+	t.Run("newCacheControlParam without TTL", func(t *testing.T) {
+		p := newCacheControlParam(nil)
+		assert.Equal(t, CacheTTL(""), p.TTL)
+		assert.NotEmpty(t, p.Type)
+	})
+
+	t.Run("newCacheControlParam with TTL", func(t *testing.T) {
+		p := newCacheControlParam(&CacheControl{TTL: CacheTTL1h})
+		assert.Equal(t, CacheTTL1h, p.TTL)
+		assert.NotEmpty(t, p.Type)
+	})
+
+	t.Run("newCacheControlParam with invalid TTL passthrough", func(t *testing.T) {
+		p := newCacheControlParam(&CacheControl{TTL: "invalid_ttl"})
+		assert.Equal(t, CacheTTL("invalid_ttl"), p.TTL)
+		assert.NotEmpty(t, p.Type)
+	})
+
+	t.Run("populateContentBlockBreakPoint with TTL", func(t *testing.T) {
+		block := anthropic.NewTextBlock("input")
+		populateContentBlockBreakPoint(block, &CacheControl{TTL: CacheTTL1h})
+		assert.NotEmpty(t, block.OfText.CacheControl.Type)
+		assert.Equal(t, CacheTTL1h, block.OfText.CacheControl.TTL)
+	})
+
+	t.Run("manual breakpoint TTL flows to params", func(t *testing.T) {
+		cm := &ChatModel{model: "test", maxTokens: 100}
+		msg := schema.UserMessage("hello")
+		sysMsg := schema.SystemMessage("system")
+		bpSys := SetMessageCacheControl(sysMsg, &CacheControl{TTL: CacheTTL1h})
+
+		params, err := cm.genMessageNewParams([]*schema.Message{bpSys, msg})
+		assert.NoError(t, err)
+		assert.Equal(t, CacheTTL1h, params.System[0].CacheControl.TTL)
+	})
+
+	t.Run("WithAutoCacheControl with TTL", func(t *testing.T) {
+		cm := &ChatModel{model: "test", maxTokens: 100}
+		msg := schema.UserMessage("hello")
+		sysMsg := schema.SystemMessage("system")
+
+		params, err := cm.genMessageNewParams(
+			[]*schema.Message{sysMsg, msg},
+			WithAutoCacheControl(&CacheControl{TTL: CacheTTL1h}),
+		)
+		assert.NoError(t, err)
+		// auto cache should set TTL on last system message
+		assert.Equal(t, CacheTTL1h, params.System[0].CacheControl.TTL)
+	})
+}

components/model/claude/examples/claude_prompt_cache/claude_prompt_cache.go

@@ -22,9 +22,10 @@ import (
 	"os"
 	"time"
 
-	"github.com/cloudwego/eino-ext/components/model/claude"
 	"github.com/cloudwego/eino/components/model"
 	"github.com/cloudwego/eino/schema"
+
+	"github.com/cloudwego/eino-ext/components/model/claude"
 )
 
 func main() {
@@ -56,10 +57,11 @@ func systemCache() {
 		log.Fatalf("NewChatModel of claude failed, err=%v", err)
 	}
 
-	breakpoint := claude.SetMessageBreakpoint(&schema.Message{
+	// SetMessageCacheControl sets a manual cache breakpoint with a 1-hour TTL.
+	breakpoint := claude.SetMessageCacheControl(&schema.Message{
 		Role:    schema.System,
 		Content: "The film Dongji Rescue, based on a true historical event, tells the story of Chinese fishermen braving turbulent seas to save strangers — a testament to the nation's capacity to create miracles in the face of adversity.\n\nEighty-three years ago, in 1942, the Japanese military seized the Lisbon Maru ship to transport 1,816 British prisoners of war from Hong Kong to Japan. Passing through the waters near Zhoushan, Zhejiang province, it was torpedoed by a US submarine. Fishermen from Zhoushan rescued 384 prisoners of war and hid them from Japanese search parties.\n\nActor Zhu Yilong, in an exclusive interview with China Daily, said he was deeply moved by the humanity shown in such extreme conditions when he accepted his role. \"This historical event proves that in dire circumstances, Chinese people can extend their goodness to protect both themselves and others,\" he said.\n\nLast Friday, a themed event for Dongji Rescue was held in Zhoushan, a city close to where the Lisbon Maru sank. Descendants of the British POWs and the rescuing fishermen gathered to watch the film and share their reflections.\n\nIn the film, the British POWs are aided by a group of fishermen from Dongji Island, whose courage and compassion cut a path through treacherous waves. After the screening, many descendants were visibly moved.\n\n\"I want to express my deepest gratitude to the Chinese people and the descendants of Chinese fishermen. When the film is released in the UK, I will bring my family and friends to watch it. Heroic acts like this deserve to be known worldwide,\" said Denise Wynne, a descendant of a British POW.\n\n\"I felt the profound friendship between the Chinese and British people through the film,\" said Li Hui, a descendant of a rescuer. Many audience members were brought to tears — some by the fishermen's bravery, others by the enduring spirit of \"never abandoning those in peril\".\n\n\"In times of sea peril, rescue is a must,\" said Wu Buwei, another rescuer's descendant, noting that this value has long been a part of Dongji fishermen's traditions.\n\nCoincidentally, on the morning of Aug 5, a real-life rescue unfolded on the shores of Dongfushan in Dongji town. Two tourists from Shanghai fell into the sea and were swept away by powerful waves. Without hesitation, two descendants of Dongji fishermen — Wang Yubin and Yang Xiaoping — leaped in to save them, braving a wind force of 9 to 10 before pulling them to safety.\n\n\"Our forebearers once rescued many British POWs here. As their descendants, we should carry forward their bravery,\" Wang said. Both rescuers later joined the film's cast and crew at the Zhoushan event, sharing the stage with actors who portrayed the fishermen in a symbolic \"reunion across 83 years\".\n\nChinese actor Wu Lei, who plays A Dang in the film, expressed his respect for the two rescuing fishermen on-site. In the film, A Dang saves a British POW named Thomas Newman. Though they share no common language, they manage to connect. In an interview with China Daily, Wu said, \"They connected through a small globe. A Dang understood when Newman pointed out his home, the UK, on the globe.\"\n\nThe film's director Fei Zhenxiang noted that the Eastern Front in World War II is often overlooked internationally, despite China's 14 years of resistance tying down large numbers of Japanese troops. \"Every Chinese person is a hero, and their righteousness should not be forgotten,\" he said.\n\nGuan Hu, codirector, said, \"We hope that through this film, silent kindness can be seen by the world\", marking the 80th anniversary of victory in the Chinese People's War of Resistance Against Japanese Aggression (1931-45) and the World Anti-Fascist War.",
-	})
+	}, &claude.CacheControl{TTL: claude.CacheTTL1h})
 
 	for i := 0; i < 2; i++ {
 		now := time.Now()
@@ -107,7 +109,8 @@ func toolInfoCache() {
 		log.Fatalf("NewChatModel of claude failed, err=%v", err)
 	}
 
-	breakpoint := claude.SetToolInfoBreakpoint(&schema.ToolInfo{
+	// SetToolInfoCacheControl sets a manual cache breakpoint on the tool with a 5-minute TTL.
+	breakpoint := claude.SetToolInfoCacheControl(&schema.ToolInfo{
 		Name: "get_time",
 		Desc: "Get the current time in a given time zone",
 		ParamsOneOf: schema.NewParamsOneOfByParams(
@@ -119,7 +122,7 @@ func toolInfoCache() {
 				},
 			},
 		)},
-	)
+		&claude.CacheControl{TTL: claude.CacheTTL5m})
 
 	mockTools := []*schema.ToolInfo{
 		{
@@ -230,8 +233,9 @@ func sessionCache() {
 		log.Fatalf("NewChatModel of claude failed, err=%v", err)
 	}
 
+	// WithAutoCacheControl enables automatic caching with a 1-hour TTL.
 	opts := []model.Option{
-		claude.WithEnableAutoCache(true),
+		claude.WithAutoCacheControl(&claude.CacheControl{TTL: claude.CacheTTL1h}),
 	}
 
 	mockTools := []*schema.ToolInfo{

components/model/claude/go.mod

@@ -3,7 +3,7 @@ module github.com/cloudwego/eino-ext/components/model/claude
 go 1.23.0
 
 require (
-	github.com/anthropics/anthropic-sdk-go v1.4.0
+	github.com/anthropics/anthropic-sdk-go v1.26.0
 	github.com/aws/aws-sdk-go-v2/config v1.29.1
 	github.com/aws/aws-sdk-go-v2/credentials v1.17.54
 	github.com/bytedance/mockey v1.2.13
@@ -73,13 +73,13 @@ require (
 	go.opentelemetry.io/otel/metric v1.24.0 // indirect
 	go.opentelemetry.io/otel/trace v1.24.0 // indirect
 	golang.org/x/arch v0.11.0 // indirect
-	golang.org/x/crypto v0.39.0 // indirect
+	golang.org/x/crypto v0.40.0 // indirect
 	golang.org/x/exp v0.0.0-20230713183714-613f0c0eb8a1 // indirect
-	golang.org/x/net v0.27.0 // indirect
-	golang.org/x/oauth2 v0.21.0 // indirect
-	golang.org/x/sync v0.15.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/text v0.26.0 // indirect
+	golang.org/x/net v0.41.0 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sync v0.16.0 // indirect
+	golang.org/x/sys v0.34.0 // indirect
+	golang.org/x/text v0.27.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
 	google.golang.org/api v0.189.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240722135656-d784300faade // indirect