thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/developer-workflows.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

3.8 KiB
Raw Permalink Blame History

Developer And Maintainer Workflows

This document keeps build, packaging, development, and benchmarking material out of the first-run README path.

Build and packaging

make build
make package
make package-portable
make package-deb
make package-arch
make runtime-check
make release-check
make release-prep
bash ./scripts/ci_portable_smoke.sh
  • make package-portable builds dist/aman-x11-linux-<version>.tar.gz plus its .sha256 file.
  • bash ./scripts/ci_portable_smoke.sh reproduces the Ubuntu CI portable install plus aman doctor smoke path locally.
  • make release-prep runs make release-check, builds the packaged artifacts, and writes dist/SHA256SUMS for the release page upload set.
  • make package-deb installs Python dependencies while creating the package.
  • For offline Debian packaging, set AMAN_WHEELHOUSE_DIR to a directory containing the required wheels.

For 1.0.0, the manual publication target is the forge release page at https://git.thaloco.com/thaloco/aman/releases, using docs/releases/1.0.0.md as the release-notes source.

Developer setup

uv workflow:

python3 -m venv --system-site-packages .venv
. .venv/bin/activate
uv sync --active
uv run aman run --config ~/.config/aman/config.json

Install the documented distro runtime dependencies first so the active virtualenv can see GTK/AppIndicator/X11 bindings from the system Python.

pip workflow:

make install-local
aman run --config ~/.config/aman/config.json

Support and control commands

make run
make run config.example.json
make doctor
make self-check
make runtime-check
make eval-models
make sync-default-model
make check-default-model
make check

CLI examples:

aman doctor --config ~/.config/aman/config.json --json
aman self-check --config ~/.config/aman/config.json --json
aman run --config ~/.config/aman/config.json
aman bench --text "example transcript" --repeat 5 --warmup 1
aman build-heuristic-dataset --input benchmarks/heuristics_dataset.raw.jsonl --output benchmarks/heuristics_dataset.jsonl --json
aman eval-models --dataset benchmarks/cleanup_dataset.jsonl --matrix benchmarks/model_matrix.small_first.json --heuristic-dataset benchmarks/heuristics_dataset.jsonl --heuristic-weight 0.25 --json
aman version
aman init --config ~/.config/aman/config.json --force

Benchmarking

aman bench --text "draft a short email to Marta confirming lunch" --repeat 10 --warmup 2
aman bench --text-file ./bench-input.txt --repeat 20 --json

bench does not capture audio and never injects text to desktop apps. It runs the processing path from input transcript text through alignment/editor/fact-guard/vocabulary cleanup and prints timing summaries.

Model evaluation

aman build-heuristic-dataset --input benchmarks/heuristics_dataset.raw.jsonl --output benchmarks/heuristics_dataset.jsonl
aman eval-models --dataset benchmarks/cleanup_dataset.jsonl --matrix benchmarks/model_matrix.small_first.json --heuristic-dataset benchmarks/heuristics_dataset.jsonl --heuristic-weight 0.25 --output benchmarks/results/latest.json
make sync-default-model
  • eval-models runs a structured model/parameter sweep over a JSONL dataset and outputs latency plus quality metrics.
  • When --heuristic-dataset is provided, the report also includes alignment-heuristic quality metrics.
  • make sync-default-model promotes the report winner to the managed default model constants and make check-default-model keeps that drift check in CI.

Internal maintainer CLI:

aman-maint sync-default-model --check --report benchmarks/results/latest.json --artifacts benchmarks/model_artifacts.json --constants src/constants.py

Dataset and artifact details live in benchmarks/README.md.