zai-cli 0.1.7__tar.gz → 0.1.9__tar.gz

{zai_cli-0.1.7 → zai_cli-0.1.9}/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.1.9] - 2026-06-30
+
+### Added
+
+- Added provider-neutral token estimation helpers and context usage reporting.
+- Added `zai context tokens`, `zai context summary`, interactive
+  `/context tokens`, and interactive `/context summary`.
+- Added interactive `/compact` to summarize older session history.
+- Added `zai session compact <name-or-id>` for saved sessions.
+- Added compacted-summary metadata to saved session payloads.
+
+### Changed
+
+- Automatic context compaction now uses configurable thresholds and prints a
+  transparent message when older history is summarized.
+- Context status now shows estimated token usage, estimated context limit,
+  remaining tokens, and compacted-summary availability.
+- Long-session summaries redact obvious API keys, bearer tokens, passwords, and
+  secret values before storage/display.
+
+## [0.1.8] - 2026-06-29
+
+### Added
+
+- Added clearer provider/model status output for `zai model list` and
+  interactive `/model`, including provider, cloud/local status, actual model
+  ID, authentication state, and beginner-friendly notes.
+- Added `zai context` and interactive `/context` to show the current folder,
+  project-memory status, repo-map/index status, and honest context visibility
+  notes.
+- Added interactive `/providers` for provider connection status and next
+  actions.
+
+### Changed
+
+- Improved first-run setup copy to explain that `zai` connects to provider
+  backends and that the selected provider decides the model.
+- Improved `zai auth status` and interactive `/auth status` with provider
+  next actions while continuing to avoid printing secret values.
+- Expanded README provider/model/context guidance and clarified that repo maps
+  and project memory are not the same as loading every file into model context.
+
 ## [0.1.7] - 2026-06-28
 
 ### Changed

