zai-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{zai_cli-0.2.2 → zai_cli-0.2.3}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.2.3] - 2026-07-14
+
+### Added
+
+- Added structured fallback-attempt diagnostics with model, failure category,
+  secret-redacted detail, and a recommended next action.
+- Added final failure summaries that list every attempted model and its result.
+
+### Changed
+
+- Chat fallback now distinguishes missing or invalid credentials, quota limits,
+  unavailable models, timeouts, network errors, malformed responses, and other
+  provider failures instead of describing them all as network issues.
+- Provider initialization and readiness-check failures no longer stop the
+  remaining fallback chain.
+- Plain mode sends fallback diagnostics to stderr so successful response output
+  on stdout remains script-friendly.
+
 ## [0.2.2] - 2026-07-13
 
 ### Added

{zai_cli-0.2.2/zai_cli.egg-info → zai_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -618,6 +618,12 @@ Providers without an API key are skipped. Ollama is used only when its local
 service is available. Provider quotas and model availability are controlled by
 their respective services and can change independently of `zai`.
 
+When an attempted model fails, `zai` reports the model, a stable failure
+category, secret-redacted provider detail, and the recommended recovery action
+before trying the next configured model. If every model fails, the final error
+lists the complete attempt chain. In `--plain` mode these diagnostics go to
+stderr, leaving successful response text on stdout.
+
 Supported configuration keys:
 
 ```text

{zai_cli-0.2.2 → zai_cli-0.2.3}/README.md

@@ -561,6 +561,12 @@ Providers without an API key are skipped. Ollama is used only when its local
 service is available. Provider quotas and model availability are controlled by
 their respective services and can change independently of `zai`.
 
+When an attempted model fails, `zai` reports the model, a stable failure
+category, secret-redacted provider detail, and the recommended recovery action
+before trying the next configured model. If every model fails, the final error
+lists the complete attempt chain. In `--plain` mode these diagnostics go to
+stderr, leaving successful response text on stdout.
+
 Supported configuration keys:
 
 ```text

zai_cli-0.2.3/tests/test_fallback_diagnostics.py

@@ -0,0 +1,177 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from zai.core import fallback
+from zai.core.errors import (
+    AllModelsFailedError,
+    AuthenticationError,
+    MalformedResponseError,
+    ModelNotFoundError,
+    NetworkError,
+    NoAPIKeyError,
+    ProviderError,
+    ProviderTimeoutError,
+    QuotaError,
+)
+from zai.providers.base import Message, Response
+
+
+@pytest.mark.parametrize(
+    ("error", "category", "guidance"),
+    [
+        (NoAPIKeyError("groq"), "missing credentials", "zai auth login groq"),
+        (AuthenticationError("groq", "bad key"), "invalid credentials", "zai auth login groq"),
+        (QuotaError("groq", "quota"), "quota/rate limit", "check quota"),
+        (ModelNotFoundError("groq", "gone"), "model unavailable", "zai model info fast"),
+        (ProviderTimeoutError("groq", "slow"), "timeout", "zai model configure fast"),
+        (NetworkError("offline"), "network error", "Check internet"),
+        (MalformedResponseError("groq", "choices"), "malformed response", "Retry once"),
+        (ProviderError("groq", "broken"), "provider error", "zai model test fast"),
+    ],
+)
+def test_failure_attempt_has_accurate_category_and_guidance(error, category, guidance):
+    attempt = fallback._failure_attempt("fast", "groq", error)
+
+    assert attempt.category == category
+    assert guidance in attempt.next_action
+
+
+def test_failure_attempt_redacts_provider_secrets():
+    attempt = fallback._failure_attempt(
+        "groq",
+        "groq",
+        AuthenticationError("groq", "api_key=super-secret-provider-token"),
+    )
+
+    assert "super-secret-provider-token" not in attempt.detail
+    assert "[REDACTED_SECRET]" in attempt.detail
+
+
+def _config(*names):
+    return {
+        "default_model": names[0],
+        "fallback_order": list(names),
+        "auto_fallback": True,
+    }
+
+
+def _provider(name, *, error=None, response="ok", available=True):
+    provider = MagicMock()
+    provider.name = name
+    provider.model_id = f"provider/{name}"
+    provider.context_window = 128_000
+    provider.supports_native_tools = True
+    provider.supports_streaming = False
+    provider.is_available.return_value = available
+    if error:
+        provider.chat.side_effect = error
+    else:
+        provider.chat.return_value = Response(content=response, model=provider.model_id)
+    return provider
+
+
+def test_chat_fallback_reports_auth_failure_and_uses_next_model(monkeypatch, capsys):
+    broken = _provider("groq", error=AuthenticationError("groq", "bad key"))
+    working = _provider("gemini", response="fallback worked")
+    providers = {"groq": broken, "gemini": working}
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", providers.get)
+
+    response, used = fallback.chat_with_fallback([Message(role="user", content="hi")])
+
+    output = capsys.readouterr().out
+    assert response.content == "fallback worked"
+    assert used == "gemini"
+    assert "groq failed" in output
+    assert "invalid credentials" in output
+    assert "Trying next model" in output
+    assert "Network issue" not in output
+
+
+def test_fallback_survives_provider_initialization_failure(monkeypatch, capsys):
+    working = _provider("gemini")
+
+    def get_provider(name):
+        if name == "groq":
+            raise RuntimeError("provider SDK failed to initialize")
+        return working
+
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", get_provider)
+
+    response, used = fallback.chat_with_fallback([Message(role="user", content="hi")])
+
+    assert response.content == "ok"
+    assert used == "gemini"
+    assert "provider error" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize("runner", [fallback.chat_with_fallback, fallback.stream_with_fallback])
+def test_fallback_does_not_swallow_cancellation_during_readiness(monkeypatch, runner):
+    from zai.core.cancellation import OperationCancelled
+
+    provider = _provider("groq")
+    provider.is_available.side_effect = OperationCancelled("stop now")
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", lambda name: provider)
+
+    with pytest.raises(OperationCancelled, match="stop now"):
+        runner([Message(role="user", content="hi")])
+
+
+def test_all_models_failed_lists_every_attempt(monkeypatch):
+    missing = _provider("groq", available=False)
+    limited = _provider("gemini", error=QuotaError("gemini", "quota exhausted"))
+    providers = {"groq": missing, "gemini": limited}
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", providers.get)
+
+    with pytest.raises(AllModelsFailedError) as caught:
+        fallback.chat_with_fallback([Message(role="user", content="hi")])
+
+    message = str(caught.value)
+    assert "groq (unavailable)" in message
+    assert "gemini (quota/rate limit)" in message
+    assert "zai model check" in message
+
+
+def test_stream_fallback_uses_same_diagnostics(monkeypatch, capsys):
+    broken = _provider("groq", error=NetworkError("offline"))
+    working = _provider("gemini", response="stream fallback")
+    providers = {"groq": broken, "gemini": working}
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", providers.get)
+
+    content, used = fallback.stream_with_fallback([Message(role="user", content="hi")])
+
+    output = capsys.readouterr().out
+    assert content == "stream fallback"
+    assert used == "gemini"
+    assert "network error" in output
+    assert "Check internet" in output
+
+
+def test_plain_mode_keeps_fallback_diagnostics_off_stdout(monkeypatch, capsys):
+    from zai.core.runtime import configure
+
+    broken = _provider("groq", error=NetworkError("offline"))
+    working = _provider("gemini", response="plain result")
+    providers = {"groq": broken, "gemini": working}
+    monkeypatch.setattr(fallback, "load_config", lambda: _config("groq", "gemini"))
+    monkeypatch.setattr(fallback, "get_provider", providers.get)
+
+    configure(plain=True)
+    try:
+        content, used = fallback.stream_with_fallback([
+            Message(role="user", content="hi")
+        ])
+    finally:
+        configure()
+
+    captured = capsys.readouterr()
+    assert content == "plain result"
+    assert used == "gemini"
+    assert "plain result" in captured.out
+    assert "groq failed" not in captured.out
+    assert "groq failed" in captured.err

zai_cli-0.2.3/zai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"

zai_cli-0.2.3/zai/core/fallback.py

@@ -0,0 +1,257 @@
+from dataclasses import dataclass
+
+from rich.console import Console
+from ..providers import PROVIDERS
+from ..providers.base import Message, Response
+from ..config import get_model_config, load_config
+from .errors import (
+    AllModelsFailedError,
+    AuthenticationError,
+    MalformedResponseError,
+    ModelNotFoundError,
+    NetworkError,
+    NoAPIKeyError,
+    ProviderError,
+    ProviderTimeoutError,
+    QuotaError,
+    RateLimitError,
+    classify_provider_error,
+)
+from .runtime import plain_enabled
+from .cancellation import OperationCancelled, raise_if_cancelled
+from .tokens import redact_secrets
+
+console = Console()
+diagnostic_console = Console(stderr=True)
+
+
+@dataclass(frozen=True)
+class FallbackAttempt:
+    model: str
+    category: str
+    detail: str
+    next_action: str
+
+    def summary(self) -> str:
+        return f"{self.model} ({self.category})"
+
+
+def _failure_attempt(model: str, provider: str, error: Exception) -> FallbackAttempt:
+    normalized = classify_provider_error(provider, error)
+    detail = redact_secrets(str(normalized))
+    if isinstance(normalized, NoAPIKeyError):
+        category = "missing credentials"
+        next_action = f"Add credentials with: zai auth login {provider}"
+    elif isinstance(normalized, AuthenticationError):
+        category = "invalid credentials"
+        next_action = f"Update credentials with: zai auth login {provider}"
+    elif isinstance(normalized, (RateLimitError, QuotaError)):
+        category = "quota/rate limit"
+        next_action = "Wait, check quota, or choose another model."
+    elif isinstance(normalized, ModelNotFoundError):
+        category = "model unavailable"
+        next_action = f"Check configuration with: zai model info {model}"
+    elif isinstance(normalized, ProviderTimeoutError):
+        category = "timeout"
+        next_action = f"Check or increase timeout with: zai model configure {model}"
+    elif isinstance(normalized, NetworkError):
+        category = "network error"
+        next_action = "Check internet, local service, or provider status."
+    elif isinstance(normalized, MalformedResponseError):
+        category = "malformed response"
+        next_action = "Retry once, then check provider status or switch models."
+    elif isinstance(normalized, ProviderError):
+        category = "provider error"
+        next_action = f"Inspect this model with: zai model test {model}"
+    else:
+        category = "unexpected error"
+        next_action = "Retry with --debug or run: zai model check"
+    return FallbackAttempt(model, category, detail, next_action)
+
+
+def _unavailable_attempt(model: str) -> FallbackAttempt:
+    return FallbackAttempt(
+        model=model,
+        category="unavailable",
+        detail="Model is not configured, credentials are missing, or its local service is down.",
+        next_action=f"Inspect this model with: zai model test {model}",
+    )
+
+
+def _report_attempt(attempt: FallbackAttempt, *, has_next: bool) -> None:
+    suffix = " Trying next model." if has_next else ""
+    output = diagnostic_console if plain_enabled() else console
+    output.print(
+        f"[yellow]{attempt.model} failed:[/yellow] {attempt.category}.{suffix}"
+    )
+    output.print(f"[dim]{attempt.detail}[/dim]")
+    output.print(f"[dim]{attempt.next_action}[/dim]")
+
+
+def _raise_all_models_failed(attempts: list[FallbackAttempt]) -> None:
+    summary = "; ".join(attempt.summary() for attempt in attempts)
+    guidance = "Run `zai model check` and `zai auth doctor`."
+    detail = f"Attempts: {summary}. {guidance}" if summary else guidance
+    raise AllModelsFailedError(detail)
+
+
+def format_model_selection(name: str) -> str:
+    try:
+        model = get_model_config(name)
+    except KeyError:
+        return name
+    return f"{name} -> {model['provider']}/{model['model_id']}"
+
+
+def get_provider(name: str):
+    try:
+        model = get_model_config(name)
+    except KeyError:
+        return None
+    cls = PROVIDERS.get(model["provider"])
+    if not cls:
+        return None
+    provider = cls()
+    provider.model_id = model["model_id"]
+    provider.context_window = model["context_window"]
+    provider.timeout = model.get("timeout", 60)
+    provider.retries = model.get("retries", 2)
+    return provider
+
+
+def _model_order(config: dict, preferred: str = None) -> list[str]:
+    first = preferred or config["default_model"]
+    if not config.get("auto_fallback", True):
+        return [first]
+    return [first] + [
+        model for model in config["fallback_order"]
+        if model != first
+    ]
+
+
+def has_available_provider() -> bool:
+    """Return True when any configured API provider or local provider is usable."""
+    config = load_config()
+    for model_name in _model_order(config):
+        try:
+            provider = get_provider(model_name)
+            if provider and provider.is_available():
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def stream_with_fallback(messages: list[Message], system: str = "", preferred: str = None) -> tuple[str, str]:
+    """Stream response with auto fallback. Returns (content, model_name)."""
+    config = load_config()
+    order = _model_order(config, preferred)
+
+    attempts: list[FallbackAttempt] = []
+    for index, model_name in enumerate(order):
+        raise_if_cancelled()
+        try:
+            provider = get_provider(model_name)
+            available = bool(provider and provider.is_available())
+        except OperationCancelled:
+            raise
+        except Exception as error:
+            attempt = _failure_attempt(model_name, model_name, error)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+        if not available:
+            attempt = _unavailable_attempt(model_name)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+        try:
+            from .context import compact_messages, estimate_text_tokens
+
+            prepared_messages = compact_messages(
+                messages,
+                getattr(provider, "context_window", 128_000),
+                reserve_tokens=max(4096, estimate_text_tokens(system) + 4096),
+            )
+            if provider.supports_streaming and not plain_enabled():
+                content = provider.stream_chat(prepared_messages, system=system)
+            else:
+                response = provider.chat(prepared_messages, system=system)
+                content = response.content
+                console.print(content, markup=False)
+            raise_if_cancelled()
+            return content, model_name
+        except OperationCancelled:
+            raise
+        except Exception as error:
+            attempt = _failure_attempt(model_name, provider.name, error)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+
+    _raise_all_models_failed(attempts)
+
+
+def chat_with_fallback(
+    messages: list[Message],
+    system: str = "",
+    preferred: str = None,
+    tools: list[dict] | None = None,
+) -> tuple[Response, str]:
+    config = load_config()
+    order = _model_order(config, preferred)
+
+    attempts: list[FallbackAttempt] = []
+    for index, model_name in enumerate(order):
+        raise_if_cancelled()
+        try:
+            provider = get_provider(model_name)
+            available = bool(provider and provider.is_available())
+        except OperationCancelled:
+            raise
+        except Exception as error:
+            attempt = _failure_attempt(model_name, model_name, error)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+        if not available:
+            attempt = _unavailable_attempt(model_name)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+        try:
+            from .context import compact_messages, estimate_text_tokens
+
+            provider_system = system
+            provider_tools = tools if provider.supports_native_tools else None
+            if tools and not provider.supports_native_tools:
+                from .tool_schema import legacy_tool_instructions
+
+                provider_system = (
+                    f"{system}\n\n{legacy_tool_instructions()}"
+                )
+            tool_schema_tokens = estimate_text_tokens(str(provider_tools or ""))
+            prepared_messages = compact_messages(
+                messages,
+                getattr(provider, "context_window", 128_000),
+                reserve_tokens=max(
+                    4096,
+                    estimate_text_tokens(provider_system) + tool_schema_tokens + 4096,
+                ),
+            )
+            response = provider.chat(
+                prepared_messages,
+                system=provider_system,
+                tools=provider_tools,
+            )
+            raise_if_cancelled()
+            return response, model_name
+        except OperationCancelled:
+            raise
+        except Exception as error:
+            attempt = _failure_attempt(model_name, provider.name, error)
+            attempts.append(attempt)
+            _report_attempt(attempt, has_next=index < len(order) - 1)
+            continue
+
+    _raise_all_models_failed(attempts)

{zai_cli-0.2.2 → zai_cli-0.2.3/zai_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -618,6 +618,12 @@ Providers without an API key are skipped. Ollama is used only when its local
 service is available. Provider quotas and model availability are controlled by
 their respective services and can change independently of `zai`.
 
+When an attempted model fails, `zai` reports the model, a stable failure
+category, secret-redacted provider detail, and the recommended recovery action
+before trying the next configured model. If every model fails, the final error
+lists the complete attempt chain. In `--plain` mode these diagnostics go to
+stderr, leaving successful response text on stdout.
+
 Supported configuration keys:
 
 ```text

{zai_cli-0.2.2 → zai_cli-0.2.3}/zai_cli.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ tests/test_code_runner.py
 tests/test_config_main.py
 tests/test_core.py
 tests/test_errors.py
+tests/test_fallback_diagnostics.py
 tests/test_file_mentions.py
 tests/test_hooks_skills_session.py
 tests/test_input.py

zai_cli-0.2.2/zai/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.2"

zai_cli-0.2.2/zai/core/fallback.py

@@ -1,171 +0,0 @@
-from rich.console import Console
-from ..providers import PROVIDERS
-from ..providers.base import Message, Response
-from ..config import get_model_config, load_config
-from .errors import (
-    AllModelsFailedError,
-    NetworkError,
-    NoAPIKeyError,
-    ProviderError,
-    RateLimitError,
-    classify_provider_error,
-)
-from .runtime import plain_enabled
-from .cancellation import OperationCancelled, raise_if_cancelled
-
-console = Console()
-
-
-def format_model_selection(name: str) -> str:
-    try:
-        model = get_model_config(name)
-    except KeyError:
-        return name
-    return f"{name} -> {model['provider']}/{model['model_id']}"
-
-
-def get_provider(name: str):
-    try:
-        model = get_model_config(name)
-    except KeyError:
-        return None
-    cls = PROVIDERS.get(model["provider"])
-    if not cls:
-        return None
-    provider = cls()
-    provider.model_id = model["model_id"]
-    provider.context_window = model["context_window"]
-    provider.timeout = model.get("timeout", 60)
-    provider.retries = model.get("retries", 2)
-    return provider
-
-
-def _model_order(config: dict, preferred: str = None) -> list[str]:
-    first = preferred or config["default_model"]
-    if not config.get("auto_fallback", True):
-        return [first]
-    return [first] + [
-        model for model in config["fallback_order"]
-        if model != first
-    ]
-
-
-def has_available_provider() -> bool:
-    """Return True when any configured API provider or local provider is usable."""
-    config = load_config()
-    for model_name in _model_order(config):
-        provider = get_provider(model_name)
-        if provider and provider.is_available():
-            return True
-    return False
-
-
-def stream_with_fallback(messages: list[Message], system: str = "", preferred: str = None) -> tuple[str, str]:
-    """Stream response with auto fallback. Returns (content, model_name)."""
-    config = load_config()
-    order = _model_order(config, preferred)
-
-    last_error = None
-    for model_name in order:
-        raise_if_cancelled()
-        provider = get_provider(model_name)
-        if not provider or not provider.is_available():
-            continue
-        try:
-            from .context import compact_messages, estimate_text_tokens
-
-            prepared_messages = compact_messages(
-                messages,
-                getattr(provider, "context_window", 128_000),
-                reserve_tokens=max(4096, estimate_text_tokens(system) + 4096),
-            )
-            if provider.supports_streaming and not plain_enabled():
-                content = provider.stream_chat(prepared_messages, system=system)
-            else:
-                response = provider.chat(prepared_messages, system=system)
-                content = response.content
-                console.print(content, markup=False)
-            raise_if_cancelled()
-            return content, model_name
-        except OperationCancelled:
-            raise
-        except RateLimitError as error:
-            last_error = str(error)
-            console.print(f"[yellow]⚡ {model_name} limit hit — switching...[/yellow]")
-            continue
-        except NoAPIKeyError:
-            continue
-        except (NetworkError, ProviderError) as error:
-            last_error = str(error)
-            console.print(f"[yellow]Network issue with {model_name} — switching...[/yellow]")
-            continue
-        except Exception as error:
-            normalized = classify_provider_error(provider.name, error)
-            console.print(f"[dim]Error with {model_name}: {normalized}[/dim]")
-            last_error = str(normalized)
-            continue
-
-    raise AllModelsFailedError(last_error or "")
-
-
-def chat_with_fallback(
-    messages: list[Message],
-    system: str = "",
-    preferred: str = None,
-    tools: list[dict] | None = None,
-) -> tuple[Response, str]:
-    config = load_config()
-    order = _model_order(config, preferred)
-
-    last_error = None
-    for model_name in order:
-        raise_if_cancelled()
-        provider = get_provider(model_name)
-        if not provider or not provider.is_available():
-            continue
-        try:
-            from .context import compact_messages, estimate_text_tokens
-
-            provider_system = system
-            provider_tools = tools if provider.supports_native_tools else None
-            if tools and not provider.supports_native_tools:
-                from .tool_schema import legacy_tool_instructions
-
-                provider_system = (
-                    f"{system}\n\n{legacy_tool_instructions()}"
-                )
-            tool_schema_tokens = estimate_text_tokens(str(provider_tools or ""))
-            prepared_messages = compact_messages(
-                messages,
-                getattr(provider, "context_window", 128_000),
-                reserve_tokens=max(
-                    4096,
-                    estimate_text_tokens(provider_system) + tool_schema_tokens + 4096,
-                ),
-            )
-            response = provider.chat(
-                prepared_messages,
-                system=provider_system,
-                tools=provider_tools,
-            )
-            raise_if_cancelled()
-            return response, model_name
-        except OperationCancelled:
-            raise
-        except RateLimitError as error:
-            console.print(f"[yellow]⚡ {model_name} limit hit — switching...[/yellow]")
-            last_error = str(error)
-            continue
-        except NoAPIKeyError:
-            continue
-        except (NetworkError, ProviderError) as error:
-            console.print(f"[yellow]Network issue with {model_name} — switching...[/yellow]")
-            last_error = str(error)
-            continue
-        except Exception as error:
-            normalized = classify_provider_error(provider.name, error)
-            console.print(f"[dim]Error with {model_name}: {normalized}[/dim]")
-            last_error = str(normalized)
-            continue
-
-    raise AllModelsFailedError(last_error or "")