dsl

Documentation

Overview

Package dsl defines serializable Graph Definition data transfer objects.

Index

• Constants
• func SemanticGraphHash(def GraphDefinition) (string, error)
• func SemanticGraphHashWithStateBindings(def GraphDefinition, bindings []StateBindingSemantic) (string, error)
• func SerializeGraphInstanceConfig(cfg GraphInstanceConfig) ([]byte, error)
• func SerializeRunRequest(req RunRequest) ([]byte, error)
• func SnapshotGraphHash(def GraphDefinition) (string, error)
• type ConditionSchema
• type DebugBreakpoint
  • func (b DebugBreakpoint) Effective() DebugBreakpoint
  • func (b DebugBreakpoint) Validate() error
• type DynamicStatePortDefinition
• type ExecutionPolicy
• type FailureRouteSpec
  • func (route *FailureRouteSpec) Validate() error
• type FailureStage
• type GraphConditionSpec
  • func CloneGraphConditionSpec(spec GraphConditionSpec) GraphConditionSpec
  • func NormalizeGraphConditionSpec(spec GraphConditionSpec) GraphConditionSpec
• type GraphDefinition
  • func DeserializeGraphDefinition(data []byte) (GraphDefinition, error)
  • func NormalizeGraphDefinition(def GraphDefinition) GraphDefinition
  • func (d GraphDefinition) Serialize() ([]byte, error)
  • func (d GraphDefinition) Validate() error
• type GraphEdgeSpec
• type GraphExecutionPolicy
• type GraphInstanceConfig
  • func DeserializeGraphInstanceConfig(data []byte) (GraphInstanceConfig, error)
  • func (c GraphInstanceConfig) Validate() error
• type GraphLimits
• type GraphNodeInstanceConfig
  • func (c GraphNodeInstanceConfig) Validate(nodeID string) error
• type GraphNodeSpec
• type GraphNodeSpecProvider
• type JSONSchema
  • func BuildGraphDefinitionSchema(stateModules map[string]StateModuleDefinition, ...) JSONSchema
  • func (s JSONSchema) Clone() JSONSchema
  • func (r JSONSchema) WriteToFile(path string) error
• type NodeTypeSchema
• type RelativeStateContract
• type RelativeStateFieldRef
• type RetryPolicy
  • func (policy RetryPolicy) MarshalJSON() ([]byte, error)
• type RunDebugOptions
  • func (o RunDebugOptions) EffectiveBreakpoints() []DebugBreakpoint
  • func (o RunDebugOptions) Validate() error
• type RunRequest
  • func DeserializeRunRequest(data []byte) (RunRequest, error)
  • func (r RunRequest) Validate() error
• type SecretRef
  • func (r SecretRef) Validate() error
• type StateAccessMode
• type StateBinding
• type StateBindingSemantic
• type StateCapabilityDefinition
• type StateCapabilityFieldDefinition
• type StateContract
  • func (c StateContract) Clone() StateContract
• type StateContractSemanticField
• type StateFieldDefinition
• type StateFieldRef
  • func (f StateFieldRef) Clone() StateFieldRef
• type StateMergeStrategy
• type StateModuleDefinition
• type StateModuleRef
• type StatePortDefinition

Constants

const (
	GraphInstanceConfigVersion = "1.0"
	RunRequestVersion          = "1.0"
	DebugBreakpointBeforeNode  = "before_node"
	DebugBreakpointAfterNode   = "after_node"
)

const EndNodeRef = "__end__"

const GraphDefinitionVersion = "1.0"

Functions

func SemanticGraphHash

func SemanticGraphHash(def GraphDefinition) (string, error)

SemanticGraphHash returns a stable hash for the executable graph definition.

Metadata is excluded because it is preserved by graph definitions for UI and tooling state, but it is not consumed when building or running a graph.

func SemanticGraphHashWithStateBindings

func SemanticGraphHashWithStateBindings(def GraphDefinition, bindings []StateBindingSemantic) (string, error)

