# Provider Implementation

> Implementing providers for Beluga AI v2 registries. Use when creating LLM, embedding, vectorstore, voice, or any other provider. Use when this capability is needed.

- Skill: `tomevault-io/provider-implementation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/provider-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/provider-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/provider-implementation

---


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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lookatitude) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->