cruxx-script 0.2.6

YAML-driven pipeline scripting for the cruxx agentic DSL
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

/// YAML schema types for pipeline definitions.
use serde::Deserialize;

#[derive(Debug, Clone, Deserialize)]
pub struct PipelineDef {
    pub pipeline: String,
    #[serde(default)]
    pub budget: Option<BudgetDef>,
    pub steps: Vec<StepDef>,
}

/// An arm or stage in a join_all or pipe — either a bare handler name string,
/// or a full step object with `step`, optional `handler`, and optional `args`.
#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
pub enum ArmDef {
    /// Bare string: the name is both the step label and the handler name.
    Name(String),
    /// Full step object: `step` is the label, `handler` overrides the name, `args` injected.
    Step {
        step: String,
        #[serde(default)]
        handler: Option<String>,
        #[serde(default)]
        args: Option<serde_json::Value>,
    },
}

impl ArmDef {
    /// The label used in traces (step name).
    pub fn label(&self) -> &str {
        match self {
            ArmDef::Name(n) => n,
            ArmDef::Step { step, .. } => step,
        }
    }

    /// The handler name to look up in the registry.
    pub fn handler_name(&self) -> &str {
        match self {
            ArmDef::Name(n) => n,
            ArmDef::Step { step, handler, .. } => handler.as_deref().unwrap_or(step),
        }
    }

    /// Optional static args to inject into the handler input.
    pub fn args(&self) -> Option<&serde_json::Value> {
        match self {
            ArmDef::Name(_) => None,
            ArmDef::Step { args, .. } => args.as_ref(),
        }
    }
}

#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
pub enum BudgetDef {
    Tokens { tokens: u64 },
    Calls { calls: u64 },
    Duration { duration_ms: u64 },
    CostCents { cost_cents: u64 },
}

#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
pub enum StepDef {
    Step(StepNode),
    Delegate(DelegateNode),
    Pipe(PipeNode),
    JoinAll(JoinAllNode),
    RouteOnConfidence(RouteNode),
    Speculate(SpeculateNode),
}

#[derive(Debug, Clone, Deserialize)]
pub struct StepNode {
    pub step: String,
    #[serde(default)]
    pub handler: Option<String>,
    #[serde(default)]
    pub args: Option<serde_json::Value>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct DelegateNode {
    pub delegate: String,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub budget: Option<BudgetDef>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct PipeNode {
    pub pipe: String,
    pub stages: Vec<ArmDef>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct JoinAllNode {
    pub join_all: String,
    pub arms: Vec<ArmDef>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct RouteNode {
    pub route_on_confidence: String,
    pub value: String,
    pub routes: Vec<RouteBranch>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct RouteBranch {
    pub range: String,
    pub label: String,
    pub handler: String,
    #[serde(default)]
    pub args: Option<serde_json::Value>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct SpeculateNode {
    pub speculate: String,
    #[serde(default = "default_speculate_mode")]
    pub mode: SpeculateMode,
    pub arms: Vec<ArmDef>,
}

#[derive(Debug, Clone, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum SpeculateMode {
    #[default]
    PickBest,
    FirstOk,
}

fn default_speculate_mode() -> SpeculateMode {
    SpeculateMode::PickBest
}