padou 0.2.0__tar.gz

padou-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.env
+.env.*
+*.swp

padou-0.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## 0.2.0 (2026-11)
+
+Faster on laptops, a new admin mode, optional web search, coding mode, and more reliable answers. Now on PyPI (`uv tool install padou`) and the AUR (`yay -S padou`).
+
+- Packaging: published to PyPI by GitHub Actions on each release (trusted publishing, no stored tokens); an AUR package; `/update` upgrades PyPI installs from PyPI
+- CONTRIBUTING.md, SECURITY.md (private vulnerability reporting), issue and pull request templates
+- A rewritten README with fresh screenshots
+- `/web on|off`: optional web search for the session, off by default, shown as `web` in the status line. Providers: DuckDuckGo (no account), your own SearXNG, or the Brave Search API. Never reads pages on your computer or local network
+- `man_page` tool: the model reads the real manuals installed on your computer (or just the parts about one option) instead of guessing options
+- More honest answers: the instructions tell the model to check first, never invent paths, options or settings, and say when its knowledge may be out of date. The context now includes your desktop, session type (Wayland/X11) and terminal
+- Recovering from tool mistakes: broken calls get an example of a correct one, calls written as text are run as real calls, and a call that keeps failing is stopped after two tries
+- Long tool output keeps its start and end, with a note about what was skipped
+- Auto-compact: near a full context, older messages are summarised automatically and the last exchange is kept (`auto_compact` under `[chat]`)
+- A quiet speed line under each answer: `3.1s · 140 tokens · 22 tok/s` (`reply_stats` under `[ui]`)
+- `padou bench`: score the current model on 17 fixed questions (two about code) in a practice folder, saved for comparison
+- Coding mode, when padou starts in a project: `@path` attaches a file (Tab completes it); the project's own test, lint and build commands can be run by the model in edit/admin mode after you approve (or allow them for the session); `/review` reviews uncommitted git changes; `d` in the confirmation box opens the change as a diff in VS Code / Code OSS / VSCodium; `/tutor` explains and hints instead of writing the code; `git_diff` and `git_diff_staged` commands
+- Enter on a suggestion (a file after `@`, a folder) takes the suggestion instead of sending the message; on a command name (`/he` → `/help`) it runs the command
+- A misspelled `@file` is reported (`no such file; did you mean …?`) instead of silently ignored, and a failed tool call keeps a readable title (`Read src/main.py`)
+- `/retry` asks the last question again; `/copy code [n]` copies just a code block; `/export [file]` saves the conversation as Markdown
+- While a tool runs, the spinner says what it's doing (`running disk_usage…`, `reading ~/x.conf…`, `searching the web…`)
+- `/exit && stop` (or `/exit stop`) quits and stops the model server
+- `/help` in groups; `/undo list` (also `/changes`); `/tools`, `/system` and `/screenshot` still work but are no longer listed
+
+- `/mode read | edit | admin` replaces `/write` (which still works, as the old name of `/mode edit`). `Shift+Tab` switches between read-only and edit, quietly: the status line shows the mode
+- Admin mode: change files anywhere, outside the start folder too. System files go through `sudo` (you type your password into sudo, never into padou), get a copy kept for `/undo` instead of the Trash, and are marked `· sudo`. The first time, admin mode explains itself and asks; after that it just switches. Deletes need the name typed, also for files. Never secrets, `/proc`, `/sys`, `/dev`, `/run`, `/boot`, your home folder or a main system folder as a whole
+- An audit log: every change and undo goes to `changes.log` in padou's state folder
+- The status line shows `read-only`, `✎ edit: <folder>` or `✎ admin: anywhere`
+
+- Live progress while padou works: elapsed time, then tokens and speed as the reply streams
+- `Esc` stops a reply and keeps what was written so far (`Ctrl+C` still cancels it completely)
+- `/think [on|off]`: let thinking models (Qwen3.5) reason before answering, per session; `thinking` under `[chat]` sets the default. Off by default, because it's much slower on a laptop
+- Shows "thinking…" or "choosing a tool…" while the model works, instead of a silent spinner
+- llama.cpp keeps the conversation in its prompt cache between questions (`cache_prompt`, and `--cache-reuse 256` in new setups), so replies start sooner
+- `padou setup` gives a 16K context on machines with 16 GB of RAM (was 8K), and restarts an already-running model server so new settings take effect; `padou doctor` suggests re-running setup when an older config misses these
+- `/clear` also clears the screen (and scrollback), then redraws the banner
+- `/models remove <n>`: free the space of a downloaded model (to the Trash; Ollama models are deleted), never the one in use
+
+## 0.1.0 (2026-10)
+
+First release.
+
+- Runs on Linux, macOS and Windows (native, PowerShell installer `install.ps1`), tested on all three by GitHub Actions
+- Write mode can also rewrite whole files, create folders, move/rename, and delete to the system Trash; every change in a confirmation box, folders need their name typed, `/undo` for all of them
+- A progress bar while the model downloads on the first start (and up to an hour to finish, instead of 5 minutes)
+- Update check once a day in the background, and `/update` to install (`[updates] check = false` turns the check off)
+- The compass star: a launch animation (dots gather from everywhere, παντού decodes to padou), rays that keep pulsing, and a pulsing star in the status line
+- Terminal chat with streaming Markdown and a status line
+- Read-only tools: `read_file`, `list_dir`, `search`, and 20 approved system commands
+- Safety rules: no shell, no sudo, validated arguments, secrets blocked (symlinks included), capped output
+- Slash commands: `/help`, `/clear`, `/models`, `/status`, `/copy`, `/tools`, `/resume`, `/compact`, `/doctor`, `/system`, `/exit`
+- Saved sessions with `/resume` and `padou -c`
+- `/screenshot` saves the screen as an SVG image
+- Folder access: tools read only the start folder by default; `/folder add|remove|anywhere|restrict`, `[tools] scope` and `folders`
+- Disclaimer (DISCLAIMER.md) and a one-time notice on first run
+- Windows (WSL) install guide; `/copy` uses `clip.exe` under WSL
+- Write mode: `/write <folder>`, `edit_file`/`write_file` with a diff and approval for every change, backups, `/undo`, `/changes`
+- `/server` status, stop, restart and log; `[server] stop_on_exit`
+- `/models` switches models in one step: restarts llama-server with the new one (downloading it once if needed) or pulls it with Ollama, and saves it as your default
+- Eight models to choose from, by Alibaba (Qwen3.5 2B/4B/9B), IBM (Granite 4.0 Micro), Mistral AI (Ministral 3 3B/8B), Microsoft (Phi-4-mini) and Google (Gemma 4 E4B)
+- `padou setup`: first-run wizard that detects OS, GPU, RAM and model servers, recommends a model and writes the config
+- Starts llama-server (or `ollama serve`) automatically when nothing is running on localhost
+- Works with llama.cpp, Ollama and LM Studio
+- Omarchy theme colours (Omarchy 4 and older), with a built-in palette elsewhere

padou-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to padou
+
+Thanks for helping! padou is a small project: bug reports, test results on your hardware, ideas and pull requests are all welcome.
+
+## Reporting a bug
+
+Open an [issue](https://github.com/padou-dev/padou/issues/new/choose) and include:
+
+- the output of `padou doctor` (it shows your system, model server, model and config problems; it contains no secrets);
+- what you typed, what you expected, and what happened (a screenshot helps; `/screenshot` saves one as an SVG);
+- the model you use. Many oddities are the model's, not padou's: `padou bench` shows how well a model works with padou.
+
+Security problems: please **don't** open a public issue; see [SECURITY.md](SECURITY.md).
+
+## Setting up
+
+```bash
+git clone https://github.com/padou-dev/padou
+cd padou
+uv sync                          # creates .venv with padou and its dependencies
+uv run pytest -q                 # the tests: they need no model server and touch nothing outside temp folders
+uv tool install --editable .     # the `padou` command, running straight from your clone
+```
+
+You don't need a GPU or a model to work on most of padou: the tests use fake model servers.
+
+## Making a change
+
+- **Keep it small-model friendly.** Every word in the system prompt and every tool description is read on every question by a 4B model on a laptop. Short and precise beats complete.
+- **Safety rules live in one place:** `tools.py` (what may be read or run) and `writes.py` (what may be changed). A change there needs tests, including the cases that must be refused.
+- **All three systems.** padou runs on Linux, macOS and Windows; differences go through `compat.py`. GitHub Actions runs the tests on all three for every push and pull request.
+- **Tests:** add or update tests in `tests/` for what you change. `uv run pytest -q` must pass.
+- **Plain language** in messages and docs: padou is used by beginners. Say what happened and what to do next.
+- **CHANGELOG.md:** add a line under *Unreleased* for anything a user would notice.
+
+Then open a pull request describing what changed and why, and how you tested it.
+
+## Releasing (maintainers)
+
+### Once: set up PyPI trusted publishing
+
+1. Create an account on [pypi.org](https://pypi.org) and turn on two-factor authentication.
+2. Go to *Your projects → Publishing* (for the first release: *Add a new pending publisher*) and fill in: project name `padou`, owner `padou-dev`, repository `padou`, workflow `release.yml`, environment `pypi`.
+3. On GitHub: *Settings → Environments → New environment* named `pypi`. Optionally add yourself as a required reviewer, so every upload waits for your OK.
+
+No password or token is stored anywhere: PyPI trusts uploads that come from that workflow in this repository.
+
+### Each release
+
+1. Set the version in `pyproject.toml` and `src/padou/__init__.py`, and turn *Unreleased* in `CHANGELOG.md` into `## X.Y.Z (date)`.
+2. Commit, push, and wait for the tests to pass on all three systems.
+3. Tag and push: `git tag -a vX.Y.Z -m "padou X.Y.Z" && git push origin vX.Y.Z`
+4. On GitHub: *Releases → Draft a new release*, pick the tag, title `padou X.Y.Z`, paste the changelog section, *Publish*. The `release` workflow checks the tag matches the version, runs the tests, builds and uploads to PyPI. Everyone's padou then shows the update notice within a day, and `/update` installs it.
+
+### The AUR package
+
+The package files are in `contrib/aur/`. First time: create an account on [aur.archlinux.org](https://aur.archlinux.org) and add your SSH public key in *My Account*. Then:
+
+```bash
+git clone ssh://aur@aur.archlinux.org/padou.git aur-padou
+cp contrib/aur/PKGBUILD aur-padou/
+cd aur-padou
+updpkgsums                         # fills in the checksum of the release tarball
+makepkg -si                        # build, run the tests and install it locally, as a check
+makepkg --printsrcinfo > .SRCINFO
+git add PKGBUILD .SRCINFO && git commit -m "padou X.Y.Z" && git push
+```
+
+For each new release: change `pkgver` (and set `pkgrel=1`) in `PKGBUILD`, and repeat from `updpkgsums`.

padou-0.2.0/DISCLAIMER.md

@@ -0,0 +1,43 @@
+# Disclaimer
+
+padou is a free, open-source hobby project, provided **"as is", without warranty of any kind**, as stated in the [MIT License](LICENSE). By installing or using padou you accept the following.
+
+## No warranty, no liability
+
+To the maximum extent permitted by applicable law, the author(s) and contributors are **not liable** for any claim, damages, data loss, system damage, security incident or other liability arising from the use of, or inability to use, padou, whether in contract, tort or otherwise. You use padou entirely **at your own risk**.
+
+## AI output can be wrong
+
+padou passes your questions to a language model running on your own machine. Language models, small local ones especially, can and do produce answers that are **incorrect, incomplete, outdated or misleading**, including invented commands, file contents or explanations that sound confident.
+
+- **Always review and understand a command before you run it.** padou suggests commands; *you* decide whether to run them, and you are solely responsible for what you run on your systems.
+- Verify important information against official documentation or a qualified person.
+- Keep backups of anything you can't afford to lose.
+
+## Not for critical decisions
+
+padou is not designed, tested or suitable for medical, legal, financial, safety-critical, security-critical or other high-stakes decisions. Do not rely on it for them.
+
+## Write mode: you approve, you are responsible
+
+padou is read-only unless **you** switch modes with `/mode`. In edit mode padou can edit, create, move and delete files and folders in the folder you chose (deleting means moving them to your system's Trash or Recycle Bin); in admin mode it can do so anywhere on your computer, including system files through `sudo` with your password. Either way, only after showing you each change and getting your approval. System files changed in admin mode can break your system; padou keeps copies for `/undo`, but that is a convenience, not a guarantee. **Every change you approve is your decision and your responsibility.** Read each confirmation box carefully: language models can propose wrong, incomplete or destructive changes, and text inside files you ask padou to read can try to manipulate the model into proposing changes you didn't ask for ("prompt injection"). Backups, the Trash and `/undo` are a convenience, not a guarantee: some drives have no Trash, a Trash can be emptied, and large deletions aren't backed up by padou. Keep your own backups, and use version control such as Git.
+
+## Safeguards, not guarantees
+
+padou's read tools are designed to be read-only: they run no shell, never use `sudo`, validate their arguments, and block known secret locations (SSH keys, password stores, `.env` files and similar). Write mode adds its own limits (approval for every change, typing a folder's name to delete it, the Trash instead of permanent deletion, backups, no system or hidden folders). These safeguards reduce risk; **they are not a guarantee**. Software has bugs, and a tool that reads files can still show their contents to the model and on your screen. Only run padou on systems and data you are entitled to access, and don't point it at folders containing information you aren't comfortable having read.
+
+## Third-party software and models
+
+padou does not include any AI model. Models (for example Qwen by Alibaba, Gemma by Google, Phi by Microsoft, Granite by IBM or Ministral by Mistral AI) and model servers (llama.cpp, Ollama, LM Studio) are **third-party** software, downloaded by those tools from their own sources and governed by **their own licences and terms**. Check the licence on each model's page before use, especially for commercial use. The author of padou is not responsible for third-party software, models or the content they produce.
+
+## No affiliation
+
+padou is an independent project. It is not affiliated with, endorsed by or sponsored by Alibaba (Qwen), Google (Gemma), Microsoft (Phi), IBM (Granite), Mistral AI (Ministral), the llama.cpp project, Ollama, LM Studio, Omarchy, Anthropic or any other company or project named in its documentation. All trademarks belong to their respective owners.
+
+## Privacy
+
+padou has no telemetry. It sends your conversations only to the model server you configure (by default, on your own machine). At most once a day it asks GitHub's public API for the latest padou release, which sends nothing about you or your conversations; turn it off with `[updates] check = false`. Conversations are saved locally on your computer (see "Where padou keeps things" in the README). You are responsible for the data you choose to share with the model and for protecting your own machine.
+
+---
+
+*This disclaimer is not legal advice. If you need legal certainty for your situation, consult a lawyer.*

padou-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 p@nos
+
+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.