Go SDK Guide

The ClawPipe Go SDK uses idiomatic Go patterns: context-based cancellation, functional options, and explicit error handling.

Install

go get github.com/finsavvyai/clawpipe-go

Requires Go 1.21+.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    clawpipe "github.com/finsavvyai/clawpipe-go"
)

func main() {
    pipe := clawpipe.New(clawpipe.Config{
        APIKey:    "cp_xxx",
        ProjectID: "my-app",
    })

    ctx := context.Background()
    result, err := pipe.Prompt(ctx, "Explain recursion",
        clawpipe.WithSystem("You are a helpful tutor"),
        clawpipe.WithMaxTokens(2000),
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Text)
    fmt.Printf("Cost: $%.4f\n", result.Meta.EstimatedCostUSD)
}

Configuration

pipe := clawpipe.New(clawpipe.Config{
    APIKey:                   "cp_xxx",
    ProjectID:                "my-app",
    GatewayURL:               "https://api.clawpipe.ai/v1",
    CacheTTL:                 5 * time.Minute,
    EnableBooster:            true,
    EnablePacker:             true,
    EnableCache:              true,
    EnableTrace:              false,
    LocalModelURL:            "",
    EnableLocalFallback:      false,
    BudgetCapUSD:             100.0,
    BudgetWarnUSD:            80.0,
    RateLimitPerDay:          100_000,
    CircuitBreakerThreshold:  5,
    CircuitBreakerRecovery:   30 * time.Second,
    Allowlist: []clawpipe.AllowlistEntry{
        {Provider: "openai"},
        {Provider: "anthropic"},
    },
})

Functional Options

Prompt options use the functional options pattern for clean, extensible calls.

Streaming

ch, err := pipe.Stream(ctx, "Analyze this code",
    clawpipe.WithSystem("You are a code reviewer"),
)
if err != nil {
    log.Fatal(err)
}

for chunk := range ch {
    fmt.Print(chunk)
}

Context Cancellation

All SDK methods accept a context.Context for timeout and cancellation support.

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

result, err := pipe.Prompt(ctx, "Quick question")
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        fmt.Println("Request timed out")
    }
}

Error Handling

import "errors"

result, err := pipe.Prompt(ctx, "Hello")
if err != nil {
    var budgetErr *clawpipe.BudgetExceededError
    var rateErr   *clawpipe.RateLimitError
    var gwErr     *clawpipe.GatewayError

    switch {
    case errors.As(err, &budgetErr):
        fmt.Println("Budget cap reached")
    case errors.As(err, &rateErr):
        fmt.Println("Rate limit exceeded")
    case errors.As(err, &gwErr):
        fmt.Printf("Provider error: %s\n", gwErr)
    default:
        log.Fatal(err)
    }
}

Observability

stats := pipe.Stats()           // TelemetrySnapshot
budget := pipe.BudgetStatus()   // BudgetStatus
rate := pipe.RateLimitStatus()  // RateLimitStatus
circuit := pipe.CircuitStatus() // map[string]CircuitStatus
logs := pipe.AuditLogs()        // []AuditLogEntry