harPY v1

harPY — harmonic research in python — is a headless Python toolkit for comparing how models perceive audio and use bounded pitch controls to reach a target note.

This is the first public release: package 1.0.0, tag v1. The older v1.0.0 development tag remains available for historical reproduction.

Included

• One harpy CLI: train, evaluate, run, and summarize.
• Deterministic single-sine tasks, waveform and spectrum observations, and eight controlled level/phase/static-noise conditions.
• Classical baselines, the packaged seed-0 supervised pitch reference, and optional experimental PPO training.
• Custom Python actor factories, matched episodes, action traces, and validated JSON, text, Markdown, and CSV results.
• A wheel, source archive, checksums, and the complete 14,400-record representation study with its provenance manifest.

Install

Use Python 3.12 on Linux or WSL. Download the wheel and its checksum, then run:

sha256sum --check harpy_audio-1.0.0-py3-none-any.whl.sha256
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install ./harpy_audio-1.0.0-py3-none-any.whl
harpy --help

The base install needs neither Torch nor Stable-Baselines3. Install the wheel with [pitch] for supervised pitch execution/training, or [train] for the complete Torch/PPO stack. These dependencies are separate downloads. This release is distributed here; it has not been uploaded to PyPI.

Getting started · Contributing · Specification

Verification and limits

The wheel and source archive were independently rebuilt with identical hashes and installed into fresh environments outside the checkout. Both passed classical smoke evaluation (12/12), a noisy traced episode, both documented Python examples, and all result readout formats, without Torch or Stable-Baselines3. All 64 packaged runtime/resource files match the frozen source. The CLI/import checks and installer lifecycle checks passed.

Runtime and reference-checkpoint bytes are unchanged from the qualified source. Historical clean qualification passed 650 benchmark and 1,000 confirmation episodes for each of seeds 0, 1, and 2. Strong-noise failures remain reported. This release does not claim learned superiority, arbitrary-model performance, or recorded-audio generalization. PPO is experimental. No new training cohort was run for release packaging.

The study download preserves all records and original producer provenance; its manifest documents the removal of local checkout prefixes from 30 artifact path labels. To inspect it:

gzip -dk spectrum-study.json.gz
harpy summarize spectrum-study.json --format markdown

Linux/WSL with Python 3.12 is the qualified package environment. The separate project website and subdomain installer are not live yet.