amun-bci 1.0.0__tar.gz

amun_bci-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Mounir (Lord1Egypt)
+
+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.

amun_bci-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: amun-bci
+Version: 1.0.0
+Summary: Amun — a Breath–Computer Interface. Pilot a falcon with your breath. No electrodes. Just air.
+Author-email: Mohamed Mounir <akim.221992@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Lord1Egypt/Amun
+Project-URL: Repository, https://github.com/Lord1Egypt/Amun
+Keywords: breath,bci,game,interface,audio,biosignal,egyptian,offline
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mic
+Requires-Dist: sounddevice>=0.4; extra == "mic"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: numpy>=1.21; extra == "dev"
+Requires-Dist: pillow>=9; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/hero.png" alt="Amun — a Breath–Computer Interface" width="100%" />
+
+# 𓅃 Amun — a Breath–Computer Interface
+
+**Same acronym. No electrodes. Just air.**
+
+Pilot the falcon of Horus across the Egyptian sky using nothing but your breath.
+Soft breath glides · a hard exhale climbs · silence dives into gravity.
+
+<img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/demo.gif" alt="Amun gameplay" width="80%" />
+
+</div>
+
+---
+
+> A ground-up reimagining of [`CoffeeIsAllYouNeed/Invisible-Driver`](https://github.com/CoffeeIsAllYouNeed/Invisible-Driver).
+> The original was a **Brain**–Computer Interface — drive a car with EEG brain waves
+> through an Arduino, electrodes and a clustering model. **Amun keeps the exact
+> acronym and changes the principle:** here **BCI** means **Breath**–Computer
+> Interface. The signal source becomes the microphone every device already has —
+> no electrodes, no Arduino, fully offline.
+
+## Why this is "the same idea, but better"
+
+| | Invisible-Driver (original) | **Amun** (this repo) |
+|---|---|---|
+| Principle | **Brain** waves (EEG) | **Breath** (acoustic) — *and optionally brain, see below* |
+| Hardware | Arduino + BioAmp + gel electrodes | **None** — any microphone |
+| Acronym | Brain–Computer Interface | **Breath**–Computer Interface |
+| Game | drive a racing car | fly the falcon of Horus over Egypt |
+| Dependencies | Python ML stack + serial | **zero** for the core game |
+| Runs offline | partly | **100% offline** |
+
+The science still lives in Python — a real `ingestion → preprocessing → features →
+classify → engine` pipeline with **k-means calibration** — but the microphone moves
+into the browser, so the whole thing runs with **no third-party dependencies**.
+
+## Quickstart
+
+```bash
+git clone https://github.com/Lord1Egypt/Amun
+cd Amun
+python -m amun           # opens the game in your browser
+```
+
+Allow the microphone and **breathe**. No microphone? Press and hold **SPACE**.
+
+Headless / no browser (great for a quick check or CI):
+
+```bash
+python -m amun --source sim --duration 5 --no-input
+```
+
+## How the breath becomes flight
+
+```
+microphone ─▶ ingestion ─▶ preprocessing ─▶ features ─▶ classify ─▶ engine ─▶ render
+ (browser)    loudness      noise-floor +     RMS /      k-means      falcon    canvas
+              frames        EMA smoothing     ZCR        anchors      physics
+```
+
+- **Silence** → no thrust → gravity → the falcon **dives**.
+- **Soft breath** → partial thrust → the falcon **glides** level.
+- **Hard exhale** → full thrust → the falcon **climbs**.
+
+Deep dive: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ·
+[`docs/SIGNAL_PIPELINE.md`](docs/SIGNAL_PIPELINE.md) ·
+[`docs/CALIBRATION.md`](docs/CALIBRATION.md).
+
+## Optional hardware (it works without any)
+
+Amun is "the hidden one" — it accepts any *invisible* signal, but **always falls
+back to the microphone** if no hardware is present.
+
+| Tier | Input | What you need |
+|---|---|---|
+| **0 · default** | breath via browser mic | nothing |
+| **1 · DIY** | the **Amun Amulet** — breath sensor + OLED + RGB + buzzer | Arduino/ESP32 + parts |
+| **2 · Brain** | a **NeuroSky MindWave** (real EEG attention) | the headset |
+
+```bash
+amun --source serial   --serial-port /dev/rfcomm0   # Amun Amulet (breath)
+amun --source neurosky --serial-port /dev/rfcomm0   # NeuroSky (brain)
+# if the device isn't found, Amun automatically uses the browser mic
+```
+
+Tier 2 brings the original "control with your mind" idea back as a bonus — so Amun
+is a **superset** of Invisible-Driver. Full build, BOM and wiring:
+[`docs/HARDWARE.md`](docs/HARDWARE.md).
+
+## Project layout
+
+```
+src/amun/      engine · ingestion · preprocessing · features · classify · calibrate · server · thinkgear
+src/amun/templates/  the browser game (Web Audio mic + canvas renderer)
+model/         your calibration profile (JSON)
+tools/         sample data · demo-gif · banner/logo · Gemini asset gen · test runner
+tests/         pytest suite (engine · features · classify · websocket · server · thinkgear)
+notebooks/     breath-signal exploration + honest clustering metric
+docs/          architecture & guides     hardware/  Amun Amulet sketch + BOM
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+python tools/test_all.py        # data + calibration + headless run + pytest (exit 0)
+```
+
+See [`TESTING.md`](TESTING.md). Everything runs with **no microphone and no hardware**.
+
+## Honesty note
+
+All performance/quality numbers (e.g. the calibration **silhouette score**) are
+**measured** on bundled, reproducible data — never invented. Your own calibration
+produces a score for your microphone and breathing.
+
+## Status
+
+Live build log: [`CHECKPOINTS.md`](CHECKPOINTS.md).
+
+## License
+
+MIT © 2026 Mohamed Mounir ([Lord1Egypt](https://github.com/Lord1Egypt))
+
+<div align="center"><img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/logo.png" alt="Amun" width="120" /></div>

amun_bci-1.0.0/README.md

@@ -0,0 +1,128 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/hero.png" alt="Amun — a Breath–Computer Interface" width="100%" />
+
+# 𓅃 Amun — a Breath–Computer Interface
+
+**Same acronym. No electrodes. Just air.**
+
+Pilot the falcon of Horus across the Egyptian sky using nothing but your breath.
+Soft breath glides · a hard exhale climbs · silence dives into gravity.
+
+<img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/demo.gif" alt="Amun gameplay" width="80%" />
+
+</div>
+
+---
+
+> A ground-up reimagining of [`CoffeeIsAllYouNeed/Invisible-Driver`](https://github.com/CoffeeIsAllYouNeed/Invisible-Driver).
+> The original was a **Brain**–Computer Interface — drive a car with EEG brain waves
+> through an Arduino, electrodes and a clustering model. **Amun keeps the exact
+> acronym and changes the principle:** here **BCI** means **Breath**–Computer
+> Interface. The signal source becomes the microphone every device already has —
+> no electrodes, no Arduino, fully offline.
+
+## Why this is "the same idea, but better"
+
+| | Invisible-Driver (original) | **Amun** (this repo) |
+|---|---|---|
+| Principle | **Brain** waves (EEG) | **Breath** (acoustic) — *and optionally brain, see below* |
+| Hardware | Arduino + BioAmp + gel electrodes | **None** — any microphone |
+| Acronym | Brain–Computer Interface | **Breath**–Computer Interface |
+| Game | drive a racing car | fly the falcon of Horus over Egypt |
+| Dependencies | Python ML stack + serial | **zero** for the core game |
+| Runs offline | partly | **100% offline** |
+
+The science still lives in Python — a real `ingestion → preprocessing → features →
+classify → engine` pipeline with **k-means calibration** — but the microphone moves
+into the browser, so the whole thing runs with **no third-party dependencies**.
+
+## Quickstart
+
+```bash
+git clone https://github.com/Lord1Egypt/Amun
+cd Amun
+python -m amun           # opens the game in your browser
+```
+
+Allow the microphone and **breathe**. No microphone? Press and hold **SPACE**.
+
+Headless / no browser (great for a quick check or CI):
+
+```bash
+python -m amun --source sim --duration 5 --no-input
+```
+
+## How the breath becomes flight
+
+```
+microphone ─▶ ingestion ─▶ preprocessing ─▶ features ─▶ classify ─▶ engine ─▶ render
+ (browser)    loudness      noise-floor +     RMS /      k-means      falcon    canvas
+              frames        EMA smoothing     ZCR        anchors      physics
+```
+
+- **Silence** → no thrust → gravity → the falcon **dives**.
+- **Soft breath** → partial thrust → the falcon **glides** level.
+- **Hard exhale** → full thrust → the falcon **climbs**.
+
+Deep dive: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ·
+[`docs/SIGNAL_PIPELINE.md`](docs/SIGNAL_PIPELINE.md) ·
+[`docs/CALIBRATION.md`](docs/CALIBRATION.md).
+
+## Optional hardware (it works without any)
+
+Amun is "the hidden one" — it accepts any *invisible* signal, but **always falls
+back to the microphone** if no hardware is present.
+
+| Tier | Input | What you need |
+|---|---|---|
+| **0 · default** | breath via browser mic | nothing |
+| **1 · DIY** | the **Amun Amulet** — breath sensor + OLED + RGB + buzzer | Arduino/ESP32 + parts |
+| **2 · Brain** | a **NeuroSky MindWave** (real EEG attention) | the headset |
+
+```bash
+amun --source serial   --serial-port /dev/rfcomm0   # Amun Amulet (breath)
+amun --source neurosky --serial-port /dev/rfcomm0   # NeuroSky (brain)
+# if the device isn't found, Amun automatically uses the browser mic
+```
+
+Tier 2 brings the original "control with your mind" idea back as a bonus — so Amun
+is a **superset** of Invisible-Driver. Full build, BOM and wiring:
+[`docs/HARDWARE.md`](docs/HARDWARE.md).
+
+## Project layout
+
+```
+src/amun/      engine · ingestion · preprocessing · features · classify · calibrate · server · thinkgear
+src/amun/templates/  the browser game (Web Audio mic + canvas renderer)
+model/         your calibration profile (JSON)
+tools/         sample data · demo-gif · banner/logo · Gemini asset gen · test runner
+tests/         pytest suite (engine · features · classify · websocket · server · thinkgear)
+notebooks/     breath-signal exploration + honest clustering metric
+docs/          architecture & guides     hardware/  Amun Amulet sketch + BOM
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+python tools/test_all.py        # data + calibration + headless run + pytest (exit 0)
+```
+
+See [`TESTING.md`](TESTING.md). Everything runs with **no microphone and no hardware**.
+
+## Honesty note
+
+All performance/quality numbers (e.g. the calibration **silhouette score**) are
+**measured** on bundled, reproducible data — never invented. Your own calibration
+produces a score for your microphone and breathing.
+
+## Status
+
+Live build log: [`CHECKPOINTS.md`](CHECKPOINTS.md).
+
+## License
+
+MIT © 2026 Mohamed Mounir ([Lord1Egypt](https://github.com/Lord1Egypt))
+
+<div align="center"><img src="https://raw.githubusercontent.com/Lord1Egypt/Amun/main/assets/logo.png" alt="Amun" width="120" /></div>

amun_bci-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "amun-bci"
+version = "1.0.0"
+description = "Amun — a Breath–Computer Interface. Pilot a falcon with your breath. No electrodes. Just air."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Mohamed Mounir", email = "akim.221992@gmail.com" }]
+keywords = ["breath", "bci", "game", "interface", "audio", "biosignal", "egyptian", "offline"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Games/Entertainment",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+# The core game has ZERO third-party dependencies (the browser captures the mic).
+dependencies = []
+
+[project.optional-dependencies]
+mic = ["sounddevice>=0.4"]            # optional headless/CLI microphone capture
+serial = ["pyserial>=3.5"]           # optional Amun Amulet / NeuroSky hardware link
+dev = ["pytest>=7", "numpy>=1.21", "pillow>=9"]  # tests, calibration ML, demo gif
+
+[project.urls]
+Homepage = "https://github.com/Lord1Egypt/Amun"
+Repository = "https://github.com/Lord1Egypt/Amun"
+
+[project.scripts]
+amun = "amun.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+amun = ["templates/*.html", "model/*.json", "data/*.csv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

amun_bci-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

amun_bci-1.0.0/src/amun/__init__.py

@@ -0,0 +1,19 @@
+"""Amun — a Breath–Computer Interface (BCI).
+
+The original *Invisible-Driver* was a **Brain**–Computer Interface: drive a car
+with EEG brain waves. Amun keeps the exact acronym and changes the principle —
+**BCI** here means **Breath**–Computer Interface. You pilot a falcon through an
+Egyptian sky using nothing but the microphone every device already has.
+
+Soft breath glides, a hard exhale climbs, silence dives into gravity.
+
+The package mirrors the original's pipeline:
+
+    ingestion -> preprocessing -> features -> classify -> engine -> render
+
+Named for **Amun**, the Egyptian god of air and the hidden/invisible — a mirror
+of "Invisible Driver."
+"""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

amun_bci-1.0.0/src/amun/__main__.py

@@ -0,0 +1,160 @@
+"""Command-line entry point for Amun.
+
+    amun                              # serve the browser game (mic in the browser)
+    amun --no-browser                 # serve without opening a browser
+    amun --source sim --duration 5    # headless run, no browser, no mic
+    amun --source mic                 # headless run using the optional sounddevice mic
+    amun --source replay --file f.csv # headless run from recorded loudness
+    amun calibrate --from data.csv    # fit a calibration profile (non-blocking)
+
+Every mode is non-blocking when given arguments: nothing waits on ``input()``,
+so CI and the test runner never hang.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from .calibrate import DEFAULT_PROFILE_PATH, calibrate_cli, load_or_default
+
+
+def _banner() -> str:
+    return (
+        "\n  𓅃  A M U N  —  Breath–Computer Interface\n"
+        "      pilot a falcon with your breath · no electrodes · just air\n"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="amun", description="Amun — a Breath–Computer Interface.")
+    sub = p.add_subparsers(dest="command")
+
+    # default: serve / run
+    p.add_argument("--source",
+                   choices=["browser", "sim", "replay", "mic", "serial", "neurosky"],
+                   default="browser",
+                   help="signal source (default: browser mic). 'serial'/'neurosky' "
+                        "are optional hardware; they fall back to the mic if absent")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8011)
+    p.add_argument("--file", type=Path, help="loudness file for --source replay")
+    p.add_argument("--serial-port", default=None,
+                   help="serial/Bluetooth port for --source serial|neurosky "
+                        "(e.g. /dev/ttyUSB0, /dev/rfcomm0, COM5)")
+    p.add_argument("--baud", type=int, default=None, help="serial baud rate override")
+    p.add_argument("--duration", type=float, default=None,
+                   help="seconds to run a headless source then exit")
+    p.add_argument("--no-browser", action="store_true", help="don't auto-open a browser")
+    p.add_argument("--no-input", action="store_true",
+                   help="never wait for keyboard input (for automation)")
+    p.add_argument("--quiet", action="store_true")
+
+    cal = sub.add_parser("calibrate", help="fit a calibration profile (non-blocking)")
+    cal.add_argument("--from", dest="from_file", type=Path, default=None,
+                     help="loudness file (one float/line); defaults to bundled sample")
+    cal.add_argument("--out", type=Path, default=DEFAULT_PROFILE_PATH)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "calibrate":
+        profile = calibrate_cli(source_file=args.from_file, save_to=args.out)
+        print(f"Calibrated from {profile.n_frames} frames "
+              f"(silhouette={profile.silhouette:.3f})")
+        print(f"  noise_floor={profile.noise_floor}  soft={profile.soft}  "
+              f"hard={profile.hard}")
+        print(f"Saved profile -> {args.out}")
+        return 0
+
+    profile = load_or_default()
+
+    # Headless sources run the engine directly without a browser.
+    if args.source in ("sim", "replay", "mic", "serial", "neurosky"):
+        from .ingestion import make_source
+        from .server import run_headless
+
+        kwargs = {}
+        if args.source == "replay":
+            if not args.file:
+                print("error: --source replay requires --file", file=sys.stderr)
+                return 2
+            kwargs["path"] = args.file
+        if args.source in ("serial", "neurosky"):
+            if not args.serial_port:
+                print(f"error: --source {args.source} requires --serial-port",
+                      file=sys.stderr)
+                return 2
+            kwargs["port"] = args.serial_port
+            if args.baud:
+                kwargs["baud"] = args.baud
+
+        source = make_source(args.source, **kwargs)
+
+        # Hardware sources may be absent — start them first and, if that fails,
+        # fall back to the always-available browser microphone. "Works anyway."
+        started = False
+        if args.source in ("serial", "neurosky", "mic"):
+            try:
+                source.start()
+                started = True
+            except RuntimeError as exc:
+                print(f"\n  ⚠ {args.source} unavailable:\n    "
+                      f"{str(exc).splitlines()[0]}")
+                print("  → falling back to the browser microphone.\n")
+                return _serve_browser(args, profile)
+
+        if not args.quiet:
+            print(_banner())
+            print(f"  running headless source={args.source} "
+                  f"duration={args.duration or '∞'}\n")
+        final = run_headless(source, profile=profile, duration=args.duration,
+                             quiet=args.quiet, already_started=started)
+        if not args.quiet:
+            print(f"  final score: {final['score']}  ankhs: {final['ankhs']}")
+        return 0
+
+    # Default: browser game.
+    return _serve_browser(args, profile)
+
+
+def _serve_browser(args, profile) -> int:
+    """Serve the browser game (microphone in the page). The guaranteed path."""
+    from .server import run_server
+
+    httpd = run_server(host=args.host, port=args.port, profile=profile,
+                       open_browser=not args.no_browser)
+    url = f"http://{args.host}:{httpd.server_address[1]}/"
+    if not args.quiet:
+        print(_banner())
+        print(f"  🜂  serving at {url}")
+        print("     open it, allow the microphone, and breathe.")
+        print("     (no mic? press & hold SPACE to breathe.  Ctrl+C to stop.)\n")
+
+    if args.no_input:
+        # bounded run for automation
+        import threading
+
+        deadline = time.monotonic() + (args.duration or 1.0)
+        t = threading.Thread(target=httpd.serve_forever, daemon=True)
+        t.start()
+        while time.monotonic() < deadline:
+            time.sleep(0.1)
+        httpd.shutdown()
+        return 0
+
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n  𓂀  may Ma'at weigh your flight kindly. Goodbye.")
+    finally:
+        httpd.shutdown()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

amun_bci-1.0.0/src/amun/calibrate.py

@@ -0,0 +1,69 @@
+"""Calibration — learn your personal silence / soft / hard breath levels.
+
+Two entry points:
+
+* :func:`calibrate_from_samples` — fit a profile from loudness frames you already
+  have (used by the browser calibration step, the notebook and the tests).
+* :func:`calibrate_cli` — a non-blocking helper that fits from a replay/sample
+  file or from bundled sample data, so automation never hangs on ``input()``
+  (per the project's CLI rules).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Sequence
+
+from .classify import CalibrationProfile, fit_profile
+
+PKG = Path(__file__).resolve().parent
+# Where a calibrated profile is written (user-writable, works when pip-installed).
+DEFAULT_PROFILE_PATH = Path.home() / ".config" / "amun" / "profile.json"
+# Read-only resources bundled inside the package (shipped in the wheel).
+BUNDLED_PROFILE = PKG / "model" / "profile.json"
+BUNDLED_SAMPLE = PKG / "data" / "calibration_sample.csv"
+
+
+def calibrate_from_samples(samples: Sequence[float],
+                           save_to: Optional[Path] = None) -> CalibrationProfile:
+    """Fit and (optionally) save a calibration profile from loudness frames."""
+    profile = fit_profile(samples)
+    if save_to is not None:
+        Path(save_to).parent.mkdir(parents=True, exist_ok=True)
+        profile.save(save_to)
+    return profile
+
+
+def load_or_default(path: Optional[Path] = None) -> CalibrationProfile:
+    """Load the saved profile; fall back to the bundled one, then to defaults."""
+    for candidate in (path or DEFAULT_PROFILE_PATH, BUNDLED_PROFILE):
+        candidate = Path(candidate)
+        if candidate.exists():
+            try:
+                return CalibrationProfile.load(candidate)
+            except Exception:
+                continue
+    return CalibrationProfile.default()
+
+
+def _read_values(path: Path) -> list:
+    return [
+        float(line)
+        for line in Path(path).read_text().splitlines()
+        if line.strip()
+    ]
+
+
+def calibrate_cli(source_file: Optional[Path] = None,
+                  save_to: Optional[Path] = None) -> CalibrationProfile:
+    """Non-blocking calibration for scripts/CI.
+
+    Reads loudness values from ``source_file`` (one float per line). If none is
+    given, uses the bundled sample dataset so it always succeeds offline.
+    """
+    if source_file is not None:
+        values = _read_values(Path(source_file))
+    else:
+        values = _read_values(BUNDLED_SAMPLE) if BUNDLED_SAMPLE.exists() else []
+    profile = calibrate_from_samples(values, save_to=save_to or DEFAULT_PROFILE_PATH)
+    return profile