func SerializeGraphInstanceConfig

func SerializeGraphInstanceConfig(cfg GraphInstanceConfig) ([]byte, error)

func SerializeRunRequest

func SerializeRunRequest(req RunRequest) ([]byte, error)

func SnapshotGraphHash

func SnapshotGraphHash(def GraphDefinition) (string, error)

SnapshotGraphHash returns a stable hash for the full normalized graph definition, including metadata.

Types

type ConditionSchema

type ConditionSchema struct {
	Type              string                      `json:"type"`
	Title             string                      `json:"title,omitempty"`
	Description       string                      `json:"description,omitempty"`
	ConfigSchema      JSONSchema                  `json:"config_schema"`
	StatePorts        []StatePortDefinition       `json:"state_ports"`
	DynamicStatePorts *DynamicStatePortDefinition `json:"dynamic_state_ports,omitempty"`
}

type DebugBreakpoint

type DebugBreakpoint struct {
	ID      string `json:"id,omitempty"`
	NodeID  string `json:"node_id"`
	Stage   string `json:"stage,omitempty"`
	Enabled *bool  `json:"enabled,omitempty"`
}

DebugBreakpoint is the user-facing breakpoint shape used by RunRequest.

func (DebugBreakpoint) Effective

func (b DebugBreakpoint) Effective() DebugBreakpoint

func (DebugBreakpoint) Validate

func (b DebugBreakpoint) Validate() error

type DynamicStatePortDefinition

type DynamicStatePortDefinition struct {
	Description   string             `json:"description,omitempty"`
	NamePattern   string             `json:"name_pattern"`
	MinPorts      int                `json:"min_ports,omitempty"`
	MaxPorts      int                `json:"max_ports,omitempty"`
	Required      bool               `json:"required,omitempty"`
	Schema        JSONSchema         `json:"schema"`
	Mode          StateAccessMode    `json:"mode"`
	MergeStrategy StateMergeStrategy `json:"merge_strategy"`
	Reducer       string             `json:"reducer,omitempty"`
}

type ExecutionPolicy

type ExecutionPolicy struct {
	Timeout        string       `json:"timeout,omitempty"`
	MaxConcurrency int          `json:"max_concurrency,omitempty"`
	Retry          *RetryPolicy `json:"retry,omitempty"`
}

type FailureRouteSpec

type FailureRouteSpec struct {
	Stages       []FailureStage `json:"stages,omitempty"`
	ErrorClasses []string       `json:"error_classes,omitempty"`
	CatchAll     bool           `json:"catch_all,omitempty"`
}

func (*FailureRouteSpec) Validate

func (route *FailureRouteSpec) Validate() error

type FailureStage

type FailureStage string

const (
	FailureStageNode      FailureStage = "node"
	FailureStageCondition FailureStage = "condition"
)

type GraphConditionSpec

type GraphConditionSpec struct {
	ID     string                  `json:"id,omitempty"`
	Type   string                  `json:"type"`
	Config map[string]any          `json:"config,omitempty"`
	State  map[string]StateBinding `json:"state,omitempty"`
}

func CloneGraphConditionSpec

func CloneGraphConditionSpec(spec GraphConditionSpec) GraphConditionSpec

func NormalizeGraphConditionSpec

func NormalizeGraphConditionSpec(spec GraphConditionSpec) GraphConditionSpec

type GraphDefinition

type GraphDefinition struct {
	Version      string                `json:"version"`
	Name         string                `json:"name,omitempty"`
	Description  string                `json:"description,omitempty"`
	StateModules []StateModuleRef      `json:"state_modules"`
	EntryPoint   string                `json:"entry_point,omitempty"`
	FinishPoint  string                `json:"finish_point,omitempty"`
	Nodes        []GraphNodeSpec       `json:"nodes"`
	Edges        []GraphEdgeSpec       `json:"edges,omitempty"`
	Policy       *GraphExecutionPolicy `json:"policy,omitempty"`
	Metadata     map[string]any        `json:"metadata,omitempty"`
}

