Karl-deck/Bundle Detectors

[KarlDeck]

Add Multi-Signal Bundle Detectors and Explorer Support

♻️ Current situation & Problem

SensorTSLM previously annotated mostly single-signal patterns such as spikes, drops, trends, and a few direct semantic labels. That worked for local signal interpretation, but it missed an important layer of meaning: multiple signals often become useful only when they are interpreted together.

Examples:

• being in bed but awake is more meaningful than inbed alone
• sleep with low heart rate is more meaningful than asleep alone
• high heart rate together with high steps and active energy is more meaningful than any of those channels independently
• workout channels often overlap with more generic exertion signals, but the workout label is usually the more descriptive interpretation

This PR adds a new bundle detection layer that looks across channels and emits higher-level co-occurrence annotations. These bundles are intended to be more useful as narrative building blocks for downstream captioning and story generation.

The PR also makes those bundles visible and searchable in the explorer, and adds data-driven analysis tooling so we can validate which signal combinations are actually useful in the dataset rather than relying only on intuition.

⚙️ Release Notes

• Added multi-signal bundle detection for higher-level co-occurring events
• Added bundle captions for sleep, exertion, stairs, workouts, and watch non-wear with context
• Added overlap resolution so more specific bundles win over generic ones
• Added randomized bundle analysis tooling to validate bundle usefulness on real data
• Added explorer support for bundle overlays, bundle event display, and bundle hit navigation
• Added explicit text annotations for Apple Watch non-wear when other channels still provide context
• Refactored bundle logic into a detector layer, with extraction/rendering kept separate

Example bundle types now include:

• awake_in_bed
• restful_sleep
• activity_surge
• steady_cardio
• nonstep_cardio
• stair_climb_burst
• stairs_effort
• workout-specific bundles for walking, cycling, running, HIIT, elliptical, yoga, strength, and other workout channels
• watch_nonwear_context

📚 Documentation

The main addition in this PR is the new bundle detection layer.

What the bundle detectors do

The bundle detectors combine multiple channels into more descriptive events.

Examples:

• sleep:inbed + sleep:asleep + low-motion context -> sleep-related bundles
• heart rate + steps + active energy -> exertion/cardio bundles
• flights climbed + heart rate -> stair-effort bundles
• workout channels + supporting physiology/movement signals -> workout bundles
• missing watch signals + continuing phone/sleep/workout signals -> watch non-wear context bundles

These bundles are then rendered as text annotations and can be used by downstream systems as richer semantic primitives.

Why this is useful

This makes SensorTSLM outputs:

• more descriptive than single-channel labels
• better aligned with how people describe behavior
• more useful for downstream story generation and summarization
• easier to inspect in the explorer
• more grounded in actual data co-occurrence patterns

Overlap handling

A key part of this PR is that overlapping bundles are no longer treated as equally good annotations.

Examples:

• HIIT should usually outrank a generic activity_surge
• cycling should usually outrank a generic nonstep_cardio
• sleep and workout bundles should generally remain separate if they represent distinct phases rather than one merged activity

The detector therefore applies a specificity/priority-based selection layer so the “harder” or more descriptive bundle survives when multiple candidates explain the same window.

Explorer support

The explorer now supports bundle inspection by:

• showing bundle captions in the event/caption views
• highlighting bundle windows as overlays
• allowing navigation to next/previous hits for bundle targets
• supporting workout bundle targets as searchable jump targets

✅ Testing

Verified with:

.venv311/bin/python -m py_compile detectors/bundle.py extractors/bundle.py explorer.py bundle_analysis.py visualizer.py captionizer.py extractors/__init__.py
.venv311/bin/python bundle_analysis.py --max-rows 15000 --top-k 15 --seed 7

Additional validation included:

• randomized sampling instead of assuming dataset order is meaningful
• checking which bundles fire most often and whether they are semantically useful
• reviewing actual generated captions to improve wording
• verifying that more specific bundles suppress weaker generic overlaps
• verifying that bundle targets are visible and searchable in the explorer
• verifying watch non-wear context annotations on real rows

Data-driven findings from validation included:

• sleep bundles such as restful_sleep and awake_in_bed are strong and interpretable
• walking/running bundles align well with HR, steps, distance, and energy
• cycling is distinct from walking because steps are often weak while HR and energy remain strong
• yoga/strength are valid lower-motion workout bundles and should stay separate from step-heavy cardio
• generic bundles like activity_surge and nonstep_cardio are useful but broader, so overlap suppression is important
• watch_nonwear_context is useful as a metadata-style annotation when phone/sleep/workout context continues during missing watch data

Code of Conduct & Contributing Guidelines

• I agree to follow the Code of Conduct and Contributing Guidelines.

[coderabbitai]

Warning

Rate limit exceeded

@KarlDeck has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 7 minutes and 43 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 7 minutes and 43 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 34452cc2-2704-4187-a70f-b0d8cf4f7dba

📥 Commits

Reviewing files that changed from the base of the PR and between 4a10d06 and d744cb9.

📒 Files selected for processing (11)

• .gitignore
• bundle_analysis.py
• captionizer.py
• detectors/bundle.py
• detectors/spike.py
• explorer.py
• extractors/__init__.py
• extractors/bundle.py
• requirements.txt
• templates/templates.json
• visualizer.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch karl-deck/BundleDetectors

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}