{zai_cli-0.1.7/zai_cli.egg-info → zai_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -63,6 +63,50 @@ An extensible AI coding assistant for the terminal.
 project-specific sessions, switch between model providers, and integrate with
 plugins and MCP servers.
 
+## What is zai?
+
+`zai` is the terminal CLI. It is not tied to one AI model. It connects to the
+provider you configure, then uses that provider's selected model ID.
+
+Cloud providers need their own API key. Ollama runs on your local machine and
+does not need a cloud API key.
+
+## Which model does zai use?
+
+Run:
+
+```bash
+zai model list
+zai auth status
+zai context
+```
+
+The model list shows the alias, provider, display name, actual model ID, local
+or cloud status, and whether a key is configured.
+
+| Provider | Cloud/local | Key needed | Setup |
+| --- | --- | --- | --- |
+| Groq | Cloud | Yes | `zai auth login groq` |
+| Gemini | Cloud | Yes | `zai auth login gemini` |
+| OpenAI | Cloud | Yes | `zai auth login openai` |
+| Anthropic/Claude | Cloud | Yes | `zai auth login anthropic` |
+| OpenRouter | Cloud | Yes | `zai auth login openrouter` |
+| Cerebras | Cloud | Yes | `zai auth login cerebras` |
+| Qwen/DashScope | Cloud | Yes | `zai auth login qwen` |
+| Ollama | Local | No cloud key | Start Ollama, then `zai model test ollama` |
+
+Quick tester flow:
+
+```bash
+pip install --upgrade --no-cache-dir zai-cli
+zai --version
+zai
+/help
+/model
+/auth status
+/context
+```
+
 ## Requirements
 
 - Python 3.10 or newer
@@ -348,6 +392,7 @@ 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
 zai auth doctor             Show auth troubleshooting guidance
+zai context                 Show loaded project context status
 zai memory show             Show last task metadata
 zai memory projects         List remembered projects
 zai memory project          Show project-scoped memory
@@ -435,6 +480,8 @@ Inside `zai` interactive mode:
 
 /model list                 List models
 /model <name>               Change model for this interactive session
+/providers                  Show provider connection status
+/context                    Show loaded project context status
 /memory                     Show last task metadata
 /commands                   List built-in and plugin slash commands
 ```
@@ -450,22 +497,57 @@ 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.
 
-## Context management
+## 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
+large repository into every prompt.
+
+Use `zai context` or `/context` to inspect the current folder, whether project
+memory exists, whether a repo-map cache is available, and how many conversation
+messages are loaded in the current interactive session.
+
+For token/context usage:
+
+```text
+zai context tokens
+zai context summary
+/context tokens
+/context summary
+/compact
+```
+
+`zai context tokens` and `/context tokens` show an approximate provider-neutral
+token estimate, the configured context limit, remaining tokens, and whether the
+session is approaching the compaction threshold.
+
+Project memory is separate from current model context. It is a small
+`.zai/project_memory.json` summary created with `zai memory refresh` or
+`/memory refresh`.
+
+Repo maps are summaries/indexes used on demand for repository questions. They
+are not full source files loaded into every model call. If a file has not been
+read or indexed for the current task, treat it as not loaded yet.
+
+For long interactive sessions, `/compact` summarizes older conversation and
+tool history so the active session can continue with less context pressure. The
+summary preserves the goal, decisions, recent work, commands/results where
+visible, and pending context in a compact form.
 
-All chat, workflow, utility, and agent requests use the same model-aware
-context pipeline:
+All chat, workflow, utility, and agent requests use a model-aware context
+pipeline:
 
 - the active provider's configured context window sets the request budget;
 - system prompts, tool schemas, and output space are reserved before messages;
 - initial project instructions and explicitly pinned messages are retained;
 - assistant tool calls remain paired with their tool-result messages;
 - oversized tool results keep their beginning and end with an omission marker;
-- older turns are compacted into a structured summary while recent turns stay
-  verbatim;
+- requests are bounded to fit the selected model's context limit;
 - context usage uses a conservative shared token estimate, while provider
   response usage is retained where the SDK reports it.
 
-This replaces the previous fixed 100k limit and manual last-message truncation.
+This keeps requests bounded. Compaction is still approximate, so save important
+stable project facts explicitly with `/remember <fact>` or `zai memory remember
+<fact>`.
 
 ## Providers and fallback
 

{zai_cli-0.1.7 → zai_cli-0.1.9}/README.md

@@ -6,6 +6,50 @@ An extensible AI coding assistant for the terminal.
 project-specific sessions, switch between model providers, and integrate with
 plugins and MCP servers.
 
+## What is zai?
+
+`zai` is the terminal CLI. It is not tied to one AI model. It connects to the
+provider you configure, then uses that provider's selected model ID.
+
+Cloud providers need their own API key. Ollama runs on your local machine and
+does not need a cloud API key.
+
+## Which model does zai use?
+
+Run:
+
+```bash
+zai model list
+zai auth status
+zai context
+```
+
+The model list shows the alias, provider, display name, actual model ID, local
+or cloud status, and whether a key is configured.
+
+| Provider | Cloud/local | Key needed | Setup |
+| --- | --- | --- | --- |
+| Groq | Cloud | Yes | `zai auth login groq` |
+| Gemini | Cloud | Yes | `zai auth login gemini` |
+| OpenAI | Cloud | Yes | `zai auth login openai` |
+| Anthropic/Claude | Cloud | Yes | `zai auth login anthropic` |
+| OpenRouter | Cloud | Yes | `zai auth login openrouter` |
+| Cerebras | Cloud | Yes | `zai auth login cerebras` |
+| Qwen/DashScope | Cloud | Yes | `zai auth login qwen` |
+| Ollama | Local | No cloud key | Start Ollama, then `zai model test ollama` |
+
+Quick tester flow:
+
+```bash
+pip install --upgrade --no-cache-dir zai-cli
+zai --version
+zai
+/help
+/model
+/auth status
+/context
+```
+
 ## Requirements
 
 - Python 3.10 or newer
@@ -291,6 +335,7 @@ 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
 zai auth doctor             Show auth troubleshooting guidance
+zai context                 Show loaded project context status
 zai memory show             Show last task metadata
 zai memory projects         List remembered projects
 zai memory project          Show project-scoped memory
@@ -378,6 +423,8 @@ Inside `zai` interactive mode:
 
 /model list                 List models
 /model <name>               Change model for this interactive session
+/providers                  Show provider connection status
+/context                    Show loaded project context status
 /memory                     Show last task metadata
 /commands                   List built-in and plugin slash commands
 ```
@@ -393,22 +440,57 @@ 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.
 
-## Context management
+## 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
+large repository into every prompt.
+
+Use `zai context` or `/context` to inspect the current folder, whether project
+memory exists, whether a repo-map cache is available, and how many conversation
+messages are loaded in the current interactive session.
+
+For token/context usage:
+
+```text
+zai context tokens
+zai context summary
+/context tokens
+/context summary
+/compact
+```
+
+`zai context tokens` and `/context tokens` show an approximate provider-neutral
+token estimate, the configured context limit, remaining tokens, and whether the
+session is approaching the compaction threshold.
+
+Project memory is separate from current model context. It is a small
+`.zai/project_memory.json` summary created with `zai memory refresh` or
+`/memory refresh`.
+
+Repo maps are summaries/indexes used on demand for repository questions. They
+are not full source files loaded into every model call. If a file has not been
+read or indexed for the current task, treat it as not loaded yet.
+
+For long interactive sessions, `/compact` summarizes older conversation and
+tool history so the active session can continue with less context pressure. The
+summary preserves the goal, decisions, recent work, commands/results where
+visible, and pending context in a compact form.
 
-All chat, workflow, utility, and agent requests use the same model-aware
-context pipeline:
+All chat, workflow, utility, and agent requests use a model-aware context
+pipeline:
 
 - the active provider's configured context window sets the request budget;
 - system prompts, tool schemas, and output space are reserved before messages;
 - initial project instructions and explicitly pinned messages are retained;
 - assistant tool calls remain paired with their tool-result messages;
 - oversized tool results keep their beginning and end with an omission marker;
-- older turns are compacted into a structured summary while recent turns stay
-  verbatim;
+- requests are bounded to fit the selected model's context limit;
 - context usage uses a conservative shared token estimate, while provider
   response usage is retained where the SDK reports it.
 
-This replaces the previous fixed 100k limit and manual last-message truncation.
+This keeps requests bounded. Compaction is still approximate, so save important
+stable project facts explicitly with `/remember <fact>` or `zai memory remember
+<fact>`.
 
 ## Providers and fallback
 

{zai_cli-0.1.7 → zai_cli-0.1.9}/tests/test_interactive.py

@@ -83,10 +83,15 @@ def test_interactive_key_setup_saves_entered_key(capsys):
 
     with patch("zai.cli.setup_wizard.get_api_key", return_value=None):
         with patch("zai.cli.setup_wizard.Confirm.ask", return_value=False):
-            with patch("zai.cli.setup_wizard.Prompt.ask", side_effect=lambda *a, **k: next(answers)):
-                with patch("zai.cli.setup_wizard.save_provider_key") as save_key:
-                    with patch("zai.cli.setup_wizard.has_available_provider", side_effect=[False, True, True]):
-                        assert _run_key_setup_interactive()
+                with patch("zai.cli.setup_wizard.Prompt.ask", side_effect=lambda *a, **k: next(answers)):
+                    with patch("zai.cli.setup_wizard.save_provider_key") as save_key:
+                        with patch("zai.cli.setup_wizard.has_available_provider", side_effect=[False, True, True]):
+                            with patch(
+                                "zai.cli.setup_wizard.load_config",
+                                return_value={"default_model": "gemini"},
+                            ):
+                                with patch("zai.cli.setup_wizard.save_config"):
+                                    assert _run_key_setup_interactive()
 
     output = capsys.readouterr().out
     assert "zai setup" in output
@@ -227,13 +232,89 @@ def test_interactive_auth_commands_do_not_call_ai(tmp_path, monkeypatch, capsys)
                                 run_interactive("groq")
 
     output = capsys.readouterr().out
-    assert "Authentication status" in output
+    assert "Provider status" in output
     assert "Saved Gemini API key" in output
     save.assert_called_once_with("gemini", "gemini-key")
     delete.assert_called_once_with("gemini")
     run_agent.assert_not_called()
 
 
+def test_interactive_context_and_providers_do_not_call_ai(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "app.py").write_text("print('hi')\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=[
+                                "/providers",
+                                "/context",
+                                "/context tokens",
+                                "/context summary",
+                                EOFError(),
+                            ],
+                        ):
+                            with patch("zai.cli.interactive.run_agent") as run_agent:
+                                run_interactive("groq")
+
+    output = capsys.readouterr().out
+    assert "Provider status" in output
+    assert "Project context" in output
+    assert "unread files are not loaded" in output
+    assert "Estimated tokens used" in output
+    assert "No compacted summary" in output
+    assert "app.py is loaded" not in output
+    run_agent.assert_not_called()
+
+
+def test_interactive_manual_compact_summarizes_history(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    prompts = [
+        "task one",
+        "task two",
+        "task three",
+        "task four",
+        "task five",
+        "/compact",
+        "/context summary",
+        EOFError(),
+    ]
+    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=prompts,
+                        ):
+                            with (
+                                patch(
+                                    "zai.cli.interactive.run_agent",
+                                    side_effect=[
+                                        "answer one",
+                                        "answer two",
+                                        "answer three",
+                                        "answer four",
+                                        "answer five",
+                                    ],
+                                ),
+                                patch(
+                                    "zai.cli.interactive.Confirm.ask",
+                                    return_value=False,
+                                ),
+                            ):
+                                run_interactive("groq")
+
+    output = capsys.readouterr().out
+    assert "Context compacted" in output
+    assert "Current compacted summary" in output
+    assert "task one" in output
+
+
 def test_interactive_offers_project_memory_after_agent_task(tmp_path, monkeypatch, capsys):
     from zai.core.project_memory import load_project_memory
 

