Eino: CallOption Capabilities and Conventions

type ChatModel interface {
    Generate(ctx context.Context, input []*schema.Message, opts ...Option) (*schema.Message, error)
    Stream(ctx context.Context, input []*schema.Message, opts ...Option) (*schema.StreamReader[*schema.Message], error)
    BindTools(tools []*schema.ToolInfo) error
}

// Abstract/common options
type Options struct {
    Temperature *float32
    MaxTokens *int
    Model *string
    TopP *float32
    Stop []string
}

type Option struct {
    apply func(opts *Options)          // for abstract/common options
    implSpecificOptFn any              // for impl-specific options (func(*T))
}

func WithTemperature(temperature float32) Option { return Option{ apply: func(o *Options){ o.Temperature = &temperature } } }
func WithMaxTokens(maxTokens int) Option         { return Option{ apply: func(o *Options){ o.MaxTokens   = &maxTokens } } }
func WithModel(name string) Option               { return Option{ apply: func(o *Options){ o.Model       = &name } } }
func WithTopP(topP float32) Option               { return Option{ apply: func(o *Options){ o.TopP        = &topP } } }
func WithStop(stop []string) Option              { return Option{ apply: func(o *Options){ o.Stop        = stop } } }

func GetCommonOptions(base *Options, opts ...Option) *Options {
    if base == nil { base = &Options{} }
    for i := range opts { if f := opts[i].apply; f != nil { f(base) } }
    return base
}

func WrapImplSpecificOptFn[T any](optFn func(*T)) Option { return Option{ implSpecificOptFn: optFn } }

func GetImplSpecificOptions[T any](base *T, opts ...Option) *T {
    if base == nil { base = new(T) }
    for i := range opts {
        if optFn, ok := opts[i].implSpecificOptFn.(func(*T)); ok { optFn(base) }
    }
    return base
}

type options struct { TopK *int32 }
func WithTopK(k int32) model.Option { return model.WrapImplSpecificOptFn(func(o *options){ o.TopK = &k }) }

common := model.GetCommonOptions(&model.Options{ Model:&c.model, Temperature:c.temperature, MaxTokens:&c.maxTokens, TopP:c.topP, Stop:c.stopSequences }, opts...)
claude := model.GetImplSpecificOptions(&options{ TopK:c.topK }, opts...)

type Runnable[I, O any] interface {
    Invoke(ctx context.Context, input I, opts ...Option) (O, error)
    Stream(ctx context.Context, input I, opts ...Option) (*schema.StreamReader[O], error)
    Collect(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (O, error)
    Transform(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (*schema.StreamReader[O], error)
}

// Option is a functional option type for calling a graph.
type Option struct {
    options []any
    handler []callbacks.Handler
    paths   []*NodePath
    maxRunSteps int
}

// DesignateNode sets the key of the node(s) to which the option will be applied.
// Only effective at the top graph.
// e.g.
//  embeddingOption := compose.WithEmbeddingOption(embedding.WithModel("text-embedding-3-small"))
//  runnable.Invoke(ctx, "input", embeddingOption.DesignateNode("my_embedding_node"))
func (o Option) DesignateNode(key ...string) Option {
    nKeys := make([]*NodePath, len(key))
    for i, k := range key { nKeys[i] = NewNodePath(k) }
    return o.DesignateNodeWithPath(nKeys...)
}

// DesignateNodeWithPath sets the path of the node(s) to which the option will be applied.
// You can make the option take effect in a subgraph by specifying the key of the subgraph.
// e.g. DesignateNodeWithPath({"sub graph node key", "node key within sub graph"})
func (o Option) DesignateNodeWithPath(path ...*NodePath) Option {
    o.paths = append(o.paths, path...)
    return o
}

// WithEmbeddingOption is a functional option for embedding component.
// e.g.
//  embeddingOption := compose.WithEmbeddingOption(embedding.WithModel("text-embedding-3-small"))
//  runnable.Invoke(ctx, "input", embeddingOption)
func WithEmbeddingOption(opts ...embedding.Option) Option { return withComponentOption(opts...) }

// call option effective for all nodes
compiledGraph.Invoke(ctx, input, WithCallbacks(handler))

// call option effective for specific component types
compiledGraph.Invoke(ctx, input, WithChatModelOption(WithTemperature(0.5)))
compiledGraph.Invoke(ctx, input, WithToolOption(WithXXX("xxx")))

// call option effective for a specific node
compiledGraph.Invoke(ctx, input, WithCallbacks(handler).DesignateNode("node_1"))

// call option effective for specific nested subgraph or its node(s)
compiledGraph.Invoke(ctx, input, WithCallbacks(handler).DesignateNodeWithPath(NewNodePath("1", "2")))