feat(stdlib): add streaming event types, events() iterator, and OTEL bridge (#902)

[planetf1]

Pull Request

Issue

Fixes #902

Description

Wave 4 (final wave) of the streaming validation epic (#891). Adds typed streaming events, an events() async iterator, and OTEL instrumentation to StreamChunkingResult.

What changed

mellea/stdlib/streaming.py

• Eight typed event dataclasses: StreamEvent base + ChunkEvent, QuickCheckEvent, StreamingDoneEvent, FullValidationEvent, RetryEvent, CompletedEvent, ErrorEvent
• StreamChunkingResult.events() — single-consumer async iterator; raises RuntimeError on second call
• OTEL application span wrapping orchestrator lifetime with span events and metric helper calls (record_requirement_check, _failure, _sampling_outcome, _error)
• ErrorEvent replaces MelleaLogger.warning stopgap; removes TODO(#902) comment
• StreamingDoneEvent emitted after the flush loop (not before), so the documented event order — QC/Chunk pairs → StreamingDoneEvent → FullValidationEvent → CompletedEvent — holds exactly
• _orchestration_exception stash moved to first statement in except block so acomplete() always has it even if a subsequent await is interrupted by CancelledError
• Terminal finally bookkeeping uses put_nowait() to eliminate await points under a pending CancelledError
• mot.is_computed() guard in except block prevents double-cancel when exception arrives after natural stream end

mellea/stdlib/__init__.py

• RetryEvent removed from __all__ (never emitted by v1 orchestrator; class remains accessible via mellea.stdlib.streaming.RetryEvent)

Docs

• docs/docs/how-to/use-async-and-streaming.md — new "Streaming with per-chunk validation" section covering events(), astream(), and the tri-state table
• docs/docs/concepts/requirements-system.md — new "Streaming validation" section covering stream_validate, state isolation, and the clone-per-attempt contract
• docs/examples/streaming/ — streaming_chunking.py updated to events() API; new examples: word_chunking.py, paragraph_chunking.py, custom_chunking.py
• docs/docs/examples/index.md — streaming/ row added
• docs/docs/tutorials/06-streaming-validation.md — new Tutorial 06 covering stream_with_chunking end-to-end: basic call → early exit → chunking strategy choice → astream() shortcut → custom ChunkingStrategy subclass
• docs/docs/docs.json — Tutorial 06 added to navigation

Review findings addressed (3-reviewer panel, 2026-05-19)

• B1 — renamed quick_check_requirements= → requirements= in all 4 new doc examples and how-to guide (was causing TypeError at runtime)
• W1 — _orchestration_exception stash moved before all awaits in except block
• W2 — StreamingDoneEvent moved after flush loop; docstrings updated
• W3 — acomplete() docstring now accurately describes the raise-once contract
• N1 — removed duplicate comment in acomplete()
• N2 — RetryEvent removed from mellea.stdlib.__all__
• N3 — added test_events_single_consumer_guard_raises_on_second_call
• N4 — pvr.reason replaced with "" in record_requirement_failure to avoid unbounded metric label cardinality
• N5 — added @pytest.mark.asyncio to test_unknown_chunking_alias_raises_value_error

Context

Wave 3 (#942) was squash-merged as 9e8a9636; this branch is rebased onto upstream/main via cherry-pick.

Testing

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

uv run pytest test/stdlib/test_streaming.py — 40 tests, all passing

Streaming tests cover: event ordering, single-consumer guard, early-exit semantics, OTEL span emission, ErrorEvent on exception, CancelledError raise-once contract, metric cardinality (pvr.reason not in label), @pytest.mark.asyncio on alias-error test.

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

🤖 Generated with Claude Code

[github-actions]

This comment is managed by a bot. Editing it is fine — checking off boxes, adding notes — but please leave the HTML comment marker on the first line alone, otherwise checklist updates will break.

Requirement PR Checklist

Use this checklist when adding or modifying requirements in mellea/stdlib/requirements/.

Base Class

• Extends appropriate base class:
  • Requirement - standard requirement
  • ALoraRequirement - uses specialized Intrinsic/Adapter for generation-based validation

Validation Logic

• validation_fn defined (if using Python-based validation)
  • re-usable functionality within the validation_fn should be separated out into mellea/stdlib/tools/
• validate returns a ValidationResult with
  • a thunk and context if using a backend to generate
  • a specific reason and score when possible

Integration

• Requirement exported in mellea/stdlib/requirements/__init__.py or, if you are adding a library of requirements, from your sub-module

[jakelorocco]

lgtm; the docs are bit lengthy but I'm okay with having all of those examples / code snippets for now; thank you

[planetf1]

Thanks for the merge! If any of the docs (tutorial length, example verbosity, etc.) need trimming or adjusting, happy to address those as follow-up issues rather than hold things up.