thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/AGENTS.md
Thales Maciel 94ead25737 Prune stale editor and Wayland surface area 
Stop shipping code that implied Aman supported a two-pass editor, external API cleanup, or a Wayland scaffold when the runtime only exercises single-pass local cleanup on X11.\n\nCollapse aiprocess to the active single-pass Llama contract, delete desktop_wayland and the empty wayland extra, and make model_eval reject pass1_/pass2_ tuning keys while keeping pass1_ms/pass2_ms as report compatibility fields.\n\nRemove the unused pillow dependency, switch to SPDX-style license metadata, and clean setuptools build state before packaging so deleted modules do not leak into wheels. Update the methodology and repo guidance docs, and add focused tests for desktop adapter selection, stale param rejection, and portable wheel contents.\n\nValidate with uv lock, python3 -m unittest discover -s tests -p 'test_*.py', python3 -m py_compile src/*.py tests/*.py, and python3 -m build --wheel --sdist --no-isolation.
2026-03-14 17:48:23 -03:00

2.1 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.

Build, Test, and Development Commands

  • Install deps (X11): uv sync.
  • 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.