registry

registry

Decorator-based registry for runtime discovery of pluggable components.

Adapted from IPW's src/ipw/core/registry.py. Each typed subclass gets its own isolated storage so registrations in one registry never leak into another.

Classes

RegistryBase

Bases: Generic[T]

Generic registry base class with class-specific entry isolation.

Methods:

register classmethod

register(key: str) -> Callable[[T], T]

Decorator that registers entry under key.

Source code in src/diapason/core/registry.py

@classmethod
def register(cls, key: str) -> Callable[[T], T]:
    """Decorator that registers *entry* under *key*."""

    def decorator(entry: T) -> T:
        entries = cls._entries()
        # Une DÉCLARATION paresseuse n'est pas un enregistrement : le vrai
        # la remplace. Sans quoi importer le module directement — ce que
        # font les tests — se heurterait à la clé qu'il vient lui-même de
        # faire déclarer.
        if key in entries and not isinstance(entries[key], _LazyEntry):
            raise ValueError(f"{cls.__name__} already has an entry for '{key}'")
        entries[key] = entry
        return entry

    return decorator

register_value classmethod

register_value(key: str, value: T) -> T

Imperatively register a value under key.

Source code in src/diapason/core/registry.py

@classmethod
def register_value(cls, key: str, value: T) -> T:
    """Imperatively register a *value* under *key*."""
    entries = cls._entries()
    if key in entries and not isinstance(entries[key], _LazyEntry):
        raise ValueError(f"{cls.__name__} already has an entry for '{key}'")
    entries[key] = value
    return value

register_lazy classmethod

register_lazy(key: str, module: str) -> None

Déclarer key sans charger son module.

Importer un moteur « pour déclencher son enregistrement » fait payer ses dépendances à TOUT LE MONDE, y compris à qui ne s'en servira jamais. MESURÉ : charger colbert_backend ou faiss_backend tirait torch et numpy — puis échouait sur une dépendance absente, et l'échec était avalé. Le coût restait, pas le moteur. Or un numpy cassé fait alors tomber diapason serve au démarrage, pour un moteur que personne n'a demandé.

Le module n'est donc chargé qu'à la première question portant sur cette clé.

Source code in src/diapason/core/registry.py

@classmethod
def register_lazy(cls, key: str, module: str) -> None:
    """Déclarer *key* sans charger son module.

    Importer un moteur « pour déclencher son enregistrement » fait payer
    ses dépendances à TOUT LE MONDE, y compris à qui ne s'en servira
    jamais. MESURÉ : charger ``colbert_backend`` ou ``faiss_backend``
    tirait ``torch`` et ``numpy`` — puis échouait sur une dépendance
    absente, et l'échec était avalé. Le coût restait, pas le moteur. Or un
    ``numpy`` cassé fait alors tomber ``diapason serve`` au démarrage, pour
    un moteur que personne n'a demandé.

    Le module n'est donc chargé qu'à la première question portant sur
    cette clé.
    """
    entries = cls._entries()
    if key not in entries:
        entries[key] = _LazyEntry(module)

get classmethod

get(key: str) -> T

Retrieve the entry for key, raising KeyError if missing.

Source code in src/diapason/core/registry.py

@classmethod
def get(cls, key: str) -> T:
    """Retrieve the entry for *key*, raising ``KeyError`` if missing."""
    cls._resolve(key)
    try:
        return cls._entries()[key]
    except KeyError as exc:
        raise KeyError(
            f"{cls.__name__} does not have an entry for '{key}'"
        ) from exc

create classmethod

create(key: str, *args: Any, **kwargs: Any) -> Any

Look up key and instantiate it with the given arguments.

Source code in src/diapason/core/registry.py

@classmethod
def create(cls, key: str, *args: Any, **kwargs: Any) -> Any:
    """Look up *key* and instantiate it with the given arguments."""
    entry = cls.get(key)
    if not callable(entry):
        raise TypeError(
            f"{cls.__name__} entry '{key}' is not callable"
            " and cannot be instantiated"
        )
    return entry(*args, **kwargs)

items classmethod

items() -> Tuple[Tuple[str, T], ...]

Return all (key, entry) pairs as a tuple.

Source code in src/diapason/core/registry.py

@classmethod
def items(cls) -> Tuple[Tuple[str, T], ...]:
    """Return all ``(key, entry)`` pairs as a tuple."""
    return tuple(cls._entries().items())

keys classmethod

keys() -> Tuple[str, ...]

Return all registered keys as a tuple.

Source code in src/diapason/core/registry.py

@classmethod
def keys(cls) -> Tuple[str, ...]:
    """Return all registered keys as a tuple."""
    return tuple(cls._entries().keys())

contains classmethod

contains(key: str) -> bool

Check whether key is registered.

Résout une entrée paresseuse : répondre « oui » puis échouer à la créer serait pire que de payer l'import ici. L'appelant qui pose la question sur cette clé précise est justement celui qui va s'en servir.

Source code in src/diapason/core/registry.py

@classmethod
def contains(cls, key: str) -> bool:
    """Check whether *key* is registered.

    Résout une entrée paresseuse : répondre « oui » puis échouer à la
    créer serait pire que de payer l'import ici. L'appelant qui pose la
    question sur cette clé précise est justement celui qui va s'en servir.
    """
    cls._resolve(key)
    return key in cls._entries()

clear classmethod

clear() -> None

Remove all entries (useful in tests).

Source code in src/diapason/core/registry.py

@classmethod
def clear(cls) -> None:
    """Remove all entries (useful in tests)."""
    cls._entries().clear()

ModelRegistry

Bases: RegistryBase[Any]

Registry for ModelSpec objects.

EngineRegistry

Bases: RegistryBase[Type['InferenceEngine']]

Registry for inference engine backends.

MemoryRegistry

Bases: RegistryBase[Type['MemoryBackend']]

Registry for memory / retrieval backends.

FactStoreRegistry

Bases: RegistryBase[Type['FactStore']]

Registry for automatic-memory fact store backends.

AgentRegistry

Bases: RegistryBase[Type['BaseAgent']]

Registry for agent implementations.

ToolRegistry

Bases: RegistryBase[Any]

Registry for tool specifications.

RouterPolicyRegistry

Bases: RegistryBase[Any]

Registry for router policy implementations.

BenchmarkRegistry

Bases: RegistryBase[Any]

Registry for benchmark implementations.

ChannelRegistry

Bases: RegistryBase[Any]

Registry for channel implementations.

LearningRegistry

Bases: RegistryBase[Any]

Registry for learning policies.

SkillRegistry

Bases: RegistryBase[Any]

Registry for skill manifests.

SpeechRegistry

Bases: RegistryBase[Any]

Registry for speech backend implementations.

CompressionRegistry

Bases: RegistryBase[Any]

Registry for context compression strategies.

TTSRegistry

Bases: RegistryBase[Any]

Registry for text-to-speech backend implementations.

ConnectorRegistry

Bases: RegistryBase[Any]

Registry for data source connectors (Gmail, Slack, etc.).

MinerRegistry

Bases: RegistryBase[Any]

Registry for Pearl mining provider implementations.

Each provider implements the MiningProvider ABC defined in diapason.mining._stubs. Registry keys are short lowercase strings such as "vllm-pearl" (CUDA + Hopper) and (future) "mlx-pearl", "llamacpp-pearl-metal", "ollama-pearl".