flows

type ActionConfig struct {
	// Type identifies the action. It is required.
	Type string
	// Handler runs the action. It is required for the "function" action, which is
	// nothing but a handler to run in pipeline order, and optional otherwise: for
	// any other type it registers the handler under Type when the action is first
	// seen.
	Handler ActionHandler
	// Text is what "tts_say" speaks, or the optional goodbye "end_conversation"
	// speaks before ending.
	Text string
	// AppendTextToContext controls whether the text the built-in speaking actions
	// say is written to the conversation. Nil defaults to true.
	AppendTextToContext *bool
	// Params carries whatever else the action needs, for a custom handler to
	// read. The built-in actions do not look at it.
	Params map[string]any
}

type ActionFinishedFrame struct {
	frames.BaseControlFrame
}

type ActionHandler func(ctx context.Context, action ActionConfig, fm *FlowManager) error

type Config struct {
	// Enqueuer queues the frames a flow produces; usually the *pipeline.Worker.
	Enqueuer Enqueuer
	// Watcher reports frames reaching the end of the pipeline, which is how an
	// action learns it has finished; usually the same *pipeline.Worker. Leaving it
	// nil gives up the actions that wait on the pipeline.
	Watcher Watcher
	// Aggregators are the conversation aggregators the pipeline shares. The flow
	// reads the conversation through them, and asks the assistant side whether a
	// turn's tool calls have all reported before it transitions.
	Aggregators *aggregators.Pair
	// LLM answers the one-shot inference the reset-with-summary strategy needs. It
	// is only required by that strategy; the concrete LLM services satisfy it.
	LLM Inferencer
	// ContextStrategy is what happens to the conversation when a node is entered.
	// Nil appends, keeping everything said so far.
	ContextStrategy *ContextStrategyConfig
	// GlobalFunctions are offered at every node, ahead of the node's own.
	GlobalFunctions []NodeFunction
}

type ContextStrategy string

type ContextStrategyConfig struct {
	// Strategy is what happens to the conversation.
	Strategy ContextStrategy
	// SummaryPrompt guides the summary, and is required by
	// ContextStrategyResetWithSummary.
	SummaryPrompt string
}

type Enqueuer interface {
	QueueFrame(f frames.Frame, dir ...processor.Direction)
	QueueFrames(fs []frames.Frame, dir ...processor.Direction)
}

type FlowManager struct {
	// contains filtered or unexported fields
}

type FunctionActionFrame struct {
	frames.BaseControlFrame
	// Action is the action that named the handler.
	Action ActionConfig
	// Function is the handler to run.
	Function ActionHandler
}

type Handler func(ctx context.Context, args json.RawMessage, fm *FlowManager) (string, *NodeConfig, error)

type Inferencer interface {
	RunInference(ctx context.Context, convo *frames.LLMContext, opts llm.InferenceOptions) (string, error)
}

type NodeConfig struct {
	// Name labels the node in logs. It is optional; an unnamed node is given a
	// generated name so two of them are told apart.
	Name string
	// RoleMessage is the assistant's persona. It is sent as the LLM service's
	// system instruction on entry and, being sticky, persists across later
	// transitions until another node sets its own. Leave it empty to keep the
	// current persona.
	RoleMessage string
	// TaskMessages state the assistant's objective at this node. They are added to
	// the conversation on entry, as the node's context strategy says.
	//
	// It is required: a nil slice is a node that never said what it is for, and is
	// rejected. An empty non-nil slice is a node that deliberately adds nothing,
	// which is allowed.
	TaskMessages []frames.Message
	// Functions are the tools available at this node. A function whose handler
	// returns a next node is an edge that transitions the flow; one that returns
	// no next node only gathers data.
	Functions []NodeFunction
	// PreActions run before the node's context is applied, so what they say is
	// spoken ahead of anything the node generates.
	PreActions []ActionConfig
	// PostActions run after the node's context is applied. On a node that speaks
	// on entry they run immediately; on one that waits for the user they are held
	// back until the assistant's first turn at this node is over.
	PostActions []ActionConfig
	// ContextStrategy overrides the manager's strategy for this node. Nil uses the
	// manager's.
	ContextStrategy *ContextStrategyConfig
	// RespondImmediately controls whether the assistant generates a response as
	// soon as the node is entered. It defaults to true; point it at false for a
	// node that should wait for the user to speak first, such as the opening node
	// of a call the user initiates.
	RespondImmediately *bool
}

type NodeFunction struct {
	// Name is the tool name the model calls. It must be unique within a node and
	// is required.
	Name string
	// Description tells the model when to call the tool.
	Description string
	// Properties describes the tool's arguments, as the properties of a JSON
	// Schema object: a map of argument name to its schema.
	Properties map[string]any
	// Required names the arguments the model must supply.
	Required []string
	// Handler runs the call and may return the next node. It is required.
	Handler Handler
	// CancelOnInterruption sets whether a call to this tool is canceled when the
	// user interrupts. Nil leaves the flow default, which does not cancel: a flow
	// function is usually doing work the conversation still needs whether or not
	// the user spoke over it.
	CancelOnInterruption *bool
	// TimeoutSecs bounds how long a call to this tool may take, overriding the
	// service-wide bound. Nil leaves the service-wide one.
	TimeoutSecs *float64
}

type State struct {
	// contains filtered or unexported fields
}

type Watcher interface {
	// Events is where the handler for the frames reaching the end of the
	// pipeline is attached.
	Events() *events.Registry
	SetReachedDownstreamFilter(f pipeline.FrameFilter)
}