queravel-cli 0.9.27__tar.gz

queravel_cli-0.9.27/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: queravel-cli
+Version: 0.9.27
+Summary: Queravel CLI — an agentic coding assistant for the terminal
+Author: Queravel
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.40
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.80
+Requires-Dist: prompt_toolkit>=3.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: python-socketio[client]>=5.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: certifi>=2024.0
+Requires-Dist: sounddevice>=0.4
+Requires-Dist: numpy>=1.24
+Requires-Dist: websockets>=12
+Requires-Dist: segno>=1.5
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Queravel CLI
+
+An agentic coding assistant for your terminal — reads and writes your local codebase, runs
+builds/tests/git, and drives long-running tasks — built on Queravel's agent engine. Runs on the
+free **Queravel** models by default (Kimi K3 / GLM 5.3 Flash / DeepSeek V4.1 Flash) — **no third-party
+API keys required**.
+
+> **Status:** Phase 1 core is live: Textual TUI, diff review, **plan mode + permission modes**,
+> **todos**, **sub-agents**, and **context auto-compaction**. It finds code by **agentic search
+> (grep/glob/read) — no RAG, no index**. See `memory/phase-status.md`.
+
+## Install
+
+```bash
+# One-liner (macOS / Linux) — installs the binary + keeps it auto-updated:
+curl -fsSL https://queravel.com/install.sh | sh
+#   Windows (PowerShell):  irm https://queravel.com/install.ps1 | iex
+
+# Homebrew:
+brew install SiliconBlast/queravel/queravel
+
+# Python (pipx):
+pipx install queravel-cli
+
+# From a clone (dev):
+git clone <repo> && cd queravel-cli && make dev
+```
+
+Then run `queravel` in any repo. First time in a project, `queravel init` writes a
+`QUERAVEL.md` so the agent learns your build/test commands and conventions.
+
+```bash
+queravel design "a landing page for my app"   # generate a self-contained HTML page locally + open it (/design in the TUI)
+queravel --browser "check if example.com loads"   # browser automation via Playwright MCP (navigate/click/type/screenshot)
+queravel research "how does WASM GC work" --breadth 5   # multi-agent deep research → cited report (/research in the TUI)
+```
+
+Deep research fans out one web sub-agent per angle in parallel, verifies claims against sources, and
+writes a cited Markdown report. **Search backend:** when you're **signed in** (`queravel login`),
+search routes through **Queravel's own engine** — 15 free providers + neural rerank + cache, **no key
+needed**. Signed out, it falls back to `TAVILY_API_KEY` → `BRAVE_API_KEY` → keyless (Wikipedia + DDG
+instant answers). Force the local path with `QUERAVEL_WEB_SEARCH=direct`.
+
+Switch models in the TUI with **`/model`** (no id → interactive picker) or `/model <id>`.
+
+**Voice input** — in the TUI, `/voice` records from your mic and drops the transcript into the prompt
+(you review before sending). Install the extra and set a speech-to-text key:
+`pip install 'queravel-cli[voice]'` + `GROQ_API_KEY` (fast) or `OPENAI_API_KEY`.
+
+## Auth
+
+Uses the free Queravel Fireworks models. The key is read at runtime from `FIREWORKS_API_KEY`, or
+(dev convenience) from the Queravel *personal* backend's `.env`. Nothing is stored in this repo.
+
+```bash
+export FIREWORKS_API_KEY=fw_...        # optional if the personal backend .env has it
+```
+
+To use another provider's model, set its API key and pass `--model <id>`.
+
+## Use
+
+```bash
+queravel                       # interactive TUI
+queravel "refactor utils.py to remove the duplicate helper"   # TUI, pre-seeded with a first task
+queravel -p "run the tests and summarize failures"            # headless (print) mode, no TUI
+
+# Sessions — resume where you left off
+queravel -c "and now add tests for it"     # --continue: resume the latest session in this dir
+queravel --resume                          # pick from a list (this dir; Ctrl+A = all dirs, / = search)
+queravel --resume 20260917-004541-645844   # resume a specific session id directly
+queravel --resume <id> --fork-session      # branch it into a NEW session (original untouched)
+
+# In the picker: →/← expand a group's branches, / to search (or paste a PR URL to
+# find the session that opened it). In a session, /branch forks the current thread.
+
+# Options
+queravel --model glm-5.3-flash --cwd /path/to/repo "..."   # models: kimi-k3 | glm-5.3-flash | deepseek-v4.1-flash
+queravel --auto -p "create hello.py and run it"      # auto-approve side effects (scratch targets)
+```
+
+### Approval / permission modes
+
+```bash
+queravel                 # default: prompt every side effect (edits show a diff to accept/reject)
+queravel --accept-edits  # auto-approve file edits; still confirm shell commands
+queravel --plan          # read-only: research & propose a plan, change nothing
+queravel --auto          # approve everything except denied/dangerous commands
+```
+
+Cycle modes live with **Ctrl+P → "Cycle approval mode"**. Manage **allow / ask / deny** rules
+interactively with **`/permissions`** (add/remove, user or project scope), or edit
+`~/.queravel/settings.json` / `.queravel/settings.json` directly:
+`{"permissions": {"allow": ["Bash(npm test:*)", "Read(src/*)"], "ask": ["Bash(git push*)"], "deny": ["WebFetch(domain:evil.com)"]}}`.
+Rule syntax: `Bash(<glob>)`, `Read/Write/Edit(<glob>)`, `WebFetch(domain:x)`,
+`mcp__server__tool`, a bare tool name, or `*`. Precedence is **deny > ask > allow**; dangerous
+commands (`rm -rf`, fork bombs, `curl|sh`, force-push, …) never auto-run.
+
+### Power features
+
+- **Todos** — the agent plans multi-step work; a live panel tracks progress.
+- **Sub-agents** — it delegates large investigations to an isolated **read-only** sub-agent (`task`)
+  that returns a findings report, keeping the main context clean.
+- **Context auto-compaction** — long sessions summarize older turns automatically to stay in-window.
+- **Checkpoint / undo** — every file edit is snapshotted; `/undo` reverts the last change.
+- **Hooks** — run shell commands at `PreToolUse` (non-zero exit blocks the tool) / `PostToolUse`
+  (e.g. auto-format after edits) via `settings.json`; matched by a regex on the tool name.
+- **QUERAVEL.md `@`-imports** — recursively include other files into your project memory.
+- **Agentic search, not RAG** — it navigates your repo with grep/glob/read on demand (always fresh,
+  no index to build).
+
+## Project memory — `QUERAVEL.md`
+
+Drop a `QUERAVEL.md` in your repo (and/or `~/.queravel/QUERAVEL.md` for global prefs). Its contents
+are injected into the agent's system prompt every run, so your project conventions, build/test
+commands, and do's/don'ts persist without re-explaining.
+
+Sessions are saved under `~/.queravel/sessions/`; the system prompt (and thus `QUERAVEL.md`) is
+rebuilt on every run, so editing `QUERAVEL.md` always takes effect — even on `--continue`.
+
+## Web & MCP
+
+- **Web tools**: the agent can `web_fetch` a URL and `web_search` (set `TAVILY_API_KEY` for a
+  reliable search API; otherwise a best-effort keyless search is used).
+- **MCP servers**: connect external tool servers (standard MCP config) in
+  `~/.queravel/mcp.json` or `.queravel/mcp.json`:
+  ```json
+  {"mcpServers": {"github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]}}}
+  ```
+  Their tools appear as `mcp__<server>__<tool>` and are gated by your approval mode.
+
+## Tools (Phase 0/1)
+
+`read_file` · `write_file` · `edit_file` (surgical) · `multi_edit` (atomic multi-change) ·
+`list_dir` · `glob` · `grep` · `run_command` (bash). All execute **in-process on your machine**,
+whole-repo, no cloud caps.
+
+## Architecture (short)
+
+A local, provider-agnostic tool-use loop (`adapters/base.py`) — Fireworks (OpenAI-compatible) by
+default, with optional BYOK providers — driving in-process local tools, rendered through a UI abstraction
+(`ui.py`) that backs both the Textual TUI (`tui.py`) and the headless `-p` mode. Mirrors the shape
+of Queravel's backend agent engine so it can be extracted and shared (Phase 1 next step). See
+`memory/` for the concept, decisions, and engine-extraction plan.

