Implement Feature

This skill guides you through implementing a new feature in Beluga AI, ensuring compliance with all framework patterns and standards.

Prerequisites

•Understand the feature requirements
•Identify which package(s) will be affected
•Review similar implementations in the codebase

Steps

1. Plan the Implementation

Before writing code:

•Identify affected packages
•Define interfaces needed (following ISP)
•Plan the configuration structure
•List dependencies (following DIP)
•Design error handling approach

2. Create/Update Package Structure

If creating a new package:

bash

mkdir -p pkg/<package_name>/{iface,internal,providers}

Required files:

•pkg/<package_name>/<package_name>.go - Main API
•pkg/<package_name>/config.go - Configuration
•pkg/<package_name>/metrics.go - OTEL metrics
•pkg/<package_name>/errors.go - Error definitions
•pkg/<package_name>/test_utils.go - Test helpers
•pkg/<package_name>/README.md - Documentation

3. Define Interfaces

In iface/interfaces.go:

package iface

import "context"

// Use -er suffix for single-method interfaces
type Processor interface {
    Process(ctx context.Context, input Input) (Output, error)
}

// Use descriptive nouns for multi-method interfaces
type DataStore interface {
    Get(ctx context.Context, key string) ([]byte, error)
    Set(ctx context.Context, key string, value []byte) error
    Delete(ctx context.Context, key string) error
}

4. Implement Configuration

In config.go:

package mypackage

import "github.com/go-playground/validator/v10"

type Config struct {
    Timeout    time.Duration `mapstructure:"timeout" yaml:"timeout" validate:"required,min=1s"`
    MaxRetries int           `mapstructure:"max_retries" yaml:"max_retries" validate:"gte=0,lte=10"`
}

func (c *Config) Validate() error {
    return validator.New().Struct(c)
}

// Functional options
type Option func(*Component)

func WithTimeout(t time.Duration) Option {
    return func(c *Component) { c.timeout = t }
}

5. Implement OTEL Metrics

In metrics.go:

package mypackage

import (
    "go.opentelemetry.io/otel/metric"
    "go.opentelemetry.io/otel/trace"
)

type Metrics struct {
    operationsTotal   metric.Int64Counter
    operationDuration metric.Float64Histogram
    errorsTotal       metric.Int64Counter
    tracer            trace.Tracer
}

func NewMetrics(meter metric.Meter, tracer trace.Tracer) (*Metrics, error) {
    ops, err := meter.Int64Counter("mypackage_operations_total")
    if err != nil {
        return nil, err
    }
    dur, err := meter.Float64Histogram("mypackage_operation_duration_seconds")
    if err != nil {
        return nil, err
    }
    errs, err := meter.Int64Counter("mypackage_errors_total")
    if err != nil {
        return nil, err
    }
    return &Metrics{
        operationsTotal:   ops,
        operationDuration: dur,
        errorsTotal:       errs,
        tracer:            tracer,
    }, nil
}

6. Implement Error Handling

In errors.go:

package mypackage

type ErrorCode string

const (
    ErrCodeInvalidInput ErrorCode = "INVALID_INPUT"
    ErrCodeTimeout      ErrorCode = "TIMEOUT"
    ErrCodeRateLimit    ErrorCode = "RATE_LIMIT"
)

type Error struct {
    Op   string    // Operation that failed
    Err  error     // Underlying error
    Code ErrorCode // Classification
}

func (e *Error) Error() string {
    return fmt.Sprintf("%s: %s: %v", e.Op, e.Code, e.Err)
}

func (e *Error) Unwrap() error {
    return e.Err
}

7. Implement Core Logic

In <package_name>.go:

package mypackage

func NewComponent(opts ...Option) *Component {
    c := &Component{
        // defaults
    }
    for _, opt := range opts {
        opt(c)
    }
    return c
}

func (c *Component) Process(ctx context.Context, input Input) (Output, error) {
    ctx, span := c.metrics.tracer.Start(ctx, "component.process")
    defer span.End()

    start := time.Now()
    defer func() {
        c.metrics.operationDuration.Record(ctx, time.Since(start).Seconds())
    }()

    c.metrics.operationsTotal.Add(ctx, 1)

    // Implementation...

    if err != nil {
        c.metrics.errorsTotal.Add(ctx, 1)
        span.RecordError(err)
        return Output{}, &Error{Op: "Process", Err: err, Code: ErrCodeInvalidInput}
    }

    return output, nil
}

8. Write Tests

Create comprehensive tests following test standards:

•Table-driven tests
•Concurrency tests
•Error scenario tests
•OTEL validation tests

9. Run Quality Checks

bash

make fmt
make lint
make test-unit
make security

10. Update Documentation

•Update package README.md
•Add examples if appropriate
•Update main documentation if needed

Validation Checklist

• Interfaces follow ISP (small, focused)
• Configuration has validation tags
• OTEL metrics implemented
• Error handling uses Op/Err/Code pattern
• All public methods have tracing
• Tests cover happy path, errors, edge cases
• make lint passes
• make test-unit passes

Output

A complete feature implementation with:

•Clean interfaces
•Configuration with validation
•OTEL observability
•Comprehensive tests
•Documentation