Thales Maciel
c6fc61c885
Some checks failed
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.
114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# Developer And Maintainer Workflows
|
|
|
|
This document keeps build, packaging, development, and benchmarking material
|
|
out of the first-run README path.
|
|
|
|
## Build and packaging
|
|
|
|
```bash
|
|
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`](./releases/1.0.0.md) as the release-notes source.
|
|
|
|
## Developer setup
|
|
|
|
`uv` workflow:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make install-local
|
|
aman run --config ~/.config/aman/config.json
|
|
```
|
|
|
|
## Support and control commands
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](../benchmarks/README.md).
|