thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/AGENTS.md
Thales Maciel c6fc61c885
Some checks failed
ci / Unit Matrix (3.10) (push) Has been cancelled
Details
ci / Unit Matrix (3.11) (push) Has been cancelled
Details
ci / Unit Matrix (3.12) (push) Has been cancelled
Details
ci / Portable Ubuntu Smoke (push) Has been cancelled
Details
ci / Package Artifacts (push) Has been cancelled
Details
Normalize native dependency ownership and split config UI 
Make distro packages the single source of truth for GTK/X11 Python bindings instead of advertising them as wheel-managed runtime dependencies. Update the uv, CI, and packaging workflows to use system site packages, regenerate uv.lock, and keep portable and Arch metadata aligned with that contract.

Pull runtime policy, audio probing, and page builders out of config_ui.py so the settings window becomes a coordinator instead of a single large mixed-concern module. Rename the config serialization and logging helpers, and stop startup logging from exposing raw vocabulary entries or custom model paths.

Remove stale helper aliases and add regression coverage for safe startup logging, packaging metadata and module drift, portable requirements, and the extracted audio helper behavior.

Validated with uv lock, python3 -m compileall -q src tests, python3 -m unittest discover -s tests -p 'test_*.py', make build, and make package-arch.
2026-03-15 11:27:54 -03:00

2.3 KiB
Raw Permalink 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): python3 -m venv --system-site-packages .venv && . .venv/bin/activate && uv sync --active.
  • Run daemon: uv run aman run --config ~/.config/aman/config.json.

System packages (example names):

  • Core: portaudio/libportaudio2.
  • GTK/X11 Python bindings: distro packages such as python3-gi / python3-xlib.
  • 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.