queravel_cli-0.9.27/README.md

@@ -0,0 +1,144 @@
+# Queravel CLI
+
+An agentic coding assistant for your terminal — reads and writes your local codebase, runs
+builds/tests/git, and drives long-running tasks — built on Queravel's agent engine. Runs on the
+free **Queravel** models by default (Kimi K3 / GLM 5.3 Flash / DeepSeek V4.1 Flash) — **no third-party
+API keys required**.
+
+> **Status:** Phase 1 core is live: Textual TUI, diff review, **plan mode + permission modes**,
+> **todos**, **sub-agents**, and **context auto-compaction**. It finds code by **agentic search
+> (grep/glob/read) — no RAG, no index**. See `memory/phase-status.md`.
+
+## Install
+
+```bash
+# One-liner (macOS / Linux) — installs the binary + keeps it auto-updated:
+curl -fsSL https://queravel.com/install.sh | sh
+#   Windows (PowerShell):  irm https://queravel.com/install.ps1 | iex
+
+# Homebrew:
+brew install SiliconBlast/queravel/queravel
+
+# Python (pipx):
+pipx install queravel-cli
+
+# From a clone (dev):
+git clone <repo> && cd queravel-cli && make dev
+```
+
+Then run `queravel` in any repo. First time in a project, `queravel init` writes a
+`QUERAVEL.md` so the agent learns your build/test commands and conventions.
+
+```bash
+queravel design "a landing page for my app"   # generate a self-contained HTML page locally + open it (/design in the TUI)
+queravel --browser "check if example.com loads"   # browser automation via Playwright MCP (navigate/click/type/screenshot)
+queravel research "how does WASM GC work" --breadth 5   # multi-agent deep research → cited report (/research in the TUI)
+```
+
+Deep research fans out one web sub-agent per angle in parallel, verifies claims against sources, and
+writes a cited Markdown report. **Search backend:** when you're **signed in** (`queravel login`),
+search routes through **Queravel's own engine** — 15 free providers + neural rerank + cache, **no key
+needed**. Signed out, it falls back to `TAVILY_API_KEY` → `BRAVE_API_KEY` → keyless (Wikipedia + DDG
+instant answers). Force the local path with `QUERAVEL_WEB_SEARCH=direct`.
+
+Switch models in the TUI with **`/model`** (no id → interactive picker) or `/model <id>`.
+
+**Voice input** — in the TUI, `/voice` records from your mic and drops the transcript into the prompt
+(you review before sending). Install the extra and set a speech-to-text key:
+`pip install 'queravel-cli[voice]'` + `GROQ_API_KEY` (fast) or `OPENAI_API_KEY`.
+
+## Auth
+
+Uses the free Queravel Fireworks models. The key is read at runtime from `FIREWORKS_API_KEY`, or
+(dev convenience) from the Queravel *personal* backend's `.env`. Nothing is stored in this repo.
+
+```bash
+export FIREWORKS_API_KEY=fw_...        # optional if the personal backend .env has it
+```
+
+To use another provider's model, set its API key and pass `--model <id>`.
+
+## Use
+
+```bash
+queravel                       # interactive TUI
+queravel "refactor utils.py to remove the duplicate helper"   # TUI, pre-seeded with a first task
+queravel -p "run the tests and summarize failures"            # headless (print) mode, no TUI
+
+# Sessions — resume where you left off
+queravel -c "and now add tests for it"     # --continue: resume the latest session in this dir
+queravel --resume                          # pick from a list (this dir; Ctrl+A = all dirs, / = search)
+queravel --resume 20260917-004541-645844   # resume a specific session id directly
+queravel --resume <id> --fork-session      # branch it into a NEW session (original untouched)
+
+# In the picker: →/← expand a group's branches, / to search (or paste a PR URL to
+# find the session that opened it). In a session, /branch forks the current thread.
+
+# Options
+queravel --model glm-5.3-flash --cwd /path/to/repo "..."   # models: kimi-k3 | glm-5.3-flash | deepseek-v4.1-flash
+queravel --auto -p "create hello.py and run it"      # auto-approve side effects (scratch targets)
+```
+
+### Approval / permission modes
+
+```bash
+queravel                 # default: prompt every side effect (edits show a diff to accept/reject)
+queravel --accept-edits  # auto-approve file edits; still confirm shell commands
+queravel --plan          # read-only: research & propose a plan, change nothing
+queravel --auto          # approve everything except denied/dangerous commands
+```
+
+Cycle modes live with **Ctrl+P → "Cycle approval mode"**. Manage **allow / ask / deny** rules
+interactively with **`/permissions`** (add/remove, user or project scope), or edit
+`~/.queravel/settings.json` / `.queravel/settings.json` directly:
+`{"permissions": {"allow": ["Bash(npm test:*)", "Read(src/*)"], "ask": ["Bash(git push*)"], "deny": ["WebFetch(domain:evil.com)"]}}`.
+Rule syntax: `Bash(<glob>)`, `Read/Write/Edit(<glob>)`, `WebFetch(domain:x)`,
+`mcp__server__tool`, a bare tool name, or `*`. Precedence is **deny > ask > allow**; dangerous
+commands (`rm -rf`, fork bombs, `curl|sh`, force-push, …) never auto-run.
+
+### Power features
+
+- **Todos** — the agent plans multi-step work; a live panel tracks progress.
+- **Sub-agents** — it delegates large investigations to an isolated **read-only** sub-agent (`task`)
+  that returns a findings report, keeping the main context clean.
+- **Context auto-compaction** — long sessions summarize older turns automatically to stay in-window.
+- **Checkpoint / undo** — every file edit is snapshotted; `/undo` reverts the last change.
+- **Hooks** — run shell commands at `PreToolUse` (non-zero exit blocks the tool) / `PostToolUse`
+  (e.g. auto-format after edits) via `settings.json`; matched by a regex on the tool name.
+- **QUERAVEL.md `@`-imports** — recursively include other files into your project memory.
+- **Agentic search, not RAG** — it navigates your repo with grep/glob/read on demand (always fresh,
+  no index to build).
+
+## Project memory — `QUERAVEL.md`
+
+Drop a `QUERAVEL.md` in your repo (and/or `~/.queravel/QUERAVEL.md` for global prefs). Its contents
+are injected into the agent's system prompt every run, so your project conventions, build/test
+commands, and do's/don'ts persist without re-explaining.
+
+Sessions are saved under `~/.queravel/sessions/`; the system prompt (and thus `QUERAVEL.md`) is
+rebuilt on every run, so editing `QUERAVEL.md` always takes effect — even on `--continue`.
+
+## Web & MCP
+
+- **Web tools**: the agent can `web_fetch` a URL and `web_search` (set `TAVILY_API_KEY` for a
+  reliable search API; otherwise a best-effort keyless search is used).
+- **MCP servers**: connect external tool servers (standard MCP config) in
+  `~/.queravel/mcp.json` or `.queravel/mcp.json`:
+  ```json
+  {"mcpServers": {"github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]}}}
+  ```
+  Their tools appear as `mcp__<server>__<tool>` and are gated by your approval mode.
+
+## Tools (Phase 0/1)
+
+`read_file` · `write_file` · `edit_file` (surgical) · `multi_edit` (atomic multi-change) ·
+`list_dir` · `glob` · `grep` · `run_command` (bash). All execute **in-process on your machine**,
+whole-repo, no cloud caps.
+
+## Architecture (short)
+
+A local, provider-agnostic tool-use loop (`adapters/base.py`) — Fireworks (OpenAI-compatible) by
+default, with optional BYOK providers — driving in-process local tools, rendered through a UI abstraction
+(`ui.py`) that backs both the Textual TUI (`tui.py`) and the headless `-p` mode. Mirrors the shape
+of Queravel's backend agent engine so it can be extracted and shared (Phase 1 next step). See
+`memory/` for the concept, decisions, and engine-extraction plan.

