Repository navigation
First published release. Extracted from a real, months-long production use orchestrating
DeepSeek translation waves (10 concurrent workers, hundreds of documents, real dollar caps that
were never exceeded) — not written speculatively ahead of real experience.
What's in it
wave.py— budget-aware concurrent wave scheduler: a concurrency cap AND a cumulative
dollar-budget cap, real token/cost tracked per job viarun_pi.py's ledger integration
(embedded, not a separate step a caller has to remember).run_pi.py—start_pi/collect_pi_result/run_pifor spawning and trackingpi
processes, with optionalsystemd-run --user --scopememory isolation (CgroupLimits) so one
runaway job's OOM can't take the whole terminal session down with it (a real incident this
fixed).resume_pi_headless()for continuing a closed session's context in a new process.pi-wave-job(CLI) — one ad-hoc job from the command line, now the default way to launch
any Pi/agent job across every project using this library:uv tool install --editable .puts
it onPATH. Structurally immune to a real bug class (pi_job.sh's file-staging race) that
affected the shell-script predecessor it replaces.interactive.py/pi-wave-session(CLI) — launch a long-running, remotely-steerable
interactive session (tmux/screen + pi-messenger mesh), separate from the one-shot job case.escalate.py— escalation protocol for a wave to flag something needing human attention.stage_check.py— generic stage-check framework for multi-step pipelines.coordinator.py— the "who's watching the wave" role, confirmed working with either an
interactive Pi session or a non-Pi agent (Claude Code or otherwise) reading the same
escalation/summary files directly.plugins/stt_translation— the real production pipeline this library was extracted from,
bundled as reference/example data.
108 tests passing. See README.md for usage, CONTRIBUTING.md for the commit-message
convention this repo enforces via a pre-commit hook.