go-framework

name	go-framework
description	Go framework design patterns for Beluga AI v2. Use when designing package structure, registries, lifecycle, or creating new packages.

Go Framework Patterns

Package Structure

<package>/
├── <interface>.go     # Extension contract
├── registry.go        # Register(), New(), List()
├── hooks.go           # Lifecycle hooks
├── middleware.go       # Middleware type + Apply()
└── providers/          # Built-in implementations

Registry + Factory

var (
    mu       sync.RWMutex
    registry = make(map[string]Factory)
)

func Register(name string, f Factory) {
    mu.Lock()
    defer mu.Unlock()
    registry[name] = f
}

func New(name string, cfg ProviderConfig) (Interface, error) {
    mu.RLock()
    f, ok := registry[name]
    mu.RUnlock()
    if !ok {
        return nil, fmt.Errorf("unknown provider %q (registered: %v)", name, List())
    }
    return f(cfg)
}

func List() []string { /* sorted keys */ }

Functional Options

type Option func(*options)
func WithTimeout(d time.Duration) Option { return func(o *options) { o.timeout = d } }
func New(opts ...Option) *Thing { o := defaults(); for _, opt := range opts { opt(&o) }; return &Thing{opts: o} }

Provider Registration

func init() {
    llm.Register("openai", func(cfg llm.ProviderConfig) (llm.ChatModel, error) { return New(cfg) })
}
// Users import: import _ "github.com/lookatitude/beluga-ai/v2/llm/providers/openai"

Rules

• Compile-time interface check: var _ Interface = (*Impl)(nil)
• Lifecycle: Start(ctx), Stop(ctx), Health() — shutdown in reverse order.
• Error handling: return (T, error), wrap with core.Error, check IsRetryable().
• context.Context is always first parameter.