Health

Raw provider health/availability signals. See the Provider health guide for how to compose your own "available" predicate.

check_providers

check_providers

check_providers(names: list[str] | None = None, *, live: bool = False, model: str | None = None) -> list[ProviderHealth]

Return ProviderHealth for each registered provider.

Parameters:

Name	Type	Description	Default
names	list[str] | None	Provider names/aliases to check, or None for every registered provider. Aliases pointing at the same provider class (e.g. claude/cc/claude_code) collapse to one result.	None
live	bool	If True, run the live probe per provider (costs a request each).	False
model	str | None	Optional model string passed through to the live probe.	None

Returns:

Type	Description
list[ProviderHealth]	One ProviderHealth per distinct provider, in the order given
list[ProviderHealth]	(or registration order when names is None).

Source code in caw/health.py

def check_providers(
    names: list[str] | None = None,
    *,
    live: bool = False,
    model: str | None = None,
) -> list[ProviderHealth]:
    """Return `ProviderHealth` for each registered provider.

    Args:
        names: Provider names/aliases to check, or ``None`` for every
            registered provider. Aliases pointing at the same provider class
            (e.g. ``claude``/``cc``/``claude_code``) collapse to one result.
        live: If True, run the live probe per provider (costs a request each).
        model: Optional model string passed through to the live probe.

    Returns:
        One `ProviderHealth` per distinct provider, in the order given
        (or registration order when ``names`` is None).
    """
    from caw.agent import _PROVIDER_REGISTRY

    keys = names if names is not None else list(_PROVIDER_REGISTRY.keys())
    results: list[ProviderHealth] = []
    seen: set[type] = set()
    for key in keys:
        cls = _PROVIDER_REGISTRY.get(key)
        if cls is None:
            available = list(_PROVIDER_REGISTRY.keys())
            raise ValueError(f"Unknown provider {key!r}. Available: {available}")
        if cls in seen:
            continue
        seen.add(cls)
        results.append(cls().check_health(live=live, model=model))
    return results

ProviderHealth

ProviderHealth dataclass

ProviderHealth(provider: str, installed: bool, binary_path: str | None = None, auth: AuthSignal | None = None, probed: bool = False, rate_limited: bool | None = None, wait_minutes: int | None = None, error: str | None = None)

Raw health signals for a single provider. No 'available' verdict.

AuthSignal

AuthSignal dataclass

AuthSignal(present: bool, detail: str, credentials_path: str | None = None, token_expires_at: datetime | None = None, token_expired: bool | None = None)

Best-effort, non-authoritative view of a provider's credentials.

Every field is a raw signal; None means "could not determine" rather than a negative result. Detection is intentionally cheap and may miss valid setups (e.g. credentials supplied by an env var we don't know about), so callers should treat a falsy present as a hint, not a verdict.