feat: metric group_by

[ashenfad]

No description provided.

[Copilot]

Pull request overview

This PR adds a group_by parameter to the metrics functions (total_duration, count_intervals, coverage_ratio) that enables cyclic histogram aggregation, such as aggregating metrics by hour-of-day or day-of-week across multiple time periods.

• Introduces GroupBy type and validation logic for period/group_by combinations
• Implements _grouped_agg helper function to aggregate metrics by cyclic keys
• Adds comprehensive test coverage for the new grouping functionality

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
calgebra/metrics.py	Core implementation of group_by functionality including validation, key extraction, grouped aggregation logic, and updates to metric functions
tests/test_metrics_groupby.py	Comprehensive test suite covering validation, grouping behavior, and edge cases for all three metrics
docs/API.md	Documentation of the new group_by feature with valid combinations table and usage examples
calgebra/docs/API.md	Duplicate documentation file (identical to docs/API.md)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.