{zai_cli-0.1.7 → zai_cli-0.1.9}/tests/test_settings_cli.py

@@ -1,3 +1,4 @@
+from io import StringIO
 from unittest.mock import MagicMock, patch
 
 import typer
@@ -26,6 +27,7 @@ def test_setup_wizard_saves_entered_key():
     from zai.cli.setup_wizard import run_setup_wizard
 
     answers = iter(["groq", "groq-key", "groq", "done"])
+    console_file = StringIO()
     with (
         patch("zai.cli.setup_wizard.has_available_provider", side_effect=[False, True, True]),
         patch("zai.cli.setup_wizard.get_api_key", return_value=None),
@@ -38,8 +40,12 @@ def test_setup_wizard_saves_entered_key():
         patch("zai.cli.setup_wizard.load_config", return_value={"default_model": "gemini"}),
         patch("zai.cli.setup_wizard.save_config") as save_config,
     ):
-        assert run_setup_wizard(console=Console(file=MagicMock())) is True
+        assert run_setup_wizard(console=Console(file=console_file)) is True
 
+    output = console_file.getvalue()
+    assert "zai is the CLI" in output
+    assert "Cloud providers need their own API key" in output
+    assert "Active provider/model" in output
     save_key.assert_called_once_with("groq", "groq-key")
     save_config.assert_called()
 
