refactor!: partition ModelOutputThunk execution metadata into Generat…

[ajbozarth]

Misc PR

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes ModelOutputThunk field refactor: partition fields into sub-structures #793

Groups the five flat execution-metadata fields (usage, model, provider,
ttfb_ms, streaming) from ModelOutputThunk into a single GenerationMetadata
dataclass accessed as mot.generation. This was motivated by __init__,
_copy_from, __copy__, and __deepcopy__ growing a new line with every
telemetry field addition — the sub-object keeps those methods lean as the
metadata surface grows and gives callers a typed namespace.

⚠️ Breaking change: mot.usage, mot.model, mot.provider, mot.ttfb_ms,
and mot.streaming are removed — use mot.generation.* instead.

All five fields were added ~5 weeks ago as part of the same telemetry epic, so
this is a hard break with no deprecated aliases. All callers in mellea/,
cli/, test/, and docs/ have been updated in this PR.

Changed files:

• mellea/core/base.py — new GenerationMetadata dataclass; ModelOutputThunk replaces 5 flat fields with self.generation
• mellea/core/__init__.py — exports GenerationMetadata
• mellea/backends/{openai,litellm,ollama,watsonx,huggingface}.py — mot.* → mot.generation.* in post_processing()
• mellea/telemetry/metrics_plugins.py — updated all 4 plugins to read via mot.generation
• mellea/helpers/openai_compatible_helpers.py — build_completion_usage updated to read output.generation.usage
• test/backends/test_{ollama,openai_ollama,litellm_ollama,watsonx,huggingface}.py — assertion updates
• test/cli/test_{serve,serve_streaming,serve_errors}.py — fixture/setup updates
• test/core/test_base.py — new copy semantics tests for GenerationMetadata
• test/telemetry/test_metrics_plugins.py — updated helpers to use GenerationMetadata constructor
• AGENTS.md, docs/docs/evaluation-and-observability/metrics.md, docs/examples/telemetry/metrics_example.py — updated field references

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.

[ajbozarth]

@planetf1 Cross-reference for #891 implementation: this PR removed the five flat execution-metadata fields (usage, model, provider, ttfb_ms, streaming) from ModelOutputThunk with no deprecated aliases. They now live on mot.generation.*.

The streaming path introduced by #891 will interact with at least mot.generation.streaming and mot.generation.ttfb_ms, so the sub-issue should use the new paths. No merge conflicts expected — the file sets are disjoint — but worth noting before #898–#901 work begins.

Minor: sub-issue #901 cites mellea/core/base.py:434-436 for the single-consumer constraint comment. Line numbers may have shifted due to changes in this PR — worth verifying when implementing.

[planetf1]

@ajbozarth thanks. One other note I found -- __copy__ now shares the GenerationMetadata instance by reference rather than copying each scalar independently, so post-copy mutations to one affect the other. No production code shallow-copies a MOT today, but #901 (stream_with_chunking) could introduce that path. If needed, copied.generation = copy(self.generation) is a one-line fix — happy to pick that up in the #901 PR rather than actioning it here speculatively. Will also make things easier if this is merged as I can design/build on top of it!

[ajbozarth]

One other note I found -- copy now shares the GenerationMetadata instance by reference rather than copying each scalar independently, so post-copy mutations to one affect the other.

Fixed in 756d1a3

@planetf1 your review should all be addressed now