Cricket-First AI Features: Roanuz Integration Roadmap

Executive Summary

This document outlines the cricket-first AI features for Hannibal, leveraging the Roanuz Cricket API integration. Hannibal's philosophy is "Cricket First" - every AI feature is designed with cricket's unique characteristics in mind (Tests, ODIs, T20s, sessions, milestones, weather interruptions, etc.).

Goal: Build the world's first AI-native cricket betting platform.

Current Infrastructure
Roanuz API Capabilities
Feature Priorities
Phase 1: Core Cricket Intelligence
Phase 2: Advanced Cricket AI
Phase 3: Agentic Cricket AI
Phase 4: Premium Features
Technical Architecture
Implementation Timeline

1. Current Infrastructure

1.1 Existing AI Services

Component	Status	Location	Description
AI Chat Assistant	✅ Live	`services/ai-chat-assistant/`	Python service, multi-provider LLM (Grok-4 Fast primary)
Fixture Analysis Service	✅ Live	`backend/src/services/fixtureAnalysisService.ts`	AI analysis for fixtures
Watchlist Service	✅ Live	`backend/src/services/watchlistService.ts`	AI-enabled alerts
B-Book Sharp Detection	✅ Live	`backend/src/services/bbook/`	Automated risk management
AI Chat Panel	✅ Live	`frontend/src/components/ai-chat/`	Floating chat widget
AI Fixture Button	✅ Live	`frontend/src/components/ai/`	Per-fixture AI panels

1.2 Roanuz Integration (Completed)

Component	Status	Location	Description
RoanuzDataAdapter	✅ Done	`backend/src/exchanges/adapters/roanuz/`	Main data adapter
RoanuzWebSocketManager	✅ Done	`backend/src/exchanges/adapters/roanuz/`	WebSocket connection manager
Cricket Data Models	✅ Done	`backend/src/exchanges/core/models/cricketData.ts`	Canonical cricket types
Cricket Events	✅ Done	`backend/src/exchanges/core/models/cricketEvents.ts`	WebSocket event types
IDataProvider Interface	✅ Done	`backend/src/exchanges/core/interfaces/IDataProvider.ts`	Port interface
Team Logos	✅ Done	`backend/public/assets/cricket/team-logos/`	268 team logos
Team Metadata	✅ Done	`backend/public/assets/cricket/cricket-teams.json`	Team data JSON

1.3 LLM Configuration

Provider	Model	Throughput	Use Case
Grok (Primary)	grok-4-fast	~90 tokens/sec	Ball-by-ball, analysis
Gemini (Fallback)	gemini-2.5-flash	~100 tokens/sec	Backup
Groq (Fallback)	llama-3.3-70b	~300 tokens/sec	High-speed fallback
Ollama (Local)	llama3:8b	Variable	Offline fallback

2. Roanuz API Capabilities

2.1 Available APIs

Category	API	Real-time	Description
Core	Auth API	-	Token-based authentication
Core	Match API	REST	Match details, status
Core	Ball-by-Ball API	WebSocket	Every delivery
Core	Overs Summary API	REST	Over-by-over stats
Core	Schedule API	REST	Upcoming matches
Core	Commentary API	REST	Text commentary
Stats	Player Stats API	REST	Career statistics
Stats	Player Performance API	REST	Recent form
Stats	Player vs Team API	REST	Head-to-head
Stats	Team Stats API	REST	Team performance
Stats	Team Timeline API	REST	Historical results
Season	Season API	REST	Tournament info
Season	Season Matches API	REST	Tournament fixtures
Season	Season Points API	REST	Points table
Season	Season Stats API	REST	Tournament stats
Premium	Fantasy Credit API	REST	Player valuations
Premium	Fantasy Points API	REST	Fantasy scoring
Premium	ChatBot API	REST	Cricket Q&A

2.2 Data Delivery Methods

Method	Latency	Use Case
WebSocket	Real-time	Ball-by-ball, live scores
REST API	~100-500ms	Stats, history, schedules
Webhook	Push	Server-side notifications

3. Feature Priorities

Priority Matrix

Priority	Label	Criteria
🔴 P0	Critical	Core differentiator, immediate value
🟡 P1	High	Strong user value, builds on P0
🟢 P2	Medium	Enhanced experience, competitive edge
🔵 P3	Low	Nice-to-have, future consideration

Feature Priority Summary

#	Feature	Priority	Effort	Impact	Phase
1	Live Ball-by-Ball AI Commentary	🔴 P0	2 weeks	Very High	1
2	Enhanced Cricket Fixture Analysis	🔴 P0	1 week	High	1
3	Cricket Milestone Alerts	🟡 P1	1 week	High	1
4	Toss & Pitch Analysis	🟡 P1	1 week	High	1
5	Session Betting Intelligence	🟡 P1	2 weeks	High	1
6	Player Performance Predictor	🟢 P2	3 weeks	Very High	2
7	Collapse/Momentum Detector	🟢 P2	2 weeks	Medium	2
8	Tournament Qualification Calculator	🟢 P2	2 weeks	Medium	2
9	Weather-Pitch-Toss Triangle	🟢 P2	2 weeks	High	2
10	Cricket Scout Agent	🔵 P3	3 weeks	High	3
11	DRS & Umpire Intelligence	🔵 P3	2 weeks	Medium	3
12	Fantasy-Betting Integration	🔵 P3	2 weeks	Medium	4
13	Roanuz ChatBot Integration	🔵 P3	1 week	Low	4

