flows

Documentation

Overview

Package flows builds structured, multi-step conversations on top of jargo's LLM service. A conversation is a graph of nodes; each node sets the assistant's task and the tools it may call, and a tool whose handler returns the next node moves the conversation on.

A FlowManager sits beside the pipeline rather than in it. It shares the LLM service and the conversation context with the pipeline and steers the conversation by swapping the system prompt, task messages and toolset as nodes are entered; the LLM service's existing tool loop then carries out each transition, regenerating with the new node's tools.

This is the initial, transition-focused version: nodes, edge and data-gathering functions, and per-node "respond on entry" control. Node actions (speaking fixed lines on entry or exit), context-reset strategies and per-call timeouts are not implemented yet.

Index

• type Config
  • func (c Config) Validate() error
• type Enqueuer
• type FlowManager
  • func New(cfg Config) (*FlowManager, error)
  • func (fm *FlowManager) CurrentNode() string
  • func (fm *FlowManager) Initialize(ctx context.Context, node *NodeConfig) error
• type Handler
• type LLM
• type NodeConfig
• type NodeFunction

Types

type Config

type Config struct {
	// LLM is the tool-capable LLM service in the pipeline.
	LLM LLM `validate:"required"`
	// Context is the conversation the pipeline's aggregators share.
	Context *frames.LLMContext `validate:"required"`
	// Enqueuer triggers the first response; usually the *pipeline.Task.
	Enqueuer Enqueuer `validate:"required"`
	// GlobalFunctions are offered at every node in addition to the node's own. A
	// node function of the same name takes precedence.
	GlobalFunctions []NodeFunction
}

Config configures a FlowManager. The three references are the same instances wired into the pipeline: the LLM service, the conversation context shared by the aggregators, and the task that runs the pipeline.

func (Config) Validate

func (c Config) Validate() error

Validate reports whether the configuration is usable.

type Enqueuer

type Enqueuer interface {
	QueueFrame(f frames.Frame)
}

Enqueuer injects a frame into the running pipeline; *pipeline.Task satisfies it. The manager uses it only to trigger the assistant's first response.

type FlowManager

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

FlowManager drives a conversation through a graph of nodes. It is not a pipeline processor: it holds the LLM service and the shared context and steers the conversation by swapping the system prompt, task messages and toolset as nodes are entered, leaving the LLM service's tool loop to carry out each transition. Build one with New and enter the graph with Initialize.

func New

func New(cfg Config) (*FlowManager, error)

New builds a FlowManager from cfg.

func (*FlowManager) CurrentNode

func (fm *FlowManager) CurrentNode() string

CurrentNode returns the name of the node the flow is on, or "" before Initialize. A node with no name reports a placeholder.

func (*FlowManager) Initialize

func (fm *FlowManager) Initialize(ctx context.Context, node *NodeConfig) error

Initialize enters the flow at node and, unless the node waits for the user, triggers the assistant's first response. Call it once per session, for example when the transport connects.

type Handler

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

Handler runs when the model calls a node function. args carries the raw JSON arguments the model produced, and fm is the manager driving the flow. It returns the result to feed back to the model as the tool result and, optionally, the next node to move to: a non-nil next transitions the flow, a nil next leaves it on the current node.

type LLM

type LLM interface {
	RegisterFunction(name string, h llm.ToolHandler)
}

LLM is the part of the LLM service the manager drives: it registers a handler for each node function so the service dispatches matching calls to it. The concrete services satisfy it through the embedded llm.Base.

type NodeConfig

type NodeConfig struct {
	// Name labels the node in logs. It is optional.
	Name string
	// RoleMessage is the assistant's persona. It is applied to the system prompt
	// 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 appended
	// to the conversation on entry, so the model pursues the new goal while
	// keeping the prior history.
	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
	// 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
}

NodeConfig defines one state of a conversation: the assistant's task at this point, the tools it may call, and whether it speaks on entry.

type NodeFunction

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
	// Parameters is the JSON-Schema object describing the tool's arguments, for
	// example `{"type":"object","properties":{…},"required":[…]}`. An empty value
	// declares a tool that takes no arguments.
	Parameters json.RawMessage
	// Handler runs the call and may return the next node. It is required.
	Handler Handler
}

NodeFunction is a tool offered to the model at a node. It pairs the schema the model sees with the handler that runs when the model calls it.