home / skills / lookatitude / beluga-ai / create_provider

create_provider skill

safe

/.agent/skills/create_provider

This skill guides you through adding a new provider (LLM, VectorStore, etc.) to Beluga AI with directory layout, interface implementation, and testing.

npx playbooks add skill lookatitude/beluga-ai --skill create_provider

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

Files (1)

SKILL.md

1.4 KB

---
name: Create New Provider
description: Step-by-step guide to adding a new provider (LLM, VectorStore, etc.) to Beluga AI.
---

# Create New Provider

This skill guides you through adding a new provider implementation to an existing package.

## Prerequisites
-   Ensure the package supports the provider pattern (e.g., `pkg/llms`, `pkg/vectorstores`).
-   Identify the interface to implement (usually in `pkg/<package>/iface` or `pkg/<package>/<package>.go`).

## Steps

1.  **Create Provider Directory**
    -   Create `pkg/<package>/providers/<provider_name>/`.
    -   Create `pkg/<package>/providers/<provider_name>/<provider_name>.go`.

2.  **Implement Interface**
    -   Define a struct `Provider` (or similar) that implements the interface.
    -   Implement the `New(options ...)` factory function.

3.  **Add Configuration**
    -   Define a config struct.
    -   Use `mapstructure` tags for decoding.

4.  **Register Global Factory**
    -   In `pkg/<package>/registry.go` (or `factory.go`), add the init block or manual registration for your new provider.

5.  **Add Testing**
    -   Create `pkg/<package>/providers/<provider_name>/<provider_name>_test.go`.
    -   Use `test_utils` for mocks.

## Example File Structure
```
pkg/llms/providers/anthropic/
├── anthropic.go       # Implementation
├── config.go          # Config struct
└── anthropic_test.go  # Tests
```

Overview

This skill provides a clear, step-by-step guide to add a new provider (LLM, VectorStore, etc.) into Beluga AI packages written in Go. It explains the required files, interface implementation, configuration decoding, factory registration, and testing structure. Follow these steps to integrate a provider that fits the package provider pattern and works with existing factories and tests.

How this skill works

The guide walks you through creating a provider directory and implementing the package interface with a Provider struct and a New(...) factory function. It covers adding a config struct that uses mapstructure tags for decoding and registering the provider factory in the package registry or init block. Finally, it shows how to add unit tests that use existing test utilities and mocks to validate behavior.

When to use it

Adding a new LLM or VectorStore implementation to an existing Beluga package (e.g., pkg/llms or pkg/vectorstores).
When the package follows a provider/factory pattern and exposes a well-defined interface to implement.
When you need pluggable providers that can be selected via configuration at runtime.
When adding CI-tested implementations that should integrate with existing test utilities and mocks.

Best practices

Implement the package interface exactly; prefer code that compiles against the interface rather than relying on implicit behavior.
Keep the provider folder self-contained: implementation, config, and tests in the same directory.
Use mapstructure tags on config fields to ensure consistent decoding from generic config loaders.
Register the factory in the package registry so the provider is discoverable by runtime configuration.
Write unit tests that exercise both config decoding and runtime behavior using the package's test utilities.

Example use cases

Add a new Anthropic LLM provider under pkg/llms/providers/anthropic with anthropic.go, config.go, and anthropic_test.go.
Introduce a new vector store implementation and register its factory so users can switch stores via config.
Create a mock provider for local development that implements the same interface and plugs into the existing registry.
Add a custom provider requiring API keys by defining secure config fields and decoding them via mapstructure.

FAQ

Where should I find the interface to implement?

Look in the package's iface folder or the main package file (e.g., pkg/<package>/iface or pkg/<package>/<package>.go).

How do I make the provider selectable at runtime?

Register the provider factory in the package registry (registry.go or factory.go) so configuration can select it by name.