prodigy 0.4.4

Turn ad-hoc Claude sessions into reproducible development pipelines with parallel AI agents
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

## Basic Retry Configuration

The enhanced retry system (`retry_v2`) provides command-level retry capabilities with sophisticated backoff strategies and error handling. This subsection covers the basic retry configuration options.

> **Note**: This documents the enhanced retry system (`retry_v2::RetryConfig`). For workflow-level retry configuration, see [Workflow-Level vs Command-Level Retry](./workflow-level-vs-command-level-retry.md).

### Where Retry Config is Used

Retry configuration can be applied at the command level in your workflow YAML files. The `retry_config` field is available on individual commands to control how that specific command is retried on failure.

**Source**: `src/cook/retry_v2.rs:14-52` (RetryConfig struct definition)

### Basic Configuration Example

The simplest retry configuration uses just the attempts field:

```yaml
commands:
  - shell: "curl https://api.example.com/data"
    retry_config:
      attempts: 3
```

This configuration will:
- Retry the command up to 3 times on failure
- Use exponential backoff with base 2.0 (default)
- Start with 1 second initial delay (default)
- Cap delays at 30 seconds maximum (default)
- Retry on all error types (default when `retry_on` is empty)

### Complete Basic Configuration

For more control, you can specify all basic retry parameters:

```yaml
commands:
  - shell: "make test"
    retry_config:
      attempts: 5              # Maximum retry attempts (default: 3)
      initial_delay: "2s"      # Initial delay between retries (default: 1s)
      max_delay: "60s"         # Maximum delay cap (default: 30s)
      backoff: exponential     # Backoff strategy (default: exponential)
```

**Field Reference** (from `src/cook/retry_v2.rs:54-68`):
- `attempts: u32` - Maximum number of retry attempts (default: 3)
- `initial_delay: Duration` - Starting delay between retries (default: 1 second)
- `max_delay: Duration` - Maximum delay ceiling (default: 30 seconds)
- `backoff: BackoffStrategy` - Strategy for calculating delays (default: Exponential { base: 2.0 })

### Default Behavior

When `retry_config` is omitted entirely, commands run **without retry**. When `retry_config` is present but fields are omitted, defaults from `RetryConfig::default()` apply:

```rust
// Default values (src/cook/retry_v2.rs:54-68)
RetryConfig {
    attempts: 3,
    backoff: BackoffStrategy::Exponential { base: 2.0 },
    initial_delay: Duration::from_secs(1),
    max_delay: Duration::from_secs(30),
    jitter: false,
    jitter_factor: 0.3,
    retry_on: Vec::new(),  // Empty = retry all errors
    retry_budget: None,
    on_failure: FailureAction::Stop,
}
```

### Relationship to Command Execution

When a command with `retry_config` fails, the `RetryExecutor` orchestrates the retry logic:

1. **Execute Command**: Run the shell/Claude command
2. **Check Result**: If successful, return immediately
3. **Check Retry Budget**: If set, ensure budget not exceeded
4. **Calculate Delay**: Use backoff strategy to determine next delay
5. **Wait**: Sleep for calculated delay (with optional jitter)
6. **Retry**: Execute command again
7. **Repeat**: Continue until success, max attempts reached, or budget exhausted

**Source**: `src/cook/retry_v2.rs:191-262` (RetryExecutor::execute_with_retry)

### Integration with RetryConfig Struct

All YAML retry configuration maps directly to the `RetryConfig` struct fields:

| YAML Field | Rust Field | Type | Default |
|------------|------------|------|---------|
| `attempts` | `attempts` | `u32` | 3 |
| `initial_delay` | `initial_delay` | `Duration` | 1s |
| `max_delay` | `max_delay` | `Duration` | 30s |
| `backoff` | `backoff` | `BackoffStrategy` | Exponential |
| `jitter` | `jitter` | `bool` | false |
| `jitter_factor` | `jitter_factor` | `f64` | 0.3 |
| `retry_on` | `retry_on` | `Vec<ErrorMatcher>` | [] (all) |
| `retry_budget` | `retry_budget` | `Option<Duration>` | None |
| `on_failure` | `on_failure` | `FailureAction` | Stop |

**Source**: `src/cook/retry_v2.rs:14-52`

### Minimal vs Full Configuration

**Minimal** (use defaults for most fields):
```yaml
retry_config:
  attempts: 5
```

**Full** (explicit control over all parameters):
```yaml
retry_config:
  attempts: 10
  backoff: fibonacci
  initial_delay: "500ms"
  max_delay: "2m"
  jitter: true
  jitter_factor: 0.5
  retry_budget: "10m"
  retry_on:
    - network
    - timeout
  on_failure: continue
```