Cheatsheet

Quick reference for zyn.

Synapse Types

Quick Start Patterns

Binary Decision

synapse, _ := zyn.Binary("Is this valid?", provider)
session := zyn.NewSession()
result, _ := synapse.Fire(ctx, session, "input")
// result: bool

Classification

synapse, _ := zyn.Classification("Classify type", []string{"a", "b", "c"}, provider)
session := zyn.NewSession()
result, _ := synapse.Fire(ctx, session, "input")
// result: string (one of categories)

Extraction

type Data struct {
    Field string `json:"field"`
}
func (d Data) Validate() error { return nil }

synapse, _ := zyn.Extract[Data]("Extract data", provider)
session := zyn.NewSession()
result, _ := synapse.Fire(ctx, session, "input")
// result: Data

Transform

synapse, _ := zyn.Transform("Translate to Spanish", provider)
session := zyn.NewSession()
result, _ := synapse.Fire(ctx, session, "Hello")
// result: string

Options

// Reliability
zyn.WithRetry(3)                              // Retry up to 3 times
zyn.WithBackoff(3, 100*time.Millisecond)      // Exponential backoff
zyn.WithTimeout(10*time.Second)               // Timeout
zyn.WithCircuitBreaker(5, 30*time.Second)     // Circuit breaker
zyn.WithRateLimit(10, 100)                    // Rate limiting
zyn.WithFallback(backupSynapse)               // Fallback synapse

// Behavior
zyn.WithErrorHandler(errorPipeline)           // Custom error handling

Temperature Constants

// Set via input struct, not synapse option
zyn.DefaultTemperatureDeterministic = 0.1  // Binary, Extract, Convert
zyn.DefaultTemperatureAnalytical    = 0.2  // Sentiment, Ranking, Analyze
zyn.DefaultTemperatureCreative      = 0.3  // Classification, Transform
zyn.TemperatureUnset                = -1   // Use synapse default
zyn.TemperatureZero                 = 0.0001 // Near-zero (0.0 = unset)

Session Operations

session := zyn.NewSession()

// Read
messages := session.Messages()    // []Message
count := session.Len()            // int
msg, _ := session.At(0)           // Message at index
usage := session.LastUsage()      // *TokenUsage

// Write
session.Append(role, content)     // Add message
session.Clear()                   // Remove all
session.Remove(index)             // Remove at index
session.Replace(index, msg)       // Replace at index
session.Insert(index, msg)        // Insert at index

// Bulk
session.Prune(n)                  // Remove last n message pairs (n*2 messages)
session.Truncate(first, last)     // Keep first n and last m
session.SetMessages(msgs)         // Replace all
session.SetUsage(usage)           // Set token usage

Message Types

type Message struct {
    Role    string
    Content string
}

// Roles
zyn.RoleUser
zyn.RoleAssistant
zyn.RoleSystem

Provider Interface

type Provider interface {
    Call(ctx context.Context, messages []Message, temperature float32) (*ProviderResponse, error)
    Name() string
}

type ProviderResponse struct {
    Content string
    Usage   TokenUsage
}

type TokenUsage struct {
    Prompt     int
    Completion int
    Total      int
}

Providers

OpenAI

import "github.com/zoobz-io/zyn/openai"

provider := openai.New(openai.Config{
    APIKey: os.Getenv("OPENAI_API_KEY"),
    Model:  "gpt-4o",  // defaults to "gpt-3.5-turbo"
})

Mock (Testing)

// Fixed response
provider := zyn.NewMockProviderWithResponse(`{"decision": true, ...}`)

// Dynamic
provider := zyn.NewMockProviderWithCallback(func(p string, t float32) (string, error) {
    return `{"decision": true, ...}`, nil
})

// Error
provider := zyn.NewMockProviderWithError("rate limit exceeded")

Validator Interface

type Validator interface {
    Validate() error
}

All custom types used with Extract, Analyze, or Convert must implement this.

Observability Signals

zyn.RequestStarted         // Before pipeline
zyn.RequestCompleted       // After success
zyn.RequestFailed          // After pipeline failure
zyn.ResponseParseFailed    // After parse/validation error
zyn.ProviderCallStarted    // Before HTTP call
zyn.ProviderCallCompleted  // After HTTP success
zyn.ProviderCallFailed     // After HTTP failure

Hook Keys

// Request fields
zyn.RequestIDKey      // string
zyn.SynapseTypeKey    // string
zyn.InputKey          // string
zyn.OutputKey         // string
zyn.ErrorKey          // string

// Provider fields
zyn.ProviderKey       // string
zyn.ModelKey          // string
zyn.TotalTokensKey    // int
zyn.DurationMsKey     // int
zyn.HTTPStatusCodeKey // int

Decision Tree: Which Synapse?

Need yes/no answer?
├─ Yes → Binary
└─ No
   └─ Pick from fixed options?
      ├─ Yes → Classification
      └─ No
         └─ Order items?
            ├─ Yes → Ranking
            └─ No
               └─ Analyze sentiment?
                  ├─ Yes → Sentiment
                  └─ No
                     └─ Extract structured data?
                        ├─ Yes → Extract[T]
                        └─ No
                           └─ Transform text?
                              ├─ Yes → Transform
                              └─ No
                                 └─ Analyze struct → text?
                                    ├─ Yes → Analyze[T]
                                    └─ No → Convert[T,U]

Common Patterns

Synapse with Reliability

synapse, _ := zyn.Binary("question", provider,
    zyn.WithRetry(3),
    zyn.WithTimeout(10*time.Second),
    zyn.WithCircuitBreaker(5, 30*time.Second),
)

Multi-Step Workflow

session := zyn.NewSession()
step1.Fire(ctx, session, input)
step2.Fire(ctx, session, "continue")  // sees step1 context
step3.Fire(ctx, session, "finish")    // sees all context

Track Token Usage

capitan.Hook(zyn.ProviderCallCompleted, func(ctx context.Context, e *capitan.Event) {
    tokens, _ := zyn.TotalTokensKey.From(e)
    log.Printf("Used %d tokens", tokens)
})