4. Phase 1: Core Cricket Intelligence (P0-P1)

4.1 Live Ball-by-Ball AI Commentary 🔴 P0

Description: Real-time AI-generated insights for every ball bowled, providing betting intelligence that no other platform offers.

Architecture: Hybrid Template + Streaming LLM

Ball Event (Roanuz WebSocket)
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│ LAYER 1: INSTANT (0ms) - Template                       │
│ "15.3 | Ashwin → Marsh | SIX! | AUS 142/3"             │
│ Odds: AUS 2.10→2.05 | IND 1.75→1.78                    │
└─────────────────────────────────────────────────────────┘
         │
         ▼ (parallel, streaming)
┌─────────────────────────────────────────────────────────┐
│ LAYER 2: GROK-4 FAST (~300ms, streaming)                │
│ "💡 Marsh's 4th six off Ashwin - Over 350 now 70%      │
│    likely. Australia building momentum for final push." │
└─────────────────────────────────────────────────────────┘
         │
         ▼ (on-demand only)
┌─────────────────────────────────────────────────────────┐
│ LAYER 3: DEEP ANALYSIS (1-2s, user-triggered)           │
│ Detailed analysis with historical context, player       │
│ matchups, and comprehensive betting recommendations.    │
└─────────────────────────────────────────────────────────┘

User Stories:

As a punter, I want instant AI insights on every ball so I can make informed in-play betting decisions
As a punter, I want to see how each ball affects match odds so I can identify value opportunities
As a punter, I want deep analysis on-demand without slowing down the live experience

Technical Requirements:

Requirement	Specification
Latency (Template)	<50ms
Latency (AI Insight)	<500ms (streaming first token <200ms)
LLM Model	Grok-4 Fast (90 tokens/sec)
Max Tokens	40-50 per ball
Temperature	0.3 (focused, consistent)
WebSocket	Roanuz ball-by-ball subscription

Roanuz APIs Used:

Ball-by-Ball API (WebSocket) - Primary data source
Commentary API - Supplement with official commentary
Player Performance API - Player context for insights

Files to Create/Modify:

backend/src/services/ballByBallService.ts (NEW)
backend/src/routes/ballByBall.ts (NEW)
frontend/src/components/cricket/BallByBallPanel.tsx (NEW)
frontend/src/components/cricket/BallInsightCard.tsx (NEW)

Success Metrics:

AI insight delivery <500ms for 95% of balls
User engagement: >30% of users view AI insights during live matches
Bet conversion: 15% increase in in-play bets when AI insights shown

4.2 Enhanced Cricket Fixture Analysis 🔴 P0

Description: Upgrade existing fixture analysis with Roanuz's rich cricket data including head-to-head records, venue stats, player form, and pitch conditions.

Current State: Generic fixture analysis using basic odds data Enhanced State: Cricket-specific analysis with deep statistical context

User Stories:

As a punter, I want to see how teams perform at specific venues so I can make informed pre-match bets
As a punter, I want player head-to-head stats so I can bet on player markets
As a punter, I want historical match data between teams so I can identify patterns

Data Enhancement:

Current Analysis	Enhanced Analysis (with Roanuz)
Team names	+ Team recent form (last 10 matches)
Current odds	+ Historical odds patterns
Basic prediction	+ Venue-specific prediction
-	+ Head-to-head record
-	+ Key player form analysis
-	+ Toss impact at venue
-	+ Weather considerations
-	+ Pitch report analysis

Roanuz APIs Used:

Team Timeline API - Historical results
Team Stats API - Performance metrics
Player Performance API - Recent form
Match API - Venue and pitch info
Schedule API - Context matches

Files to Modify:

backend/src/services/fixtureAnalysisService.ts - Add Roanuz data fetching
backend/src/prompts/fixtureAnalysis.ts - Enhanced prompts with cricket context

Success Metrics:

Analysis quality score: >4.2/5 user rating
Pre-match bet conversion: 20% increase
Analysis depth: 3x more data points per analysis

4.3 Cricket Milestone Alerts 🟡 P1

Description: Automated alerts for cricket-specific milestones that create betting opportunities.

Milestone Types:

Category	Milestones	Betting Implication
Batting	50, 100, 150, 200	Individual markets
Batting	Strike rate >150, >200	Runs in over markets
Bowling	3-for, 5-for, hat-trick	Wicket markets
Bowling	Maiden over, dot ball streak	Economy markets
Partnership	50, 100, 150+ stand	Team total markets
Team	50, 100, 150 in powerplay	Powerplay markets
Team	Required rate >10, >12, >15	Match winner shift
Match	DLS par score reached	Match outcome

User Stories:

As a punter, I want to be alerted when a batsman approaches 100 so I can bet on century markets
As a punter, I want partnership milestone alerts so I can identify team momentum shifts
As a punter, I want required run rate alerts so I can bet on chase outcomes

Roanuz APIs Used:

Ball-by-Ball API (WebSocket) - Real-time tracking
Match API - Score and status
Player Performance API - Player milestone tracking

Files to Create/Modify:

backend/src/services/milestoneAlertService.ts (NEW)
backend/src/services/watchlistService.ts - Integrate milestone alerts
frontend/src/components/alerts/MilestoneAlert.tsx (NEW)

Success Metrics:

Alert latency: <2 seconds from milestone
Alert engagement: >40% click-through rate
Bet conversion from alerts: >25%

4.4 Toss & Pitch Analysis Agent 🟡 P1

Description: AI agent that analyzes toss result, pitch conditions, and historical venue data to provide immediate betting recommendations.

Analysis Output:

┌─────────────────────────────────────────────────────────┐
│ 🪙 TOSS ANALYSIS                                        │
│ India won toss - chose to BAT                          │
├─────────────────────────────────────────────────────────┤
│ 📊 VENUE HISTORY (Last 20 matches at Wankhede)         │
│ • Bat first wins: 12 (60%)                             │
│ • Chase wins: 8 (40%)                                  │
│ • Avg 1st innings: 178                                 │
│ • Avg 2nd innings: 165                                 │
├─────────────────────────────────────────────────────────┤
│ 🏏 PITCH REPORT                                        │
│ • Surface: Hard, even bounce                           │
│ • Expected: Good for batting, spin later               │
│ • Dew factor: Heavy (favors chasing)                   │
├─────────────────────────────────────────────────────────┤
│ 🤖 AI RECOMMENDATION                                   │
│ "Despite venue favoring bat-first, heavy dew makes     │
│  chasing easier. Australia at 2.15 offers value.       │
│  Consider: Total OVER 350.5 @ 1.90"                    │
└─────────────────────────────────────────────────────────┘

User Stories:

As a punter, I want instant analysis when toss happens so I can bet before odds move
As a punter, I want venue-specific insights so I understand toss importance
As a punter, I want pitch condition analysis so I can bet on totals

Roanuz APIs Used:

Match API - Toss result, venue info
Team Timeline API - Venue-specific history
Commentary API - Pitch report extraction

Files to Create:

backend/src/services/tossAnalysisService.ts (NEW)
frontend/src/components/cricket/TossAnalysisPanel.tsx (NEW)

Success Metrics:

Analysis available within 30 seconds of toss
Toss-based bet conversion: 30%+
Prediction accuracy (toss advantage): >55%

4.5 Session Betting Intelligence 🟡 P1

Description: Cricket-specific session analysis for Test matches and ODI/T20 innings phases.

Session Types:

Format	Sessions	Key Markets
Test	Morning, Lunch, Tea, Final	Runs in session, wickets in session
ODI	Powerplay, Middle, Death (per innings)	Runs in phase, wickets in phase
T20	Powerplay, Middle, Death (per innings)	Runs in phase, boundaries in phase

AI Analysis Per Session:

┌─────────────────────────────────────────────────────────┐
│ 🏏 POWERPLAY ANALYSIS (Overs 1-6)                      │
├─────────────────────────────────────────────────────────┤
│ Current: 42/1 after 4.2 overs                          │
│ Projected: 58-65 runs at powerplay end                 │
│ Historical avg at venue: 52                            │
├─────────────────────────────────────────────────────────┤
│ 🤖 AI INSIGHT                                          │
│ "Above average start. New ball swinging less than      │
│  expected. Rohit aggressive against pace. Recommend:   │
│  OVER 55.5 powerplay runs @ 1.85"                     │
└─────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Ball-by-Ball API - Over-by-over tracking
Overs Summary API - Phase statistics
Team Stats API - Historical phase performance

Files to Create:

backend/src/services/sessionBettingService.ts (NEW)
frontend/src/components/cricket/SessionPanel.tsx (NEW)

Success Metrics:

Session prediction accuracy: >55%
Session market bet conversion: 25%+
User engagement during sessions: 40%+

5. Phase 2: Advanced Cricket AI (P2)

5.1 Player Performance Predictor 🟢 P2

Description: AI model that predicts individual player performance based on historical data, recent form, opponent analysis, and venue factors.

Prediction Types:

Player Type	Predictions	Markets
Batsman	Runs, strike rate, boundaries	Top batsman, player runs
Bowler	Wickets, economy, dots	Top bowler, player wickets
All-rounder	Combined performance	Man of match
Keeper	Catches, stumpings	Dismissals market

AI Analysis Output:

┌─────────────────────────────────────────────────────────┐
│ 🏏 PLAYER PREDICTION: Virat Kohli                      │
├─────────────────────────────────────────────────────────┤
│ Match: IND vs AUS, Wankhede, T20                       │
│ Market: Top Indian Batsman @ 3.50                      │
├─────────────────────────────────────────────────────────┤
│ 📊 FACTORS                                             │
│ • Recent form: 45, 89*, 23, 67, 12 (L5)               │
│ • vs AUS (career): 892 runs @ 47, SR 138              │
│ • At Wankhede (T20): 234 runs @ 58, SR 145            │
│ • vs Zampa (L3 yrs): 67 runs, 3 dismissals            │
├─────────────────────────────────────────────────────────┤
│ 🤖 AI PREDICTION                                       │
│ Predicted runs: 38-55 (confidence: 72%)                │
│ Top batsman probability: 28%                           │
│ Recommendation: VALUE at 3.50 (fair odds: 3.20)        │
└─────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Player Stats API - Career statistics
Player Performance API - Recent form
Player vs Team API - Head-to-head matchups
Team Stats API - Team context

Files to Create:

backend/src/services/playerPredictorService.ts (NEW)
backend/src/models/playerPrediction.ts (NEW)
frontend/src/components/cricket/PlayerPredictionCard.tsx (NEW)

Success Metrics:

Top batsman/bowler prediction: >30% accuracy (vs 20% baseline)
Player runs prediction: MAE <12 runs
User adoption: 50%+ view predictions before betting

5.2 Collapse/Momentum Detector 🟢 P2

Description: Real-time detection of batting collapses and momentum shifts that create betting opportunities.

Detection Patterns:

Pattern	Trigger	Betting Opportunity
Early Collapse	3+ wickets in first 10 overs	Back bowling team, under totals
Middle Collapse	4+ wickets for <40 runs	Back opposition, under totals
Death Collapse	3+ wickets in final 5 overs	Adjusted team total
Momentum Swing	30+ runs in 2 overs	Over totals, innings runs
Powerplay Surge	>60 in powerplay	Over totals

AI Alert Example:

🚨 COLLAPSE DETECTED - England Batting
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3 wickets in last 18 balls
Score: 89/5 → 98/8 (9 runs, 3 wkts)

📊 Historical Pattern Match:
Similar collapses at Lord's: 8 instances
Average final score after: 142
Current projection: 125-145

🤖 AI RECOMMENDATION:
"Classic English middle-order collapse on seaming
pitch. Archer and Wood still bowling well.
BACK: Under 155.5 @ 1.75 (strong value)"

Roanuz APIs Used:

Ball-by-Ball API (WebSocket) - Real-time tracking
Match API - Match state
Overs Summary API - Phase analysis

Files to Create:

backend/src/services/momentumDetectorService.ts (NEW)
frontend/src/components/cricket/MomentumAlert.tsx (NEW)

Success Metrics:

Collapse detection latency: <30 seconds
False positive rate: <15%
Bet conversion from alerts: 35%+

5.3 Tournament Qualification Calculator 🟢 P2

Description: Real-time calculation of tournament qualification scenarios and how current match affects standings.

Features:

Feature	Description
Live Scenarios	How current match result affects qualification
NRR Calculator	Net run rate impact of different margins
Must-Win Tracker	Teams that must win for qualification
Elimination Alert	When team is mathematically eliminated

AI Analysis Output:

┌─────────────────────────────────────────────────────────┐
│ 📊 IPL QUALIFICATION SCENARIOS                         │
│ Current Match: RCB vs CSK                              │
├─────────────────────────────────────────────────────────┤
│ IF RCB WIN:                                            │
│ • RCB: 14 pts, NRR +0.32 (qualifies with 1 match left)│
│ • CSK: 12 pts (needs to win by 30+ runs AND PBKS loss)│
├─────────────────────────────────────────────────────────┤
│ IF CSK WIN:                                            │
│ • CSK: 14 pts, NRR +0.18 (guaranteed top 2)           │
│ • RCB: 12 pts (still in contention)                   │
├─────────────────────────────────────────────────────────┤
│ 🤖 AI INSIGHT                                          │
│ "RCB MUST WIN to guarantee qualification. CSK playing │
│  for seeding. Expect aggressive RCB approach.          │
│  Consider: RCB to score most 6s @ 2.10"               │
└─────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Season Points API - Current standings
Season Matches API - Remaining fixtures
Team Stats API - NRR calculations

Files to Create:

backend/src/services/qualificationService.ts (NEW)
frontend/src/components/cricket/QualificationPanel.tsx (NEW)

Success Metrics:

Scenario accuracy: 100%
NRR calculation precision: ±0.01
Tournament bet conversion: 25%+

5.4 Weather-Pitch-Toss Triangle Analysis 🟢 P2