@@ -79,11 +85,13 @@ def test_model_list_set_fallback_and_usage():
     ):
         selected = runner.invoke(app, ["model", "set", "groq"])
         fallback = runner.invoke(app, ["model", "fallback", "off"])
-    unknown = runner.invoke(app, ["model", "set", "missing"])
-    usage = runner.invoke(app, ["model", "fallback", "maybe"])
+    with patch("zai.cli.settings.load_config", return_value=config):
+        unknown = runner.invoke(app, ["model", "set", "missing"])
+        usage = runner.invoke(app, ["model", "fallback", "maybe"])
 
     assert "Available Models" in listed.output
-    assert "gemini-3.5-flash" in listed.output
+    assert "Model ID" in listed.output
+    assert "gemini" in listed.output
     assert "Default model set to" in selected.output
     assert "Automatic model fallback" in fallback.output
     assert config["default_model"] == "groq"
@@ -93,6 +101,74 @@ def test_model_list_set_fallback_and_usage():
     assert "Usage: zai model" in usage.output
 
 
+def test_model_list_explains_provider_model_and_auth_without_secret(monkeypatch):
+    app = settings_app()
+    config = {
+        "default_model": "groq",
+        "fallback_order": ["groq"],
+        "model_overrides": {},
+        "auto_fallback": True,
+    }
+    monkeypatch.setenv("GROQ_API_KEY", "sk-secret-value")
+
+    with patch("zai.cli.settings.load_config", return_value=config):
+        result = CliRunner().invoke(app, ["model", "list"])
+
+    assert result.exit_code == 0
+    assert "Provider" in result.output
+    assert "Model ID" in result.output
+    assert "cloud" in result.output
+    assert "openai/gpt-oss-120b" in result.output
+    assert "key configured" in result.output
+    assert "sk-secret-value" not in result.output
+
+
+def test_auth_status_shows_provider_next_actions_without_secret(monkeypatch):
+    app = settings_app()
+    monkeypatch.setenv("GEMINI_API_KEY", "gemini-secret")
+
+    result = CliRunner().invoke(app, ["auth", "status"])
+
+    assert result.exit_code == 0
+    assert "Provider status" in result.output
+    assert "auth login" in result.output
+    assert "groq" in result.output
+    assert "key configured" in result.output
+    assert "gemini-secret" not in result.output
+
+
+def test_context_command_is_honest_about_unloaded_files(tmp_path, monkeypatch):
+    app = settings_app()
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "app.py").write_text("print('hi')\n")
+
+    result = CliRunner().invoke(app, ["context"])
+
+    assert result.exit_code == 0
+    assert f"Folder: {tmp_path}" in result.output
+    assert "Project memory: missing" in result.output
+    assert "Repo map/index: not loaded yet" in result.output
+    assert "unread files are not loaded" in result.output
+    assert "Estimated tokens used" in result.output
+    assert "app.py is loaded" not in result.output
+
+
+def test_context_tokens_and_summary_commands(tmp_path, monkeypatch):
+    app = settings_app()
+    monkeypatch.chdir(tmp_path)
+
+    tokens = CliRunner().invoke(app, ["context", "tokens"])
+    summary = CliRunner().invoke(app, ["context", "summary"])
+    bad = CliRunner().invoke(app, ["context", "bad"])
+
+    assert tokens.exit_code == 0
+    assert "Estimated tokens used" in tokens.output
+    assert "Compacted summary" in tokens.output
+    assert summary.exit_code == 0
+    assert "No compacted summary" in summary.output
+    assert "Usage: zai context" in bad.output
+
+
 def test_model_check_reports_valid_and_invalid_configuration():
     app = settings_app()
     runner = CliRunner()
