Component Registry

The ComponentRegistry is the single source of truth for agent and service discovery in Lobster AI. It discovers and loads components dynamically via Python entry points, enabling a modular architecture where agents can be installed as separate packages.

Overview

The ComponentRegistry enables:

Automatic discovery of installed agent packages via entry points
Runtime registration of agents, services, and plugins
Version compatibility checking for external plugins
Thread-safe component access

Entry Point Groups

Lobster uses seven entry point groups for component discovery:

Group	Purpose	Example
`lobster.agents`	Agent registration (AGENT_CONFIG instances)	`transcriptomics_expert`
`lobster.services`	Service class registration	`publication_processing`
`lobster.agent_configs`	Custom agent LLM configurations	`metadata_assistant`
`lobster.adapters`	Modality adapter factories for data loading	`metabolomics_lc_ms`
`lobster.providers`	Database provider classes for data access	`metabolights`
`lobster.download_services`	Download service classes for database retrieval	`metabolights_download`
`lobster.queue_preparers`	Queue preparation classes for accession mapping	`metabolights_preparer`
`lobster.omics_types`	OmicsTypeConfig instances for type registration	`metabolomics`

The first three groups (lobster.agents, lobster.services, lobster.agent_configs) handle agent and service discovery. The remaining four groups enable the modular omics plugin architecture, allowing new omics types to be added via external packages with zero changes to core.

For details on configuring entry points, see Entry Points.

Basic Usage

Import the singleton instance:

from lobster.core.component_registry import component_registry

Listing All Agents

# Get all discovered agents (core + custom packages)
all_agents = component_registry.list_agents()

for name, config in all_agents.items():
    print(f"{name}: {config.display_name}")
    print(f"  Tier: {config.tier_requirement}")
    print(f"  Package: {config.package_name or 'lobster-ai (core)'}")

Getting a Specific Agent

# Get agent config by name
transcriptomics = component_registry.get_agent("transcriptomics_expert")

if transcriptomics:
    print(f"Found: {transcriptomics.display_name}")
    print(f"Description: {transcriptomics.description}")

# Require agent (raises ValueError if not found)
research = component_registry.get_agent("research_agent", required=True)

Checking Agent Availability

# Check if agent is installed
if component_registry.has_agent("proteomics_expert"):
    print("Proteomics agent available")
else:
    print("Install with: pip install lobster-proteomics")

Service Discovery

Services are registered via the lobster.services entry point group:

# Optional mode (default) - returns None if not found
PublicationQueue = component_registry.get_service("publication_queue", required=False)

if PublicationQueue:
    queue = PublicationQueue(queue_file=path)
else:
    print("Service not available (premium feature)")

# Required mode - raises ValueError if not found
try:
    ClusteringService = component_registry.get_service("clustering_service", required=True)
    service = ClusteringService()
except ValueError as e:
    print(f"Service not found: {e}")

# List all available services
services = component_registry.list_services()
for name, module_path in services.items():
    print(f"{name}: {module_path}")

Agent Config API (LLM Configurations)

Custom agent LLM configurations are discovered via lobster.agent_configs:

# Get custom agent config
config = component_registry.get_agent_config("metadata_assistant")

# List all custom configs
configs = component_registry.list_agent_configs()

Version Compatibility

The registry automatically checks plugin compatibility before loading:

from lobster.core.component_registry import check_plugin_compatibility

is_compatible, message = check_plugin_compatibility("lobster-transcriptomics")
if not is_compatible:
    print(f"Plugin incompatible: {message}")

Incompatible plugins are logged as warnings and skipped during discovery.

Adapter and Provider Discovery

The ComponentRegistry also discovers modality adapters, database providers, download services, and queue preparers via entry points. These enable the modular omics plugin architecture:

# Adapters are discovered by DataManagerV2 via lobster.adapters entry points
# Providers are discovered by ContentAccessService via lobster.providers entry points
# Download services are discovered by DownloadOrchestrator via lobster.download_services entry points
# Queue preparers are discovered by QueuePreparationService via lobster.queue_preparers entry points

Entry-point discovery runs first, with hardcoded fallbacks used only when no plugin provides the component. This means external packages can extend Lobster's omics support without modifying core.

Diagnostics

Get comprehensive registry information:

info = component_registry.get_info()
print(f"Agents: {info['agents']['count']}")
print(f"Services: {info['services']['count']}")
print(f"Custom configs: {info['custom_agent_configs']['count']}")

Thread Safety

The ComponentRegistry is thread-safe. Component discovery happens once on first access:

# Safe to call from multiple threads
component_registry.load_components()  # Idempotent

Reset (Testing)

For testing, you can reset the registry state:

component_registry.reset()  # Clears all cached components

Migration from AGENT_REGISTRY

The global AGENT_REGISTRY dictionary is deprecated. Use ComponentRegistry instead.

Old pattern (deprecated):

from lobster.config.agent_registry import AGENT_REGISTRY
agent_config = AGENT_REGISTRY.get("research_agent")

New pattern:

from lobster.core.component_registry import component_registry
agent_config = component_registry.get_agent("research_agent")

Benefits of ComponentRegistry:

Dynamic discovery (no hardcoded dictionary)
Supports external packages (lobster-custom-*)
Version compatibility checking
Thread-safe singleton

Registering Custom Components

Agents

To register your own agents, add entry points to your package's pyproject.toml:

[project.entry-points."lobster.agents"]
my_custom_agent = "my_package.agents.my_agent:AGENT_CONFIG"

The AGENT_CONFIG must be an AgentRegistryConfig instance. See Creating Agents for the full guide.

Omics Types

To register a new omics type with adapters, providers, and download services:

[project.entry-points."lobster.omics_types"]
my_omics = "my_package.config:MY_OMICS_CONFIG"

[project.entry-points."lobster.adapters"]
my_omics_adapter = "my_package.adapter:create_adapter"

[project.entry-points."lobster.providers"]
my_database = "my_package.provider:MyProvider"

[project.entry-points."lobster.download_services"]
my_download = "my_package.download:MyDownloadService"

[project.entry-points."lobster.queue_preparers"]
my_preparer = "my_package.queue:MyQueuePreparer"

See Entry Points for the full guide on adding new omics types via plugins.

API Reference