"""
Runtime module: Load and save LLMHub runtime configurations.

This module provides programmatic access to runtime configuration operations,
allowing developers to load and save runtime configs without using the CLI.
"""
from pathlib import Path
from typing import Union

from llmhub_runtime.models import RuntimeConfig
from ..runtime_io import (
    load_runtime as _load_runtime,
    save_runtime as _save_runtime,
    RuntimeError,
)


def load_runtime(runtime_path: Union[str, Path]) -> RuntimeConfig:
    """
    Load runtime configuration from YAML file.
    
    This function reads a runtime configuration file, parses it, and validates
    the structure. Runtime configs contain concrete provider and model selections
    for each role, as generated by the spec-to-runtime conversion process.
    
    Args:
        runtime_path: Path to runtime YAML file (string or Path object)
    
    Returns:
        RuntimeConfig object with runtime configuration containing:
            - project: Project name
            - env: Environment name
            - providers: Dictionary of provider configurations with API keys
            - roles: Dictionary of role configurations with model selections
            - defaults: Optional default role configuration
    
    Raises:
        RuntimeError: If file not found, cannot be parsed, or validation fails
    
    Example:
        >>> from llmhub_cli.runtime import load_runtime
        >>> 
        >>> # Load runtime configuration
        >>> runtime = load_runtime("llmhub.yaml")
        >>> 
        >>> # Access runtime properties
        >>> print(f"Project: {runtime.project}")
        >>> print(f"Providers: {list(runtime.providers.keys())}")
        >>> 
        >>> # Access role configurations
        >>> for role_name, role_config in runtime.roles.items():
        ...     print(f"{role_name}: {role_config.provider}:{role_config.model}")
        >>> 
        >>> # Use with LLMHub
        >>> from llmhub_runtime import LLMHub
        >>> hub = LLMHub(config=runtime)
        >>> response = hub.completion(role="llm.inference", messages=[...])
    
    See Also:
        - save_runtime: Save a runtime configuration to file
        - RuntimeConfig: The runtime configuration model (from llmhub_runtime)
        - LLMHub: Runtime execution hub (from llmhub_runtime)
    """
    return _load_runtime(runtime_path)


def save_runtime(runtime_path: Union[str, Path], config: RuntimeConfig) -> None:
    """
    Save runtime configuration to YAML file.
    
    This function writes a RuntimeConfig object to a YAML file. It's useful
    for persisting generated runtime configurations or creating environment-
    specific config files.
    
    Args:
        runtime_path: Path where runtime YAML will be saved (string or Path)
        config: RuntimeConfig object to save
    
    Raises:
        RuntimeError: If unable to write file (permissions, disk space, etc.)
    
    Example:
        >>> from llmhub_cli import load_spec, generate_runtime_from_spec, save_runtime
        >>> 
        >>> # Load spec and generate runtime
        >>> spec = load_spec("llmhub.spec.yaml")
        >>> result = generate_runtime_from_spec(spec)
        >>> 
        >>> # Save to default location
        >>> save_runtime("llmhub.yaml", result.runtime)
        >>> 
        >>> # Save to environment-specific files
        >>> save_runtime("llmhub.dev.yaml", result.runtime)
        >>> save_runtime("llmhub.staging.yaml", result.runtime)
        >>> save_runtime("llmhub.prod.yaml", result.runtime)
        >>> 
        >>> # Verify by loading back
        >>> loaded = load_runtime("llmhub.yaml")
        >>> assert loaded.project == spec.project
    
    See Also:
        - load_runtime: Load a runtime configuration from file
        - generate_runtime_from_spec: Generate runtime from spec
        - RuntimeConfig: The runtime configuration model
    """
    _save_runtime(runtime_path, config)


__all__ = [
    "load_runtime",
    "save_runtime",
    "RuntimeConfig",
    "RuntimeError",
]
