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

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

@@ -5,6 +5,52 @@ 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
+
+- Added structured live-provider validation results with the resolved model,
+  token usage, failure detail, and a recommended next action.
+
+### Changed
+
+- Authentication login validation now distinguishes missing or invalid
+  credentials, quota limits, model configuration errors, network failures, and
+  unexpected provider failures.
+- `zai model test` now reports actionable recovery commands and shows the token
+  cost of a successful validation request when providers return usage data.
+
+## [0.2.1] - 2026-06-30
+
+### Added
+
+- Added `@file` completion in normal interactive prompts.
+- Added safe `@file` mention expansion so prompts like `explain @app.py`
+  include bounded referenced file content.
+
+### Changed
+
+- Mention expansion skips missing, hidden, oversized, binary, and
+  sensitive-looking files without crashing the prompt.
+
 ## [0.2.0] - 2026-06-30
 
 ### Added

{zai_cli-0.2.0/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.0
+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
@@ -198,6 +198,10 @@ zai auth login openai
 zai auth login anthropic
 ```
 
+When prompted, authentication login can send one tiny live request to validate
+the key. The result identifies the resolved model and gives a recovery command
+for invalid credentials, quota limits, model errors, or network failures.
+
 Remove a saved API key from `zai`:
 
 ```bash
@@ -426,7 +430,7 @@ zai model add <name>        Add a custom model alias
 zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
-zai model test <name>       Verify credentials and model availability
+zai model test <name>       Verify credentials/model and show recovery guidance
 zai auth status             Show API-key and external CLI auth status
 zai auth login <provider>   Connect a provider API key
 zai auth logout <provider>  Remove a provider API key from zai
@@ -538,6 +542,18 @@ Interactive input also provides:
 - `Ctrl+C` to cancel the current input or operation without ending the session;
 - a basic Rich prompt fallback in redirected or unsupported terminals.
 
+You can reference files in natural prompts with `@file`:
+
+```text
+explain @app.py
+fix @src/main.py
+compare @README.md and @CHANGELOG.md
+```
+
+`zai` loads bounded text from valid referenced files and appends it to the
+prompt context. Hidden files, sensitive-looking paths, binary files, and very
+large files are skipped with a note instead of crashing the session.
+
 ## How much of my project does zai see?
 
 `zai` starts from the folder where you run it. It does not load every file in a
@@ -602,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.0 → zai_cli-0.2.3}/README.md

@@ -141,6 +141,10 @@ zai auth login openai
 zai auth login anthropic
 ```
 
+When prompted, authentication login can send one tiny live request to validate
+the key. The result identifies the resolved model and gives a recovery command
+for invalid credentials, quota limits, model errors, or network failures.
+
 Remove a saved API key from `zai`:
 
 ```bash
@@ -369,7 +373,7 @@ zai model add <name>        Add a custom model alias
 zai model remove <name>     Remove a custom model alias
 zai model configure <name>  Set timeout and retry policy
 zai model info <name>       Show effective model configuration
-zai model test <name>       Verify credentials and model availability
+zai model test <name>       Verify credentials/model and show recovery guidance
 zai auth status             Show API-key and external CLI auth status
 zai auth login <provider>   Connect a provider API key
 zai auth logout <provider>  Remove a provider API key from zai
@@ -481,6 +485,18 @@ Interactive input also provides:
 - `Ctrl+C` to cancel the current input or operation without ending the session;
 - a basic Rich prompt fallback in redirected or unsupported terminals.
 
+You can reference files in natural prompts with `@file`:
+
+```text
+explain @app.py
+fix @src/main.py
+compare @README.md and @CHANGELOG.md
+```
+
+`zai` loads bounded text from valid referenced files and appends it to the
+prompt context. Hidden files, sensitive-looking paths, binary files, and very
+large files are skipped with a note instead of crashing the session.
+
 ## How much of my project does zai see?
 
 `zai` starts from the folder where you run it. It does not load every file in a
@@ -545,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.0 → zai_cli-0.2.3}/tests/test_auth.py

@@ -14,6 +14,7 @@ from zai.core.auth import (
     mask_secret,
     save_provider_key,
     validate_provider,
+    validate_provider_details,
 )
 
 
@@ -66,18 +67,58 @@ def test_external_login_command_for_codex_and_claude():
 def test_validate_provider_normalizes_results():
     provider = MagicMock()
     provider.is_available.return_value = True
-    provider.chat.return_value = MagicMock()
+    provider.chat.return_value = MagicMock(model="provider/model", tokens_used=7)
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "OK"
+        details = validate_provider_details("groq")
+        assert details.status == "OK"
+        assert details.model == "provider/model"
+        assert details.tokens_used == 7
+        assert "zai model set groq" in details.next_action
 
     provider.chat.side_effect = RuntimeError("unauthorized api key")
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "invalid"
+        details = validate_provider_details("groq")
+        assert details.status == "invalid"
+        assert "zai auth login groq" in details.next_action
 
     provider.chat.side_effect = RuntimeError("rate limit")
     with patch("zai.core.auth.get_provider", return_value=provider):
         assert validate_provider("groq") == "quota/rate limit"
 
