registry

registry

Instrument registry — the central lookup for all available instruments.

Combines native instruments (Marianne's 4 built-in backends) with config-loaded profiles from YAML files. The conductor creates a registry at startup, populates it with native instruments, then loads profiles from directories.

Native instruments map Marianne's existing Backend subclasses to InstrumentProfile metadata. This lets the new instrument-based lookup coexist with the existing backend system — scores using backend: continue to work unchanged, while scores using instrument: resolve through this registry.

The registry is a simple dict wrapper. No caching, no lazy loading, no magic. Instruments are registered once at startup and looked up by name thereafter.

Usage

from marianne.instruments.registry import InstrumentRegistry, register_native_instruments

registry = InstrumentRegistry() register_native_instruments(registry)

... load profiles from directories ...

profile = registry.get("gemini-cli")

Classes

InstrumentRegistry

InstrumentRegistry()

Central registry for all available instruments.

A simple name-to-profile mapping with registration, lookup, and listing operations. Thread safety is not needed — the registry is populated at conductor startup before any concurrent access.

Source code in src/marianne/instruments/registry.py

def __init__(self) -> None:
    self._profiles: dict[str, InstrumentProfile] = {}

Functions

register

register(profile, *, override=False)

Register an instrument profile.

Parameters:

Name	Type	Description	Default
profile	InstrumentProfile	The InstrumentProfile to register.	required
override	bool	If True, replace an existing profile with the same name. If False (default), raise ValueError on collision.	False

Raises:

Type	Description
ValueError	If a profile with the same name is already registered and override is False.

Source code in src/marianne/instruments/registry.py

def register(
    self,
    profile: InstrumentProfile,
    *,
    override: bool = False,
) -> None:
    """Register an instrument profile.

    Args:
        profile: The InstrumentProfile to register.
        override: If True, replace an existing profile with the same
            name. If False (default), raise ValueError on collision.

    Raises:
        ValueError: If a profile with the same name is already
            registered and override is False.
    """
    if profile.name in self._profiles and not override:
        raise ValueError(
            f"Instrument '{profile.name}' is already registered. "
            f"Use override=True to replace it."
        )
    self._profiles[profile.name] = profile
    _logger.debug(
        "instrument_registered",
        name=profile.name,
        kind=profile.kind,
        override=override,
    )

get

get(name)

Look up an instrument by name.

Parameters:

Name	Type	Description	Default
name	str	The instrument name (e.g. 'claude_cli', 'gemini-cli').	required

Returns:

Type	Description
InstrumentProfile | None	The InstrumentProfile, or None if not found.

Source code in src/marianne/instruments/registry.py

def get(self, name: str) -> InstrumentProfile | None:
    """Look up an instrument by name.

    Args:
        name: The instrument name (e.g. 'claude_cli', 'gemini-cli').

    Returns:
        The InstrumentProfile, or None if not found.
    """
    return self._profiles.get(name)

list_all

list_all()

Return all registered profiles, sorted by name.

Source code in src/marianne/instruments/registry.py

def list_all(self) -> list[InstrumentProfile]:
    """Return all registered profiles, sorted by name."""
    return sorted(self._profiles.values(), key=lambda p: p.name)

Functions

register_native_instruments

register_native_instruments(registry)

Register Marianne's 4 built-in backends as named instruments.

This bridges the native backend system (BackendConfig → Backend) with the new instrument system (InstrumentProfile → registry lookup). After calling this, the registry contains profiles for claude_cli, anthropic_api, ollama, and recursive_light.

Native instruments are registered first, before config-loaded profiles. Config profiles can override them with override=True if needed.

Parameters:

Name	Type	Description	Default
registry	InstrumentRegistry	The registry to populate.	required

Source code in src/marianne/instruments/registry.py

def register_native_instruments(registry: InstrumentRegistry) -> None:
    """Register Marianne's 4 built-in backends as named instruments.

    This bridges the native backend system (BackendConfig → Backend) with
    the new instrument system (InstrumentProfile → registry lookup). After
    calling this, the registry contains profiles for claude_cli, anthropic_api,
    ollama, and recursive_light.

    Native instruments are registered first, before config-loaded profiles.
    Config profiles can override them with override=True if needed.

    Args:
        registry: The registry to populate.
    """
    for factory in [
        _claude_cli_profile,
        _anthropic_api_profile,
        _ollama_profile,
        _recursive_light_profile,
    ]:
        profile = factory()
        registry.register(profile)
        _logger.info(
            "native_instrument_registered",
            name=profile.name,
            kind=profile.kind,
        )

    _logger.info(
        "native_instruments_complete",
        count=4,
    )