queravel_cli-0.9.27/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "queravel-cli"
+version = "0.9.27"
+description = "Queravel CLI — an agentic coding assistant for the terminal"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Queravel" }]
+dependencies = [
+    # Fireworks.ai (the default provider) speaks the OpenAI-compatible API.
+    "openai>=1.40",
+    "rich>=13.7",
+    # Textual powers the classic full-screen TUI.
+    "textual>=0.80",
+    # prompt_toolkit powers the native inline frontend (normal buffer, no mouse capture,
+    # so the terminal owns scroll + selection + copy — Claude Code's default model).
+    "prompt_toolkit>=3.0",
+    # MCP client (connect external tool servers over stdio).
+    "mcp>=1.0",
+    # Remote control: Socket.IO client to the Queravel backend (the relay).
+    "python-socketio[client]>=5.11",
+    # On-device ("Local") model host: `code-host --local-serve` runs a Socket.IO SERVER
+    # on 127.0.0.1 via socketio.AsyncServer(async_mode="aiohttp"). The socketio[client]
+    # extra above only pulls the websocket CLIENT — the aiohttp async SERVER backend is a
+    # separate dependency and MUST be declared, or the local host crashes with
+    # ModuleNotFoundError: No module named 'aiohttp' in the shipped (PyInstaller) binary.
+    "aiohttp>=3.9",
+    # CA certificates for HTTPS. Declared + bundled (see queravel.spec) so the FROZEN
+    # binary verifies TLS on ANY machine: a PyInstaller build otherwise bakes in the
+    # build host's cert path (e.g. .../anaconda3/ssl/cert.pem), which doesn't exist on
+    # users' machines → every HTTPS download (models, llama-server) fails. __init__ points
+    # SSL_CERT_FILE at the bundled certifi bundle.
+    "certifi>=2024.0",
+    # Voice input (/voice): mic capture. Wheels bundle PortAudio on macOS/Windows/Linux,
+    # so voice works out of the box; transcription routes through the Queravel backend.
+    "sounddevice>=0.4",
+    "numpy>=1.24",
+    # Streaming voice (/voice hold-to-talk): full-duplex WebSocket to the backend STT relay.
+    "websockets>=12",
+    # /rc Remote Control: render a scannable QR of the session link in the terminal.
+    "segno>=1.5",
+]
+
+[project.optional-dependencies]
+# Anthropic is an OPTIONAL provider (used only for --model claude-…).
+anthropic = ["anthropic>=1.0"]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+queravel = "queravel_cli.__main__:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["queravel_cli*"]