+    provider.chat.side_effect = RuntimeError("unknown model does not exist")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert details.status == "model error"
+        assert "zai model info groq" in details.next_action
+
+    provider.chat.side_effect = RuntimeError("unexpected provider failure")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert details.status == "provider error"
+        assert "zai auth doctor" in details.next_action
+
+    provider.chat.side_effect = RuntimeError("api_key=super-secret-provider-token")
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        details = validate_provider_details("groq")
+        assert "super-secret-provider-token" not in details.detail
+        assert "[REDACTED_SECRET]" in details.detail
+
+
+def test_validate_provider_reports_unknown_and_unavailable():
+    unknown = validate_provider_details("unknown")
+    assert unknown.status == "missing"
+    assert unknown.detail == "Unknown provider."
+
+    provider = MagicMock()
+    provider.is_available.return_value = False
+    with patch("zai.core.auth.get_provider", return_value=provider):
+        unavailable = validate_provider_details("groq")
+
+    assert unavailable.status == "missing"
+    assert "zai auth login groq" in unavailable.next_action
+
 
 def test_top_level_auth_status_does_not_print_secret(monkeypatch):
     monkeypatch.setenv("OPENAI_API_KEY", "sk-live-secret")

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/tests/test_file_mentions.py

@@ -0,0 +1,30 @@
+from zai.core.file_mentions import expand_file_mentions, extract_file_mentions
+
+
+def test_extract_file_mentions_keeps_order_and_uniqueness():
+    text = "explain @app.py then compare @README.md and @app.py."
+
+    assert extract_file_mentions(text) == ["app.py", "README.md"]
+
+
+def test_expand_file_mentions_loads_bounded_file_context(tmp_path):
+    (tmp_path / "app.py").write_text("print('hi')\n", encoding="utf-8")
+
+    expanded = expand_file_mentions("explain @app.py", tmp_path)
+
+    assert "explain @app.py" in expanded
+    assert "Referenced @file context" in expanded
+    assert "--- @app.py ---" in expanded
+    assert "print('hi')" in expanded
+
+
+def test_expand_file_mentions_skips_hidden_and_sensitive_files(tmp_path):
+    (tmp_path / ".env").write_text("API_KEY=secret\n", encoding="utf-8")
+    (tmp_path / "token.txt").write_text("secret\n", encoding="utf-8")
+
+    expanded = expand_file_mentions("read @.env and @token.txt", tmp_path)
+
+    assert "API_KEY=secret" not in expanded
+    assert "Mention notes" in expanded
+    assert "Skipped @.env" in expanded
+    assert "Skipped @token.txt" in expanded

{zai_cli-0.2.0 → zai_cli-0.2.3}/tests/test_input.py

@@ -97,6 +97,22 @@ def test_path_completion(tmp_path):
     assert not any(".secret" in candidate[0] for candidate in candidates)
 
 
+def test_file_mention_completion_in_natural_prompt(tmp_path):
+    (tmp_path / "src").mkdir()
+    (tmp_path / "sample.py").write_text("")
+    (tmp_path / ".secret").write_text("")
+
+    candidates = completion_candidates(
+        "explain @s",
+        str(tmp_path),
+        {"fix"},
+    )
+
+    assert ("@src/", "@src/", "file mention") in candidates
+    assert ("@sample.py", "@sample.py", "file mention") in candidates
+    assert not any(".secret" in candidate[0] for candidate in candidates)
+
+
 def test_prompt_falls_back_when_prompt_toolkit_missing(tmp_path):
     real_import = __import__
 

{zai_cli-0.2.0 → zai_cli-0.2.3}/tests/test_interactive.py

@@ -305,6 +305,32 @@ def test_interactive_pins_project_rules_before_agent_call(tmp_path, monkeypatch)
     )
 
 
