home / skills / lookatitude / beluga-ai / provider-implementation

provider-implementation skill

safe

This skill helps you implement providers for Beluga AI v2 registries across LLM, embedding, vectorstore, voice, and more.

npx playbooks add skill lookatitude/beluga-ai --skill provider-implementation

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

Files (1)

SKILL.md

1.8 KB

---
name: provider-implementation
description: Implementing providers for Beluga AI v2 registries. Use when creating LLM, embedding, vectorstore, voice, or any other provider.
---

# Provider Implementation

## Checklist

1. Implement the full interface (ChatModel, Embedder, VectorStore, STT, TTS, etc.).
2. Register via `init()` with parent package's `Register()`.
3. Map provider errors to `core.Error` with correct ErrorCode.
4. Support context cancellation.
5. Include token/usage metrics where applicable.
6. Compile-time check: `var _ Interface = (*Impl)(nil)`.
7. Unit tests with mocked HTTP responses (httptest).

## File Structure

```
llm/providers/openai/
├── openai.go          # Implementation + New() + init()
├── stream.go          # Streaming
├── errors.go          # Error mapping
├── openai_test.go     # Tests
└── testdata/          # Recorded HTTP responses
```

## Template

```go
var _ llm.ChatModel = (*Model)(nil)

func init() {
    llm.Register("openai", func(cfg llm.ProviderConfig) (llm.ChatModel, error) { return New(cfg) })
}

func New(cfg llm.ProviderConfig) (*Model, error) {
    if cfg.APIKey == "" { return nil, &core.Error{Op: "openai.new", Code: core.ErrAuth, Message: "API key required"} }
    return &Model{client: newClient(cfg.APIKey, cfg.BaseURL), model: cfg.Model}, nil
}

func (m *Model) Stream(ctx context.Context, msgs []schema.Message, opts ...llm.GenerateOption) iter.Seq2[schema.StreamChunk, error] {
    return func(yield func(schema.StreamChunk, error) bool) { /* stream implementation */ }
}
```

## Error Mapping

```go
switch apiErr.StatusCode {
case 401: code = core.ErrAuth
case 429: code = core.ErrRateLimit
case 408, 504: code = core.ErrTimeout
case 400: code = core.ErrInvalidInput
}
```

See `docs/providers.md` for provider categories and priorities.

Overview

This skill guides implementing providers for Beluga AI v2 registries. It explains required interfaces, registration, error mapping, tests, and practical file layout so new providers integrate reliably with the runtime. The guidance is concise and focused on outcomes: correctness, observability, and graceful cancellation.

How this skill works

The skill inspects the provider implementation checklist and a minimal Go template to ensure each provider implements the full interface (ChatModel, Embedder, VectorStore, STT, TTS, etc.). It enforces registration via init(), maps external API errors to core.Error with proper ErrorCode, supports context cancellation, and recommends usage metrics and compile-time interface checks. It also outlines test strategy using httptest and recorded responses.

When to use it

When adding a new LLM, embedding, vectorstore, STT, or TTS provider to Beluga v2.
When you need a reliable pattern for mapping upstream API errors to core.Error codes.
When you want compile-time safety that your implementation satisfies the provider interface.
When preparing provider unit tests with mocked HTTP responses and replay data.
When you need to add streaming support and usage metrics for billing/monitoring.

Best practices

Always include a compile-time interface assertion: var _ Interface = (*Impl)(nil).
Register providers in init() using the parent package Register(name, factory) pattern.
Map HTTP/status errors to core.Error with correct ErrorCode (auth, rate limit, timeout, invalid input).
Honor context cancellation on all network or blocking operations to avoid leaks and improve responsiveness.
Record token/usage metrics where applicable and surface them via provider telemetry.
Write unit tests using httptest and store recorded responses in testdata for deterministic CI.

Example use cases

Implementing an OpenAI-compatible ChatModel and exposing Stream() for real-time tokens.
Adding a custom embedding provider that satisfies the Embedder interface and reports usage metrics.
Building a vectorstore provider that integrates with an external DB and implements the VectorStore interface with context-aware operations.
Creating STT/TTS providers that map provider-specific errors to core.Error and support cancellation mid-stream.
Writing unit tests that replay recorded API responses from testdata for offline CI validation.

FAQ

What compile-time checks should I add?

Include a var _ Interface = (*Impl)(nil) assertion for every interface your provider implements to catch mismatches at compile time.

How do I map external HTTP errors to core.Error codes?

Translate status codes to core.ErrAuth for 401, core.ErrRateLimit for 429, core.ErrTimeout for 408/504, and core.ErrInvalidInput for 400; include the original op and message for debugging.