Description: Comprehensive pre-match analysis combining weather forecasts, pitch conditions, and toss impact.

Analysis Components:

┌────────────────────────────────────────────────────────┐
│           WEATHER-PITCH-TOSS TRIANGLE                  │
│                                                        │
│                    ☀️ WEATHER                          │
│                    Clear, 28°C                         │
│                    Humidity: 65%                       │
│                    Dew: Expected                       │
│                   /            \                       │
│                  /              \                      │
│                 /                \                     │
│    🏟️ PITCH ─────────────────────── 🪙 TOSS          │
│    Dry, cracks                    Win toss =          │
│    Day 1 score: 280-320           Bowl first          │
│    Spin from Day 3                85% chase           │
│                                                        │
├────────────────────────────────────────────────────────┤
│ 🤖 COMBINED AI ANALYSIS                                │
│                                                        │
│ "Perfect storm for chasing team:                       │
│  • Dew will neutralize spin after 7pm                 │
│  • Pitch offering turn but dew-affected ball skids    │
│  • 8/10 recent night games here won chasing           │
│                                                        │
│  RECOMMENDATION: Wait for toss. If bat second         │
│  available at 1.95+, strong value."                   │
└────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Match API - Venue, pitch info
Commentary API - Pitch report extraction
Team Timeline API - Venue history

External Integration:

Weather API (OpenWeatherMap) - Forecast data

Files to Create:

backend/src/services/triangleAnalysisService.ts (NEW)
frontend/src/components/cricket/TriangleAnalysis.tsx (NEW)

Success Metrics:

Pre-match analysis engagement: 60%+
Toss-based recommendation accuracy: >55%
Weather prediction integration: 95% uptime

6. Phase 3: Agentic Cricket AI (P3)

6.1 Cricket Scout Agent 🔵 P3

Description: Autonomous AI agent that monitors all live cricket matches and proactively alerts users to betting opportunities based on their preferences.

Agent Capabilities:

Capability	Description
Multi-Match Monitoring	Watches all live matches simultaneously
Pattern Recognition	Detects betting patterns across matches
Personalized Alerts	Learns user betting preferences
Value Detection	Identifies odds discrepancies
Cross-Match Arbitrage	Spots correlated opportunities

User Flow:

┌─────────────────────────────────────────────────────────┐
│ 🕵️ CRICKET SCOUT AGENT                                 │
│ Monitoring: 8 live matches                             │
├─────────────────────────────────────────────────────────┤
│ Your Preferences:                                      │
│ ✅ T20 matches                                         │
│ ✅ Top batsman markets                                 │
│ ✅ Value bets (>10% edge)                              │
│ ✅ Indian teams                                        │
├─────────────────────────────────────────────────────────┤
│ 🔔 LIVE ALERTS                                         │
│                                                        │
│ 🏏 IND vs AUS (T20, Live)                             │
│ "Kohli starts slowly (12 off 15). Odds drifted to     │
│  4.50 for top batsman. Historical: recovers 70% of    │
│  slow starts. VALUE: Back @ 4.50 (fair: 3.80)"        │
│                                                        │
│ 🏏 BBL: Stars vs Sixers (Live)                        │
│ "Glenn Maxwell batting at 5 due to injury. Available  │
│  for top batsman @ 8.00 (usually 4.50). ALERT!"       │
└─────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Schedule API - All live matches
Ball-by-Ball API (WebSocket) - Multi-match streaming
Player Performance API - Player context
Match API - Match states

Files to Create:

backend/src/agents/cricketScoutAgent.ts (NEW)
backend/src/agents/agentOrchestrator.ts (NEW)
frontend/src/components/agents/ScoutAgentPanel.tsx (NEW)

Success Metrics:

Value bet detection accuracy: >60%
User engagement with alerts: 50%+
ROI on agent recommendations: >5%

6.2 DRS & Umpire Intelligence 🔵 P3

Description: Analysis of DRS patterns and umpiring decisions to identify potential referral situations and their betting implications.

Intelligence Types:

Type	Analysis	Betting Use
DRS Tracking	Team reviews remaining	Next wicket method
Umpire Patterns	Historical decision data	LBW likelihood
Ball Tracking	Predictive impact zone	Appeal outcomes
Team Tendencies	When teams review	DRS market timing

AI Alert Example:

🔍 DRS SITUATION ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Team: India | Reviews: 2 remaining
Umpire: Kumar Dharmasena

📊 UMPIRE STATS (This Series):
• LBW given: 8 | Overturned: 3 (37.5%)
• Caught behind given: 5 | Overturned: 2 (40%)

📊 INDIA DRS PATTERN:
• Reviews taken: 6 | Successful: 4 (67%)
• Average review at: Ball impact middle stump line

🤖 AI INSIGHT:
"Dharmasena trigger-happy on LBWs this series.
India aggressive with reviews. If tight LBW
decision comes, expect immediate review. Next
wicket caught @ 1.70 may have value."