queravel_cli-0.9.27/queravel_cli/__init__.py

@@ -0,0 +1,30 @@
+"""Queravel CLI — an agentic coding assistant for the terminal.
+
+Phase 0: a minimal, self-contained agent loop that proves local tool execution
+end-to-end, mirroring the interface of Queravel's backend agent engine so the
+engine can be extracted and shared in Phase 1. See memory/ for the full concept.
+"""
+
+__version__ = "0.9.27"
+
+# HTTPS trust store for the FROZEN binary. PyInstaller bakes in the build host's OpenSSL
+# cert path (e.g. .../anaconda3/ssl/cert.pem), which does NOT exist on users' machines, so
+# stdlib ssl/urllib would fail every TLS handshake (model + llama-server downloads). Point
+# SSL_CERT_FILE at the bundled certifi CA bundle (certifi is collected into the binary by
+# queravel.spec) so verification works on any machine. Runs at import, before any HTTPS.
+# No-op from source when the env/certs are already valid (setdefault won't override).
+def _ensure_ca_bundle() -> None:
+    import os
+    if os.environ.get("SSL_CERT_FILE"):
+        return
+    try:
+        import certifi
+        ca = certifi.where()
+        if ca and os.path.exists(ca):
+            os.environ["SSL_CERT_FILE"] = ca
+            os.environ.setdefault("REQUESTS_CA_BUNDLE", ca)
+    except Exception:
+        pass
+
+
+_ensure_ca_bundle()