func DeserializeGraphDefinition

func DeserializeGraphDefinition(data []byte) (GraphDefinition, error)

func NormalizeGraphDefinition

func NormalizeGraphDefinition(def GraphDefinition) GraphDefinition

func (GraphDefinition) Serialize

func (d GraphDefinition) Serialize() ([]byte, error)

func (GraphDefinition) Validate

func (d GraphDefinition) Validate() error

type GraphEdgeSpec

type GraphEdgeSpec struct {
	From      string              `json:"from"`
	To        string              `json:"to"`
	Condition *GraphConditionSpec `json:"condition,omitempty"`
	Failure   *FailureRouteSpec   `json:"failure,omitempty"`
}

type GraphExecutionPolicy

type GraphExecutionPolicy struct {
	Limits       GraphLimits     `json:"limits,omitempty"`
	NodeDefaults ExecutionPolicy `json:"node_defaults,omitempty"`
}

type GraphInstanceConfig

type GraphInstanceConfig struct {
	Version      string                             `json:"version"`
	ID           string                             `json:"id"`
	GraphRef     string                             `json:"graph_ref"`
	GraphVersion string                             `json:"graph_version,omitempty"`
	Name         string                             `json:"name,omitempty"`
	Description  string                             `json:"description,omitempty"`
	NodeConfigs  map[string]GraphNodeInstanceConfig `json:"node_configs,omitempty"`
	Secrets      map[string]SecretRef               `json:"secrets,omitempty"`
	Metadata     map[string]any                     `json:"metadata,omitempty"`
}

GraphInstanceConfig binds a graph definition to one runnable local instance.

func DeserializeGraphInstanceConfig

func DeserializeGraphInstanceConfig(data []byte) (GraphInstanceConfig, error)

func (GraphInstanceConfig) Validate

func (c GraphInstanceConfig) Validate() error

type GraphLimits

type GraphLimits struct {
	MaxSuperSteps      int    `json:"max_super_steps,omitempty"`
	MaxNodeExecutions  int    `json:"max_node_executions,omitempty"`
	MaxFanOut          int    `json:"max_fan_out,omitempty"`
	MaxConcurrentRuns  int    `json:"max_concurrent_runs,omitempty"`
	MaxConcurrentNodes int    `json:"max_concurrent_nodes,omitempty"`
	MaxConcurrentTools int    `json:"max_concurrent_tools,omitempty"`
	MaxStateBytes      int64  `json:"max_state_bytes,omitempty"`
	MaxWallTime        string `json:"max_wall_time,omitempty"`
}

type GraphNodeInstanceConfig

type GraphNodeInstanceConfig struct {
	Config   map[string]any       `json:"config,omitempty"`
	Secrets  map[string]SecretRef `json:"secrets,omitempty"`
	Disabled bool                 `json:"disabled,omitempty"`
	Metadata map[string]any       `json:"metadata,omitempty"`
}

GraphNodeInstanceConfig holds instance-bound values for a single nodes.

func (GraphNodeInstanceConfig) Validate

func (c GraphNodeInstanceConfig) Validate(nodeID string) error

type GraphNodeSpec

type GraphNodeSpec struct {
	ID          string                  `json:"id"`
	Name        string                  `json:"name"`
	Type        string                  `json:"type"`
	Description string                  `json:"description,omitempty"`
	Config      map[string]any          `json:"config,omitempty"`
	State       map[string]StateBinding `json:"state"`
	Policy      *ExecutionPolicy        `json:"policy,omitempty"`
}

GraphNodeSpec describes a static nodes inside GraphDefinition. Runtime-bound values such as model paths, secret references, and per-instance overrides should live in GraphInstanceConfig instead of Config.

type GraphNodeSpecProvider

type GraphNodeSpecProvider interface {
	GraphNodeSpec() GraphNodeSpec
}

type JSONSchema

