> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Registry

> Register and use custom LLM providers in PraisonAI TypeScript SDK

# 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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { getDefaultRegistry } from 'praisonai';

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

### createProviderRegistry

Create an isolated registry instance for multi-agent safety.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { listProviders } from 'praisonai';

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

### hasProvider

Check if a provider is registered.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { hasProvider } from 'praisonai';

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

### unregisterProvider

Remove a provider from the registry.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { unregisterProvider } from 'praisonai';

unregisterProvider('custom-provider');
```

## Built-in Providers

The following providers are registered by default:

| Provider    | Aliases  | Environment Variable |
| ----------- | -------- | -------------------- |
| `openai`    | `oai`    | `OPENAI_API_KEY`     |
| `anthropic` | `claude` | `ANTHROPIC_API_KEY`  |
| `google`    | `gemini` | `GOOGLE_API_KEY`     |

## Creating a Custom Provider

Extend `BaseProvider` to create a custom provider:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import type {
  ProviderConstructor,
  ProviderLoader,
  RegisterOptions,
  IProviderRegistry,
  ProviderInput,
  CreateProviderOptions
} from 'praisonai';
```