intellicrack.providers.registry

Provider registry for managing LLM providers.

This module provides a centralized registry for registering, connecting, and managing all LLM provider instances.

class CredentialLoaderProtocol[source]

Bases: Protocol

Protocol for objects that can load provider credentials.

Any object exposing get_credentials(str) -> ProviderCredentials | None is acceptable.

get_credentials(provider)[source]

Return credentials for the given provider, or None when unavailable.

Parameters:: provider (str) – The provider to load credentials for.
Returns:: Loaded credentials or None when unavailable.
Return type:: ProviderCredentials | None

__init__(*args, **kwargs)

class ProviderRegistry[source]

Bases: object

Registry for all LLM providers.

Manages provider instances, connections, and provides a unified interface for accessing any configured LLM provider.

__init__(credential_loader=None)[source]

Initialize the ProviderRegistry with an optional credential loader.

Parameters:: credential_loader (CredentialLoaderProtocol | None) – Optional credential loader for auto-connecting providers.
Return type:: None

register(provider)[source]

Register a provider instance.

The provider’s concrete class is also recorded so the registry can act as a name-to-class factory through connect_provider().

Parameters:: provider (LLMProviderBase) – The provider instance to register.
Return type:: None

Note

If a provider with the same name is already registered, it will be replaced with a warning logged.

register_class(name, provider_class)[source]

Register a provider class without instantiating it.

Useful when callers want connect_provider() to construct the provider on demand from credentials provided by the configured CredentialLoaderProtocol.

Parameters:

name (str) – The provider instance id to associate with the class.
provider_class (type[LLMProviderBase]) – Concrete provider class to register.

Return type:

None

unregister(name)[source]

Unregister a provider.

Parameters:: name (str) – The provider name to unregister.
Returns:: True if provider was removed, False if not found.
Return type:: bool

get(name)[source]

Get a registered provider by name.

Parameters:: name (str) – The provider name.
Returns:: The provider instance or None if not registered.
Return type:: LLMProviderBase | None

get_or_raise(name)[source]

Get a registered provider by name, raising if not found.

Parameters:: name (str) – The provider name.
Returns:: The provider instance.
Return type:: LLMProviderBase
Raises:: ProviderError – If provider is not registered.

list_registered()[source]

List all registered providers.

Returns:: List of registered provider names.
Return type:: list[str]

list_connected()[source]

List all connected providers.

Returns:: List of connected provider names.
Return type:: list[str]

async connect_provider(name, credentials=None)[source]

Connect a specific provider.

When credentials is None and a credential loader was supplied at construction time, this method calls loader.get_credentials(name) to fetch credentials before connecting the provider. If no instance exists yet but a class was registered via register_class(), the class is instantiated and registered before connecting.

Parameters:

name (str) – The provider to connect.
credentials (ProviderCredentials | None) – Credentials to use. If None, attempts to load from credential loader.

Returns:

True on successful connection. The current implementation re-raises every failure for the caller, so callers can rely on True meaning “connected”.

Return type:

bool

Raises:

ProviderError – If provider not registered or no credentials are available, or the provider raises ProviderError during connect.
AuthenticationError – If provider authentication fails.
ConfigurationError – If a configuration problem prevents connection.
ConnectionError – If network connection fails.
TimeoutError – If connection times out.
OSError – If an OS-level I/O error occurs.
RuntimeError – If the provider encounters a runtime failure.
ValueError – If an invalid value is encountered during connection.

async disconnect_provider(name)[source]

Disconnect a specific provider.

Clears _active_provider if it pointed at the disconnected provider.

Parameters:: name (str) – The provider to disconnect.
Return type:: None

async disconnect_all()[source]

Disconnect from all providers, aggregating any failures.

Each provider’s disconnect() is wrapped in an isolated try/except. After every provider has been processed, any collected errors are re-raised as a single ProviderError whose details["errors"] field carries a list of per-provider failures.

Raises:: ProviderError – If one or more providers failed to disconnect.
Return type:: None

set_active(name)[source]

Set the active provider.

Parameters:: name (str) – The provider to make active.
Raises:: ProviderError – If provider not registered or not connected.
Return type:: None

property active: LLMProviderBase | None

The currently active provider.

Returns:: The active provider instance or None if none set.
Return type:: LLMProviderBase | None

property active_name: str | None

The name of the currently active provider.

Returns:: The active provider name or None if none set.
Return type:: str | None

get_active_provider()[source]

Return the currently active provider, if any.

Returns:: The active provider instance or None if none set.
Return type:: LLMProviderBase | None

has_connected_provider()[source]

Check if any provider is connected.

Returns:: True if at least one provider is connected.
Return type:: bool

get_provider_registry(credential_loader=None)[source]

Get the global provider registry instance.

Uses double-checked locking to ensure thread-safe lazy initialization of the singleton instance. The first check avoids lock acquisition overhead on the common path after initialization, while the inner check under the lock guarantees that only one instance is ever created even under concurrent access.

The optional credential_loader is used only on first construction; once the singleton exists, subsequent calls return the existing instance and the argument is ignored. Use reset_provider_registry() from tests to rebuild the singleton with a different loader.

Parameters:: credential_loader (CredentialLoaderProtocol | None) – Optional credential loader to inject on first construction.
Returns:: The singleton ProviderRegistry instance.
Return type:: ProviderRegistry

reset_provider_registry()[source]

Reset the global provider registry singleton.

Intended for use by tests that need to rebuild the registry between cases. Production code should not call this.

Return type:: None