@@ -349,6 +425,27 @@ def test_session_rename_delete_and_export():
     assert "Export failed" in export_failed.output
 
 
+def test_session_compact_routes_history():
+    from zai.providers.base import Message
+
+    app = settings_app()
+    history = [
+        Message(role="user", content=f"message {index}")
+        for index in range(12)
+    ]
+    info = {"name": "auth", "project_path": "project"}
+    with (
+        patch("zai.cli.settings.load_history", return_value=history),
+        patch("zai.cli.settings.get_session_info", return_value=info),
+        patch("zai.cli.settings.save_history") as save,
+    ):
+        result = CliRunner().invoke(app, ["session", "compact", "auth"])
+
+    assert result.exit_code == 0
+    assert "Session compacted" in result.output
+    save.assert_called_once()
+
+
 def test_undo_list_empty_and_populated():
     app = settings_app()
     runner = CliRunner()

zai_cli-0.1.9/tests/test_tokens.py

@@ -0,0 +1,57 @@
+from zai.core.compaction import manual_compact_messages
+from zai.core.tokens import (
+    compacted_summaries,
+    context_usage,
+    estimate_messages_tokens,
+    estimate_tokens,
+    redact_secrets,
+)
+from zai.providers.base import Message
+
+
+def test_estimate_tokens_is_stable_and_nonzero():
+    assert estimate_tokens("") == 0
+    assert estimate_tokens("hello world") >= 2
+    assert estimate_tokens("x" * 120) >= 40
+
+
+def test_context_usage_reports_thresholds():
+    messages = [Message(role="user", content="x" * 900)]
+    usage = context_usage(messages, context_limit=100)
+
+    assert usage.tokens_used == estimate_messages_tokens(messages)
+    assert usage.tokens_remaining == 0
+    assert usage.should_warn is True
+    assert usage.should_compact is True
+
+
+def test_secret_redaction_covers_common_patterns():
+    text = (
+        "OPENAI_API_KEY=sk-abcdefghijklmnopqrstuvwxyz "
+        "Authorization: Bearer abcdefghijklmnopqrstuvwxyz "
+        "password=hunter2"
+    )
+    redacted = redact_secrets(text)
+
+    assert "sk-abcdefghijklmnopqrstuvwxyz" not in redacted
+    assert "abcdefghijklmnopqrstuvwxyz" not in redacted
+    assert "hunter2" not in redacted
+    assert "[REDACTED_SECRET]" in redacted
+
+
+def test_manual_compaction_creates_summary_and_keeps_recent_messages():
+    messages = [
+        Message(role="user", content="initial goal"),
+        Message(role="assistant", content="decision made"),
+        Message(role="tool", content="api_key=sk-secretsecretsecret", tool_name="run"),
+    ]
+    messages.extend(Message(role="user", content=f"step {index}") for index in range(12))
+
+    compacted, summary = manual_compact_messages(messages, max_tokens=128_000, keep_recent=4)
+
+    assert summary is not None
+    assert "initial goal" in summary.content
+    assert "decision made" in summary.content
+    assert "sk-secretsecretsecret" not in summary.content
+    assert compacted[-1].content == "step 11"
+    assert compacted_summaries(compacted)

zai_cli-0.1.9/zai/__init__.py

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