feat: real-time commentary with streaming text & tone

[oyeyemipamilerin6-collab]

Overview

This PR adds a real-time Match Commentary Generator that consumes live move streams, detects tactical events, synthesizes an appropriate commentary tone, and streams engaging sentences token-by-token over WebSockets — with first-token latency under 200ms and no spam on routine moves.

Related Issue

Closes AI-29

Changes

🎙️ Commentary Engine

• [ADD] agent-engines/gpu_worker/personality.py

  • Implements CommentaryEngine consuming live move streams.
  • Detects brilliant moves, trades, missed opportunities, clock panics (<15s), and sudden counter-attacks.
  • Selects commentary tone: Excited/Hype, Dry/Sarcastic, Academic Grandmaster, or Casual Beginner.
  • Streams generated commentary text token-by-token over WebSocket.
  • Rate-limits commentary to at most 1 comment every 3 moves or major tactical event.
  • Suppresses routine opening moves and filters profane/toxic output.

• [ADD] Event trigger detectors

  • Sacrifice detector: flags material sacrifices and brilliancies.
  • Clock scramble detector: flags positions with <15s on the clock.
  • Missed opportunity and counter-attack detectors for non-routine events.

• [MODIFY] agent-engines/gpu_worker/models.py

  • Adds structured commentary event schemas and tone enums for WebSocket serialization.

• [ADD] agent-engines/tests/test_commentary_engine.py

  • Coverage for all tactical triggers, tone selection, streaming token latency, and rate limiting.

Verification Results

pytest agent-engines/tests/test_commentary_engine.py
✅ 14/14 passed

Live acceptance check:
✅ Contextual commentary for brilliant moves, trades, missed opportunities, clock panics, counter-attacks
✅ First-token streaming latency < 200ms
✅ Rate limit enforced (≤1 comment per 3 moves / tactical event)
✅ No profanity or spam on routine opening moves

Acceptance Criteria	Status
Generates contextual commentary accurately referencing players and moves	✅ Brilliant/trade/miss/clock/counter-attack triggers verified in unit tests
Token-by-token streaming response latency < 200ms for first token	✅ First-token latency measured under 200ms in streaming test
Unit tests test commentary triggers across tactical game events	✅ Sacrifice, clock scramble, missed opportunity, trade, counter-attack covered

Closes #1067

[drips-wave]

@oyeyemipamilerin6-collab Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits