feat(agentic): define AgenticModel component

components/agentic/callback_extra.go

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package agentic
+
+import (
+	"github.com/cloudwego/eino/callbacks"
+	"github.com/cloudwego/eino/schema"
+)
+
+// Config is the config for the model.
+type Config struct {
+	// Model is the model name.
+	Model string
+	// Temperature is the temperature, which controls the randomness of the model.
+	Temperature float32
+	// TopP is the top p, which controls the diversity of the model.
+	TopP float32
+}
+
+// CallbackInput is the input for the model callback.
+type CallbackInput struct {
+	// Messages is the messages to be sent to the model.
+	Messages []*schema.AgenticMessage
+	// Tools is the tools to be used in the model.
+	Tools []*schema.ToolInfo
+	// ToolChoice controls which tool is called by the model.
+	ToolChoice *schema.ToolChoice
+	// Config is the config for the model.
+	Config *Config
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// CallbackOutput is the output for the model callback.
+type CallbackOutput struct {
+	// Message is the message generated by the model.
+	Message *schema.AgenticMessage
+	// Config is the config for the model.
+	Config *Config
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// ConvCallbackInput converts the callback input to the model callback input.
+func ConvCallbackInput(src callbacks.CallbackInput) *CallbackInput {
+	switch t := src.(type) {
+	case *CallbackInput: // when callback is triggered within component implementation, the input is usually already a typed *model.CallbackInput
+		return t
+	case []*schema.AgenticMessage: // when callback is injected by graph node, not the component implementation itself, the input is the input of Chat Model interface, which is []*schema.AgenticMessage
+		return &CallbackInput{
+			Messages: t,
+		}
+	default:
+		return nil
+	}
+}
+
+// ConvCallbackOutput converts the callback output to the model callback output.
+func ConvCallbackOutput(src callbacks.CallbackOutput) *CallbackOutput {
+	switch t := src.(type) {
+	case *CallbackOutput: // when callback is triggered within component implementation, the output is usually already a typed *model.CallbackOutput
+		return t
+	case *schema.AgenticMessage: // when callback is injected by graph node, not the component implementation itself, the output is the output of Chat Model interface, which is *schema.AgenticMessage
+		return &CallbackOutput{
+			Message: t,
+		}
+	default:
+		return nil
+	}
+}

components/agentic/interface.go

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package agentic
+
+import (
+	"context"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+type Model interface {
+	Generate(ctx context.Context, input []*schema.AgenticMessage, opts ...Option) (*schema.AgenticMessage, error)
+	Stream(ctx context.Context, input []*schema.AgenticMessage, opts ...Option) (*schema.StreamReader[*schema.AgenticMessage], error)
+	WithTools(tools []*schema.ToolInfo) (Model, error)
+}

components/agentic/option.go

@@ -0,0 +1,139 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package agentic
+
+import (
+	"github.com/cloudwego/eino/schema"
+)
+
+// Options is the common options for the model.
+type Options struct {
+	// Temperature is the temperature for the model, which controls the randomness of the model.
+	Temperature *float64
+	// Model is the model name.
+	Model *string
+	// TopP is the top p for the model, which controls the diversity of the model.
+	TopP *float64
+	// Tools is a list of tools the model may call.
+	Tools []*schema.ToolInfo
+	// ToolChoice controls which tool is called by the model.
+	ToolChoice *schema.ToolChoice
+}
+
+// Option is the call option for ChatModel component.
+type Option struct {
+	apply func(opts *Options)
+
+	implSpecificOptFn any
+}
+
+// WithTemperature is the option to set the temperature for the model.
+func WithTemperature(temperature float64) Option {
+	return Option{
+		apply: func(opts *Options) {
+			opts.Temperature = &temperature
+		},
+	}
+}
+
+// WithModel is the option to set the model name.
+func WithModel(name string) Option {
+	return Option{
+		apply: func(opts *Options) {
+			opts.Model = &name
+		},
+	}
+}
+
+// WithTopP is the option to set the top p for the model.
+func WithTopP(topP float64) Option {
+	return Option{
+		apply: func(opts *Options) {
+			opts.TopP = &topP
+		},
+	}
+}
+
+// WithTools is the option to set tools for the model.
+func WithTools(tools []*schema.ToolInfo) Option {
+	if tools == nil {
+		tools = []*schema.ToolInfo{}
+	}
+	return Option{
+		apply: func(opts *Options) {
+			opts.Tools = tools
+		},
+	}
+}
+
+// WithToolChoice is the option to set tool choice for the model.
+func WithToolChoice(toolChoice schema.ToolChoice) Option {
+	return Option{
+		apply: func(opts *Options) {
+			opts.ToolChoice = &toolChoice
+		},
+	}
+}
+
+// WrapImplSpecificOptFn is the option to wrap the implementation specific option function.
+func WrapImplSpecificOptFn[T any](optFn func(*T)) Option {
+	return Option{
+		implSpecificOptFn: optFn,
+	}
+}
+
+// GetCommonOptions extract model Options from Option list, optionally providing a base Options with default values.
+func GetCommonOptions(base *Options, opts ...Option) *Options {
+	if base == nil {
+		base = &Options{}
+	}
+
+	for i := range opts {
+		opt := opts[i]
+		if opt.apply != nil {
+			opt.apply(base)
+		}
+	}
+
+	return base
+}
+
+// GetImplSpecificOptions extract the implementation specific options from Option list, optionally providing a base options with default values.
+// e.g.
+//
+//	myOption := &MyOption{
+//		Field1: "default_value",
+//	}
+//
+//	myOption := model.GetImplSpecificOptions(myOption, opts...)
+func GetImplSpecificOptions[T any](base *T, opts ...Option) *T {
+	if base == nil {
+		base = new(T)
+	}
+
+	for i := range opts {
+		opt := opts[i]
+		if opt.implSpecificOptFn != nil {
+			optFn, ok := opt.implSpecificOptFn.(func(*T))
+			if ok {
+				optFn(base)
+			}
+		}
+	}
+
+	return base
+}

components/types.go

@@ -51,12 +51,13 @@ func IsCallbacksEnabled(i any) bool {
 type Component string
 
 const (
-	ComponentOfPrompt      Component = "ChatTemplate"
-	ComponentOfChatModel   Component = "ChatModel"
-	ComponentOfEmbedding   Component = "Embedding"
-	ComponentOfIndexer     Component = "Indexer"
-	ComponentOfRetriever   Component = "Retriever"
-	ComponentOfLoader      Component = "Loader"
-	ComponentOfTransformer Component = "DocumentTransformer"
-	ComponentOfTool        Component = "Tool"
+	ComponentOfPrompt       Component = "ChatTemplate"
+	ComponentOfChatModel    Component = "ChatModel"
+	ComponentOfAgenticModel Component = "AgenticModel"
+	ComponentOfEmbedding    Component = "Embedding"
+	ComponentOfIndexer      Component = "Indexer"
+	ComponentOfRetriever    Component = "Retriever"
+	ComponentOfLoader       Component = "Loader"
+	ComponentOfTransformer  Component = "DocumentTransformer"
+	ComponentOfTool         Component = "Tool"
 )

go.mod

@@ -39,7 +39,8 @@ require (
 	github.com/yargevad/filepathx v1.0.0 // indirect
 	golang.org/x/arch v0.11.0 // indirect
 	golang.org/x/exp v0.0.0-20230713183714-613f0c0eb8a1 // indirect
-	golang.org/x/sys v0.26.0 // indirect
+	golang.org/x/sys v0.29.0 // indirect
+	golang.org/x/term v0.28.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -115,9 +115,10 @@ golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.26.0 h1:KHjCJyddX0LoSTb3J+vWpupP9p0oznkqVk/IfjymZbo=
-golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/term v0.10.0 h1:3R7pNqamzBraeqj/Tj8qt1aQ2HpmlC+Cx/qL/7hn4/c=
+golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
+golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.28.0 h1:/Ts8HFuMR2E6IP/jlo7QVLZHggjKQbhu/7H0LJFr3Gg=
+golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=