Documentation
¶
Overview ¶
Package graph implements the core graph engine for FlowCraft.
A Graph is a compiled, immutable directed graph of Nodes connected by Edges. Nodes operate on a shared Board and pass control to successor node(s). Edges may carry compiled conditions (evaluated by expr-lang/expr) for dynamic routing.
Index ¶
- Constants
- Variables
- func GetTyped[T any](b *Board, key string) (T, bool)
- func IsCompatible(output, input PortType) bool
- func ValidateInputs(b *Board, node PortDeclarable) error
- func ValidateInputsWithConfig(b *Board, node PortDeclarable, config map[string]any) error
- func ValidateOutputs(b *Board, node PortDeclarable) error
- type Board
- type BoardSnapshot
- type CompiledCondition
- type Configurable
- type Describable
- type Edge
- type EdgeDefinition
- type ExecutionContext
- type Graph
- func (g *Graph) AllEdges() []Edge
- func (g *Graph) Edges(from string) []Edge
- func (g *Graph) Entry() string
- func (g *Graph) Meta() GraphMeta
- func (g *Graph) Name() string
- func (g *Graph) Node(id string) (Node, bool)
- func (g *Graph) Reverse(to string) []string
- func (g *Graph) SkipCondition(id string) (*CompiledCondition, bool)
- type GraphDefinition
- type GraphMeta
- type Node
- type NodeDefinition
- type Port
- type PortDeclarable
- type PortType
- type RawGraph
- type StreamCallback
- type StreamEvent
Constants ¶
const END = "__end__"
END is a sentinel node ID that marks the end of execution.
const (
VarInterruptedNode = "__interrupted_node"
)
Board variable keys used by the graph execution engine.
Variables ¶
var ErrInterrupt = errdefs.Interrupted(errdefs.New("execution interrupted"))
ErrInterrupt is returned by a node's ExecuteBoard to signal a graceful early exit. The executor stops and returns the current Board alongside ErrInterrupt so the caller can persist and resume later.
Functions ¶
func IsCompatible ¶
IsCompatible checks if an output port type can feed into an input port type.
func ValidateInputs ¶
func ValidateInputs(b *Board, node PortDeclarable) error
ValidateInputs checks that all required input ports have corresponding Board variables.
func ValidateInputsWithConfig ¶
func ValidateInputsWithConfig(b *Board, node PortDeclarable, config map[string]any) error
ValidateInputsWithConfig checks that all required input ports are satisfied.
func ValidateOutputs ¶
func ValidateOutputs(b *Board, node PortDeclarable) error
ValidateOutputs checks that all required output ports have been written to the Board.
Types ¶
type Board ¶
Board is the graph execution blackboard (vars + message channels). Kanban card coordination lives in kanban.Board.
func RestoreBoard ¶
func RestoreBoard(snap *BoardSnapshot) *Board
RestoreBoard reconstructs a Board from a snapshot.
type BoardSnapshot ¶
type BoardSnapshot = workflow.BoardSnapshot
BoardSnapshot is serializable execution state (vars + channels only).
type CompiledCondition ¶
type CompiledCondition struct {
Raw string
// contains filtered or unexported fields
}
CompiledCondition holds a pre-compiled expr-lang program for edge/skip conditions.
func CompileCondition ¶
func CompileCondition(raw string) (*CompiledCondition, error)
CompileCondition compiles a raw expression string into a reusable program.
type Configurable ¶
Configurable is an optional interface for nodes whose config can be dynamically resolved (e.g. variable reference expansion).
type Describable ¶
type Describable interface {
Description() string
}
Describable is an optional interface for nodes that provide a description.
type Edge ¶
type Edge struct {
From string
To string
Condition *CompiledCondition
}
Edge represents a directed connection between two nodes.
type EdgeDefinition ¶
type EdgeDefinition struct {
From string `json:"from" yaml:"from"`
To string `json:"to" yaml:"to"`
Condition string `json:"condition,omitempty" yaml:"condition,omitempty"`
}
EdgeDefinition describes a single edge in a GraphDefinition.
type ExecutionContext ¶
type ExecutionContext struct {
Context context.Context
Stream StreamCallback
RunID string
}
ExecutionContext wraps a standard context.Context with graph execution metadata.
type Graph ¶
type Graph struct {
// contains filtered or unexported fields
}
Graph is an immutable, executable directed graph of nodes. It can only be created via NewGraph (called by Assemble) and provides read-only accessors. The executor is the sole consumer.
func NewGraph ¶
NewGraph constructs an immutable Graph. This is intended to be called by the Assemble step, not by end users directly.
func (*Graph) SkipCondition ¶
func (g *Graph) SkipCondition(id string) (*CompiledCondition, bool)
type GraphDefinition ¶
type GraphDefinition struct {
Name string `json:"name" yaml:"name"`
Entry string `json:"entry" yaml:"entry"`
Nodes []NodeDefinition `json:"nodes" yaml:"nodes"`
Edges []EdgeDefinition `json:"edges" yaml:"edges"`
}
GraphDefinition is the declarative definition of a graph (YAML/JSON).
func (*GraphDefinition) Validate ¶
func (d *GraphDefinition) Validate() error
Validate checks that the definition is structurally valid.
type GraphMeta ¶
type GraphMeta struct {
NodeCount int `json:"node_count"`
EdgeCount int `json:"edge_count"`
HasCycles bool `json:"has_cycles"`
HasParallel bool `json:"has_parallel"`
MaxDepth int `json:"max_depth"`
}
GraphMeta contains structural analysis results produced by the compiler.
type Node ¶
type Node interface {
ID() string
Type() string
ExecuteBoard(ctx ExecutionContext, board *Board) error
}
Node is the interface that all graph nodes must implement.
func NewPassthroughNode ¶
NewPassthroughNode creates a no-op node with the given ID and type.
type NodeDefinition ¶
type NodeDefinition struct {
ID string `json:"id" yaml:"id"`
Type string `json:"type" yaml:"type"`
Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
SkipCondition string `json:"skip_condition,omitempty" yaml:"skip_condition,omitempty"`
}
NodeDefinition describes a single node in a GraphDefinition.
type Port ¶
type Port struct {
Name string `json:"name"`
Type PortType `json:"type"`
Required bool `json:"required"`
Desc string `json:"desc,omitempty"`
}
Port declares a typed input or output slot on a node.
type PortDeclarable ¶
PortDeclarable is an optional interface for nodes that declare typed input/output ports for compile-time and runtime validation.
type PortType ¶
type PortType string
PortType identifies the data type of a node port.
const ( PortTypeString PortType = "string" PortTypeInteger PortType = "integer" PortTypeFloat PortType = "float" PortTypeBool PortType = "bool" PortTypeArray PortType = "array" PortTypeObject PortType = "object" PortTypeMessages PortType = "messages" PortTypeUsage PortType = "usage" PortTypeAny PortType = "any" )
type RawGraph ¶
type RawGraph struct {
Name string
Entry string
Nodes map[string]Node
Edges map[string][]Edge
Reverse map[string][]string
SkipConditions map[string]*CompiledCondition
}
RawGraph is the intermediate graph structure produced by the compiler. All fields are exported for static analysis during compilation. It is NOT intended for direct execution — use Assemble to produce an immutable *Graph for the executor.
type StreamCallback ¶
type StreamCallback = workflow.StreamCallback
StreamCallback is the signature for receiving streaming events during execution.
type StreamEvent ¶
type StreamEvent = workflow.StreamEvent
StreamEvent carries a streaming event emitted by a node during execution.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package compiler provides the GraphCompiler that transforms a GraphDefinition into a CompiledGraph with static analysis.
|
Package compiler provides the GraphCompiler that transforms a GraphDefinition into a CompiledGraph with static analysis. |
|
Package executor provides the graph execution engine.
|
Package executor provides the graph execution engine. |
|
Package node provides the Go-native LLM and Knowledge graph nodes.
|
Package node provides the Go-native LLM and Knowledge graph nodes. |
|
scripts
Package scripts embeds all built-in JS node scripts via embed.FS.
|
Package scripts embeds all built-in JS node scripts via embed.FS. |
|
Package variable provides a typed variable system for the graph engine.
|
Package variable provides a typed variable system for the graph engine. |