type JSONSchema map[string]any

func BuildGraphDefinitionSchema

func BuildGraphDefinitionSchema(stateModules map[string]StateModuleDefinition, nodeTypes map[string]NodeTypeSchema, conditions map[string]ConditionSchema, reducerIDs ...string) JSONSchema

func (JSONSchema) Clone

func (s JSONSchema) Clone() JSONSchema

func (JSONSchema) WriteToFile

func (r JSONSchema) WriteToFile(path string) error

type NodeTypeSchema

type NodeTypeSchema struct {
	Type              string                      `json:"type"`
	Title             string                      `json:"title,omitempty"`
	Description       string                      `json:"description,omitempty"`
	ConfigSchema      JSONSchema                  `json:"config_schema"`
	StatePorts        []StatePortDefinition       `json:"state_ports"`
	DynamicStatePorts *DynamicStatePortDefinition `json:"dynamic_state_ports,omitempty"`
}

type RelativeStateContract

type RelativeStateContract struct {
	Fields []RelativeStateFieldRef `json:"fields"`
}

type RelativeStateFieldRef

type RelativeStateFieldRef struct {
	Path     string          `json:"path"`
	Mode     StateAccessMode `json:"mode"`
	Required bool            `json:"required,omitempty"`
}

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts              int      `json:"max_attempts,omitempty"`
	InitialInterval          string   `json:"initial_interval,omitempty"`
	MaxInterval              string   `json:"max_interval,omitempty"`
	BackoffMultiplier        *float64 `json:"backoff_multiplier,omitempty"`
	Jitter                   *float64 `json:"jitter,omitempty"`
	RetryableErrorClasses    []string `json:"retryable_error_classes,omitempty"`
	NonRetryableErrorClasses []string `json:"non_retryable_error_classes,omitempty"`
}

func (RetryPolicy) MarshalJSON

func (policy RetryPolicy) MarshalJSON() ([]byte, error)

type RunDebugOptions

type RunDebugOptions struct {
	StepMode         bool              `json:"step_mode,omitempty"`
	Breakpoints      []DebugBreakpoint `json:"breakpoints,omitempty"`
	PauseBefore      []string          `json:"pause_before,omitempty"`
	PauseAfter       []string          `json:"pause_after,omitempty"`
	IncludeState     bool              `json:"include_state,omitempty"`
	IncludeStateDiff bool              `json:"include_state_diff,omitempty"`
	IncludeArtifacts bool              `json:"include_artifacts,omitempty"`
	IncludeSnapshots bool              `json:"include_snapshots,omitempty"`
}

RunDebugOptions controls one execution's debug behavior.

func (RunDebugOptions) EffectiveBreakpoints

func (o RunDebugOptions) EffectiveBreakpoints() []DebugBreakpoint

func (RunDebugOptions) Validate

func (o RunDebugOptions) Validate() error

type RunRequest

type RunRequest struct {
	Version                string           `json:"version"`
	InstanceID             string           `json:"instance_id"`
	Input                  map[string]any   `json:"input,omitempty"`
	Stream                 bool             `json:"stream,omitempty"`
	Debug                  *RunDebugOptions `json:"debug,omitempty"`
	ResumeFromRunID        string           `json:"resume_from_run_id,omitempty"`
	ResumeFromCheckpointID string           `json:"resume_from_checkpoint_id,omitempty"`
	Metadata               map[string]any   `json:"metadata,omitempty"`
}

RunRequest describes a single execution against one graph instance.

func DeserializeRunRequest

func DeserializeRunRequest(data []byte) (RunRequest, error)

func (RunRequest) Validate

func (r RunRequest) Validate() error

type SecretRef

