How to Add a New LLM Provider to aisuite: Provider Naming Convention Guide

To add a new LLM provider to aisuite, create a Python module named <provider>_provider.py in aisuite/providers/ and define a class named <Provider>Provider that inherits from BaseProvider, implementing at minimum the _chat method.

Adding support for a new large language model to the aisuite framework requires following a strict naming convention that enables automatic discovery and dynamic loading. The andrewyng/aisuite repository dynamically instantiates provider clients by parsing model strings like "provider:model-name" and mapping the prefix to specific files and classes. By adhering to these conventions, you can integrate any LLM API with minimal boilerplate while maintaining full compatibility with aisuite's unified chat completion interface.

Understanding the Provider Naming Convention

aisuite discovers providers through a deterministic mapping between model string prefixes and Python modules. When the Client receives a request for "myprovider:gpt-4", it extracts the prefix myprovider and attempts to load a corresponding implementation using two strict rules.

File Naming Requirements

The provider implementation must reside in the aisuite/providers/ directory as a Python module named using all lowercase letters with underscores separating words:

<provider>_provider.py

For reference, the OpenAI implementation follows this pattern exactly in aisuite/providers/openai_provider.py. The file name prefix (openai) must match the provider key used in model strings, converted to lowercase with underscores replacing any spaces or hyphens.

Class Naming Requirements

Inside the module, define exactly one provider class using PascalCase where the provider name is capitalized and suffixed with Provider:

<Provider>Provider

The class name must correspond to the file name converted to title case. For example, openai_provider.py contains class OpenaiProvider, while anthropic_provider.py contains class AnthropicProvider. This class must inherit from BaseProvider (located in aisuite/providers/base.py) and implement the required interface methods.

Step-by-Step Implementation Guide

Step 1: Create the Provider Module

Create a new file in aisuite/providers/ following the naming convention. For a provider named "MyProvider", create:

# aisuite/providers/myprovider_provider.py

Step 2: Implement the Provider Class

Define the class inheriting from BaseProvider and implement the required constructor and _chat method. The _chat method must accept model, messages, and optional keyword arguments, returning a dictionary matching the OpenAI chat completion response format.

# aisuite/providers/myprovider_provider.py

from aisuite.providers.base import BaseProvider

class MyproviderProvider(BaseProvider):
    """Implementation for MyProvider's API."""
    
    def __init__(self, api_key: str, **kwargs):
        super().__init__(api_key=api_key, **kwargs)
        # Initialize the provider's SDK client here

        self.client = MyProviderSDK(api_key=api_key)
    
    def _chat(self, *, model: str, messages: list, **kwargs):
        """
        Translate aisuite's chat schema to the provider's request format,
        execute the API call, and return an OpenAI-compatible response dict.
        """
        # Convert messages to provider-specific format

        response = self.client.chat.completions.create(
            model=model,
            messages=messages,
            **kwargs
        )
        return response.to_dict()
    
    def _embedding(self, *, model: str, input: str, **kwargs):
        """
        Optional: Implement embeddings if the provider supports them.
        Required only if you want to support embedding operations.
        """
        pass

Step 3: Configure Optional Dependencies

Register the provider's SDK as an optional dependency in pyproject.toml to allow users to install it with pip install 'aisuite[myprovider]':

[project.optional-dependencies]
myprovider = ["myprovider-sdk>=1.0"]

Step 4: Test Your Implementation

Create a test file following the pattern tests/providers/test_<provider>_provider.py to validate that your provider correctly implements the aisuite contract, handles authentication, and returns properly formatted responses.

Complete Working Example

Here is a minimal but complete implementation skeleton for a hypothetical provider:

# aisuite/providers/example_provider.py

from aisuite.providers.base import BaseProvider

class ExampleProvider(BaseProvider):
    """Provider implementation for ExampleAI's chat API."""
    
    def __init__(self, api_key: str, base_url: str = None, **kwargs):
        super().__init__(api_key=api_key, **kwargs)
        self.api_key = api_key
        self.base_url = base_url or "https://api.example.com/v1"
    
    def _chat(self, *, model: str, messages: list, temperature: float = 0.7, **kwargs):
        """Execute chat completion request."""
        import requests
        
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        payload = {
            "model": model,
            "messages": messages,
            "temperature": temperature,
            **kwargs
        }
        
        response = requests.post(
            f"{self.base_url}/chat/completions",
            headers=headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()

Using Your New Provider

Once implemented, users can immediately use your provider by referencing it in the model string with the format "provider:model-name":

import aisuite as ai

client = ai.Client()

# The prefix 'myprovider' matches the file myprovider_provider.py

response = client.chat.completions.create(
    model="myprovider:awesome-model",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum entanglement."},
    ],
    temperature=0.7,
)

print(response.choices[0].message.content)

The Client automatically extracts the myprovider prefix, imports MyproviderProvider from aisuite/providers/myprovider_provider.py, instantiates it with the configured API key, and routes the request to the _chat method.

Summary

• File naming: Create <provider>_provider.py in aisuite/providers/ using lowercase and underscores
• Class naming: Define <Provider>Provider using PascalCase that matches the file name
• Inheritance: Extend BaseProvider from aisuite.providers.base to ensure interface compatibility
• Required methods: Implement __init__ for initialization and _chat for chat completions; optionally implement _embedding
• Dependencies: Add SDK requirements to [project.optional-dependencies] in pyproject.toml for optional installation
• Testing: Create test files in tests/providers/ following the test_<provider>_provider.py pattern

Frequently Asked Questions

What is the exact file naming convention for aisuite providers?

You must name the file <provider>_provider.py using all lowercase letters with underscores separating words, placed in the aisuite/providers/ directory. For example, a provider for "Azure OpenAI" would be azure_openai_provider.py.

Do I need to implement both _chat and _embedding methods?

You must implement _chat to support chat completions, which is the core functionality of aisuite. The _embedding method is optional and only required if you want your provider to support text embedding operations through aisuite's interface.

How does aisuite discover new providers automatically?

When the Client parses a model string like "provider:model-name", it extracts the prefix before the colon, converts it to the file naming format, and attempts to import a class from aisuite/providers/<provider>_provider.py with the name <Provider>Provider. If both the file and class exist and follow the naming convention exactly, the provider is loaded dynamically without requiring registration in a central registry.

Where should I declare dependencies for my custom provider?

Declare your provider's SDK dependencies as optional extras in pyproject.toml under [project.optional-dependencies]. This allows users to install your provider specifically using pip install "aisuite[yourprovider]" while keeping the base aisuite installation lightweight for users who do not need that particular provider.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}