Roanuz APIs Used:

Ball-by-Ball API - Dismissal types, DRS events
Commentary API - Decision details
Match API - Reviews remaining

Files to Create:

backend/src/services/drsAnalysisService.ts (NEW)
frontend/src/components/cricket/DRSPanel.tsx (NEW)

Success Metrics:

DRS outcome prediction: >55%
Umpire pattern accuracy: Data-validated
User interest in DRS markets: 30%+ engagement

7. Phase 4: Premium Features (P3)

7.1 Fantasy-Betting Integration 🔵 P3

Description: Bridge fantasy cricket valuations with betting markets to identify mispriced player markets.

Integration Points:

Fantasy Data	Betting Application
Player credits	Market value baseline
Fantasy points projection	Player performance bets
Ownership percentage	Contrarian indicators
Credit changes	Form-based odds movement

Analysis Output:

┌─────────────────────────────────────────────────────────┐
│ 🎯 FANTASY-BETTING ARBITRAGE                           │
├─────────────────────────────────────────────────────────┤
│ Player: Suryakumar Yadav                               │
│ Fantasy Credits: 10.5 (Premium)                        │
│ Fantasy Ownership: 78% (High)                          │
│ Projected Fantasy Points: 45-55                        │
├─────────────────────────────────────────────────────────┤
│ Betting Market:                                        │
│ Top Batsman: @ 4.50                                    │
│ Over 32.5 Runs: @ 1.85                                 │
├─────────────────────────────────────────────────────────┤
│ 🤖 AI ANALYSIS                                         │
│ "SKY priced as #1 fantasy pick but 4th favorite in    │
│  top batsman market. Market inefficiency detected.     │
│  Fantasy crowd often right on form - VALUE at 4.50"   │
└─────────────────────────────────────────────────────────┘

Roanuz APIs Used:

Fantasy Credit API - Player valuations
Fantasy Points API - Projected points
Player Performance API - Form context

Files to Create:

backend/src/services/fantasyBettingService.ts (NEW)
frontend/src/components/cricket/FantasyInsights.tsx (NEW)

Success Metrics:

Fantasy-betting correlation accuracy: >60%
New user acquisition from fantasy players: 20%+
Cross-product engagement: 40%+ users view both

7.2 Roanuz ChatBot Integration 🔵 P3

Description: Integrate Roanuz's Cricket ChatBot API to provide instant cricket trivia and statistics within the AI chat.

Use Cases:

Query Type	Example	Response Source
Statistics	"Kohli's average vs Australia"	Roanuz ChatBot
Records	"Highest T20 score at Wankhede"	Roanuz ChatBot
History	"When did India last beat AUS in AUS"	Roanuz ChatBot
Betting	"Should I bet on Kohli today"	Hannibal AI (enhanced)

Integration Architecture:

User Query
    │
    ▼
┌───────────────────┐
│ Query Classifier  │
│ (Hannibal AI)     │
└───────────────────┘
    │
    ├─── Stats/Records ──▶ Roanuz ChatBot API
    │                           │
    │                           ▼
    │                    ┌─────────────┐
    │                    │ Cricket Data │
    │                    └─────────────┘
    │                           │
    └─── Betting Query ──┐      │
                        │      │
                        ▼      ▼
               ┌─────────────────────┐
               │ Hannibal AI Service │
               │ (Enhanced Response) │
               └─────────────────────┘
                        │
                        ▼
                  Final Response

Roanuz APIs Used:

ChatBot API - Cricket Q&A
Player Stats API - Supplement data
Team Stats API - Supplement data

Files to Modify:

services/ai-chat-assistant/app/main.py - Add Roanuz ChatBot tool
services/ai-chat-assistant/app/tools/roanuz_chatbot.py (NEW)

Success Metrics:

Query classification accuracy: >90%
Response latency: <1s for stats queries
User satisfaction: >4/5 rating

8. Technical Architecture

8.1 System Overview

┌──────────────────────────────────────────────────────────────────┐
│                     HANNIBAL CRICKET AI PLATFORM                  │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐            │
│  │  Frontend  │◄──►│  Backend   │◄──►│  AI Chat   │            │
│  │  (Next.js) │    │  (Node.js) │    │  (Python)  │            │
│  └────────────┘    └─────┬──────┘    └──────┬─────┘            │
│                          │                   │                   │
│            ┌─────────────┼───────────────────┼───────┐          │
│            │             │                   │       │          │
│            ▼             ▼                   ▼       ▼          │
│  ┌──────────────┐ ┌──────────────┐ ┌───────────┐ ┌─────────┐  │
│  │    Redis     │ │  PostgreSQL  │ │ Grok-4    │ │ Roanuz  │  │
│  │   (Cache)    │ │    (Data)    │ │  Fast     │ │   API   │  │
│  └──────────────┘ └──────────────┘ └───────────┘ └─────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

8.2 Data Flow Architecture

