Skip to main content

Provider Registry

The Provider Registry allows you to register custom LLM providers that can be used with createProvider(). This enables integration with any LLM provider beyond the built-in OpenAI, Anthropic, and Google providers.

Quick Start

import { registerProvider, createProvider, BaseProvider } from 'praisonai';

// Define a custom provider
class CloudflareProvider extends BaseProvider {
  readonly providerId = 'cloudflare';

  async generateText(options) {
    // Your implementation
  }

  async streamText(options) {
    // Your implementation
  }

  async generateObject(options) {
    // Your implementation
  }

  formatTools(tools) {
    // Your implementation
  }

  formatMessages(messages) {
    // Your implementation
  }
}

// Register the provider
registerProvider('cloudflare', CloudflareProvider);

// Use it like any built-in provider
const provider = createProvider('cloudflare/workers-ai-model');

API Reference

registerProvider

Register a custom provider to the global registry.
import { registerProvider } from 'praisonai';

registerProvider(name: string, provider: ProviderConstructor | ProviderLoader, options?: RegisterOptions);
Parameters:
  • name - Provider name (e.g., ‘cloudflare’, ‘ollama’)
  • provider - Provider class or factory function
  • options - Optional configuration
    • override - Allow overwriting existing registration (default: false)
    • aliases - Additional names that resolve to this provider
Example with aliases:
registerProvider('cloudflare', CloudflareProvider, {
  aliases: ['cf', 'workers-ai']
});

// All of these now work:
createProvider('cloudflare/model');
createProvider('cf/model');
createProvider('workers-ai/model');

createProvider

Create a provider instance from various input types.
import { createProvider } from 'praisonai';

// String format: "provider/model"
const provider = createProvider('openai/gpt-4o');

// String format with default provider detection
const provider = createProvider('gpt-4o-mini'); // Defaults to OpenAI

// Provider instance (pass-through)
const provider = createProvider(existingProvider);

// Spec object
const provider = createProvider({
  name: 'openai',
  modelId: 'gpt-4o',
  config: { timeout: 5000 }
});

getDefaultRegistry

Get the global provider registry instance.
import { getDefaultRegistry } from 'praisonai';

const registry = getDefaultRegistry();
console.log(registry.list()); // ['openai', 'anthropic', 'google']

createProviderRegistry

Create an isolated registry instance for multi-agent safety.
import { createProviderRegistry, registerBuiltinProviders } from 'praisonai';

const isolatedRegistry = createProviderRegistry();
registerBuiltinProviders(isolatedRegistry);

// Register custom providers only to this registry
isolatedRegistry.register('custom', CustomProvider);

// Use with createProvider
const provider = createProvider('custom/model', { registry: isolatedRegistry });

listProviders

List all registered provider names.
import { listProviders } from 'praisonai';

console.log(listProviders()); // ['openai', 'anthropic', 'google']

hasProvider

Check if a provider is registered.
import { hasProvider } from 'praisonai';

console.log(hasProvider('openai')); // true
console.log(hasProvider('cloudflare')); // false (until registered)

unregisterProvider

Remove a provider from the registry.
import { unregisterProvider } from 'praisonai';

unregisterProvider('custom-provider');

Built-in Providers

The following providers are registered by default:
ProviderAliasesEnvironment Variable
openaioaiOPENAI_API_KEY
anthropicclaudeANTHROPIC_API_KEY
googlegeminiGOOGLE_API_KEY

Creating a Custom Provider

Extend BaseProvider to create a custom provider:
import { BaseProvider, ProviderConfig, GenerateTextOptions, GenerateTextResult } from 'praisonai';

class OllamaProvider extends BaseProvider {
  readonly providerId = 'ollama';
  private baseUrl: string;

  constructor(modelId: string, config?: ProviderConfig) {
    super(modelId, config);
    this.baseUrl = config?.baseUrl || 'http://localhost:11434';
  }

  async generateText(options: GenerateTextOptions): Promise<GenerateTextResult> {
    const response = await fetch(`${this.baseUrl}/api/generate`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model: this.modelId,
        prompt: options.messages.map(m => m.content).join('\n'),
        stream: false
      })
    });

    const data = await response.json();
    return {
      text: data.response,
      usage: {
        promptTokens: 0,
        completionTokens: 0,
        totalTokens: 0
      }
    };
  }

  async *streamText(options: StreamTextOptions): AsyncGenerator<StreamChunk> {
    // Streaming implementation
  }

  async generateObject<T>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<T>> {
    // Object generation implementation
  }

  formatTools(tools: ToolDefinition[]): any[] {
    return tools;
  }

  formatMessages(messages: Message[]): any[] {
    return messages;
  }
}

// Register and use
registerProvider('ollama', OllamaProvider);
const provider = createProvider('ollama/llama2');

Lazy Loading

Providers can be registered with lazy loading for better startup performance:
registerProvider('heavy-provider', () => {
  // This code only runs when the provider is first used
  const { HeavyProvider } = require('./heavy-provider');
  return HeavyProvider;
});

Multi-Agent Safety

Use isolated registries when running multiple agents that need different provider configurations:
import { createProviderRegistry, registerBuiltinProviders, createProvider } from 'praisonai';

// Agent 1's registry
const agent1Registry = createProviderRegistry();
registerBuiltinProviders(agent1Registry);
agent1Registry.register('custom', Agent1CustomProvider);

// Agent 2's registry
const agent2Registry = createProviderRegistry();
registerBuiltinProviders(agent2Registry);
agent2Registry.register('custom', Agent2CustomProvider);

// Each agent uses its own provider
const agent1Provider = createProvider('custom/model', { registry: agent1Registry });
const agent2Provider = createProvider('custom/model', { registry: agent2Registry });

Error Handling

The registry provides clear error messages:
try {
  createProvider('unknown-provider/model');
} catch (error) {
  // Error: Unknown provider: 'unknown-provider'. 
  // Available providers: openai, anthropic, google.
  // Register a custom provider with registerProvider('unknown-provider', YourProviderClass).
}

TypeScript Types

import type {
  ProviderConstructor,
  ProviderLoader,
  RegisterOptions,
  IProviderRegistry,
  ProviderInput,
  CreateProviderOptions
} from 'praisonai';