aman/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/aman.py is the primary entrypoint (X11 STT daemon).
• src/recorder.py handles audio capture using PortAudio via sounddevice.
• src/aman.py owns Whisper setup and transcription.
• src/aiprocess.py runs the in-process Llama-3.2-3B cleanup.
• src/desktop_x11.py encapsulates X11 hotkeys, tray, and injection.
• src/desktop_wayland.py scaffolds Wayland support (exits with a message).

Build, Test, and Development Commands

• Install deps (X11): uv sync --extra x11.
• Install deps (Wayland scaffold): uv sync --extra wayland.
• Run daemon: uv run python3 src/aman.py --config ~/.config/aman/config.json.

System packages (example names):

• Core: portaudio/libportaudio2.
• X11 tray: libayatana-appindicator3.

Coding Style & Naming Conventions

• Shell scripts use Bash with set -euo pipefail.
• Indentation is two spaces; prefer lowercase variable names for locals and uppercase for environment-configured values.
• Keep functions small and focused; add comments only where the intent is not obvious.

Testing Guidelines

• Automated tests live in tests/ and run with python3 -m unittest discover -s tests -p 'test_*.py'.

Commit & Pull Request Guidelines

• Commit history is minimal and does not establish a convention; use short, imperative messages (e.g., "Add device override").
• PRs should include a concise description, repro steps, and any environment variables or dependencies added.

Configuration Tips

• Audio input is configured via the recording.input field in config.json.
• STT model and device are configured via the stt section in config.json.
• LLM model settings are locked; model downloads to ~/.cache/aman/models/.
• -v/--verbose enables verbose logs (including llama.cpp) with llama:: prefix.
• Press Esc while recording to cancel without processing.