Skip to content

feat: channel points hint system with EventSub integration#79

Open
FlorentPoinsaut wants to merge 3 commits into
mainfrom
feat/channel-points-hints
Open

feat: channel points hint system with EventSub integration#79
FlorentPoinsaut wants to merge 3 commits into
mainfrom
feat/channel-points-hints

Conversation

@FlorentPoinsaut
Copy link
Copy Markdown
Member

Summary

This PR implements the channel points hint system described in #78.

Changes

Core Features

  • SemanticEngine.get_hints(): retrieves top-N Word2Vec neighbors, filtered and cleaned
  • GameState hint system: adds hint pool, HintResult enum, next_hint() method with skip logic for already-guessed words
  • Config variables: HINT_REWARD_NAME, HINTS_PER_GAME (default 5), HINT_POOL_SIZE (default 50)
  • OAuth scopes update: adds channel:read:redemptions and channel:manage:redemptions to default scopes

EventSub Integration

  • EventSub WebSocket subscription for channel points redemptions
  • Auto-cancel (refund) redemptions when no game running, limit reached, or pool exhausted
  • Channel ID resolution via async Helix client at bot startup
  • Graceful degradation when HINT_REWARD_NAME is empty (feature disabled)

Bot Commands

  • Renamed: hinttop (shows top 10 guesses leaderboard)
  • New: hint (broadcaster only) — manually triggers next hint from pool without channel points

Overlay

  • Persistent hints panel showing all revealed hint words

Tests & Documentation

  • 314 tests passing (86% coverage)
  • Updated README with new command table
  • Updated viewer agent description
  • Comprehensive test coverage for get_hints(), next_hint(), EventSub handler, and renamed commands

Acceptance Criteria (from #78)

  • Viewer redeems configured reward → bot posts hint in chat with index
  • Hints revealed farthest-to-closest (progressive tension)
  • Already-guessed words skipped silently
  • Redemption auto-cancelled when no game running or limit reached
  • All revealed hints shown in overlay (persistent list)
  • Reward name comparison is case-insensitive and whitespace-trimmed
  • EventSub subscription skipped with warning if HINT_REWARD_NAME empty
  • Startup validates required OAuth scopes (forces re-login if missing)

Breaking Changes

⚠️ Re-authentication required: Users must run poetry run python main.py auth-login to grant new OAuth scopes (channel:read:redemptions, channel:manage:redemptions).

Closes #78

- Add SemanticEngine.get_hints() to retrieve Word2Vec neighbors
- Extend GameState with hint pool, HintResult enum, and next_hint() method
- Add HINT_REWARD_NAME, HINTS_PER_GAME, HINT_POOL_SIZE config variables
- Update default OAuth scopes to include channel:read:redemptions and channel:manage:redemptions
- Implement EventSub WebSocket subscription for channel points redemptions
- Auto-cancel (refund) redemptions when no game running or limit reached
- Rename 'hint' command to 'top' (shows leaderboard)
- Add new 'hint' broadcaster command to manually trigger next hint
- Update overlay to display all revealed hints in persistent panel
- Add comprehensive tests for hints, renamed commands, and EventSub handling
- Update help text, README, agent descriptions, and functional tests

Resolves #78
- Add HINT_REWARD_NAME, HINTS_PER_GAME, HINT_POOL_SIZE to environment variables table
- Add comprehensive setup section with step-by-step instructions for:
  - Creating Twitch channel points reward
  - Configuring environment variables
  - Granting required OAuth scopes
  - Starting the bot with EventSub subscription
- Explain auto-refund behavior and hint progression (farthest to closest)
The warning originates from TwitchIO's internal architecture:
- twitchio/ext/eventsub/__init__.py imports EventSubClient (HTTP server)
  even when we only use EventSubWSClient (WebSocket client)
- EventSubClient's inheritance from web.Application is deprecated in aiohttp
- We cannot avoid this warning without modifying TwitchIO itself

Solution: Filter the warning in pytest config with detailed comment explaining
the issue. This is the recommended approach for third-party library warnings
that are outside our control.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: channel points redemption triggers semantic hint reveal

1 participant