From b1816ed443d715d0c706a40fd202d595d4a11926 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sat, 26 Sep 2026 08:19:24 +0200 Subject: Document the config folder, the tools and the live test Co-Authored-By: Claude Opus 5.5 --- README.md | 41 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ea51698..1d7ecef 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,8 @@ A local push-to-talk voice assistant. Unmute the microphone, speak, mute it: the assistant transcribes what you said, asks a local LLM, and speaks the -answer. Italian and English. Nothing leaves the machine. +answer. Italian and English. Speech, transcripts and the model stay on the +machine; only tools you enable (weather, web search) reach the network. ``` mic button ──> arecord ──> whisper-server (STT) ──> llama-server (LLM) ──> Kokoro (TTS) ──> aplay @@ -32,9 +33,11 @@ mic button ──> arecord ──> whisper-server (STT) ──> llama-server (LL - a running `llama-server` with an OpenAI-compatible API - Python 3 with `onnxruntime`, `numpy` and `kokoro-onnx` - `espeak-ng`, ALSA utils (`amixer`, `arecord`, `aplay`), `curl` +- `jq` for the weather and search example tools, `python3-dateutil` for the calendar one - a USB microphone with a hardware mute button exposed as an ALSA switch -Paths, the card name and ports are constants at the top of `assistant.py`. +Paths, the card name, ports and voices can be changed in `config.toml`, see +"Configuration and tools" below. ## Usage @@ -43,6 +46,40 @@ python3 assistant.py # run python3 assistant.py --test # self-check ``` +## Configuration and tools + +Everything is optional. Settings and tools live in +`~/.config/desktop-assistant/` (or `$XDG_CONFIG_HOME/desktop-assistant/`): + +```sh +mkdir -p ~/.config/desktop-assistant +cp examples/config.toml ~/.config/desktop-assistant/ +cp -r examples/tools ~/.config/desktop-assistant/ +``` + +- `config.toml`: every key is optional, the example lists the defaults. + `[env]` is added to every tool's environment; put instance URLs and + key file paths there. +- `tools/.toml`: one tool each, enabled by being there. A tool is a + command run without a shell, its stdout goes back to the model: + +```toml +description = "What the tool does, for the model" +command = ["script.sh", "{param}"] # looked up in tools/ first, then PATH +timeout = 10 +announce.it = ["Cerco un attimo."] # optional, said while it runs +announce.en = ["Let me look that up."] + +[params.param] +type = "string" +description = "What the model should pass" +``` + +The example tools only read: `now` (date), `calendar` (`agenda.py` over +a vdirsyncer folder), `weather` (OpenWeatherMap, key file in the +conky-theme-udt format), `search` (a SearXNG instance with the JSON +format enabled). + ## License Copyright (C) 2026 Danilo M. -- cgit v1.2.3