breathe-cli 1.8__py3-none-any.whl

breathe.py

@@ -0,0 +1,700 @@
+#!/usr/bin/env python3
+"""Breathe CLI — paced breathing for HFrEF vagal training. macOS only."""
+
+import argparse
+import os
+import select
+import signal
+import shutil
+import subprocess
+import sys
+import termios
+import time
+import tty
+from dataclasses import dataclass
+
+# ── Constants ────────────────────────────────────────────────────────
+
+VERSION = '1.8'
+
+PRESETS = {
+    'balanced': {'duration_min': 10, 'inhale_s': 5, 'exhale_s': 5},
+    'calm': {'duration_min': 15, 'inhale_s': 4, 'exhale_s': 6},
+    'extended':    {'duration_min': 20, 'inhale_s': 4, 'exhale_s': 6},
+}
+
+PRESET_DESCRIPTIONS = {'balanced': 'Equal ratio, neutral baseline',
+                       'calm': 'Exhale-weighted, parasympathetic emphasis',
+                       'extended': 'Full dose, Bernardi protocol'}
+
+SOUND_INHALE = '/System/Library/Sounds/Tink.aiff'
+SOUND_EXHALE = '/System/Library/Sounds/Pop.aiff'
+AFPLAY       = '/usr/bin/afplay'
+AFPLAY_VOL   = '0.3'
+
+LOG_FILE   = os.path.expanduser('~/.breathe_log.csv')
+LOG_HEADER = 'date,time,preset,ratio,duration_target_s,duration_actual_s,breaths,completion_pct,status'
+
+BAR_WIDTH      = 30
+FRAME_RATE_HZ  = 20
+FRAME_SLEEP    = 1.0 / FRAME_RATE_HZ
+COUNTDOWN_SECS = 3
+MIN_TERM_WIDTH = 40
+MIN_CYCLE_SECS = 8
+
+ANSI_CLEAR    = '\033[2J\033[H'
+ANSI_HIDE_CUR = '\033[?25l'
+ANSI_SHOW_CUR = '\033[?25h'
+ANSI_RESET    = '\033[0m'
+ANSI_DIM      = '\033[2m'
+ANSI_CYAN     = '\033[36m'
+ANSI_GREEN    = '\033[32m'
+ANSI_CLR_LINE = '\033[K'
+
+INHALE, EXHALE, PAUSED = 'INHALE', 'EXHALE', 'PAUSED'
+PHASE_LABEL = {INHALE: 'IN', EXHALE: 'OUT'}
+
+SAFETY_TEXT = """\
+Breathe CLI \u2014 safety notes
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+This app paces slow breathing at 6 breaths per minute for vagal tone
+support. It is a habit tool, not a medical device.
+
+STOP THE SESSION IMMEDIATELY if you experience:
+
+  \u2022 Lightheadedness or dizziness \u2014 you may be breathing too deeply.
+    Reduce depth, not rate. If it persists, stop.
+  \u2022 Palpitations \u2014 stop, note the time, mention at your next
+    cardiology visit.
+  \u2022 Tingling in hands or face \u2014 hyperventilation signal. Stop,
+    return to normal breathing.
+
+This app deliberately does NOT support:
+  \u2022 Breath retention (kumbhaka) of any length
+  \u2022 Rapid breathing (kapalbhati, bhastrika, Wim Hof patterns)
+  \u2022 Total breath cycles shorter than 8 seconds
+
+Press q or Ctrl+C to end any session. Exit is always immediate.
+
+DISCLAIMER: This app is not a medical device. It does not diagnose,
+treat, or prevent any condition. Consult your physician before starting
+a breathing practice, especially with a cardiac or respiratory condition.
+Use at your own risk. The author assumes no liability for any adverse
+effects. By using this app you acknowledge and accept these terms.
+
+For the clinical evidence behind these constraints, see README.md."""
+
+@dataclass
+class Config:
+    duration_s: int
+    inhale_s: int
+    exhale_s: int
+    preset_name: str       # 'balanced', 'calm', 'extended', or 'custom'
+    sound_enabled: bool
+    quiet: bool
+
+    @property
+    def ratio_str(self):
+        return '{}-{}'.format(self.inhale_s, self.exhale_s)
+
+@dataclass
+class Result:
+    breaths: int = 0
+    elapsed: float = 0.0
+    completed: bool = False
+    aborted: bool = False
+
+@dataclass
+class Layout:
+    width: int
+    height: int
+    header_row: int
+    phase_row: int
+    bar_row: int
+    progress_row: int
+    footer_row: int
+    minimal: bool
+    use_colour: bool
+    use_unicode: bool
+
+def supports_colour():
+    if os.environ.get('NO_COLOR'):
+        return False
+    return sys.stdout.isatty()
+
+def supports_unicode():
+    enc = getattr(sys.stdout, 'encoding', '') or ''
+    return 'utf' in enc.lower()
+
+def format_mmss(seconds):
+    m, s = divmod(int(seconds), 60)
+    return '{:02d}:{:02d}'.format(m, s)
+
+def format_human(seconds):
+    m, s = divmod(int(seconds), 60)
+    if m > 0:
+        return '{} min {} s'.format(m, s)
+    return '{} s'.format(s)
+
+def compute_layout():
+    size = shutil.get_terminal_size((80, 24))
+    w, h = size.columns, size.lines
+    minimal = w < MIN_TERM_WIDTH
+    mid = h // 2
+    return Layout(
+        width=w, height=h,
+        header_row=max(mid - 4, 1),
+        phase_row=max(mid - 1, 3),
+        bar_row=max(mid + 1, 5),
+        progress_row=max(mid + 3, 7),
+        footer_row=min(mid + 5, h),
+        minimal=minimal,
+        use_colour=supports_colour(),
+        use_unicode=supports_unicode(),
+    )
+
+def check_audio(quiet):
+    """Init audio subsystem. Returns 'afplay' or 'bell'."""
+    if (os.path.isfile(AFPLAY) and os.access(AFPLAY, os.X_OK)
+            and os.path.isfile(SOUND_INHALE)
+            and os.path.isfile(SOUND_EXHALE)):
+        return 'afplay'
+    if not quiet:
+        sys.stderr.write('audio unavailable: falling back to terminal bell\n')
+    return 'bell'
+
+def play_sound(phase, audio_mode):
+    if audio_mode == 'afplay':
+        path = SOUND_INHALE if phase == INHALE else SOUND_EXHALE
+        try:
+            subprocess.Popen(
+                [AFPLAY, '-v', AFPLAY_VOL, path],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except OSError:
+            pass
+    elif audio_mode == 'bell':
+        sys.stdout.write('\a')
+        sys.stdout.flush()
+
+def setup_raw_tty():
+    if not sys.stdin.isatty():
+        return None
+    try:
+        old = termios.tcgetattr(sys.stdin)
+        tty.setcbreak(sys.stdin.fileno())
+        return old
+    except termios.error:
+        return None
+
+def restore_tty(old_settings):
+    if old_settings is not None:
+        try:
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+        except termios.error:
+            pass
+
+def poll_key():
+    if not sys.stdin.isatty():
+        return None
+    try:
+        r, _, _ = select.select([sys.stdin], [], [], 0)
+        if r:
+            return sys.stdin.read(1)
+    except (OSError, ValueError):
+        pass
+    return None
+
+def move_to(row, col):
+    sys.stdout.write('\033[{};{}H'.format(row, col))
+
+def draw_header(layout, config, remaining_s, paused, muted):
+    move_to(layout.header_row, 1)
+    sys.stdout.write(ANSI_CLR_LINE)
+    parts = []
+    if paused:
+        parts.append('\u2016' if layout.use_unicode else 'P')
+    if muted:
+        parts.append('\U0001f507' if layout.use_unicode else 'M')
+    if not parts:
+        parts.append('\u25cf' if layout.use_unicode else '*')
+    indicator = ' '.join(parts)
+    line = '  {} \u00b7 {} \u00b7 {}   [{}]'.format(
+        config.preset_name, config.ratio_str,
+        format_mmss(remaining_s),
+        indicator,
+    )
+    sys.stdout.write(line)
+
+def draw_phase(layout, phase):
+    move_to(layout.phase_row, 1)
+    sys.stdout.write(ANSI_CLR_LINE)
+    label = PHASE_LABEL.get(phase, phase)
+    if layout.use_colour:
+        colour = ANSI_CYAN if phase == INHALE else ANSI_GREEN
+        styled = colour + label + ANSI_RESET
+    else:
+        styled = label
+    if layout.minimal:
+        sys.stdout.write('  ' + styled)
+    else:
+        pad = (layout.width - len(label)) // 2
+        sys.stdout.write(' ' * pad + styled)
+
+def draw_bar(layout, progress, phase):
+    move_to(layout.bar_row, 1)
+    sys.stdout.write(ANSI_CLR_LINE)
+    if phase == INHALE:
+        filled = round(progress * BAR_WIDTH)
+    else:
+        filled = round((1.0 - progress) * BAR_WIDTH)
+    filled = max(0, min(BAR_WIDTH, filled))
+    empty = BAR_WIDTH - filled
+    if layout.use_unicode:
+        bar = '\u2588' * filled + '\u2591' * empty
+    else:
+        bar = '#' * filled + '-' * empty
+    if layout.minimal:
+        sys.stdout.write('  ' + bar)
+    else:
+        pad = (layout.width - BAR_WIDTH) // 2
+        sys.stdout.write(' ' * pad + bar)
+
+def draw_progress(layout, config, elapsed):
+    move_to(layout.progress_row, 1)
+    sys.stdout.write(ANSI_CLR_LINE)
+    cycle_s = config.inhale_s + config.exhale_s
+    frac = min(1.0, elapsed / config.duration_s) if config.duration_s > 0 else 1.0
+    filled = round(frac * BAR_WIDTH)
+    filled = max(0, min(BAR_WIDTH, filled))
+    empty = BAR_WIDTH - filled
+    if layout.use_unicode:
+        bar = '\u2501' * filled + '\u2500' * empty
+    else:
+        bar = '=' * filled + '-' * empty
+    if layout.use_colour:
+        bar = ANSI_DIM + bar + ANSI_RESET
+    if layout.minimal:
+        sys.stdout.write('  ' + bar)
+    else:
+        pad = (layout.width - BAR_WIDTH) // 2
+        sys.stdout.write(' ' * pad + bar)
+
+def draw_footer(layout, paused):
+    move_to(layout.footer_row, 1)
+    sys.stdout.write(ANSI_CLR_LINE)
+    if paused:
+        text = 'space resume \u00b7 q quit'
+    else:
+        text = 'space pause \u00b7 s mute \u00b7 q quit'
+    if layout.use_colour:
+        text = ANSI_DIM + text + ANSI_RESET
+    sys.stdout.write('  ' + text)
+
+def render_frame(layout, config, elapsed, remaining_s, phase, progress,
+                 paused, muted):
+    draw_header(layout, config, remaining_s, paused, muted)
+    draw_phase(layout, phase)
+    draw_bar(layout, progress, phase)
+    draw_progress(layout, config, elapsed)
+    draw_footer(layout, paused)
+    sys.stdout.flush()
+
+_abort = [False]
+
+def _sigint_handler(signum, frame):
+    _abort[0] = True
+
+def run_countdown(layout, config):
+    """Run the 3-second settle countdown. Returns False if aborted."""
+    for i in range(COUNTDOWN_SECS, 0, -1):
+        if _abort[0]:
+            return False
+        move_to(layout.phase_row, 1)
+        sys.stdout.write(ANSI_CLR_LINE)
+        label = str(i)
+        if layout.minimal:
+            sys.stdout.write('  ' + label)
+        else:
+            pad = (layout.width - len(label)) // 2
+            sys.stdout.write(' ' * pad + label)
+        draw_header(layout, config, config.duration_s, False, False)
+        draw_bar(layout, 0.0, INHALE)
+        draw_footer(layout, False)
+        sys.stdout.flush()
+        for _ in range(FRAME_RATE_HZ):
+            if _abort[0]:
+                return False
+            key = poll_key()
+            if key == 'q':
+                return False
+            time.sleep(FRAME_SLEEP)
+    return True
+
+def run_session(config, result):
+    is_tty = sys.stdout.isatty() and sys.stdin.isatty()
+
+    # ── Non-TTY path ─────────────────────────────────────────────
+    if not is_tty:
+        if not config.quiet:
+            sys.stderr.write('Warning: not a TTY, running without animation.\n')
+        start = time.monotonic()
+        cycle_s = config.inhale_s + config.exhale_s
+        try:
+            time.sleep(config.duration_s)
+            result.completed = True
+        except KeyboardInterrupt:
+            result.aborted = True
+        result.elapsed = min(time.monotonic() - start, float(config.duration_s))
+        result.breaths = int(result.elapsed // cycle_s)
+        return
+
+    audio_mode = check_audio(config.quiet) if config.sound_enabled else 'none'
+    layout = compute_layout()
+    if layout.minimal and not config.quiet:
+        sys.stderr.write('Warning: terminal narrow, running in minimal mode.\n')
+
+    old_termios = setup_raw_tty()
+    old_sigint = signal.signal(signal.SIGINT, _sigint_handler)
+    _abort[0] = False
+
+    muted = not config.sound_enabled
+
+    try:
+        sys.stdout.write(ANSI_HIDE_CUR)
+        sys.stdout.write(ANSI_CLEAR)
+        sys.stdout.flush()
+
+        if not run_countdown(layout, config):
+            result.aborted = True
+            return
+
+        cycle_s = config.inhale_s + config.exhale_s
+        state = INHALE
+        phase_start_wall = time.monotonic()
+        breathing_base = 0.0
+
+        if not muted and audio_mode != 'none':
+            play_sound(INHALE, audio_mode)
+
+        while True:
+            now = time.monotonic()
+
+            # ── PAUSED ──────────────────────────────────────
+            if state == PAUSED:
+                if _abort[0]:
+                    result.aborted = True
+                    break
+                key = poll_key()
+                if key == 'q':
+                    result.aborted = True
+                    break
+                elif key == ' ':
+                    if breathing_base >= config.duration_s:
+                        render_frame(layout, config, config.duration_s, 0,
+                                     EXHALE, 1.0, False, muted)
+                        time.sleep(0.4)
+                        result.completed = True
+                        break
+                    state = INHALE
+                    phase_start_wall = now
+                    if not muted and audio_mode != 'none':
+                        play_sound(INHALE, audio_mode)
+                elif key == 's':
+                    muted = not muted
+                if state == PAUSED:
+                    render_frame(layout, config, paused_elapsed,
+                                 paused_remaining, paused_phase,
+                                 paused_progress, True, muted)
+                    time.sleep(FRAME_SLEEP)
+                    continue
+                # Resume: fall through to active code
+
+            # ── INHALE / EXHALE ─────────────────────────────
+            if _abort[0]:
+                result.aborted = True
+                break
+
+            phase_dur = (config.inhale_s if state == INHALE
+                         else config.exhale_s)
+            phase_elapsed = now - phase_start_wall
+            progress = phase_elapsed / phase_dur
+
+            # Phase transition
+            if progress >= 1.0:
+                if state == INHALE:
+                    phase_start_wall += config.inhale_s
+                    state = EXHALE
+                    if not muted and audio_mode != 'none':
+                        play_sound(EXHALE, audio_mode)
+                else:
+                    result.breaths += 1
+                    breathing_base = result.breaths * cycle_s
+                    if breathing_base >= config.duration_s:
+                        render_frame(layout, config, config.duration_s, 0,
+                                     EXHALE, 1.0, False, muted)
+                        time.sleep(0.4)
+                        result.completed = True
+                        break
+                    phase_start_wall += config.exhale_s
+                    state = INHALE
+                    if not muted and audio_mode != 'none':
+                        play_sound(INHALE, audio_mode)
+                # Recalculate for the new phase so the render below
+                # shows the correct label and bar on the same frame
+                # the sound fires (no stale-frame flicker).
+                phase_dur = (config.inhale_s if state == INHALE
+                             else config.exhale_s)
+                phase_elapsed = now - phase_start_wall
+                progress = phase_elapsed / phase_dur
+
+            # Countdown: integer seconds remaining based on actual
+            # session length (which is always a multiple of cycle_s).
+            clean_phase_s = int(phase_elapsed)
+            if state == INHALE:
+                elapsed_display = breathing_base + phase_elapsed
+                remaining_s = (config.duration_s - breathing_base
+                               - clean_phase_s)
+            else:
+                elapsed_display = (breathing_base + config.inhale_s
+                                   + phase_elapsed)
+                remaining_s = (config.duration_s - breathing_base
+                               - config.inhale_s - clean_phase_s)
+
+            key = poll_key()
+            if key == 'q':
+                result.aborted = True
+                break
+            elif key == ' ':
+                paused_phase = state
+                paused_progress = progress
+                paused_elapsed = elapsed_display
+                paused_remaining = remaining_s
+                state = PAUSED
+                render_frame(layout, config, paused_elapsed,
+                             paused_remaining, paused_phase,
+                             paused_progress, True, muted)
+                time.sleep(FRAME_SLEEP)
+                continue
+            elif key == 's':
+                muted = not muted
+
+            render_frame(layout, config, elapsed_display, remaining_s,
+                         state, progress, False, muted)
+            time.sleep(FRAME_SLEEP)
+
+        result.elapsed = breathing_base
+
+    finally:
+        sys.stdout.write(ANSI_SHOW_CUR)
+        sys.stdout.write(ANSI_RESET)
+        move_to(layout.footer_row + 2, 1)
+        sys.stdout.flush()
+        restore_tty(old_termios)
+        signal.signal(signal.SIGINT, old_sigint)
+
+def _completion(config, result):
+    pct = min(100, int(result.elapsed / config.duration_s * 100)) if config.duration_s > 0 else 100
+    status = 'completed' if result.completed else 'ended early (user)'
+    return pct, status
+
+def print_summary(config, result):
+    label = config.preset_name if config.preset_name != 'custom' else 'custom'
+    target = '{} min ({}, {})'.format(config.duration_s // 60, label, config.ratio_str)
+    pct, status = _completion(config, result)
+    print('Session summary')
+    print('\u2500' * 15)
+    print('Target:    {}'.format(target))
+    print('Completed: {} ({}%)'.format(format_human(result.elapsed), pct))
+    print('Breaths:   {} full cycles'.format(result.breaths))
+    print('Status:    {}'.format(status))
+
+def log_session(config, result, session_start_time):
+    """Append one CSV row to ~/.breathe_log.csv. Never raises."""
+    try:
+        write_header = not os.path.isfile(LOG_FILE)
+        with open(LOG_FILE, 'a') as f:
+            if write_header:
+                f.write(LOG_HEADER + '\n')
+            pct, status = _completion(config, result)
+            row = '{},{},{},{},{},{},{},{},{}'.format(
+                time.strftime('%Y-%m-%d', session_start_time),
+                time.strftime('%H:%M:%S', session_start_time),
+                config.preset_name,
+                config.ratio_str,
+                config.duration_s,
+                int(result.elapsed),
+                result.breaths,
+                pct,
+                status,
+            )
+            f.write(row + '\n')
+    except OSError as e:
+        sys.stderr.write('Warning: could not write session log: {}\n'.format(e))
+
+def print_log_path():
+    if os.path.isfile(LOG_FILE):
+        print(LOG_FILE)
+    else:
+        print('{} (no sessions logged yet)'.format(LOG_FILE))
+
+def print_safety():
+    print(SAFETY_TEXT)
+
+def print_presets():
+    print('Available presets:\n')
+    fmt = '  {:<10} {:>8}   {:<20} {}'
+    print(fmt.format('Name', 'Duration', 'Ratio (in-ex)', 'Target use'))
+    print(fmt.format('\u2500' * 10, '\u2500' * 8, '\u2500' * 20, '\u2500' * 24))
+    for name, p in PRESETS.items():
+        bpm = 60.0 / (p['inhale_s'] + p['exhale_s'])
+        ratio = '{}s-{}s ({:.0f} bpm)'.format(p['inhale_s'], p['exhale_s'], bpm)
+        print(fmt.format(name, '{} min'.format(p['duration_min']),
+                         ratio, PRESET_DESCRIPTIONS[name]))
+
+def _die(msg):
+    sys.stderr.write('Error: ' + msg + '\n')
+    sys.exit(1)
+
+def parse_ratio(ratio_str):
+    _fmt_err = 'Ratio must be in the form `inhale-exhale` (e.g. `5-5` or `4-6`).'
+    parts = ratio_str.split('-')
+    if len(parts) > 2:
+        _die('Three-number ratios imply a breath hold. '
+             'This app does not support breath retention. See `breathe --safety`.')
+    if len(parts) != 2:
+        _die(_fmt_err)
+    try:
+        inhale, exhale = int(parts[0]), int(parts[1])
+    except ValueError:
+        _die(_fmt_err)
+    if inhale + exhale < MIN_CYCLE_SECS:
+        _die('Total breath cycle must be \u2265 8 seconds (no rapid breathing).')
+    if not (3 <= inhale <= 10):
+        _die('Inhale must be 3\u201310 seconds.')
+    if not (3 <= exhale <= 10):
+        _die('Exhale must be 3\u201310 seconds.')
+    if exhale > 2 * inhale:
+        _die('Exhale must not exceed twice the inhale (no clinical evidence'
+             ' for extreme ratios). See README.md for details.')
+    return inhale, exhale
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog='breathe',
+        description='Paced breathing for HFrEF vagal training.',
+        epilog='Example: breathe --preset balanced',
+    )
+    parser.add_argument('--version', action='version',
+                        version='breathe {}'.format(VERSION))
+    parser.add_argument('--safety', action='store_true',
+                        help='Show safety information and exit')
+    parser.add_argument('--list-presets', action='store_true',
+                        help='Show available presets and exit')
+    parser.add_argument('--preset', '-p', choices=list(PRESETS.keys()),
+                        help='Use a named preset (balanced, calm, extended)')
+    parser.add_argument('--duration', '-d', type=int, metavar='MINUTES',
+                        help='Session duration in minutes (1\u201360, default: 10)')
+    parser.add_argument('--ratio', '-r', metavar='IN-EX',
+                        help='Breath ratio as inhale-exhale (e.g. 5-5 or 4-6)')
+    parser.add_argument('--no-sound', '-n', action='store_true',
+                        help='Disable audio cues')
+    parser.add_argument('--quiet', '-q', action='store_true',
+                        help='Suppress startup warnings')
+    parser.add_argument('--log', action='store_true',
+                        help='Show log file path and exit')
+    parser.add_argument('--no-log', action='store_true',
+                        help='Suppress session logging for this run')
+    return parser
+
+def main():
+    if sys.version_info < (3, 7):
+        sys.stderr.write('Error: breathe requires Python 3.7+\n')
+        sys.exit(1)
+
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.safety:
+        print_safety()
+        sys.exit(0)
+
+    if args.log:
+        print_log_path()
+        sys.exit(0)
+
+    if args.list_presets:
+        print_presets()
+        sys.exit(0)
+
+    # Build config from args
+    if args.preset:
+        if args.duration is not None or args.ratio is not None:
+            _die('--preset cannot be combined with --duration or --ratio.')
+        p = PRESETS[args.preset]
+        inhale_s, exhale_s = p['inhale_s'], p['exhale_s']
+        duration_min = p['duration_min']
+        preset_name = args.preset
+    elif args.duration is not None or args.ratio is not None:
+        inhale_s, exhale_s = 5, 5
+        duration_min = 10
+        preset_name = 'custom'
+        if args.ratio:
+            inhale_s, exhale_s = parse_ratio(args.ratio)
+        if args.duration is not None:
+            duration_min = args.duration
+    else:
+        # No args: auto-select preset by time of day
+        hour = time.localtime().tm_hour
+        if hour < 12:
+            preset_name = 'balanced'
+        elif hour < 17:
+            preset_name = 'extended'
+        else:
+            preset_name = 'calm'
+        p = PRESETS[preset_name]
+        inhale_s, exhale_s = p['inhale_s'], p['exhale_s']
+        duration_min = p['duration_min']
+
+    if not (1 <= duration_min <= 60):
+        _die('Duration must be 1\u201360 minutes.')
+
+    # Round duration up to a whole number of breath cycles so that
+    # the countdown, progress bar, and session end are all in sync.
+    cycle_s = inhale_s + exhale_s
+    duration_s = -(-duration_min * 60 // cycle_s) * cycle_s
+
+    config = Config(
+        duration_s=duration_s,
+        inhale_s=inhale_s,
+        exhale_s=exhale_s,
+        preset_name=preset_name,
+        sound_enabled=not args.no_sound,
+        quiet=args.quiet,
+    )
+
+    result = Result()
+    exc_info = None
+    session_start_time = time.localtime()
+
+    try:
+        run_session(config, result)
+    except KeyboardInterrupt:
+        result.aborted = True
+    except Exception:
+        exc_info = sys.exc_info()
+
+    print_summary(config, result)
+
+    if not args.no_log:
+        log_session(config, result, session_start_time)
+
+    if exc_info is not None:
+        import traceback
+        traceback.print_exception(*exc_info)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

breathe_cli-1.8.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: breathe-cli
+Version: 1.8
+Summary: Paced resonance breathing for vagal tone training. Single-file terminal app, no dependencies.
+Author-email: Marek Kowalczyk <mko1971@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marekkowalczyk/breathe-cli
+Project-URL: Documentation, https://marekkowalczyk.github.io/breathe-cli/
+Project-URL: Issues, https://github.com/marekkowalczyk/breathe-cli/issues
+Keywords: breathing,resonance-breathing,hrv,heart-rate-variability,vagal-tone,biofeedback,cli,terminal,health
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Breathe CLI
+
+A terminal app that paces resonance breathing for vagal tone training. macOS only, single file, no dependencies.
+
+```
+$ breathe
+
+  calm · 4-6 · 14:32   [●]
+
+                INHALE
+
+          ██████████████░░░░░░░░░░░░░░░░
+
+  space pause · s mute · q quit
+```
+
+## Why this exists
+
+Resonance breathing — slow, paced breathing at around 6 breaths per minute — is one of the few non-pharmacological interventions shown to improve cardiac vagal tone. The mechanism is straightforward: slow breathing amplifies respiratory sinus arrhythmia (RSA), the natural heart-rate variation linked to the breath cycle. Stronger RSA means stronger vagal outflow, which in turn improves baroreceptor sensitivity and shifts autonomic balance away from sympathetic dominance.
+
+This matters most for people with heart failure with reduced ejection fraction (HFrEF), where sympathetic overdrive is both a symptom and an accelerant of disease progression. Bernardi et al. (1998) demonstrated that slow breathing at 6 bpm improves oxygen saturation and exercise tolerance in CHF patients, with effects visible after a single session. A follow-up study (Bernardi et al. 2002) showed that slow breathing also increases arterial baroreflex sensitivity in CHF — a marker strongly associated with prognosis.
+
+This app is a habit tool that makes daily practice frictionless: open terminal, run `breathe`, follow the bar. It is not a medical device.
+
+### The science in brief
+
+**Why 6 breaths per minute?** The cardiovascular system has a resonance frequency — typically between 4.5 and 6.5 bpm in adults — at which heart rate oscillations are maximally amplified (Vaschillo et al. 2006). Breathing at or near this frequency produces the largest RSA swings, which drive the strongest vagal training stimulus. Individual resonance frequency varies and can only be identified precisely with HRV biofeedback hardware. Without it, 6 bpm is the best population-level default: it sits at the centre of the typical range and matches the rate used in the CHF clinical trials (Bernardi et al. 1998, 2002).
+
+**Why a longer exhale in the `calm` and `extended` presets?** Cardiac vagal efferent activity is gated to the respiratory cycle — vagal outflow is stronger during expiration than inspiration. A longer exhale (4s in, 6s out) extends the phase of peak vagal drive within each breath, biasing the autonomic balance further toward parasympathetic tone (Russo et al. 2017, Lehrer & Gevirtz 2014). The total cycle is still 10 seconds (6 bpm). The `balanced` preset uses equal timing (5-5) as a neutral baseline; the `calm` and `extended` presets use the exhale-weighted ratio for parasympathetic emphasis.
+
+**Why these safety constraints?** See the [Design choices](#design-choices) section below. Each constraint maps to a specific physiological risk that is elevated in cardiac patients.
+
+### Finding your resonance frequency
+
+The presets use 6 bpm because it works well for most people and matches the clinical trial protocols. But individual resonance frequency varies — typically between 4.5 and 6.5 bpm — and breathing at *your* resonance frequency produces a stronger vagal training stimulus than breathing at the population average (Vaschillo et al. 2006).
+
+If you have HRV biofeedback hardware, you can find your personal optimum. If you don't, the 6 bpm default is a good choice — consistent daily practice matters more than nailing the exact frequency.
+
+#### What you need
+
+- A chest-strap heart rate monitor (e.g. Polar H10, Garmin HRM-Pro). Wrist-based optical sensors are not accurate enough for beat-to-beat HRV.
+- Software that displays real-time R-R intervals or HRV metrics: [Kubios](https://www.kubios.com), [Elite HRV](https://elitehrv.com), [HRV4Training](https://www.hrv4training.com), or a dedicated biofeedback system.
+
+#### Protocol
+
+Run this test sitting upright in a quiet room, at the same time of day you normally practice. The whole procedure takes about 30 minutes.
+
+1. **Baseline** (2 min). Breathe normally. Let your heart rate settle. Start your HRV recording.
+2. **Test rate 1: 6.0 bpm** (3 min). Run `breathe --ratio 5-5 -d 3 --no-log`. Follow the pacer. At the end, note the average RMSSD (or, if your software shows a live heart rate trace, note how wide the oscillations are — peak-to-trough in bpm).
+3. **Rest** (1–2 min). Breathe normally.
+4. **Test rate 2: 5.5 bpm** (3 min). Run `breathe --ratio 5-6 -d 3 --no-log`. Note the same metric.
+5. **Rest** (1–2 min).
+6. **Test rate 3: 5.0 bpm** (3 min). Run `breathe --ratio 6-6 -d 3 --no-log`. Note the same metric.
+7. **Rest** (1–2 min).
+8. **Test rate 4: 4.6 bpm** (3 min). Run `breathe --ratio 6-7 -d 3 --no-log`. Note the same metric.
+
+**Interpreting results:** The rate that produces the highest RMSSD, the highest LF power in the HRV spectrum, or the visibly widest heart rate oscillations is your resonance frequency. If two adjacent rates are close, pick the slower one — it's more comfortable for long sessions.
+
+**Limitations:** Phase durations are whole seconds, so only certain BPMs are representable: 4.6, 5.0, 5.5, 6.0, 6.7, 7.5 bpm. Your true resonance might fall between two testable rates. Pick the closest one. The difference in training effect between 5.0 and 5.5 bpm is small.
+
+#### Using your frequency
+
+Once you know your frequency, use `--ratio` to match it:
+
+```bash
+breathe --ratio 6-7    # 13s cycle = 4.6 bpm
+breathe --ratio 6-6    # 12s cycle = 5.0 bpm
+breathe --ratio 5-6    # 11s cycle = 5.5 bpm
+breathe --ratio 5-5    # 10s cycle = 6.0 bpm (default)
+```
+
+You can also add exhale emphasis at your resonance frequency:
+
+```bash
+breathe --ratio 5-7    # 12s cycle = 5.0 bpm, exhale-weighted
+breathe --ratio 4-7    # 11s cycle = 5.5 bpm, exhale-weighted
+breathe --ratio 4-8    # 12s cycle = 5.0 bpm, strong exhale emphasis
+```
+
+### References
+
+- Bernardi L, Spadacini G, Bellwon J, et al. ["Effect of breathing rate on oxygen saturation and exercise performance in chronic heart failure."](https://doi.org/10.1016/S0140-6736(97)10341-5) *Lancet*. 1998;351(9112):1308-1311.
+- Bernardi L, Porta C, Spicuzza L, et al. ["Slow breathing increases arterial baroreflex sensitivity in patients with chronic heart failure."](https://doi.org/10.1161/hc0202.103311) *Circulation*. 2002;105(2):143-145.
+- Bernardi L, Sleight P, Bandinelli G, et al. ["Effect of rosary prayer and yoga mantras on autonomic cardiovascular rhythms."](https://doi.org/10.1136/bmj.323.7327.1446) *BMJ*. 2001;323:1446.
+- Vaschillo EG, Vaschillo B, Lehrer PM. ["Characteristics of resonance in heart rate variability stimulated by biofeedback."](https://doi.org/10.1007/s10484-006-9009-3) *Appl Psychophysiol Biofeedback*. 2006;31(2):129-142.
+- Lehrer PM, Gevirtz R. ["Heart rate variability biofeedback: how and why does it work?"](https://doi.org/10.3389/fpsyg.2014.00756) *Front Psychol*. 2014;5:756.
+- Russo MA, Santarelli DM, O'Rourke D. ["The physiological effects of slow breathing in the healthy human."](https://doi.org/10.1183/20734735.009817) *Breathe*. 2017;13(4):298-309.
+
+## Design choices
+
+This app is deliberately constrained. Several common breathing-app features are excluded for safety and focus:
+
+**No breath retention.** Breath holds (kumbhaka) raise intrathoracic pressure via a Valsalva-like mechanism and can trigger vasovagal syncope or arrhythmia in cardiac patients. The Bernardi protocols use continuous breathing with no hold phases. The app rejects three-number ratios like `4-7-8` with an explicit safety error.
+
+**No rapid breathing.** Patterns faster than 7.5 bpm (cycles shorter than 8 seconds) move toward hyperventilation territory, reducing arterial CO2 and mobilising catecholamines — the opposite of the vagal intent (Russo et al. 2017). The app enforces a minimum cycle length of 8 seconds.
+
+**No breath holds between phases.** There is no pause between inhale and exhale. The breath is continuous, matching the protocol in Bernardi et al. (1998, 2002).
+
+**Immediate exit, always.** Pressing `q` or `Ctrl+C` ends the session within one frame. The terminal is always restored — cursor, colours, input mode — even if the app crashes. The `finally` block that does this is the most important code in the file.
+
+**No dependencies.** Single Python file, stdlib only. Nothing to install, nothing to break. Runs on the Python that ships with macOS.
+
+**No curses.** Direct ANSI escape codes only. The curses library has edge cases with non-default terminals on macOS Mojave.
+
+## Requirements
+
+- macOS (uses `/usr/bin/afplay` for audio cues)
+- Python 3.7+
+
+## Installation
+
+```bash
+# Clone or download breathe.py, then:
+chmod +x breathe.py
+
+# Option A: run directly
+./breathe.py
+
+# Option B: symlink into your PATH
+ln -s "$(pwd)/breathe.py" /usr/local/bin/breathe
+breathe
+```
+
+## Usage
+
+### No arguments — time-of-day auto-select
+
+```bash
+breathe
+```
+
+With no arguments, the app picks a preset based on the time of day:
+
+| Time of day  | Preset      | Duration | Ratio | BPM |
+|--------------|-------------|----------|-------|-----|
+| Before noon  | `balanced`  | 10 min   | 5s-5s | 6   |
+| 12:00–16:59  | `extended`  | 20 min   | 4s-6s | 6   |
+| 17:00+       | `calm`      | 15 min   | 4s-6s | 6   |
+
+All presets target 6 breaths per minute. The `balanced` preset uses equal inhale/exhale (5-5) as a neutral baseline. The `calm` and `extended` presets use a longer exhale (4-6), which emphasises vagal activation during the expiratory phase. The time-of-day auto-select picks `calm` in the evening as a default — but you can use any preset at any time.
+
+### Presets
+
+```bash
+breathe --preset balanced    # 10 min, 5s-5s
+breathe --preset calm        # 15 min, 4s-6s
+breathe --preset extended    # 20 min, 4s-6s (full Bernardi protocol dose)
+breathe --list-presets        # show the table
+```
+
+### Custom sessions
+
+```bash
+breathe --duration 5                # 5 minutes, default 5-5 ratio
+breathe --ratio 4-6                 # default 10 minutes, 4-6 ratio
+breathe --duration 12 --ratio 4-6   # 12 minutes, 4-6 ratio
+```
+
+Duration: 1–60 minutes (rounded up to complete breath cycles). Ratio: inhale and exhale each 3–10 seconds, total cycle >= 8 seconds, exhale at most 2x inhale.
+
+### Flags
+
+| Flag              | Short | Description                                |
+|-------------------|-------|--------------------------------------------|
+| `--preset NAME`   | `-p`  | Use a named preset                         |
+| `--duration MIN`  | `-d`  | Session length in minutes (1–60)           |
+| `--ratio IN-EX`   | `-r`  | Breath ratio, e.g. `5-5` or `4-6`         |
+| `--no-sound`      | `-n`  | Disable audio cues                         |
+| `--quiet`         | `-q`  | Suppress startup warnings                  |
+| `--no-log`        |       | Don't log this session                     |
+| `--log`           |       | Print log file path and exit               |
+| `--safety`        |       | Print safety information and exit          |
+| `--list-presets`  |       | Print preset table and exit                |
+| `--version`       |       | Print version and exit                     |
+
+### Runtime keys
+
+During a session:
+
+| Key       | Action                                                            |
+|-----------|-------------------------------------------------------------------|
+| `space`   | Pause / resume. Resume restarts from the beginning of INHALE.     |
+| `s`       | Toggle sound mute.                                                |
+| `q`       | Quit immediately. Terminal is restored.                           |
+| `Ctrl+C`  | Same as `q`.                                                      |
+
+### The display
+
+```
+  balanced · 5-5 · 09:12   [●]       <- preset, ratio, countdown, status
+
+                INHALE                <- current phase (cyan) or EXHALE (green)
+
+          ████████████████░░░░░░░░░░░░░░  <- breath bar (fills on inhale, drains on exhale)
+
+  space pause · s mute · q quit       <- available controls
+```
+
+The status indicator shows `●` during breathing, `‖` when paused, and `🔇` when muted.
+
+The countdown timer tracks completed breathing time only. If you pause for 30 seconds during a 1-minute session, the session takes ~90 seconds of wall-clock time to complete — the timer doesn't advance while paused.
+
+## Session logging
+
+Each session appends a row to `~/.breathe_log.csv`:
+
+```
+date,time,preset,ratio,duration_target_s,duration_actual_s,breaths,completion_pct,status
+2026-05-30,07:15:02,balanced,5-5,600,600,60,100,completed
+2026-05-30,19:30:14,calm,4-6,900,420,42,46,ended early (user)
+```
+
+Use `--no-log` to skip logging for a session. Use `--log` to see the log file path.
+
+## Testing
+
+Automated tests cover logic and arithmetic (formatting, ratio parsing, safety rejections, preset invariants, countdown calculation):
+
+```bash
+python3 -m unittest test_breathe -v
+```
+
+TUI behaviour (rendering, animation, terminal restoration) is covered by 25 manual acceptance tests in `dev/breathe-cli-spec.md`.
+
+## Safety
+
+Run `breathe --safety` for the full safety screen. The short version:
+
+**Stop immediately** if you experience lightheadedness, palpitations, or tingling in your hands or face.
+
+This app deliberately does not support breath retention, rapid breathing, or any pattern not grounded in the slow-breathing clinical literature. These constraints are enforced in the code and cannot be overridden. See [The science in brief](#the-science-in-brief) and [Design choices](#design-choices) for the clinical rationale.
+
+## Disclaimer
+
+This app is not a medical device. It does not diagnose, treat, cure, or prevent any disease or condition. Always consult your physician before starting a breathing practice, especially if you have a cardiac or respiratory condition. Use entirely at your own risk. The author assumes no liability for any adverse effects arising from the use of this software. By using this app you acknowledge that you understand and accept these terms.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full text.
+
+Created by [Marek Kowalczyk](https://orcid.org/0009-0008-3874-6736).

breathe_cli-1.8.dist-info/RECORD

@@ -0,0 +1,7 @@
+breathe.py,sha256=623dX5GgfYkCadSmYlimW1sZlQ4L742zKrk0YO4uhIQ,24343
+breathe_cli-1.8.dist-info/licenses/LICENSE,sha256=lKouHgKx3I4JtjzalKNSwEM0U25d6ca7Y6AP7PY5d2U,1072
+breathe_cli-1.8.dist-info/METADATA,sha256=Upc6vuNhQ9wT31UKLc3VTHPCvdLbeTB_DJLEbIfCH04,15259
+breathe_cli-1.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+breathe_cli-1.8.dist-info/entry_points.txt,sha256=z5O39aNCyZBvVsa94eezZbHlSugZfKNZB_HxcA8ND7Y,41
+breathe_cli-1.8.dist-info/top_level.txt,sha256=iqVRyeRyaqNT9iVMMh_c_avGu__JgNXMlYNEeVDVGKA,8
+breathe_cli-1.8.dist-info/RECORD,,

breathe_cli-1.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

breathe_cli-1.8.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+breathe = breathe:main

breathe_cli-1.8.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marek Kowalczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breathe_cli-1.8.dist-info/top_level.txt

@@ -0,0 +1 @@
+breathe