zai-cli 0.1.0__py3-none-any.whl

zai_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,722 @@
+Metadata-Version: 2.4
+Name: zai-cli
+Version: 0.1.0
+Summary: Your personal AI CLI — free, fast, and smart
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
+Project-URL: Repository, https://github.com/HumaizaNaz/zai_cli
+Project-URL: Issues, https://github.com/HumaizaNaz/zai_cli/issues
+Project-URL: Changelog, https://github.com/HumaizaNaz/zai_cli/blob/main/CHANGELOG.md
+Keywords: ai,cli,assistant,gemini,groq,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: prompt-toolkit>=3.0.48
+Requires-Dist: pathspec>=0.12.1
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
+Provides-Extra: groq
+Requires-Dist: groq>=0.11.0; extra == "groq"
+Provides-Extra: cerebras
+Requires-Dist: cerebras-cloud-sdk>=1.0.0; extra == "cerebras"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: all
+Requires-Dist: google-genai>=1.0.0; extra == "all"
+Requires-Dist: groq>=0.11.0; extra == "all"
+Requires-Dist: cerebras-cloud-sdk>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.40.0; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.12.0; extra == "dev"
+Requires-Dist: mypy>=1.16.0; extra == "dev"
+Requires-Dist: pip-audit>=2.9.0; extra == "dev"
+Requires-Dist: tomli>=2.2.1; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# zai
+
+An extensible AI coding assistant for the terminal.
+
+`zai` can chat about a project, inspect and modify files, run commands, resume
+project-specific sessions, switch between model providers, and integrate with
+plugins and MCP servers.
+
+## Requirements
+
+- Python 3.10 or newer
+- At least one supported API key, or a running local Ollama server
+- Optional: Playwright for browser commands
+- Optional: Node.js and `npx` for MCP servers
+
+## Install
+
+```bash
+pip install zai-cli
+zai setup
+```
+
+The PyPI distribution is named `zai-cli`; the installed command and Python
+package remain `zai`.
+
+For local development:
+
+```bash
+pip install -e ".[all,dev]"
+python -m pytest -q
+```
+
+Optional live service checks:
+
+```bash
+ZAI_RUN_LIVE_TESTS=1 python -m pytest tests/integration -m integration
+```
+
+Optional selectors include `ZAI_LIVE_PROVIDER=groq`,
+`ZAI_LIVE_BROWSER=1`, and `ZAI_LIVE_MCP=1`. Live tests can consume provider
+quota or download/start external tools.
+
+## Quick start
+
+```bash
+# Configure providers
+zai setup
+
+# Start the interactive coding assistant in the current directory
+zai
+
+# One-off chat
+zai ask "Explain recursion"
+
+# Explicit chat command
+zai chat "Explain this project"
+
+# Work with code
+zai skill review main.py
+zai repo map
+zai run script.py
+zai git status
+```
+
+## Main commands
+
+```text
+zai                         Start the interactive project assistant
+zai ask <message>           Send a one-off message
+zai chat [message]          Chat with the configured model
+zai --plain ask <message>   Emit only plain final response text
+zai --debug ...             Show full tracebacks for unexpected errors
+
+zai file read <path>        Read a file
+zai file list [directory]   Recursively list files
+zai run <file.py>           Run a Python file
+zai repo map                Build a repository map
+zai repo ask <question>     Ask about a repository
+zai search <query>          Search general DuckDuckGo web results and summarize
+
+zai skill <name> <file>     Run a built-in or plugin skill
+zai git status              Show Git status
+zai git log                 Show recent commits
+zai git diff                Show changes
+zai git commit              Generate and optionally use a commit message
+zai git review              Review current changes
+
+zai vision <image>          Analyze an image with Gemini or Groq
+zai browser scrape <url>    Extract visible page text
+zai browser screenshot <url>
+zai browser analyze <url>
+
+zai model list              List configured models
+zai model set <name>        Set the default model
+zai model fallback on|off   Enable or disable automatic provider fallback
+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 memory show             Show last task metadata
+zai memory projects         List remembered projects
+zai memory clear            Clear memory metadata
+
+zai hook list
+zai hook add <event> <command>
+zai hook remove --id <id>
+
+zai mcp available
+zai mcp list
+zai mcp add <name>
+zai mcp connect <name>
+zai mcp tools
+zai mcp remove <name>
+
+zai plugin list
+zai plugin new <name>
+zai plugin install <name>
+zai plugin trust <name>
+zai plugin untrust <name>
+zai plugin enable <name>
+zai plugin disable <name>
+zai plugin remove <name>
+```
+
+Run `zai --help` for the authoritative command list.
+
+### Plugin and browser security
+
+Plugins execute Python with the same operating-system permissions as `zai`.
+Local and pip-installed plugins therefore remain blocked until their current
+code fingerprint is explicitly trusted:
+
+```bash
+zai plugin install example
+# Review the package or ~/.zai/plugins/example.py first
+zai plugin trust example
+```
+
+Every local plugin requires a `<name>.plugin.json` sidecar manifest. Packaged
+plugins require `zai-plugin.json` in their distribution. Manifests declare the
+plugin name, source, version, and requested permissions from:
+`project_read`, `project_write`, `network`, `subprocess`, and `secrets`.
+
+Trust fingerprints bind both code and manifest. If either changes, the plugin
+is blocked until reviewed and re-trusted. Installing or enabling a plugin asks
+for explicit confirmation. Agent-triggered plugin tools also show declared
+permissions and ask for confirmation. Use `zai plugin untrust <name>` to revoke
+trust.
+
+Browser commands accept only credential-free public HTTP(S) URLs. Localhost,
+private/link-local addresses, unsafe redirects, and non-HTTP schemes are
+blocked. Screenshot output is restricted to PNG/JPEG paths inside the current
+project. Browser downloads are disabled, top-level documents are capped at
+2 MB when the server reports their size, and search responses are capped at
+1 MB.
+
+Vision input is decoded and verified before it is sent to a provider. Images
+are limited to supported raster formats, 10 MB, and 40 megapixels.
+
+## Interactive commands
+
+Inside `zai` interactive mode:
+
+```text
+/help                       Show interactive commands
+/files                      List current project files
+/diff                       Show the Git diff
+/undo                       Undo the latest recorded filesystem action
+/plan <task>                Generate a plan before execution
+/test                       Run pytest and request fixes for failures
+/watch                      Toggle file-change monitoring
+
+/resume [name]              Resume the latest project session or a named one
+/session save [name]        Save the current conversation
+/session load <name>        Load a named conversation
+/session list               List saved conversations
+/session search <query>     Search current-project conversations
+/session rename <old> <new> Rename a saved conversation
+/session delete <name>      Delete a saved conversation
+
+/model list                 List models
+/model <name>               Change model for this interactive session
+/memory                     Show last task metadata
+/commands                   List built-in and plugin slash commands
+```
+
+Command names support safe typo correction when one close, unambiguous match
+exists.
+
+Interactive input also provides:
+
+- persistent history in `~/.zai/input_history` with Up/Down navigation;
+- Tab completion for slash commands, models, sessions, and project paths;
+- multiline input with `Alt+Enter` or `Ctrl+J`;
+- `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
+
+All chat, workflow, utility, and agent requests use the same 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;
+- 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.
+
+## Providers and fallback
+
+The default fallback order is:
+
+```text
+gemini -> groq -> cerebras -> openrouter -> qwen -> claude -> gpt4o -> ollama
+```
+
+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`.
+
+Supported configuration keys:
+
+```text
+GEMINI_API_KEY
+GROQ_API_KEY
+CEREBRAS_API_KEY
+OPENROUTER_API_KEY
+QWEN_API_KEY
+ANTHROPIC_API_KEY
+OPENAI_API_KEY
+```
+
+Keys are stored in `~/.zai/.env` by `zai setup`.
+
+## Sessions and undo
+
+- Successful interactive turns are automatically saved per project.
+- `/resume` loads the latest session for the current project.
+- Sessions have stable IDs and can be resumed by name or ID prefix.
+- Ambiguous partial names are rejected instead of loading the wrong session.
+- Named and legacy sessions remain supported.
+- The latest 100 named sessions are retained; project auto-sessions remain one
+  per project.
+- Undo records are stored under the project's `.zai/undo/` directory.
+- File creation, file edits, folder creation, and path renames are undoable.
+- A non-empty generated folder is never removed by `/undo`.
+
+Add `.zai/` to the project's `.gitignore` to avoid committing local undo data.
+
+## Safety
+
+Model-controlled filesystem actions are restricted to the current project.
+Writes, edits, folder creation, and renames are verified after execution.
+Failed file verification triggers a best-effort rollback.
+
+Shell commands are classified as:
+
+- safe: executed directly;
+- approval required: deletion, dependency changes, downloads, Git state
+  changes, shell chaining, and redirection;
+- blocked: destructive operations such as `git reset --hard`, disk formatting,
+  shutdown commands, and destructive database statements.
+
+Commands run as direct argument arrays with `shell=False`. Shell chaining,
+redirection, command substitution, and shell interpreters are rejected.
+User-defined slash-command substitutions can run only safe allowlisted
+commands. Hooks also use direct executable invocation.
+
+Tool calls use validated JSON schemas. Legacy XML tool calls remain accepted
+temporarily for compatibility.
+
+## Hooks
+
+Available hook events:
+
+```text
+PreToolUse
+PostToolUse
+SessionStart
+SessionEnd
+UserPromptSubmit
+```
+
+Hook commands receive event data as JSON on standard input. Exit code `2`
+blocks the action for blocking events.
+
+Example:
+
+```bash
+zai hook add PreToolUse "python validate_tool.py"
+```
+
+## Browser support
+
+Browser commands require Playwright:
+
+```bash
+pip install playwright
+playwright install chromium
+```
+
+## Development status
+
+`zai` is currently version `0.1.0` and should be treated as a strong beta.
+See `CHANGELOG.md` for release notes and known limitations.
+
+Current quality baseline:
+
+- 440 non-live tests passing
+- 76% measured code coverage with a 75% CI minimum
+- Python 3.10–3.14 test matrix
+- installed-wheel smoke tests on Linux, Windows, and macOS
+- wheel and source-package validation with Twine
+- Ruff critical-rule linting, scoped MyPy checks for browser/search and
+  persistence safety modules, and dependency auditing
+- project-scoped filesystem safety
+- direct command execution with `shell=False`
+- persistent sessions and undo
+- structured and validated tool calls
+
+Review generated changes and command output before using them in important
+repositories.
+
+## Roadmap to a stable CLI
+
+The following phases define the remaining work required before calling `zai`
+stable. Phases should be completed in order because later work depends on the
+reliability established by earlier phases.
+
+### Phase 1: Live service validation
+
+Goal: prove that the mocked provider and integration tests match real external
+services.
+
+Validated on Windows on June 23, 2026:
+
+- Groq chat and native tool-call flows;
+- DuckDuckGo general web search;
+- Playwright Chromium scrape and screenshot flows;
+- filesystem MCP connection, tool discovery, and `list_directory` execution.
+
+Gemini and a paid provider remain pending because credentials were not
+available in the validation environment.
+
+Implementation work:
+
+1. Test Groq with a real API key.
+2. Test Gemini with a real API key.
+3. Test at least one paid provider when credentials are available.
+4. Run the DuckDuckGo live search test.
+5. Install Playwright and test browser scrape and screenshot commands.
+6. Test one MCP server, preferably filesystem or GitHub.
+7. Verify provider fallback by intentionally making the preferred provider
+   unavailable.
+8. Record provider-specific errors and normalize any response differences.
+
+Relevant locations:
+
+```text
+tests/integration/test_live_services.py
+zai/providers/
+zai/tools/search.py
+zai/tools/browser.py
+zai/mcp/
+```
+
+Commands:
+
+```bash
+# Use a configured provider
+ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_PROVIDER=groq \
+python -m pytest tests/integration -m integration -v
+
+# Browser validation
+ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_BROWSER=1 \
+python -m pytest tests/integration -m integration -v
+
+# MCP validation
+ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_MCP=1 \
+python -m pytest tests/integration -m integration -v
+```
+
+Definition of done:
+
+- Groq and Gemini each complete chat and agent tool flows.
+- Browser scrape and screenshot work on Windows and Linux.
+- At least one MCP server connects, lists tools, and executes a tool.
+- Provider fallback is demonstrated against real providers.
+- Live failures produce actionable user-facing messages.
+
+### Phase 2: Terminal user experience
+
+Goal: make interactive use comfortable for long coding sessions.
+
+Completed:
+
+- persistent history and Up/Down navigation using `prompt_toolkit`;
+- slash-command, model, session, and project-path completion;
+- multiline prompts using `Alt+Enter` or `Ctrl+J`;
+- visible input/operation cancellation without ending the session;
+- basic prompt fallback for terminals without an interactive screen buffer.
+
+Global `--debug` enables full tracebacks for unexpected errors. Global
+`--plain` makes one-shot AI requests use non-streaming calls and emit the final
+response without model or token metadata, which is suitable for scripts and CI.
+
+Ctrl+C uses a shared cooperative cancellation token across fallback attempts,
+agent turns, subprocess commands, MCP requests, and plugin-call boundaries.
+Running subprocesses are terminated, MCP servers receive cancellation
+notifications, and session/undo state is saved only for completed turns.
+Synchronous provider SDK calls are interrupted by Ctrl+C where the SDK permits;
+otherwise their result is discarded at the next cancellation boundary.
+
+Definition of done:
+
+- Interactive history survives restart.
+- Common commands and paths autocomplete.
+- Long multiline requests can be entered naturally.
+- Cancellation does not corrupt session or undo state.
+
+### Phase 3: Model and provider configuration
+
+Goal: remove hard-coded model assumptions and make provider configuration easy
+to maintain.
+
+Completed:
+
+1. Custom model IDs and context windows can be stored in user configuration.
+2. Added:
+
+   ```text
+   zai model add
+   zai model remove
+   zai model info
+   zai model test
+   ```
+
+3. Users can select a model ID independently from the provider transport.
+4. Custom aliases are validated before saving.
+5. Existing configuration is normalized to schema version 3.
+6. Interactive completion and fallback include custom aliases.
+7. Per-model timeout and retry settings apply to built-in and custom aliases.
+8. Provider failures are normalized into authentication, quota/rate-limit,
+   model-not-found, timeout, network, and malformed-response categories.
+9. Successful responses display the selected alias, provider, and model ID.
+
+Remaining:
+
+1. Add explicit migrations for schema versions after version 3.
+
+Suggested configuration:
+
+```json
+{
+  "default_model": "groq",
+  "auto_fallback": true,
+  "models": {
+    "groq": {
+      "provider": "groq",
+      "model_id": "provider-model-id",
+      "timeout": 60
+    }
+  }
+}
+```
+
+Definition of done:
+
+- Changing a model never requires editing Python source.
+- Invalid provider/model configuration is rejected clearly.
+- `zai model test <name>` verifies credentials and model availability.
+- Old configuration files migrate automatically.
+
+Context-management work completed alongside this phase:
+
+- model-specific context limits;
+- shared budgeting across chat, workflows, utilities, and agent mode;
+- pinned project context, structured compaction, and bounded tool results;
+- native tool-call/result pair preservation during compaction.
+
+### Phase 4: Large repository performance
+
+Goal: keep repository understanding fast and bounded on large projects.
+
+Implementation work:
+
+1. [x] Respect `.gitignore`, `.ignore`, and configurable ignore patterns.
+2. [x] Enforce file-size, repository-size, indexed-file, and scanned-file limits.
+3. [x] Cache repository maps using paths, modification metadata, and SHA-256 hashes.
+4. [x] Re-extract symbols only for changed files.
+5. [x] Prioritize source files and skip generated, binary, secret, and symlinked files.
+6. [x] Extract symbols from Python, JavaScript/TypeScript, Go, Rust, Java, C#,
+   Ruby, PHP, Swift, and Kotlin.
+7. [x] Bound repository context using the active model's token budget.
+8. [x] Show indexing progress, cache activity, and skipped-file counts.
+
+The incremental cache is stored at `.zai/cache/repomap.json` and should remain
+excluded from version control.
+
+Relevant locations:
+
+```text
+zai/core/repomap.py
+zai/core/context.py
+zai/cli/utilities.py
+```
+
+Performance targets:
+
+- index 10,000 normal source files without loading every complete file;
+- repeated map generation should use cache;
+- default repository context should stay within the active model limit;
+- generated directories and binary files should not enter prompts.
+
+Definition of done:
+
+- [x] large deterministic fixtures cover bounded scans and incremental cache hits;
+- [x] cached scans avoid symbol extraction for unchanged files;
+- [x] context selection is deterministic and token bounded.
+
+### P1.5: Plugin and browser security
+
+Goal: prevent implicit arbitrary-code execution, SSRF, and filesystem escape.
+
+- [x] Require a reviewed code fingerprint before loading local or pip plugins.
+- [x] Require validated manifests and declared permissions before code import.
+- [x] Confirm external installation and re-enabling.
+- [x] Invalidate plugin trust when local code or package records change.
+- [x] Require confirmation before every agent-triggered plugin tool call.
+- [x] Reject plugin names that can escape the plugin directory.
+- [x] Allow browser automation only for public credential-free HTTP(S) URLs.
+- [x] Block private, loopback, link-local, and unsafe redirected requests.
+- [x] Restrict screenshots to supported image files inside the current project.
+- [x] Add regression tests for plugin trust and browser network boundaries.
+
+### Phase 5: Session and undo management
+
+Goal: make session history and filesystem recovery manageable rather than only
+automatic.
+
+Available commands:
+
+```text
+zai session list
+zai session show <name>
+zai session search <query>
+zai session rename <old> <new>
+zai session delete <name>
+zai session export <name> --format md|json
+
+zai undo list
+zai undo show <id>
+zai undo apply [id]
+zai undo redo
+zai undo clear
+```
+
+Completed:
+
+- stable session IDs, titles, creation/update timestamps, and project metadata;
+- top-level `list`, `show`, `search`, `rename`, `delete`, and `export` commands;
+- interactive `/resume`, `/session list|search|rename|delete`;
+- project-scoped listing/search and exact or unambiguous ID/name resolution;
+- Markdown and JSON session export restricted to the selected project;
+- stable undo action IDs, timestamps, summaries, and affected paths;
+- inspectable and selectable multi-step undo;
+- redo and history clearing;
+- conflict detection before restoring files changed outside ZAI;
+- bounded retention for session history and undo backups;
+- project-local cache and recovery data excluded from Git.
+
+Definition of done:
+
+- [x] users can inspect an operation before undoing it;
+- [x] multiple undo and redo operations are deterministic;
+- [x] stale/conflicting restores are blocked safely;
+- [x] sessions can be searched, exported, renamed, and deleted.
+
+### Phase 6: Stable release
+
+Goal: publish a reproducible release that works from a clean installation.
+
+Release procedure:
+
+1. Run all non-live tests:
+
+   ```bash
+   python -m pytest -m "not integration" -q
+   ```
+
+2. Enforce coverage:
+
+   ```bash
+   python -m pytest -m "not integration" \
+     --cov=zai --cov-report=term-missing --cov-fail-under=75
+   ```
+
+3. Run configured live tests.
+4. Build and validate:
+
+   ```bash
+   python scripts/release_preflight.py
+   python -m build
+   python -m twine check dist/*
+   python scripts/release_preflight.py --artifacts dist
+   ```
+
+5. Install the wheel into fresh Windows and Linux virtual environments.
+6. Run smoke tests:
+
+   ```bash
+   zai --version
+   zai --help
+   zai model list
+   zai repo map
+   zai ask "Reply with ok"
+   ```
+
+7. [x] Add a real repository URL to `pyproject.toml`.
+8. [x] Write `CHANGELOG.md`.
+9. Bump the package version.
+10. Run the `Staged package release` workflow with `target=testpypi` and
+    install from TestPyPI.
+11. Run the same workflow with `target=pypi` only after the TestPyPI wheel
+    passes.
+12. Create a signed Git tag and GitHub release.
+
+The publish workflow additionally runs release preflight with
+`--require-repository-url`. Use `target=testpypi` for the staging publish and
+`target=pypi` for the real PyPI publish.
+
+Definition of done:
+
+- clean wheel installation succeeds on Windows and Linux;
+- CI passes for every supported Python version;
+- package data includes all built-in slash commands;
+- TestPyPI installation passes smoke tests;
+- release notes document features, limitations, and migration steps.
+
+## Recommended implementation order
+
+Use this order for the next development cycle:
+
+1. Live Groq validation, because Groq is the primary low-resource cloud option.
+2. Terminal history, autocomplete, multiline input, and cancellation.
+3. Configurable model IDs and `zai model test`.
+4. Repository-map caching and `.gitignore` support.
+5. Multi-step undo/redo and session management.
+6. Fresh wheel installation and TestPyPI release.
+
+Do not add unrelated feature commands until these phases are complete. The
+priority is predictable daily use, recoverability, and release quality.
+
+## License
+
+MIT
+
+# zai_cli