zall 0.1.0__tar.gz

zall-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 zall contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zall-0.1.0/PKG-INFO

@@ -0,0 +1,470 @@
+Metadata-Version: 2.4
+Name: zall
+Version: 0.1.0
+Summary: A falsifiable, reproducible coding agent CLI — model-agnostic, chain-hashed, replayable. Features LSP integration, CodeGraph code intelligence, sandbox isolation, plugin system, and MCP support.
+Author: qinrayn (Yuhan Zhang)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/qinrayn/zall
+Project-URL: Repository, https://github.com/qinrayn/zall
+Project-URL: Documentation, https://github.com/qinrayn/zall#readme
+Project-URL: Changelog, https://github.com/qinrayn/zall/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/qinrayn/zall/issues
+Project-URL: CI, https://github.com/qinrayn/zall/actions
+Keywords: coding-agent,cli,ai,llm,developer-tools,reproducible,code-assistant,agent,automation,lsp,code-intelligence,sandbox,mcp,plugin-system,chain-hash
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.5
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.24
+Requires-Dist: rich>=13
+Requires-Dist: prompt_toolkit>=3.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: mypy>=1.7; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: bs4
+Requires-Dist: beautifulsoup4>=4.0; extra == "bs4"
+Provides-Extra: images
+Requires-Dist: pillow>=10.0; extra == "images"
+Provides-Extra: tui
+Requires-Dist: textual>=8.0.0; extra == "tui"
+Provides-Extra: all
+Requires-Dist: zall[bs4,dev,images,tui]; extra == "all"
+Dynamic: license-file
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/zall-v0.1.0-blue?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
+  <img alt="zall" src="https://img.shields.io/badge/zall-v0.1.0-blue?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
+</picture>
+
+<p align="center">
+  <em>A falsifiable, reproducible coding agent CLI — model-agnostic, engineering-grade</em>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-≥3.10-blue" alt="Python ≥3.10"></a>
+  <a href="https://github.com/Qinrayn/zall/actions/workflows/ci.yml"><img src="https://github.com/Qinrayn/zall/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/zall/"><img src="https://img.shields.io/pypi/v/zall" alt="PyPI"></a>
+  <a href="https://pypi.org/project/zall/"><img src="https://img.shields.io/pypi/dm/zall" alt="Downloads"></a>
+  <a href="https://github.com/Qinrayn/zall/stargazers"><img src="https://img.shields.io/github/stars/Qinrayn/zall?style=flat" alt="GitHub Stars"></a>
+  <br>
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="#architecture">Architecture</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## 📦 Installation
+
+```bash
+pip install zall
+```
+
+Requires Python 3.10+. For optional features:
+
+```bash
+pip install "zall[tui]"       # inline/full-screen Textual UI (recommended)
+pip install "zall[bs4]"      # web_fetch with BeautifulSoup HTML parsing
+pip install "zall[images]"    # read_image with Pillow
+pip install "zall[dev]"       # development tools (pytest, mypy, ruff)
+pip install "zall[all]"       # everything
+```
+
+Works on Windows, macOS and Linux (pure-Python wheel, `py3-none-any`).
+
+## 🚀 Quick Start
+
+### 1. Set your API key
+
+```bash
+# OpenAI-compatible API
+export ZALL_API_KEY="sk-..."
+export ZALL_MODEL="gpt-4o"
+
+# Or use Anthropic, Gemini, Ollama, or any OpenAI-compatible provider
+export ZALL_PROVIDER="anthropic"
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### 2. Run a task
+
+```bash
+# One-shot: fix a bug
+zall "refactor the auth module to use async"
+
+# One-shot with verbose output
+zall "write a snake game in Python" --verbose
+
+# Interactive REPL
+zall
+```
+
+### 3. Interactive REPL
+
+```
+> /help                    # Show all commands
+> /model gpt-4o            # Switch model
+> /plan on                 # Read-only mode
+> /lsp status              # Live code diagnostics
+> /codegraph search MyClass  # Find symbols
+> /sandbox process         # Isolated execution
+> /eval                    # Evaluate sessions
+> /replay <id>             # Replay a session
+> /cost                    # Token usage
+> /compact                 # Compress context
+> /doctor                  # Diagnose setup
+```
+
+## ✨ Features
+
+### 🧠 Code Intelligence
+
+| Feature | Description |
+|---------|-------------|
+| **LSP Integration** | Live diagnostics, go-to-definition, hover info, completions. Supports pyright, typescript-language-server, rust-analyzer, gopls, clangd |
+| **CodeGraph** | Multi-language symbol indexer for Python, JS, TS, Rust, Go, Java, C++, Ruby, PHP, Swift |
+| **`code_understanding`** | Combine search + outline + read in one agent call |
+
+### 🛡️ Safety & Reproducibility
+
+| Feature | Description |
+|---------|-------------|
+| **PR-0 Hallucination Detection** | Architectural detection — `stop_reason=STOP` with no tool calls gets flagged |
+| **Chain-hash Timeline** | Every session is cryptographically chained and replayable |
+| **ConfirmGate** | Three-layer safety: rule engine + gate + override audit |
+| **Sensitive-file Protection** | `.env`, SSH private keys, cloud credentials are never read into model context — enforced in `read_file`, `grep` (both engines) and `@file` injection |
+| **Type-ahead Guard** | Keystrokes buffered while the model runs can never auto-approve a confirmation menu (grace window in TUI, stdin flush in REPL) |
+| **Sandbox** | Process isolation with worktree/process/bwrap/container modes |
+| **ToolKind Classification** | 19 semantic tool kinds with read/write detection |
+
+### 🔌 Extensibility
+
+| Feature | Description |
+|---------|-------------|
+| **Plugin System** | Manifest-based plugins with git install, Python entry points |
+| **21 Agent Tools** | read/write/edit/bash/grep/glob/list_dir/search/web_fetch/spawn_subagent + LSP + CodeGraph |
+| **MCP Support** | Connect any MCP server (Model Context Protocol) |
+| **AgentDefinition** | YAML-based agent profiles with toolset presets |
+| **5 Toolset Presets** | `zall`, `explore`, `plan`, `codex`, `opencode` |
+
+### 🎯 Agent Architecture
+
+| Feature | Description |
+|---------|-------------|
+| **Six-Dimension Ontology** | Every `AgentLoop` implements all six dimensions — Identity / Commitment / Perception / Authority / Accountability / Verifiability — enforced by the I-0/I-7 completeness invariants (`tests/test_ontology_invariants.py`) |
+| **ChatState** | Actor-based message management with events, usage tracking, compaction |
+| **AgentBuilder** | Fluent builder for AgentLoop construction |
+| **Subagent & Coordinator** | Typed sub-agents (general-purpose, explore, plan) with capability isolation; thread-parallel spawning + `Coordinator` primitive for dispatch-and-aggregate multi-agent orchestration |
+| **Self-Evolution** | Pi-style extension/lifecycle hooks for auto-learning, usage tracking, pattern discovery; `/suggest` and `/learn` commands for insight and application; high-confidence K-value auto-adjustment; cross-session learned memory injection |
+
+## 🎬 Demo
+
+### One-shot: Create a Snake game
+
+```bash
+zall "Create a classic Snake game in Python with pygame"
+```
+
+zall writes the code, tests it, and fixes any issues automatically:
+
+```
+❯ zall "Create a classic Snake game in Python with pygame"
+● read_file(file_path="snake.py")
+  └ File does not exist yet — will create new
+● write_file(file_path="snake.py", content="...")
+  └ 142 lines written
+● bash(command="python -c 'import pygame; print(pygame.version.ver)'")
+  └ pygame 2.6.1
+● bash(command="python snake.py")
+  └ Process exited with code 0 (game window opened successfully)
+● bash(command="pytest test_snake.py -q")
+  └ 5 passed in 0.32s
+✓ Task completed (8 steps, 2 model calls)
+```
+
+### Interactive Bug Fixing
+
+```bash
+zall  # Start interactive REPL
+```
+
+```
+> /model gpt-4o
+> /lsp status
+  ✓ pyright: active (2 errors, 3 warnings)
+> fix the off-by-one error in binary_search.py
+  ● read_file(src/binary_search.py)
+  ● edit_file(old_string="...", new_string="...")
+  ● bash(command="pytest tests/test_search.py -x -q")
+  └ 12 passed in 0.45s
+✓ Bug fixed in 3 steps
+```
+
+### @file Reference (Claude Code-style)
+
+```bash
+zall "Refactor the auth module @src/auth.py to use async/await"
+```
+
+Files referenced with `@` are automatically injected into the model context — no need for the agent to `read_file` first.
+
+### Multi-step Research Task
+
+```bash
+zall --yes -j "Study the Collatz stopping time for numbers up to 100000"
+```
+
+The agent runs a full research pipeline: write code → execute → analyze → report → detect and fix its own errors:
+
+```
+✓ Collatz study complete: max stopping time=350 (n=77031),
+  mean=107.54 (corrected after agent self-detected its initial
+  mean=114.98 included out-of-range memo keys)
+```
+
+> **PR-0 Hallucination Detection**: The agent independently caught its own mistake — the mean calculation included intermediate memo keys outside the study range. It diagnosed the root cause, fixed the code, and re-ran. This is not a prompt-based guard; it's architectural (IPR-0).
+
+## 🏗️ Architecture
+
+```
+zall/
+├── core/              # Primitives: model, agent, chat_state, gate, goal, safety, tool
+│   ├── loop.py        # AgentLoop orchestrator (synchronous main controller)
+│   ├── loop_config.py # AgentConfig — unified configuration dataclass
+│   ├── loop_events.py # LoopEvent, RunEgress, StepResult
+│   ├── loop_errors.py # ToolNotFound, AgentRunaway, ContextLimitExceeded
+│   ├── tool_kind.py   # ToolKind taxonomy — 19 semantic kinds
+│   ├── policies.py    # CompactionPolicy, ReminderPolicy
+│   ├── agent.py       # AgentDefinition + ToolsetPreset + CapabilityMode
+│   ├── chat_state.py  # Actor-based message management
+│   ├── safety.py      # Three-state context_judge (whitelist/greylist/blacklist)
+│   ├── gate.py        # ConfirmGate state machine (8-state)
+│   └── verifiability.py  # RunRecorder (chain-hash) + TrustAnchor (ed25519)
+├── cli/               # Rich REPL, 25+ slash commands, replay, session management
+├── tools/             # 21 tools: read/write/edit/bash/grep/lsp/codegraph/…
+├── adapters/          # OpenAI-compat, Anthropic, Gemini, Ollama
+├── codegraph/         # Multi-language symbol indexer
+├── lsp/               # LSP client (pyright, rust-analyzer, gopls, clangd)
+├── sandbox/           # Process isolation (worktree/process/bwrap/container)
+├── plugin/            # Plugin system with marketplace
+├── mcp/               # MCP client for Model Context Protocol
+├── safety/            # Rule loader and config management
+├── eval/              # 5-dimensional R-Metric evaluation
+└── skills/            # Skill loader and executor
+```
+
+### Key Design Principles
+
+1. **Model Agnostic (IPR-3)**: Core never imports model SDKs. `ModelAdapter` is a Protocol — adapters are pluggable.
+2. **Immutable First**: All Pydantic models are `frozen=True`. `AgentConfig` is a frozen dataclass.
+3. **Declarative Safety**: `context_judge` uses rule matching (fnmatch glob) — no model calls, no arbitrary code.
+4. **Dual Safety Nets**: GitProtect (git stash) + CheckpointManager (filesystem snapshots).
+5. **Full Audit Trail**: `RunRecorder` + chain-hash SHA-256 + `TrustAnchor` ed25519 signing.
+6. **Self-Falsifying (PR-0)**: Architectural hallucination detection, not prompt-based.
+
+## ⚙️ Configuration
+
+### config.toml
+
+Create `~/.zall/config.toml`:
+
+```toml
+[general]
+default_model = "gpt-4o"
+timeout = 300  # seconds (default: 300, was 120 in v0.4.2)
+
+[openai]
+api_key = "sk-..."
+api_base = "https://api.openai.com/v1"
+
+[anthropic]
+api_key = "sk-ant-..."
+
+[gemini]
+api_key = "..."
+
+[ollama]
+api_base = "http://localhost:11434"
+default_model = "llama3"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ZALL_API_KEY` | API key (highest priority) |
+| `ZALL_MODEL` | Model name override |
+| `ZALL_PROVIDER` | Provider: `openai`, `anthropic`, `gemini`, `ollama` |
+| `ZALL_API_BASE` | Custom API base URL |
+| `ZALL_TIMEOUT` | Request timeout in seconds |
+| `ZALL_VERBOSE` | Enable verbose output |
+| `ZALL_PLAN_MODE` | Enable read-only plan mode |
+
+### Agent Definition Files
+
+Place `.md` files in `.zall/agents/` with YAML frontmatter:
+
+```yaml
+---
+name: my-agent
+description: Custom agent for Python development
+toolset: zall
+permission_mode: auto
+model: gpt-4o
+---
+Your custom system prompt here...
+```
+
+## 📖 API Reference
+
+### Python API
+
+```python
+from zall.core.builder import AgentBuilder
+from zall.core.loop_config import AgentConfig
+from zall.core.goal import GoalType
+from zall.cli.orchestrator import run
+
+# One-shot execution
+egress = run(
+    "refactor the auth module",
+    model="gpt-4o",
+    judge_mode="none",
+    stream=True,
+)
+
+# Programmatic agent loop
+loop = (
+    AgentBuilder()
+    .with_model(adapter)
+    .with_tools(tools)
+    .with_goal(goal)
+    .with_config(AgentConfig(max_steps=30, stream=True))
+    .build()
+)
+egress = loop.run(system_prompt="You are a coding assistant...")
+```
+
+### CLI Reference
+
+```
+zall [task] [options]
+
+Options:
+	  --model TEXT       Model name (overrides config)
+	  --yes, -y          Auto-accept greylist actions
+	  --strict, -S       Strict mode: enable full confirm/downgrade gates
+	  --judge MODE       Judge mode: none (default), system
+	  --json             Output events as NDJSON
+	  --no-stream        Disable token streaming
+	  --max-steps N      Maximum steps before termination
+	  --init             Initialize .zall/ config in current directory
+	  --verbose          Show full tool output
+	  --version, -V      Show version
+
+Commands in REPL:
+  /help, /model, /plan, /lsp, /codegraph, /sandbox,
+  /chatstate, /plugin, /add, /drop, /diff, /search,
+  /web, /git, /commit, /sessions, /resume, /replay,
+  /eval, /cost, /compact, /undo, /retry, /doctor,
+  /checkpoint, /clear, /suggest, /learn
+```
+
+## 🆚 Comparison
+
+### vs Claude Code / Copilot / Cursor
+
+| Feature | zall | Claude Code | GitHub Copilot | Cursor |
+|---------|------|-------------|----------------|--------|
+| Hallucination detection | **Architectural** (PR-0) | Prompt-based | None | None |
+| Reproducibility | Chain-hash + Replay | Log files only | None | None |
+| Safety | 3-layer gate + audit | Implicit | None | Implicit |
+| Model independence | 4 adapters (Protocol) | Anthropic-only | OpenAI/Gemini | OpenAI/Anthropic |
+| Code intelligence | LSP + CodeGraph | Limited | Built-in | Built-in |
+| Sandbox isolation | Process/Worktree modes | None | None | None |
+| Multi-agent orchestration | Parallel subagents + Coordinator | Task/subagent | None | None |
+| Plugin system | Manifest-based | None | Extensions | Extensions |
+| Audit trail | Chain-hash + ed25519 | None | None | None |
+| Open source | ✅ MIT | ❌ | ❌ | ❌ |
+| Self-hostable | ✅ | ❌ | ❌ | ❌ |
+| Local models | ✅ (Ollama) | ❌ | ❌ | ❌ |
+
+## 🧪 Development
+
+```bash
+# Clone and install
+git clone https://github.com/Qinrayn/zall.git
+cd zall
+pip install -e ".[dev,bs4,images]"
+
+# Run tests
+python -m pytest tests/ -q
+
+# Type check
+mypy src/zall/
+
+# Lint
+ruff check src/
+
+# Build
+python -m build
+```
+
+### Test Structure
+
+The project follows **IPR-0**: every invariant has a counterexample test. Tests are organized by component:
+
+```
+tests/
+├── test_loop_invariants.py          # AgentLoop core invariants
+├── test_safety_invariants.py        # context_judge rules
+├── test_gate_invariants.py          # ConfirmGate state machine
+├── test_verifiability_invariants.py # Chain-hash timeline
+├── test_read_file_invariants.py     # ReadFileTool invariants
+├── test_bash_invariants.py          # BashTool invariants
+├── test_chat_state_invariants.py    # ChatState actor
+├── test_lsp_invariants.py           # LSP integration
+├── test_sandbox_invariants.py       # Sandbox isolation
+└── ...
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
+
+- **Report bugs**: [github.com/Qinrayn/zall/issues](https://github.com/Qinrayn/zall/issues)
+- **Feature requests**: Open an issue with the `enhancement` label
+- **Pull requests**: PRs are reviewed within 48 hours
+- **Security issues**: See [SECURITY.md](SECURITY.md)
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 qinrayn (Yuhan Zhang)
+
+## 🙏 Acknowledgements
+
+- **xAI Grok Build** — Architecture inspiration for agent definition, tool taxonomy, and modular design
+- **Claude Code** — Interaction design patterns
+- **OpenAI Function Calling** — API compatibility
+- **MCP Specification** — Model Context Protocol integration