+def test_interactive_expands_file_mentions_before_agent_call(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "app.py").write_text("print('hello')\n")
+    with patch("zai.cli.interactive.has_available_provider", return_value=True):
+        with patch("zai.cli.interactive.fire_hook", return_value=True):
+            with patch("zai.cli.interactive.plugin_loader.load_all", return_value={}):
+                with patch("zai.cli.interactive.plugin_loader.get_errors", return_value={}):
+                    with patch("zai.cli.interactive._connect_mcp_servers"):
+                        with patch(
+                            "zai.cli.interactive.InteractiveInput.prompt",
+                            side_effect=["explain @app.py", EOFError()],
+                        ):
+                            with (
+                                patch(
+                                    "zai.cli.interactive.run_agent",
+                                    return_value="done",
+                                ) as run_agent,
+                                patch("zai.cli.interactive.Confirm.ask", return_value=False),
+                            ):
+                                run_interactive("groq")
+
+    prompt = run_agent.call_args.args[0]
+    assert "Referenced @file context" in prompt
+    assert "print('hello')" in prompt
+
+
 def test_interactive_manual_compact_summarizes_history(tmp_path, monkeypatch, capsys):
     monkeypatch.chdir(tmp_path)
     prompts = [

{zai_cli-0.2.0 → zai_cli-0.2.3}/tests/test_settings_cli.py

@@ -159,6 +159,7 @@ def test_context_command_is_honest_about_unloaded_files(tmp_path, monkeypatch):
 def test_rules_command_shows_loaded_project_rules(tmp_path, monkeypatch):
     app = settings_app()
     monkeypatch.chdir(tmp_path)
+    (tmp_path / ".git").mkdir()
     (tmp_path / ".zai").mkdir()
     (tmp_path / ".zai" / "rules.md").write_text("Never commit secrets.\n")
 
@@ -271,6 +272,25 @@ def test_model_test_passes_and_reports_unavailable():
     assert "Model unavailable" in unavailable.output
 
 
+def test_model_test_reports_actionable_auth_failure():
+    from zai.core.errors import AuthenticationError
+
+    app = settings_app()
+    runner = CliRunner()
+    provider = MagicMock()
+    provider.name = "groq"
+    provider.is_available.return_value = True
+    provider.chat.side_effect = AuthenticationError("groq", "bad key")
+
+    with patch("zai.core.fallback.get_provider", return_value=provider):
+        result = runner.invoke(app, ["model", "test", "groq"])
+
+    assert result.exit_code == 0
+    assert "invalid credentials" in result.output
+    assert "zai auth login groq" in result.output
+    assert "bad key" in result.output
+
+
 def test_model_configure_updates_builtin_runtime_settings():
     app = settings_app()
     config = {

zai_cli-0.2.3/zai/__init__.py

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

{zai_cli-0.2.0 → zai_cli-0.2.3}/zai/cli/interactive.py

@@ -15,13 +15,14 @@ from ..core.auth import (
     get_auth_provider,
     run_external_login,
     save_provider_key,
-    validate_provider,
+    validate_provider_details,
 )
 from ..core.agent import plan_agent, run_agent, undo_last
 from ..core.commands import get_command_prompt, list_commands, load_commands
 from ..core.compaction import manual_compact_messages
 from ..core.hooks import fire as fire_hook
 from ..core.fallback import has_available_provider
+from ..core.file_mentions import expand_file_mentions
 from ..core.context import ContextManager
 from ..core.memory import add_project, get_last_session, save_session
 from ..core.project_memory import (
@@ -282,14 +283,13 @@ def _run_auth_login(provider: str, *, device: bool = False) -> None:
                 f"Test {info.display_name} now? This sends one tiny request.",
                 default=False,
             ):
-                status = validate_provider(info.key)
-                style = "green" if status == "OK" else "yellow"
-                console.print(f"[{style}]Validation: {status}[/{style}]")
-                if status != "OK":
-                    console.print(
-                        f"[dim]Update it with `/auth login {info.key}` "
-                        f"or remove it with `/auth logout {info.key}`.[/dim]"
-                    )
+                validation = validate_provider_details(info.key)
+                style = "green" if validation.status == "OK" else "yellow"
+                console.print(f"[{style}]Validation: {validation.status}[/{style}]")
+                if validation.model:
+                    console.print(f"[dim]Model: {validation.model}[/dim]")
+                if validation.next_action:
+                    console.print(f"[dim]{validation.next_action.replace('zai ', '/')}[/dim]")
     command = external_login_command(info.key, device=device)
     if command:
         command_text = " ".join(command)
@@ -748,12 +748,13 @@ def run_interactive(model: str = None) -> None:
                     console.print("[red]Usage: /plan <what you want to build>[/red]")
                 else:
                     console.print("[dim]Planning...[/dim]")
-                    plan = plan_agent(task, history, cwd, preferred)
+                    expanded_task = expand_file_mentions(task, cwd)
+                    plan = plan_agent(expanded_task, history, cwd, preferred)
                     if plan and Prompt.ask("[cyan]Proceed?[/cyan]", default="no").lower() in ("yes", "y"):
                         console.print("[dim]Executing...[/dim]")
-                        result = run_agent(task, history, cwd, preferred)
+                        result = run_agent(expanded_task, history, cwd, preferred)
                         if result:
-                            remember_turn(task, result)
+                            remember_turn(expanded_task, result)
                             save_session(task=task[:80], model=preferred)
                             maybe_offer_project_memory(task)
             elif stripped == "/test":
@@ -955,9 +956,10 @@ def run_interactive(model: str = None) -> None:
                     console.print("[dim]Type /commands to see available commands[/dim]")
             else:
                 fire_hook("UserPromptSubmit", {"message": stripped[:200]})
-                result = run_agent(stripped, history, cwd, preferred)
+                expanded = expand_file_mentions(stripped, cwd)
+                result = run_agent(expanded, history, cwd, preferred)
                 if result:
-                    remember_turn(stripped, result)
+                    remember_turn(expanded, result)
                     save_session(task=stripped[:80], model=preferred)
                     maybe_offer_project_memory(stripped)
         except KeyboardInterrupt: