Backend Registry

deep_db_agents.backend_registry

Singleton registry of BackendProtocol backends indexed by UUID.

Allows registering a backend instance (derived from deepagents' BackendProtocol), obtaining an opaque identifier that can later be used to retrieve or remove it, without letting the reference to the object circulate through the system.

The registry is shared at the process level: whoever registers a backend (add) is responsible for removing it (remove) at the end of the agent's lifetime, otherwise the instance stays referenced for the entire process lifetime.

BERegistry

Singleton UUID -> BackendProtocol registry.

Every instantiation returns the same object, so the registry is shared at the process level. Creation and mutations are protected by a lock: tools may run in parallel threads (parallel tool calls in the tool node).

reg = BERegistry() key = reg.add(my_backend) reg.get(key) is my_backend True reg.remove(key) reg.get(key) is None True

__new__

__new__() -> BERegistry

Create or return the singleton instance.

Returns:

Name	Type	Description
BERegistry	BERegistry	The single shared instance of the registry.

Source code in src/deep_db_agents/backend_registry.py

def __new__(cls) -> BERegistry:
    """Create or return the singleton instance.

    Returns:
        BERegistry: The single shared instance of the registry.
    """
    if cls._instance is None:
        with cls._instance_lock:
            if cls._instance is None:  # double-checked: avoids duplicate instances
                instance = super().__new__(cls)
                instance._backends = {}
                instance._lock = threading.Lock()
                cls._instance = instance
    return cls._instance

add

add(backend: BackendProtocol) -> str

Register a backend and return its identifier.

Parameters:

Name	Type	Description	Default
backend	BackendProtocol	The BackendProtocol instance to register.	required

Returns:

Name	Type	Description
str	str	The UUID (as a string) associated with the registered backend.

Raises:

Type	Description
TypeError	If backend is not a BackendProtocol instance.

Source code in src/deep_db_agents/backend_registry.py

def add(self, backend: BackendProtocol) -> str:
    """Register a backend and return its identifier.

    Args:
        backend: The ``BackendProtocol`` instance to register.

    Returns:
        str: The UUID (as a string) associated with the registered backend.

    Raises:
        TypeError: If ``backend`` is not a ``BackendProtocol`` instance.
    """
    if not isinstance(backend, BackendProtocol):
        raise TypeError(f"Expected a BackendProtocol, got {type(backend).__name__!r}.")
    key = str(uuid.uuid4())
    with self._lock:
        self._backends[key] = backend
    return key

get

get(key: str) -> BackendProtocol | None

Retrieve a registered backend.

Parameters:

Name	Type	Description	Default
key	str	The UUID string previously returned by :meth:add.	required

Returns:

Type	Description
BackendProtocol | None	BackendProtocol | None: The registered backend, or None if
BackendProtocol | None	key is not registered.

Source code in src/deep_db_agents/backend_registry.py

def get(self, key: str) -> BackendProtocol | None:
    """Retrieve a registered backend.

    Args:
        key: The UUID string previously returned by :meth:`add`.

    Returns:
        BackendProtocol | None: The registered backend, or ``None`` if
        ``key`` is not registered.
    """
    with self._lock:
        return self._backends.get(key)

remove

remove(key: str) -> None

Remove a registered backend.

Parameters:

Name	Type	Description	Default
key	str	The UUID string previously returned by :meth:add.	required

Returns:

Type	Description
None	None. This is a no-op if key does not exist.

Source code in src/deep_db_agents/backend_registry.py

def remove(self, key: str) -> None:
    """Remove a registered backend.

    Args:
        key: The UUID string previously returned by :meth:`add`.

    Returns:
        None. This is a no-op if ``key`` does not exist.
    """
    with self._lock:
        self._backends.pop(key, None)