Capitalize first letter of generated captions

[max-rosenblattl]

♻️ Current situation & Problem

Several caption templates start with a placeholder ({name}, {activity_name}) that resolves to a lowercase value (e.g., "heart rate", "active energy", "yoga", "running"). Rendered captions therefore start with a lowercase letter — e.g., "heart rate centered at 80 bpm…", "running took up minute 10 to 30.". extractors/semantic.py already worked around this with an inline `caption[0].upper() + caption[1:]`, but the other emit sites didn't.

⚙️ Release Notes

• Add `util.capitalize` helper that uppercases the first alphabetic character (skips leading punctuation/whitespace, no-op if already uppercase or empty).
• Apply it at every full-caption emit site:
  • `extractors/statistical.py`, `extractors/structural.py`, `extractors/semantic.py`
  • `synthesizers/_helper.finalize_caption_text` (covers all `WorkoutSynthesizer` subclasses via `_workout.py`)
  • `synthesizers/sleep.py` (both the asleep/in-bed branches)
• Replaces the inline capitalization in `extractors/semantic.py` with the shared helper (also safer on empty strings).

Metric-suffix fragments built in `_helper.py` (e.g. "averaging a heart rate of 80 bpm") are intentionally left lowercase since they are concatenated mid-sentence after a leading caption.

📚 Documentation

No template changes needed; capitalization is now applied at the rendering boundary, so future templates can keep using lowercase placeholders without producing ungrammatical sentence starts.

✅ Testing

• Smoke-tested `capitalize` on edge cases (already capital, empty, leading punctuation, leading whitespace).
• Ran the weekly explorer (`MHC_WEEKLY_DATASET_DIR=… .venv/bin/python explorer.py --weekly`); rendered captions now start with a capital letter across statistical, structural, semantic, sleep, and workout categories.

Code of Conduct & Contributing Guidelines

By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines:

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

[coderabbitai]

📝 Walkthrough

Walkthrough

A new capitalize utility function is introduced in util.py to handle first-letter capitalization. This function is then adopted across multiple extractors and synthesizers—semantic, statistical, structural, sleep stages, and helpers—replacing inline capitalization implementations or ensuring consistent capitalization behavior.

Changes

Cohort / File(s)	Summary
Utility Function util.py	Introduces new capitalize(text: str) function that uppercases the first alphabetic character in a string while leaving other characters unchanged.
Extractors extractors/semantic.py, extractors/statistical.py, extractors/structural.py	Each extractor refactored to delegate caption capitalization to the shared capitalize helper instead of inline string operations or unprocessed template output.
Synthesizers synthesizers/_helper.py, synthesizers/sleep.py	Caption finalization and sleep annotation text generation updated to use the capitalize function for consistent first-letter normalization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: capitalizing the first letter of generated captions across the codebase.
Description check	✅ Passed	The description thoroughly explains the problem, solution, implementation details, and testing performed, directly relating to the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch max-rosenblattl/capitalize-caption-first-letter

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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

[coderabbitai]

🧹 Nitpick comments (1)

util.py (1)

16-20: ⚡ Quick win

Add a focused test for this helper.

Since this now drives caption casing across multiple emitters, a small regression here would fan out widely. Please cover empty input, leading punctuation/whitespace, and already-capitalized text.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@util.py` around lines 16 - 20, Add a focused unit test suite for the
capitalize(text: str) helper in util.py that verifies behavior for empty input,
leading punctuation/whitespace, and already-capitalized text: create tests
calling capitalize("") expecting "", capitalize("  -hello") expecting the first
alphabetic character to be capitalized ("  -Hello"), and capitalize("Already")
expecting "Already" (unchanged); also include a test for a lowercase word like
"word" -> "Word" to ensure basic functionality remains correct and assert exact
string equality for each case.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@util.py`:
- Around line 16-20: Add a focused unit test suite for the capitalize(text: str)
helper in util.py that verifies behavior for empty input, leading
punctuation/whitespace, and already-capitalized text: create tests calling
capitalize("") expecting "", capitalize("  -hello") expecting the first
alphabetic character to be capitalized ("  -Hello"), and capitalize("Already")
expecting "Already" (unchanged); also include a test for a lowercase word like
"word" -> "Word" to ensure basic functionality remains correct and assert exact
string equality for each case.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7e7118f9-d257-4544-8859-dad8a7737172

📥 Commits

Reviewing files that changed from the base of the PR and between 1085683 and f0a2b98.

📒 Files selected for processing (6)

• extractors/semantic.py
• extractors/statistical.py
• extractors/structural.py
• synthesizers/_helper.py
• synthesizers/sleep.py
• util.py