RhythmQuest

RhythmQuest is an experimental adaptive study timer. It records how a user responds at each work interval, then estimates the next work duration from state labels, reaction time, breaks, away time, and return behavior.

It is not a fixed Pomodoro clone. The work duration is stored as a continuous value (next_duration_s) and is updated after each answered interval.

What it does

• Runs as a static browser app from index.html
• Supports GUI buttons, keyboard input, and Makey Makey-style physical input
• Uses a single Start action, then transitions through IDLE, WORK, ALARM, BREAK, AWAY, and ENDED
• Logs events to a 37-column CSV export
• Supports model output sources: ml, fallback, and ml_stub
• Falls back to rule-based control when no trained model is available
• Adds a lightweight RPG layer: Quest, Stamina, EXP, damage signal, spoils reveal, and break BGM

Core interaction:

Touch or click during ALARM = stop the alarm = answer your state = create a log

Try it locally

On Windows:

.\scripts\setup.ps1
.\scripts\serve.ps1
.\scripts\test.ps1

On macOS/Linux:

bash scripts/setup.sh
bash scripts/serve.sh
bash scripts/test.sh

The local server script serves the app at:

http://127.0.0.1:8765/

See docs/tooling.md for setup and test details.

Network boundary

Runtime use is designed to avoid external API communication and automatic upload of personal logs.

Setup scripts may use the network to fetch development/runtime dependencies, including ONNX Runtime Web, Playwright dependencies, and free audio assets. After setup, the app should run locally as a static browser app.

Input labels

A/B/C are user state labels, not time presets.

A = fatigue_low
B = fatigue_mid
C = fatigue_high
D = break_request
E = away
F = end
R = return

Makey Makey input is treated as keyboard input and normalized in software. The standard flow is input_mode=makey with answer_timing_mode=direct_label.

CSV and data

Users can copy or download the session log as CSV. The current CSV contract is defined in docs/spec-current.md and includes hardware_profile, device_id, level_id, spoils_id, spoils_rarity, and bgm_id.

RhythmQuest does not upload personal logs automatically. Local/private output paths are ignored by .gitignore:

logs/
data/
exports/
*.local.csv
*.local.json
rhythmquest-log-*.csv

Machine learning policy

The intended controller is:

normal case: ML model predicts next_duration_s
failure/no-model case: rule fallback predicts next_duration_s

The app can run without a trained model. In that case, it uses fallbackPredict and records model_source=fallback. The ?ml_stub=1 query mode is available for development and regression testing.

This repository includes an initial bootstrap ONNX model at models/rq-gru-v1.onnx. It is a Tiny GRU trained on synthetic, rule-shaped examples so the real ONNX path can run before personal logs exist. If that file is missing, scripts/setup.ps1 / scripts/setup.sh will try to regenerate it when Python has torch, onnx, and onnxruntime; otherwise the app still runs through fallback control.

Asset provenance

Image assets under assets/images/ are AI-generated project assets created by the project owner through Cursor's image-generation interface, with the tool-displayed model label Nano Banana. See assets/images/PROVENANCE.md.

Audio assets under assets/audio/ include Kenney CC0 assets, project-edited exports, and project-generated procedural fallback sounds. See assets/audio/LICENSES.md and assets/audio/PROVENANCE.md.

Break BGM is used only during BREAK. Work-session BGM is intentionally excluded.

Current scope

Included:

• GUI A-F/R input
• Keyboard A-F/R input
• Makey-equivalent A-F/R input
• Single Start button
• Adaptive next_duration_s
• Alarm loop and input feedback sounds
• Break BGM tied to the current spoils roll
• CSV copy/download
• ONNX Runtime Web integration point
• Rule fallback controller
• Playwright smoke tests

Not included:

• GPIO control
• External API communication during runtime use
• Automatic upload of personal logs
• OS-dependent USB autorun
• Heavy PyTorch training on Raspberry Pi
• Work-session BGM
• Paid gacha, ranking, shop, or equipment systems
• Medical diagnosis or health advice

Project documents

Start here:

• docs/README.md: documentation map and current source-of-truth notes
• docs/spec-current.md: current requirements
• docs/detailed-design.md: detailed design
• docs/test-plan-current.md: acceptance test plan
• docs/tooling.md: setup, serve, and test commands

Specialized references:

• docs/hardware-design.md: Makey Makey physical input setup
• docs/makey-direct-input.md: direct-label input behavior
• docs/ml-modeling.md: ML model design
• docs/online-learning-policy.md: online inference and learning boundary
• docs/regression-feedback.md: negative-signal and fallback control design
• docs/audio-policy.md: audio policy
• docs/references.md: research references and rationale

Older documents such as docs/spec.md, docs/test-plan.md, and docs/design-current.md are historical. Prefer the *-current.md files unless a document explicitly says otherwise.

License

RhythmQuest source code and documentation are released under the MIT License. See LICENSE.

Third-party and generated assets may have separate provenance or license notes. See:

• assets/images/PROVENANCE.md
• assets/audio/LICENSES.md
• assets/audio/PROVENANCE.md

Development rule

If a behavior is not covered by docs/spec-current.md, update the specification first, then change the implementation.