Roanuz WebSocket ─────────────────────────────────────────────────►
     │
     ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ WebSocket   │───►│   Event     │───►│   Redis     │
│  Manager    │    │ Normalizer  │    │   Cache     │
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │
     ┌───────────────────────────────────────┼───────────────┐
     │                                       │               │
     ▼                                       ▼               ▼
┌─────────────┐                      ┌─────────────┐  ┌─────────┐
│  Ball-by-   │                      │  Milestone  │  │  Scout  │
│  Ball AI    │                      │   Alerts    │  │  Agent  │
└──────┬──────┘                      └──────┬──────┘  └────┬────┘
       │                                    │              │
       └────────────────┬───────────────────┴──────────────┘
                        ▼
               ┌────────────────┐
               │   WebSocket    │
               │   to Client    │
               └────────────────┘

8.3 AI Service Integration

┌──────────────────────────────────────────────────────────────────┐
│                     AI SERVICE ARCHITECTURE                       │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Request ───► Query Router ───┬──► Cricket Stats ──► Roanuz API │
│                               │                                  │
│                               ├──► Betting Analysis ─► Grok-4   │
│                               │                                  │
│                               ├──► Ball Insight ────► Grok-4    │
│                               │    (Fast, Streaming)             │
│                               │                                  │
│                               └──► Deep Analysis ───► Grok-4    │
│                                    (Full context)                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

8.4 Caching Strategy

Data Type	Cache TTL	Update Trigger
Match State (Live)	30s	WebSocket event
Match State (Complete)	1 hour	Match end
Ball-by-Ball	10s	Each ball event
Player Stats	1 hour	On-demand refresh
Team Stats	1 hour	On-demand refresh
AI Analysis	5 min	Cache miss
Fixture Analysis	30 min	Manual refresh

8.5 WebSocket Subscription Model

// Single connection per match, multiple subscriptions
interface MatchSubscription {
  matchId: string;
  subscriptions: {
    ballByBall: boolean;    // Every delivery
    scorecard: boolean;     // Score updates
    commentary: boolean;    // Text commentary
    odds: boolean;          // Odds updates (from exchange)
  };
  handlers: {
    onBall: (event: BallEvent) => void;
    onMilestone: (event: MilestoneEvent) => void;
    onWicket: (event: WicketEvent) => void;
    onOddsChange: (event: OddsEvent) => void;
  };
}

9. Implementation Timeline

9.1 Phase 1: Core Cricket Intelligence (Weeks 1-8)

Week	Feature	Team	Deliverable
1-2	Enhanced Fixture Analysis	Backend	Roanuz data integration
2-3	Enhanced Fixture Analysis	Frontend	Updated analysis UI
3-5	Ball-by-Ball AI Commentary	Backend	Service + WebSocket
5-6	Ball-by-Ball AI Commentary	Frontend	Live panel UI
6-7	Cricket Milestone Alerts	Full Stack	Alert system
7-8	Toss & Pitch Analysis	Full Stack	Analysis agent
8+	Session Betting Intelligence	Full Stack	Session panels

9.2 Phase 2: Advanced Cricket AI (Weeks 9-16)

Week	Feature	Team	Deliverable
9-11	Player Performance Predictor	Backend	ML model + API
11-12	Player Performance Predictor	Frontend	Prediction cards
12-14	Collapse/Momentum Detector	Full Stack	Detection system
14-16	Tournament Qualification	Full Stack	Calculator
16+	Weather-Pitch-Toss Triangle	Full Stack	Analysis system

9.3 Phase 3 & 4: Advanced Features (Weeks 17-24)

Week	Feature	Team	Deliverable
17-19	Cricket Scout Agent	Backend	Agent framework
19-20	Cricket Scout Agent	Frontend	Agent UI
20-22	DRS & Umpire Intelligence	Full Stack	Analysis system
22-24	Fantasy-Betting Integration	Full Stack	Cross-product
24+	Roanuz ChatBot Integration	Backend	Chat enhancement

9.4 Resource Requirements

Phase	Backend Dev	Frontend Dev	AI/ML	Duration
Phase 1	1 FTE	1 FTE	0.5 FTE	8 weeks
Phase 2	1 FTE	1 FTE	1 FTE	8 weeks
Phase 3	1 FTE	0.5 FTE	1 FTE	4 weeks
Phase 4	0.5 FTE	0.5 FTE	0.5 FTE	4 weeks

10. Success Criteria

10.1 Key Performance Indicators

KPI	Target	Measurement
AI Feature Adoption	>60%	Users engaging with AI features
Ball-by-Ball Engagement	>30%	Live match viewers using AI
AI-Driven Bets	>25%	Bets placed with AI recommendation
Prediction Accuracy	>55%	Win rate of AI recommendations
User Satisfaction	>4.2/5	NPS for AI features
Latency (Ball Insight)	<500ms	P95 latency
System Uptime	>99.5%	AI service availability

10.2 Competitive Differentiation

