Tz support

[burkh4rt]

This pull request introduces comprehensive support for timezone-aware datetime handling throughout the collation and tokenization pipeline. The main changes ensure that all timestamps are normalized to the configured default_timezone (defaulting to UTC if unset), and that this timezone is preserved in all downstream processing. Documentation has been updated to clarify the new behavior, including the implications for clock tokens, dataset merging, and daylight-saving transitions. The codebase has been refactored to implement these changes, replacing the previous approach of converting all times to naive UTC.

Timezone-aware datetime normalization and propagation:

• All timestamps are now normalized to timezone-aware datetimes in the collation config’s default_timezone, and this timezone is preserved throughout the pipeline. Tz-aware columns are converted instant-preserving; tz-naive columns are assumed to be local times in the specified zone. Ambiguous local times (due to DST) take the later instant, and nonexistent times raise an error. (src/cocoa/collator.py, src/cocoa/config/collation.yaml, README.md, docs/api/collator.md) [1] [2] [3] [4] [5] [6] [7] [8] [9]

• The collation config (collation.yaml) and example configs now explicitly include a default_timezone field, and documentation reflects the new timezone handling. (src/cocoa/config/collation.yaml, README.md) [1] [2] [3]

Documentation updates and clarifications:

• The README, API docs, and recipes have been updated to describe the new timezone-aware behavior, the meaning of clock tokens (CLCK//HH), and the importance of consistent default_timezone values when merging datasets or transferring tokenizers. (README.md, docs/api/tokenizer.md, recipes/date-based-generative-inference.md, recipes/tokenizer-transfer.md, CLAUDE.md) [1] [2] [3] [4] [5] [6]

• Clock tokens now explicitly refer to hours in the configured default_timezone, and documentation clarifies their behavior around daylight-saving shifts. (README.md, docs/api/tokenizer.md, recipes/date-based-generative-inference.md) [1] [2] [3]

Other improvements:

• Added a new reference to a federated generative event models paper in the README. (README.md)
• Updated the package version to 26.6.3. (pyproject.toml)
• Added .prettierignore to VSCode settings. (.vscode/settings.json)
• Updated the cotorra trainer link to point to PyPI. (README.md)

These changes make the handling of timezones explicit, robust, and well-documented, improving both correctness and reproducibility when working with time-based data.

[Copilot]

Pull request overview

Adds timezone-aware datetime normalization throughout collation and downstream processing.

Changes:

• Normalizes timestamps to default_timezone, preserving timezone metadata.
• Documents DST, clock-token, transfer, and merge behavior.
• Updates package metadata and editor configuration.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/cocoa/collator.py	Implements timezone normalization.
src/cocoa/config/collation.yaml	Adds the default timezone.
README.md	Documents timezone behavior and updates references.
docs/api/collator.md	Describes collation timezone semantics.
docs/api/tokenizer.md	Clarifies clock-token timezone semantics.
recipes/date-based-generative-inference.md	Clarifies local-midnight inference.
recipes/tokenizer-transfer.md	Documents timezone consistency requirements.
CLAUDE.md	Updates repository guidance and caveats.
pyproject.toml	Bumps the package version.
.vscode/settings.json	Configures Prettier’s ignore file.

---

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