home / skills / lookatitude / beluga-ai / go-framework

go-framework skill

safe

This skill helps design Go framework architecture by applying registry, lifecycle, and middleware patterns to packages and providers.

npx playbooks add skill lookatitude/beluga-ai --skill go-framework

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
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

```go
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

```go
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

```go
func init() {
    llm.Register("openai", func(cfg llm.ProviderConfig) (llm.ChatModel, error) { return New(cfg) })
}
// Users import: import _ "github.com/lookatitude/beluga-ai/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.

Overview

This skill captures recommended Go framework design patterns tailored for Beluga AI v2. It provides concise conventions for package layout, provider registries, lifecycle hooks, middleware, and functional options. Use it to standardize new packages, implementations, and integrations within the Beluga ecosystem.

How this skill works

The skill defines a canonical package structure with clear file responsibilities: interface contracts, registry/factory, lifecycle hooks, middleware, and built-in providers. It prescribes a thread-safe registry + factory pattern, functional options for configuration, provider registration via init hooks, and a consistent lifecycle and error-handling contract. These patterns are lightweight and composable so you can plug implementations into common registries and lifecycle managers.

When to use it

Designing a new Beluga package that will have multiple provider implementations
Creating a registry or plugin system that needs thread-safe lookup and factory creation
Defining lifecycle-aware components that must start, stop, and report health in order
Implementing middleware that should be applied consistently across implementations
Standardizing configuration using functional options for clear defaults and overrides

Best practices

Follow the recommended package layout: interface, registry, hooks, middleware, providers
Use a sync.RWMutex protected map for registries and expose Register, New, and List
Prefer functional options for optional settings and sensible defaults
Register built-in providers in init() so users can import side-effect packages
Enforce compile-time interface adherence with var _ Interface = (*Impl)(nil)
Make context.Context the first function parameter and return (T, error) for ops

Example use cases

Implementing a new LLM provider and registering it under a name for dynamic selection
Building a lifecycle manager that starts components in order and shuts them down in reverse
Creating middleware chains for request/response processing across providers
Providing a factory-based client constructor that accepts functional options for timeout and retries
Listing available implementations to populate configuration UIs or validation logic

FAQ

How should I register a provider so users can enable it with a config name?

Register the provider in an init() function using Register(name, factory). Users enable it by referencing the name and importing the package for its side effects.

What lifecycle methods are expected?

Implement Start(ctx), Stop(ctx), and Health(). Start components in defined order and call Stop in reverse to ensure clean shutdown.