type SecretRef struct {
	Source   string         `json:"source"`
	Ref      string         `json:"ref"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

SecretRef points to a secret value stored outside GraphDefinition.

func (SecretRef) Validate

func (r SecretRef) Validate() error

type StateAccessMode

type StateAccessMode string

const (
	StateAccessRead      StateAccessMode = "read"
	StateAccessWrite     StateAccessMode = "write"
	StateAccessReadWrite StateAccessMode = "read_write"
)

type StateBinding

type StateBinding struct {
	Path    string `json:"path"`
	Reducer string `json:"reducer,omitempty"`
}

type StateBindingSemantic

type StateBindingSemantic struct {
	ComponentType string                       `json:"component_type"`
	ComponentID   string                       `json:"component_id,omitempty"`
	EdgeIndex     int                          `json:"edge_index,omitempty"`
	Port          string                       `json:"port"`
	Path          string                       `json:"path"`
	Capability    string                       `json:"capability,omitempty"`
	Contract      []StateContractSemanticField `json:"contract,omitempty"`
}

type StateCapabilityDefinition

type StateCapabilityDefinition struct {
	ID     string                           `json:"id"`
	Schema JSONSchema                       `json:"schema"`
	Fields []StateCapabilityFieldDefinition `json:"fields"`
}

type StateCapabilityFieldDefinition

type StateCapabilityFieldDefinition struct {
	Name          string             `json:"name"`
	Schema        JSONSchema         `json:"schema"`
	MergeStrategy StateMergeStrategy `json:"merge_strategy,omitempty"`
	Reducer       string             `json:"reducer,omitempty"`
}

type StateContract

type StateContract struct {
	Fields []StateFieldRef `json:"fields,omitempty"`
}

func (StateContract) Clone

func (c StateContract) Clone() StateContract

type StateContractSemanticField

type StateContractSemanticField struct {
	Path          string             `json:"path"`
	Mode          StateAccessMode    `json:"mode"`
	Required      bool               `json:"required,omitempty"`
	MergeStrategy StateMergeStrategy `json:"merge_strategy"`
	Reducer       string             `json:"reducer,omitempty"`
	Type          string             `json:"type,omitempty"`
}

type StateFieldDefinition

type StateFieldDefinition struct {
	Path        string     `json:"path"`
	Description string     `json:"description,omitempty"`
	Schema      JSONSchema `json:"schema"`
}

type StateFieldRef

type StateFieldRef struct {
	Path          string             `json:"path,omitempty"`
	Mode          StateAccessMode    `json:"mode"`
	Required      bool               `json:"required,omitempty"`
	Description   string             `json:"description,omitempty"`
	Schema        JSONSchema         `json:"schema,omitempty"`
	MergeStrategy StateMergeStrategy `json:"merge_strategy,omitempty"`
	Reducer       string             `json:"reducer,omitempty"`
}

func (StateFieldRef) Clone

func (f StateFieldRef) Clone() StateFieldRef

type StateMergeStrategy

type StateMergeStrategy string

const (
	StateMergeReplace StateMergeStrategy = "replace"
	StateMergeMerge   StateMergeStrategy = "merge"
	StateMergeAppend  StateMergeStrategy = "append"
)

type StateModuleDefinition

type StateModuleDefinition struct {
	Name         string                      `json:"name"`
	Version      string                      `json:"version"`
	Fields       []StateFieldDefinition      `json:"fields,omitempty"`
	Capabilities []StateCapabilityDefinition `json:"capabilities,omitempty"`
}

type StateModuleRef

type StateModuleRef struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type StatePortDefinition

type StatePortDefinition struct {
	Name          string                `json:"name"`
	Description   string                `json:"description,omitempty"`
	DefaultPath   string                `json:"default_path,omitempty"`
	Required      bool                  `json:"required,omitempty"`
	Schema        JSONSchema            `json:"schema,omitempty"`
	Mode          StateAccessMode       `json:"mode,omitempty"`
	Capability    string                `json:"capability,omitempty"`
	Contract      RelativeStateContract `json:"contract,omitempty"`
	MergeStrategy StateMergeStrategy    `json:"merge_strategy,omitempty"`
	Reducer       string                `json:"reducer,omitempty"`
}