chore: import upstream snapshot with attribution

components/model/interface.go

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2024 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 model
+
+import (
+	"context"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+// messageType is the sealed type constraint for message types used in BaseModel.
+// Only *schema.Message and *schema.AgenticMessage satisfy this constraint.
+type messageType interface {
+	*schema.Message | *schema.AgenticMessage
+}
+
+// BaseModel is the generic base model interface parameterized by message type M.
+// It exposes two modes of interaction:
+//   - [BaseModel.Generate]: blocks until the model returns a complete response.
+//   - [BaseModel.Stream]: returns a [schema.StreamReader] that yields message
+//     chunks incrementally as the model generates them.
+type BaseModel[M messageType] interface {
+	Generate(ctx context.Context, input []M, opts ...Option) (M, error)
+	Stream(ctx context.Context, input []M, opts ...Option) (*schema.StreamReader[M], error)
+}
+
+// BaseChatModel is a backward-compatible type alias for BaseModel specialized
+// with *schema.Message. All existing code using model.BaseChatModel continues
+// to work without modification.
+//
+// It exposes two modes of interaction:
+//   - [BaseChatModel.Generate]: blocks until the model returns a complete response.
+//   - [BaseChatModel.Stream]: returns a [schema.StreamReader] that yields message
+//     chunks incrementally as the model generates them.
+//
+// The input is a slice of [schema.Message] representing the conversation history.
+// Messages carry a role (system, user, assistant, tool) and support multimodal
+// content (text, images, audio, video). Tool messages must include a ToolCallID
+// that correlates them with a prior assistant tool-call message.
+//
+// Stream usage — the caller is responsible for closing the reader:
+//
+//	reader, err := m.Stream(ctx, messages)
+//	if err != nil { ... }
+//	defer reader.Close()
+//	for {
+//	    chunk, err := reader.Recv()
+//	    if errors.Is(err, io.EOF) { break }
+//	    if err != nil { ... }
+//	    // handle chunk
+//	}
+//
+// Note: a [schema.StreamReader] can only be read once. If multiple consumers
+// need the stream, it must be copied before reading.
+//
+//go:generate  mockgen -destination ../../internal/mock/components/model/ChatModel_mock.go --package model github.com/cloudwego/eino/components/model BaseChatModel,ChatModel,ToolCallingChatModel
+type BaseChatModel = BaseModel[*schema.Message]
+
+// Deprecated: Use [ToolCallingChatModel] instead.
+//
+// ChatModel extends [BaseChatModel] with tool binding via [ChatModel.BindTools].
+// BindTools mutates the instance in place, which causes a race condition when
+// the same instance is used concurrently: one goroutine's tool list can
+// overwrite another's. Prefer [ToolCallingChatModel.WithTools], which returns
+// a new immutable instance and is safe for concurrent use.
+type ChatModel interface {
+	BaseChatModel
+
+	// BindTools bind tools to the model.
+	// BindTools before requesting ChatModel generally.
+	// notice the non-atomic problem of BindTools and Generate.
+	BindTools(tools []*schema.ToolInfo) error
+}
+
+// ToolCallingChatModel extends [BaseChatModel] with safe tool binding.
+//
+// Unlike the deprecated [ChatModel.BindTools], [ToolCallingChatModel.WithTools]
+// does not mutate the receiver — it returns a new instance with the given tools
+// attached. This makes it safe to share a base model instance across goroutines
+// and derive per-request variants with different tool sets:
+//
+//	base, _ := openai.NewChatModel(ctx, cfg)           // shared, no tools
+//	withSearch, _ := base.WithTools([]*schema.ToolInfo{searchTool})
+//	withCalc, _  := base.WithTools([]*schema.ToolInfo{calcTool})
+type ToolCallingChatModel interface {
+	BaseChatModel
+
+	WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
+}
+
+// AgenticModel is a type alias for BaseModel specialized with
+// *schema.AgenticMessage. Unlike ToolCallingChatModel, agentic models do NOT
+// expose a WithTools method; tools are passed at request time via the
+// model.WithTools option, consistent with how ChatModelAgent binds tools.
+type AgenticModel = BaseModel[*schema.AgenticMessage]