thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/AGENTS.md
Thales Maciel 4d0081d1d0 Split aman.py into focused CLI and runtime modules 
Break the old god module into flat siblings for CLI parsing, run lifecycle, daemon state, shared processing helpers, benchmark tooling, and maintainer-only model sync so changes stop sharing one giant import graph.

Keep aman as a thin shim over aman_cli, move sync-default-model behind the hidden aman-maint entrypoint plus Make wrappers, and update packaging metadata plus maintainer docs to reflect the new surface.

Retarget the tests to the new seams with dedicated runtime, run, benchmark, maintainer, and entrypoint suites, and verify with python3 -m unittest discover -s tests -p "test_*.py", python3 -m py_compile src/*.py tests/*.py, PYTHONPATH=src python3 -m aman --help, PYTHONPATH=src python3 -m aman version, and PYTHONPATH=src python3 -m aman_maint --help.
2026-03-14 14:54:57 -03:00

2.3 KiB
Raw Blame History

Repository Guidelines

Project Structure & Module Organization

  • src/aman.py is the thin console/module entrypoint shim.
  • src/aman_cli.py owns the main end-user CLI parser and dispatch.
  • src/aman_run.py owns foreground runtime startup, tray wiring, and settings flow.
  • src/aman_runtime.py owns the daemon lifecycle and runtime state machine.
  • src/aman_benchmarks.py owns bench, eval-models, and heuristic dataset tooling.
  • src/aman_model_sync.py and src/aman_maint.py own maintainer-only model promotion flows.
  • src/recorder.py handles audio capture using PortAudio via sounddevice.
  • src/aman_processing.py owns shared Whisper/editor pipeline helpers.
  • 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.
  • Install deps (Wayland scaffold): uv sync --extra wayland.
  • Run daemon: uv run aman run --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.