service-registry

Table of Contents

• [Overview](#overview)
• [When to Use](#when-to-use)
• [Core Concepts](#core-concepts)
• [Service Configuration](#service-configuration)
• [Execution Result](#execution-result)
• [Quick Start](#quick-start)
• [Register Services](#register-services)
• [Execute via Service](#execute-via-service)
• [Health Checks](#health-checks)
• [Service Selection](#service-selection)
• [Auto-Selection](#auto-selection)
• [Failover Pattern](#failover-pattern)
• [Integration Pattern](#integration-pattern)
• [Detailed Resources](#detailed-resources)
• [Exit Criteria](#exit-criteria)

Service Registry

Overview

A registry pattern for managing connections to external services. Handles configuration, health checking, and execution across multiple service integrations.

When To Use

• Managing multiple external services.
• Need consistent execution interface.
• Want health monitoring across services.
• Building service failover logic.

When NOT To Use

• Single service integration without registry needs

Core Concepts

Service Configuration

@dataclass
class ServiceConfig:
    name: str
    command: str
    auth_method: str  # "api_key", "oauth", "token"
    auth_env_var: str
    quota_limits: dict
    models: list[str] = field(default_factory=list)

Verification: Run the command with --help flag to verify availability.

Execution Result

@dataclass
class ExecutionResult:
    success: bool
    stdout: str
    stderr: str
    exit_code: int
    duration: float
    tokens_used: int

Verification: Run the command with --help flag to verify availability.

Quick Start

Register Services

from leyline.service_registry import ServiceRegistry

registry = ServiceRegistry()

registry.register(
    "gemini",
    ServiceConfig(
        name="gemini",
        command="gemini",
        auth_method="api_key",
        auth_env_var="GEMINI_API_KEY",
        quota_limits={"rpm": 60, "daily": 1000},
    ),
)

Verification: Run the command with --help flag to verify availability.

Execute via Service

result = registry.execute(
    service="gemini",
    prompt="Analyze this code",
    files=["src/main.py"],
    model="gemini-3-pro",
)

if result.success:
    print(result.stdout)

Verification: Run the command with --help flag to verify availability.

Health Checks

# Check single service
status = registry.health_check("gemini")

# Check all services
all_status = registry.health_check_all()
for service, healthy in all_status.items():
    print(f"{service}: {'OK' if healthy else 'FAILED'}")

Verification: Run the command with --help flag to verify availability.

Service Selection

Auto-Selection

# Select best service for task
service = registry.select_service(
    requirements={"large_context": True, "fast_response": False}
)

Verification: Run the command with --help flag to verify availability.

Failover Pattern

def execute_with_failover(prompt: str, files: list) -> ExecutionResult:
    for service in registry.get_healthy_services():
        result = registry.execute(service, prompt, files)
        if result.success:
            return result
    raise AllServicesFailedError()

Verification: Run the command with --help flag to verify availability.

Integration Pattern

# In your skill's frontmatter
dependencies: [leyline:service-registry]

Verification: Run the command with --help flag to verify availability.

Detailed Resources

• Service Config: See modules/service-config.md for configuration options.
• Execution Patterns: See modules/execution-patterns.md for advanced usage.

Exit Criteria

• Services registered with configuration.
• Health checks passing.
• Execution results properly handled.