hermes-agent/agent/provider_preflight.py

"""Provider Preflight — Poka-yoke validation of provider/model config.

Validates provider and model configuration before session start.
Prevents wasted context on misconfigured providers.

Usage:
    from agent.provider_preflight import preflight_check
    result = preflight_check(provider="openrouter", model="xiaomi/mimo-v2-pro")
    if not result["valid"]:
        print(result["error"])
"""

from __future__ import annotations

import logging
import os
from typing import Any, Dict, Optional

logger = logging.getLogger(__name__)


# Provider -> required env var
PROVIDER_KEYS = {
    "openrouter": "OPENROUTER_API_KEY",
    "anthropic": "ANTHROPIC_API_KEY",
    "openai": "OPENAI_API_KEY",
    "nous": "NOUS_API_KEY",
    "ollama": None,  # Local, no key needed
    "local": None,
}


def check_provider_key(provider: str) -> Dict[str, Any]:
    """Check if provider has a valid API key configured."""
    provider_lower = provider.lower().strip()

    env_var = None
    for known, key in PROVIDER_KEYS.items():
        if known in provider_lower:
            env_var = key
            break

    if env_var is None:
        # Unknown provider — assume OK (custom/local)
        return {"valid": True, "provider": provider, "key_status": "unknown"}

    if env_var is None:
        # Local provider, no key needed
        return {"valid": True, "provider": provider, "key_status": "not_required"}

    key_value = os.getenv(env_var, "").strip()
    if not key_value:
        return {
            "valid": False,
            "provider": provider,
            "key_status": "missing",
            "error": f"{env_var} is not set. Provider '{provider}' will fail.",
            "fix": f"Set {env_var} in ~/.hermes/.env",
        }

    if len(key_value) < 10:
        return {
            "valid": False,
            "provider": provider,
            "key_status": "too_short",
            "error": f"{env_var} is suspiciously short ({len(key_value)} chars). May be invalid.",
            "fix": f"Verify {env_var} value in ~/.hermes/.env",
        }

    return {"valid": True, "provider": provider, "key_status": "set"}


def check_model_availability(model: str, provider: str) -> Dict[str, Any]:
    """Check if model is likely available for provider."""
    if not model:
        return {"valid": False, "error": "No model specified"}

    # Basic sanity checks
    model_lower = model.lower()

    # Anthropic models should use anthropic provider
    if "claude" in model_lower and "anthropic" not in provider.lower():
        return {
            "valid": True,  # Allow but warn
            "warning": f"Model '{model}' usually runs on Anthropic provider, not '{provider}'",
        }

    # Ollama models
    ollama_indicators = ["llama", "mistral", "qwen", "gemma", "phi", "hermes"]
    if any(x in model_lower for x in ollama_indicators) and ":" not in model:
        return {
            "valid": True,
            "warning": f"Model '{model}' may need a version tag for Ollama (e.g., {model}:latest)",
        }

    return {"valid": True}


def preflight_check(
    provider: str = "",
    model: str = "",
    fallback_provider: str = "",
    fallback_model: str = "",
) -> Dict[str, Any]:
    """Full pre-flight check for provider/model configuration.

    Returns:
        Dict with valid (bool), errors (list), warnings (list).
    """
    errors = []
    warnings = []

    # Check primary provider
    if provider:
        result = check_provider_key(provider)
        if not result["valid"]:
            errors.append(result.get("error", f"Provider {provider} invalid"))

    # Check primary model
    if model:
        result = check_model_availability(model, provider)
        if not result["valid"]:
            errors.append(result.get("error", f"Model {model} invalid"))
        elif result.get("warning"):
            warnings.append(result["warning"])

    # Check fallback
    if fallback_provider:
        result = check_provider_key(fallback_provider)
        if not result["valid"]:
            warnings.append(f"Fallback provider {fallback_provider} also invalid: {result.get('error','')}")

    if fallback_model:
        result = check_model_availability(fallback_model, fallback_provider)
        if not result["valid"]:
            warnings.append(f"Fallback model {fallback_model} invalid")
        elif result.get("warning"):
            warnings.append(result["warning"])

    return {
        "valid": len(errors) == 0,
        "errors": errors,
        "warnings": warnings,
        "provider": provider,
        "model": model,
    }