Options

Configuration options for synapses.

Usage

Options are passed when creating synapses:

synapse, err := zyn.Binary("question", provider,
    zyn.WithRetry(3),
    zyn.WithTimeout(10*time.Second),
)

Reliability Options

WithRetry

func WithRetry(maxAttempts int) Option

Retry failed calls up to maxAttempts times.

zyn.WithRetry(3)  // Try up to 3 times

WithBackoff

func WithBackoff(maxAttempts int, initialDelay time.Duration) Option

Retry with exponential backoff. Delays double after each failure.

zyn.WithBackoff(3, 100*time.Millisecond)
// Delays: 100ms, 200ms, 400ms

WithTimeout

func WithTimeout(duration time.Duration) Option

Set maximum execution time for the entire call (including retries).

zyn.WithTimeout(10 * time.Second)

WithCircuitBreaker

func WithCircuitBreaker(threshold int, recoveryTime time.Duration) Option

Open circuit after threshold consecutive failures. Attempt recovery after recoveryTime.

zyn.WithCircuitBreaker(5, 30*time.Second)
// Opens after 5 failures, tries again after 30s

States:

• Closed - Normal operation
• Open - Fails immediately without calling provider
• Half-Open - After recovery time, allows one test request

WithRateLimit

func WithRateLimit(rps float64, burst int) Option

Limit request rate with token bucket algorithm.

zyn.WithRateLimit(10.0, 100)
// 10 requests/second sustained, burst up to 100

WithFallback

func WithFallback(fallbackSynapse Synapse) Option

Use fallback synapse when primary fails.

backup, _ := zyn.Binary("question", backupProvider)
primary, _ := zyn.Binary("question", primaryProvider,
    zyn.WithFallback(backup),
)

WithErrorHandler

func WithErrorHandler(handler pipz.Chainable[*pipz.Error[*SynapseRequest]]) Option

Custom error handling pipeline.

// Define identity for the error handler
var logErrorsID = pipz.NewIdentity("log-errors", "Logs errors")

handler := pipz.Apply(logErrorsID,
    func(ctx context.Context, e *pipz.Error[*zyn.SynapseRequest]) (*pipz.Error[*zyn.SynapseRequest], error) {
        log.Printf("Error: %v", e.Err)
        return e, nil
    },
)

synapse, _ := zyn.Binary("q", provider, zyn.WithErrorHandler(handler))

Temperature

Temperature is set per-input on each synapse's input struct, not as a construction option.

// Set temperature via input struct
input := zyn.BinaryInput{
    Subject:     "test@example.com",
    Temperature: 0.1,
}
result, err := synapse.FireWithInput(ctx, session, input)

Constants:

// Special values
zyn.TemperatureUnset float32 = -1    // Use synapse default
zyn.TemperatureZero  float32 = 0.0001 // Near-zero (0.0 treated as unset)

// Default temperatures by task type
zyn.DefaultTemperatureDeterministic float32 = 0.1 // Binary, Extraction, Convert
zyn.DefaultTemperatureAnalytical    float32 = 0.2 // Sentiment, Ranking, Analyze
zyn.DefaultTemperatureCreative      float32 = 0.3 // Classification, Transform

Note: A zero-value float32 (0.0) is treated as unset for ergonomic struct initialization. Use TemperatureZero for explicit near-zero temperature.

Combining Options

Options compose in order. Multiple options of the same type may override or wrap.

synapse, _ := zyn.Classification("classify", categories, provider,
    // Retry with backoff first
    zyn.WithBackoff(3, 100*time.Millisecond),

    // Then timeout bounds total duration
    zyn.WithTimeout(30*time.Second),

    // Circuit breaker protects against outages
    zyn.WithCircuitBreaker(5, 60*time.Second),

    // Rate limit controls throughput
    zyn.WithRateLimit(10, 50),

    // Fallback as last resort
    zyn.WithFallback(backupSynapse),
)

Execution Order

Request
  │
  ▼
RateLimit (wait for token)
  │
  ▼
CircuitBreaker (fail if open)
  │
  ▼
Timeout (start timer)
  │
  ▼
Retry/Backoff (retry loop)
  │
  ▼
Provider (actual LLM call)
  │
  ▼
ErrorHandler (on failure)
  │
  ▼
Fallback (if configured and failed)

Option Compatibility