Documentation
¶
Overview ¶
Package dsl defines the compozy.loop/v1 authoring document.
Package dsl defines the compozy.loop/v1 authoring document.
Index ¶
- Constants
- func DeriveGoalHandle(nodeID NodeID, label string, itemIndex int) (string, error)
- func IsKnownControlKind(kind string) bool
- func IsKnownSourceKind(kind string) bool
- func IsKnownTerminalState(value TerminalState) bool
- func IsReservedActionKind(kind string) bool
- func Serialize(def Definition) ([]byte, error)
- type ActionKind
- type Budget
- type BudgetExceeded
- type CatalogMeta
- type ConcurrencyPolicy
- type Contract
- type ControlKind
- type CriterionType
- type Definition
- type DefinitionExtensionState
- type Edge
- type EventSubscription
- type FileParseKind
- type GateCriterion
- type GoalParams
- type Graph
- type GraphDocument
- type HarvestSpec
- type Input
- type InputRef
- type InputType
- type Meta
- type NoProgress
- type Node
- type NodeClass
- type NodeID
- type NodeParams
- type RetrySpec
- type RunAgentParams
- type RunLoopMode
- type RunLoopParams
- type RuntimeDefaults
- type RuntimeMatch
- type RuntimeRule
- type RuntimeSpec
- type Schema
- type SessionSpec
- type SourceKind
- type StartBinding
- type StartKind
- type TerminalState
- type TransformMapping
- type TransformParams
- type VerdictPolicy
Constants ¶
const ( // SessionModeContinuous reuses one durable binding across Goal turns. SessionModeContinuous = "continuous" // RetryOnFailureFreshSession rotates a proven-not-started Goal binding attempt. RetryOnFailureFreshSession = "fresh_session" // GoalOnExhaustedHalt terminates a Goal at its effective turn limit. GoalOnExhaustedHalt = "halt" // GoalOnExhaustedEscalate requests approval at the effective turn limit. GoalOnExhaustedEscalate = "escalate" )
const ( // APIVersion is the only loop DSL version accepted by this package. APIVersion = "compozy.loop/v1" // KindLoop is the document kind for loop definitions. KindLoop = "Loop" // GateMaxRevisionsCeiling is the hard structural gate revision ceiling. GateMaxRevisionsCeiling = 64 )
Variables ¶
This section is empty.
Functions ¶
func DeriveGoalHandle ¶
DeriveGoalHandle returns the fixed persisted binding identity for one Goal node item.
func IsKnownControlKind ¶
IsKnownControlKind validates the closed control enum.
func IsKnownSourceKind ¶
IsKnownSourceKind validates the closed source enum.
func IsKnownTerminalState ¶
func IsKnownTerminalState(value TerminalState) bool
IsKnownTerminalState reports whether value belongs to the closed terminal outcome vocabulary.
func IsReservedActionKind ¶
IsReservedActionKind reports whether kind is first-party and not a ToolID.
func Serialize ¶
func Serialize(def Definition) ([]byte, error)
Serialize encodes one compozy.loop/v1 YAML document.
Types ¶
type ActionKind ¶
type ActionKind string
ActionKind is open except for reserved first-party kinds.
const ( // ActionRunAgent executes an agent turn. ActionRunAgent ActionKind = "run-agent" // ActionRunLoop starts another loop definition. ActionRunLoop ActionKind = "run-loop" // ActionTransform reshapes data in daemon. ActionTransform ActionKind = "transform" // ActionGoal advances a durable convergence cycle. ActionGoal ActionKind = "goal" )
func ReservedActionKinds ¶
func ReservedActionKinds() []ActionKind
ReservedActionKinds returns the reserved first-party action kinds.
type Budget ¶
type Budget struct {
Tokens int32 `json:"tokens" yaml:"tokens"`
WallClockSec int32 `json:"wall_clock_sec" yaml:"wall_clock_sec"`
OnExceeded BudgetExceeded `json:"on_exceeded,omitempty" yaml:"on_exceeded,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Budget defines opt-in hard limits.
type BudgetExceeded ¶
type BudgetExceeded string
BudgetExceeded controls the outcome for a set budget breach.
const ( // BudgetExceededHalt maps a breach to exhausted. BudgetExceededHalt BudgetExceeded = "halt" // BudgetExceededEscalate maps a breach to needs-approval. BudgetExceededEscalate BudgetExceeded = "escalate" )
type CatalogMeta ¶
type CatalogMeta struct {
UseWhen string `json:"use_when,omitempty" yaml:"use_when,omitempty"`
Keywords []string `json:"keywords,omitempty" yaml:"keywords,omitempty"`
Category string `json:"category,omitempty" yaml:"category,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
CatalogMeta is the matchable catalog projection embedded in a definition.
type ConcurrencyPolicy ¶
type ConcurrencyPolicy string
ConcurrencyPolicy controls same-loop concurrent starts.
const ( // ConcurrencyForbid rejects concurrent starts of the same loop. ConcurrencyForbid ConcurrencyPolicy = "forbid" // ConcurrencyAllow permits concurrent starts of the same loop. ConcurrencyAllow ConcurrencyPolicy = "allow" // ConcurrencyQueue creates a queued loop run for later promotion. ConcurrencyQueue ConcurrencyPolicy = "queue" )
type Contract ¶
type Contract struct {
Goal string `json:"goal" yaml:"goal"`
DefinitionOfDone string `json:"definition_of_done" yaml:"definition_of_done"`
Constraints []string `json:"constraints,omitempty" yaml:"constraints,omitempty"`
Boundaries []string `json:"boundaries,omitempty" yaml:"boundaries,omitempty"`
StopWhen string `json:"stop_when,omitempty" yaml:"stop_when,omitempty"`
Verification []GateCriterion `json:"verification,omitempty" yaml:"verification,omitempty"`
TerminalStates []TerminalState `json:"terminal_states,omitempty" yaml:"terminal_states,omitempty"`
IterationCap int `json:"iteration_cap" yaml:"iteration_cap"`
NoProgress NoProgress `json:"no_progress" yaml:"no_progress"`
Budget Budget `json:"budget" yaml:"budget"`
RuntimeDefaults *RuntimeDefaults `json:"runtime_defaults,omitempty" yaml:"runtime_defaults,omitempty"`
RuntimeRules []RuntimeRule `json:"runtime_rules,omitempty" yaml:"runtime_rules,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Contract defines goal, verification, and stop semantics.
type ControlKind ¶
type ControlKind string
ControlKind is the closed control-node vocabulary.
const ( // ControlFanOut materializes a finite collection into branches. ControlFanOut ControlKind = "fan-out" // ControlCollect joins fan-out branches. ControlCollect ControlKind = "collect" // ControlBranch routes by CEL condition. ControlBranch ControlKind = "branch" // ControlGate evaluates criteria and routing policy. ControlGate ControlKind = "gate" // ControlSubLoop embeds an inline nested loop body. ControlSubLoop ControlKind = "sub-loop" )
type CriterionType ¶
type CriterionType string
CriterionType is the closed gate criterion vocabulary.
const ( // CriterionCommand runs a project command. CriterionCommand CriterionType = "command" // CriterionAgentJudge asks an agent to judge against a rubric. CriterionAgentJudge CriterionType = "agent-judge" // CriterionHuman waits for a human decision. CriterionHuman CriterionType = "human" // CriterionExtension calls an extension tool. CriterionExtension CriterionType = "extension" )
type Definition ¶
type Definition struct {
APIVersion string `json:"apiVersion" yaml:"apiVersion"`
Kind string `json:"kind" yaml:"kind"`
Meta Meta `json:"meta" yaml:"meta"`
Concurrency ConcurrencyPolicy `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
Inputs map[string]Input `json:"inputs,omitempty" yaml:"inputs,omitempty"`
Contract Contract `json:"contract" yaml:"contract"`
Graph Graph `json:"graph" yaml:"graph"`
*DefinitionExtensionState ` yaml:",inline"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Definition is the canonical compozy.loop/v1 document.
func GraphToDefinition ¶
func GraphToDefinition(graph *GraphDocument) Definition
GraphToDefinition merges graph edits back into the original definition.
func Parse ¶
func Parse(data []byte) (Definition, error)
Parse decodes one compozy.loop/v1 YAML document.
func (*Definition) Normalize ¶
func (d *Definition) Normalize()
Normalize applies document-level zero-value semantics without inventing authoring defaults.
func (Definition) ValidateHeader ¶
func (d Definition) ValidateHeader() error
ValidateHeader checks the fixed document identity.
type DefinitionExtensionState ¶
type DefinitionExtensionState struct {
Start []StartBinding `json:"start,omitempty" yaml:"start,omitempty"`
NetworkParticipation *participation.Request `json:"network_participation,omitempty" yaml:"network_participation,omitempty"`
}
DefinitionExtensionState keeps optional authoring extensions off the hot Definition value.
type Edge ¶
type Edge struct {
From NodeID `json:"from" yaml:"from"`
To NodeID `json:"to" yaml:"to"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Edge declares one blocks dependency.
type EventSubscription ¶
type EventSubscription struct {
Kind string `json:"kind" yaml:"kind"`
Filter string `json:"filter,omitempty" yaml:"filter,omitempty"`
}
EventSubscription declares one internal watch-events subscription.
type FileParseKind ¶
type FileParseKind string
FileParseKind is the closed file-import parse mode vocabulary.
const ( // FileParseJSON imports JSON files. FileParseJSON FileParseKind = "json" // FileParseText imports text files. FileParseText FileParseKind = "text" )
type GateCriterion ¶
type GateCriterion struct {
ID string `json:"id" yaml:"id"`
Type CriterionType `json:"type" yaml:"type"`
Check string `json:"check,omitempty" yaml:"check,omitempty"`
Expect string `json:"expect,omitempty" yaml:"expect,omitempty"`
Agent string `json:"agent,omitempty" yaml:"agent,omitempty"`
Runtime RuntimeSpec `json:"runtime,omitzero" yaml:"runtime,omitempty"`
Rubric string `json:"rubric,omitempty" yaml:"rubric,omitempty"`
Prompt string `json:"prompt,omitempty" yaml:"prompt,omitempty"`
Tool string `json:"tool,omitempty" yaml:"tool,omitempty"`
Inputs map[string]any `json:"inputs,omitempty" yaml:"inputs,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
GateCriterion is one typed check in a gate or verification bundle.
type GoalParams ¶
type GoalParams struct {
Agent string `json:"agent" yaml:"agent"`
Objective string `json:"objective" yaml:"objective"`
Judge []GateCriterion `json:"judge" yaml:"judge"`
MaxTurns int `json:"max_turns" yaml:"max_turns"`
OnExhausted string `json:"on_exhausted,omitempty" yaml:"on_exhausted,omitempty"`
OutputSchema *Schema `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`
Runtime RuntimeSpec `json:"runtime,omitzero" yaml:"runtime,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
GoalParams is the canonical schema for action kind goal.
type Graph ¶
type Graph struct {
Nodes []Node `json:"nodes" yaml:"nodes"`
Edges []Edge `json:"edges" yaml:"edges"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Graph is the acyclic loop body.
type GraphDocument ¶
type GraphDocument struct {
Original Definition
Nodes []Node
Edges []Edge
}
GraphDocument is the editor-facing graph plus the original definition.
func DefinitionToGraph ¶
func DefinitionToGraph(def Definition) *GraphDocument
DefinitionToGraph extracts the graph while retaining the original definition for structural merge.
type HarvestSpec ¶
type HarvestSpec struct {
Kind string `json:"kind,omitempty" yaml:"kind,omitempty"`
Window string `json:"window,omitempty" yaml:"window,omitempty"`
Responder string `json:"responder,omitempty" yaml:"responder,omitempty"`
ContentRule string `json:"content_rule,omitempty" yaml:"content_rule,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
HarvestSpec configures action output harvest semantics.
type Input ¶
type Input struct {
Type InputType `json:"type" yaml:"type"`
Required bool `json:"required,omitempty" yaml:"required,omitempty"`
Description string `json:"description,omitempty" yaml:"description,omitempty"`
Ref *InputRef `json:"ref,omitempty" yaml:"ref,omitempty"`
Default any `json:"default,omitempty" yaml:"default,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Input declares one named loop input.
type InputRef ¶
type InputRef struct {
Kind string `json:"kind" yaml:"kind"`
Extra map[string]any `json:"-" yaml:",inline"`
}
InputRef narrows an input of type ref to one resource kind.
type InputType ¶
type InputType string
InputType is the closed declared input type vocabulary.
const ( // InputTypeString declares a string input. InputTypeString InputType = "string" // InputTypeNumber declares a numeric input. InputTypeNumber InputType = "number" // InputTypeBoolean declares a boolean input. InputTypeBoolean InputType = "boolean" // InputTypeFile declares a file input. InputTypeFile InputType = "file" // InputTypeAgent declares an agent reference input. InputTypeAgent InputType = "agent" // InputTypeRef declares a typed resource reference input. InputTypeRef InputType = "ref" )
type Meta ¶
type Meta struct {
Name string `json:"name" yaml:"name"`
Version int `json:"version,omitempty" yaml:"version,omitempty"`
Description string `json:"description,omitempty" yaml:"description,omitempty"`
Catalog CatalogMeta `json:"catalog" yaml:"catalog"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Meta describes a loop definition for catalog and authoring surfaces.
type NoProgress ¶
type NoProgress struct {
Window int `json:"window" yaml:"window"`
HashFields []string `json:"hash_fields,omitempty" yaml:"hash_fields,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
NoProgress defines the generation-level progress signature.
type Node ¶
type Node struct {
ID NodeID `json:"id" yaml:"id"`
Class NodeClass `json:"class" yaml:"class"`
Kind string `json:"kind" yaml:"kind"`
Session *SessionSpec `json:"session,omitempty" yaml:"session,omitempty"`
Timeout string `json:"timeout,omitempty" yaml:"timeout,omitempty"`
Retry *RetrySpec `json:"retry,omitempty" yaml:"retry,omitempty"`
Harvest *HarvestSpec `json:"harvest,omitempty" yaml:"harvest,omitempty"`
Produces Schema `json:"produces,omitempty" yaml:"produces,omitempty"`
Params NodeParams `json:"params,omitempty" yaml:"params,omitempty"`
Collection string `json:"collection,omitempty" yaml:"collection,omitempty"`
Filter string `json:"filter,omitempty" yaml:"filter,omitempty"`
BatchSize int `json:"batch_size,omitempty" yaml:"batch_size,omitempty"`
MaxParallel int `json:"max_parallel,omitempty" yaml:"max_parallel,omitempty"`
MaxFanOut int `json:"max_fan_out,omitempty" yaml:"max_fan_out,omitempty"`
Condition string `json:"condition,omitempty" yaml:"condition,omitempty"`
Criteria []GateCriterion `json:"criteria,omitempty" yaml:"criteria,omitempty"`
VerdictPolicy VerdictPolicy `json:"verdict_policy,omitempty" yaml:"verdict_policy,omitempty"`
OnResult map[string]any `json:"on_result,omitempty" yaml:"on_result,omitempty"`
MaxRevisions int `json:"max_revisions,omitempty" yaml:"max_revisions,omitempty"`
Body *Graph `json:"body,omitempty" yaml:"body,omitempty"`
Contract *Contract `json:"contract,omitempty" yaml:"contract,omitempty"`
InputRef string `json:"input_ref,omitempty" yaml:"input_ref,omitempty"`
Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`
Parse FileParseKind `json:"parse,omitempty" yaml:"parse,omitempty"`
WatchSpec map[string]any `json:"watch,omitempty" yaml:"watch,omitempty"`
Events []EventSubscription `json:"events,omitempty" yaml:"events,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
Node is the single envelope for every graph node.
type NodeClass ¶
type NodeClass string
NodeClass is the closed node class vocabulary.
const ( // NodeClassAction is open and resolves against reserved kinds or ToolIDs. NodeClassAction NodeClass = "action" // NodeClassControl is a closed statically-verifiable class. NodeClassControl NodeClass = "control" // NodeClassSource is a closed statically-verifiable class. NodeClassSource NodeClass = "source" )
type NodeParams ¶
NodeParams holds raw action params and can decode into per-kind schema types.
func (NodeParams) Decode ¶
func (p NodeParams) Decode(dest any) error
Decode unmarshals params into a concrete per-kind schema type.
type RetrySpec ¶
type RetrySpec struct {
MaxAttempts int `json:"max_attempts,omitempty" yaml:"max_attempts,omitempty"`
OnFailure string `json:"on_failure,omitempty" yaml:"on_failure,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
RetrySpec configures node retry policy.
type RunAgentParams ¶
type RunAgentParams struct {
Agent string `json:"agent" yaml:"agent"`
Prompt string `json:"prompt" yaml:"prompt"`
OutputSchema Schema `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`
CWD string `json:"cwd,omitempty" yaml:"cwd,omitempty"`
Runtime RuntimeSpec `json:"runtime,omitzero" yaml:"runtime,omitempty"`
AllowedTools []string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`
MaxTurns int `json:"max_turns,omitempty" yaml:"max_turns,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
RunAgentParams is the canonical schema for action kind run-agent.
type RunLoopMode ¶
type RunLoopMode string
RunLoopMode controls child-loop completion semantics.
const ( // RunLoopAwait waits for a child loop terminal event. RunLoopAwait RunLoopMode = "await" // RunLoopDetach returns immediately with the child run id. RunLoopDetach RunLoopMode = "detach" )
type RunLoopParams ¶
type RunLoopParams struct {
Loop string `json:"loop" yaml:"loop"`
Inputs map[string]any `json:"inputs,omitempty" yaml:"inputs,omitempty"`
Mode RunLoopMode `json:"mode,omitempty" yaml:"mode,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
RunLoopParams is the canonical schema for action kind run-loop.
type RuntimeDefaults ¶
type RuntimeDefaults struct {
Worker RuntimeSpec `json:"worker,omitzero" yaml:"worker,omitempty" toml:"worker"`
Judge RuntimeSpec `json:"judge,omitzero" yaml:"judge,omitempty" toml:"judge"`
}
RuntimeDefaults defines worker and judge runtime defaults.
type RuntimeMatch ¶
type RuntimeMatch struct {
ID string `json:"id,omitempty" yaml:"id,omitempty" toml:"id"`
Type string `json:"type,omitempty" yaml:"type,omitempty" toml:"type"`
Complexity string `json:"complexity,omitempty" yaml:"complexity,omitempty" toml:"complexity"`
Extra map[string]any `json:"-" yaml:",inline"`
}
RuntimeMatch selects exactly one task identity dimension.
type RuntimeRule ¶
type RuntimeRule struct {
Match RuntimeMatch `json:"match" yaml:"match" toml:"match"`
Runtime RuntimeSpec `json:"runtime" yaml:"runtime" toml:"runtime"`
}
RuntimeRule applies one field-merged runtime override to matching tasks.
type RuntimeSpec ¶
type RuntimeSpec struct {
Provider string `json:"provider,omitempty" yaml:"provider,omitempty" toml:"provider"`
Model string `json:"model,omitempty" yaml:"model,omitempty" toml:"model"`
Reasoning string `json:"reasoning,omitempty" yaml:"reasoning,omitempty" toml:"reasoning"`
Extra map[string]any `json:"-" yaml:",inline"`
}
RuntimeSpec selects one provider runtime without owning provider policy.
func (*RuntimeSpec) UnmarshalYAML ¶
func (r *RuntimeSpec) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML keeps runtime authoring closed and type-safe at every YAML ingress.
type SessionSpec ¶
type SessionSpec struct {
Handle string `json:"handle,omitempty" yaml:"handle,omitempty"`
Isolated bool `json:"isolated,omitempty" yaml:"isolated,omitempty"`
Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
SessionSpec configures action session binding.
type SourceKind ¶
type SourceKind string
SourceKind is the closed source-node vocabulary.
const ( // SourceInput exposes a declared input into the graph. SourceInput SourceKind = "input" // SourceFileImport imports workspace files. SourceFileImport SourceKind = "file-import" // SourceWatchSource polls an extension watch source. SourceWatchSource SourceKind = "watch-source" // SourceWatchEvents subscribes to committed internal Compozy events. SourceWatchEvents SourceKind = "watch-events" )
type StartBinding ¶
type StartBinding struct {
Kind StartKind `json:"kind" yaml:"kind"`
Inputs map[string]any `json:"inputs,omitempty" yaml:"inputs,omitempty"`
InputMapping map[string]string `json:"input_mapping,omitempty" yaml:"input_mapping,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
StartBinding declares one permitted start surface.
type StartKind ¶
type StartKind string
StartKind is the closed start-surface allowlist vocabulary.
const ( // StartManual allows operator web/manual starts. StartManual StartKind = "manual" // StartCLI allows CLI starts. StartCLI StartKind = "cli" // StartHTTP allows HTTP starts. StartHTTP StartKind = "http" // StartUDS allows UDS starts. StartUDS StartKind = "uds" // StartTrigger allows automation trigger starts. StartTrigger StartKind = "trigger" // StartSchedule allows scheduled starts. StartSchedule StartKind = "schedule" // StartWebhook allows webhook starts. StartWebhook StartKind = "webhook" // StartNetwork allows network starts. StartNetwork StartKind = "network" // StartExtension allows extension starts. StartExtension StartKind = "extension" // StartNativeTool allows native-tool starts. StartNativeTool StartKind = "native_tool" )
type TerminalState ¶
type TerminalState string
TerminalState is the closed terminal outcome vocabulary.
const ( // TerminalDone means the contract is verified. TerminalDone TerminalState = "done" // TerminalNoOp means the loop had nothing to do. TerminalNoOp TerminalState = "no-op" // TerminalBlocked means an explicit external dependency blocked progress. TerminalBlocked TerminalState = "blocked" // TerminalFailed means an unrecoverable failure occurred. TerminalFailed TerminalState = "failed" // TerminalExhausted means a hard stop limit tripped. TerminalExhausted TerminalState = "exhausted" // TerminalStalled means progress stopped. TerminalStalled TerminalState = "stalled" )
type TransformMapping ¶
type TransformMapping struct {
From string `json:"from,omitempty" yaml:"from,omitempty"`
Value any `json:"value,omitempty" yaml:"value,omitempty"`
Template string `json:"template,omitempty" yaml:"template,omitempty"`
Extra map[string]any `json:"-" yaml:",inline"`
}
TransformMapping maps one output key from a namespace path, literal, or template.
type TransformParams ¶
type TransformParams struct {
Map map[string]TransformMapping `json:"map" yaml:"map"`
Extra map[string]any `json:"-" yaml:",inline"`
}
TransformParams is the canonical schema for action kind transform.
type VerdictPolicy ¶
type VerdictPolicy string
VerdictPolicy controls how a gate reaches a verdict.
const ( // VerdictPolicyReviseUntilClean requires an agent/human verdict source. VerdictPolicyReviseUntilClean VerdictPolicy = "revise_until_clean" // VerdictPolicyFixedPasses is command-only compatible. VerdictPolicyFixedPasses VerdictPolicy = "fixed_passes" )