Feature	Hannibal	Competitors
Ball-by-Ball AI	✅ Real-time	❌ None
Cricket-First Design	✅ Native	⚠️ Generic
Player Predictions	✅ ML-powered	⚠️ Basic
Autonomous Agents	✅ Scout Agent	❌ None
Fantasy Integration	✅ Native	❌ Separate

11. Appendix

11.1 Glossary

Term	Definition
B-Book	Platform takes opposite side of user bets
DRS	Decision Review System (cricket technology)
NRR	Net Run Rate (tournament ranking metric)
PAL	Provider Abstraction Layer
Session	Period of play in Test cricket
Powerplay	Fielding restrictions period

11.2 References

Document Version: 1.0 Last Updated: 2026-01-26 Author: Hannibal AI Team

Executive Summary​

Table of Contents​

1. Current Infrastructure​

1.1 Existing AI Services​

1.2 Roanuz Integration (Completed)​

1.3 LLM Configuration​

2. Roanuz API Capabilities​

2.1 Available APIs​

2.2 Data Delivery Methods​

3. Feature Priorities​

Priority Matrix​

Feature Priority Summary​

4. Phase 1: Core Cricket Intelligence (P0-P1)​

4.1 Live Ball-by-Ball AI Commentary 🔴 P0​

4.2 Enhanced Cricket Fixture Analysis 🔴 P0​

4.3 Cricket Milestone Alerts 🟡 P1​

4.4 Toss & Pitch Analysis Agent 🟡 P1​

4.5 Session Betting Intelligence 🟡 P1​

5. Phase 2: Advanced Cricket AI (P2)​

5.1 Player Performance Predictor 🟢 P2​

5.2 Collapse/Momentum Detector 🟢 P2​

5.3 Tournament Qualification Calculator 🟢 P2​

5.4 Weather-Pitch-Toss Triangle Analysis 🟢 P2​

6. Phase 3: Agentic Cricket AI (P3)​

6.1 Cricket Scout Agent 🔵 P3​

6.2 DRS & Umpire Intelligence 🔵 P3​

7. Phase 4: Premium Features (P3)​

7.1 Fantasy-Betting Integration 🔵 P3​

7.2 Roanuz ChatBot Integration 🔵 P3​

8. Technical Architecture​

8.1 System Overview​

8.2 Data Flow Architecture​

8.3 AI Service Integration​

8.4 Caching Strategy​

8.5 WebSocket Subscription Model​

9. Implementation Timeline​

9.1 Phase 1: Core Cricket Intelligence (Weeks 1-8)​

9.2 Phase 2: Advanced Cricket AI (Weeks 9-16)​

9.3 Phase 3 & 4: Advanced Features (Weeks 17-24)​

9.4 Resource Requirements​

10. Success Criteria​

10.1 Key Performance Indicators​

10.2 Competitive Differentiation​

11. Appendix​

11.1 Glossary​

11.2 References​

Executive Summary

Table of Contents

1. Current Infrastructure

1.1 Existing AI Services

1.2 Roanuz Integration (Completed)

1.3 LLM Configuration

2. Roanuz API Capabilities

2.1 Available APIs

2.2 Data Delivery Methods

3. Feature Priorities

Priority Matrix

Feature Priority Summary

4. Phase 1: Core Cricket Intelligence (P0-P1)

4.1 Live Ball-by-Ball AI Commentary 🔴 P0

4.2 Enhanced Cricket Fixture Analysis 🔴 P0

4.3 Cricket Milestone Alerts 🟡 P1

4.4 Toss & Pitch Analysis Agent 🟡 P1

4.5 Session Betting Intelligence 🟡 P1

5. Phase 2: Advanced Cricket AI (P2)

5.1 Player Performance Predictor 🟢 P2

5.2 Collapse/Momentum Detector 🟢 P2

5.3 Tournament Qualification Calculator 🟢 P2

5.4 Weather-Pitch-Toss Triangle Analysis 🟢 P2

6. Phase 3: Agentic Cricket AI (P3)

6.1 Cricket Scout Agent 🔵 P3

6.2 DRS & Umpire Intelligence 🔵 P3

7. Phase 4: Premium Features (P3)

7.1 Fantasy-Betting Integration 🔵 P3

7.2 Roanuz ChatBot Integration 🔵 P3

8. Technical Architecture

8.1 System Overview

8.2 Data Flow Architecture

8.3 AI Service Integration

8.4 Caching Strategy

8.5 WebSocket Subscription Model

9. Implementation Timeline

9.1 Phase 1: Core Cricket Intelligence (Weeks 1-8)

9.2 Phase 2: Advanced Cricket AI (Weeks 9-16)

9.3 Phase 3 & 4: Advanced Features (Weeks 17-24)

9.4 Resource Requirements

10. Success Criteria

10.1 Key Performance Indicators

10.2 Competitive Differentiation

11. Appendix

11.1 Glossary

11.2 References