- Three specialized XGBoost models (spread, moneyline, totals)
- Interactive predictions dashboard with confidence tiers
- Historical data page with advanced filtering (196k+ records)
- Multi-page Streamlit app with optimized performance
- Data leakage-free models with proven ROI
- Git LFS integration for large datasets
- Lazy loading architecture for fast startup
Focus: Core betting predictions and historical analysis
Included:
- ✅ Spread, moneyline, and totals predictions
- ✅ Top 10 betting recommendations per strategy
- ✅ Historical play-by-play data filtering
- ✅ Confidence tiers with visual indicators
- ✅ Performance-optimized for Streamlit Cloud
- ✅ Proper error handling and graceful fallbacks
Success Metrics:
- 10-20 beta users onboarded
- <10 second initial load time
- No timeout errors on Historical Data page
- User feedback collected
Focus: User experience enhancements based on beta 0.1 feedback
Problem: Users don't know what's happening during 5-10 second initial load
~~Implementation:
# In predictions.py
with st.spinner("🏈 Loading NFL data and predictions..."):
progress_bar = st.progress(0)
# Load historical data
progress_bar.progress(25, text="Loading historical games...")
historical_game_level_data = load_historical_data()
# Load predictions
progress_bar.progress(50, text="Loading model predictions...")
predictions_df = load_predictions()
# Load play-by-play data
progress_bar.progress(75, text="Loading play-by-play data...")
historical_data = load_data()
progress_bar.progress(100, text="Ready!")
time.sleep(0.5) # Brief pause to show completion
progress_bar.empty()Effort: 2-3 hours
Impact: Significantly improves perceived performance~~
Problem: Users want to analyze filtered data in Excel or save betting recommendations
Implementation:
# Add to each tab with dataframes
import io
def convert_df_to_csv(df):
return df.to_csv(index=False).encode('utf-8')
# In betting recommendations tabs
st.download_button(
label="📥 Download Recommendations as CSV",
data=convert_df_to_csv(filtered_df),
file_name=f'nfl_spread_bets_{datetime.now().strftime("%Y%m%d")}.csv',
mime='text/csv',
)
# In Historical Data page
st.download_button(
label="📥 Export Filtered Data",
data=convert_df_to_csv(filtered_data),
file_name=f'nfl_historical_data_{datetime.now().strftime("%Y%m%d")}.csv',
mime='text/csv',
)Effort: 3-4 hours
Impact: Enables power users to do custom analysis
Status: ✅ COMPLETED (Nov 27, 2025)
Notes:
- Added a PDF export generator in the sidebar that builds a compact, print-friendly PDF of upcoming games (today or later) and exposes a download button with embedded PDF icon. The PDF uses a compact layout and short headers to fit more columns.
- Exported PDFs are saved under
data_files/exports/for auditability. The app no longer attempts to spawn a local static server to open the PDF link — the download button is the canonical retrieval method. - The generator filters predictions to include only upcoming games and will write a short message to the PDF if no upcoming games are found.
- PDF generate button uses HTML with embedded PDF icon for consistency with download buttons.
- All download buttons use embedded icons (
csv_icon.png,pdf_icon.png) with proper fallback tofavicon.ico.
Problem: Users can't refresh predictions or clear cached data manually
~~Implementation:
# Add to sidebar
with st.sidebar:
st.write("### ⚙️ Settings")
if st.button("🔄 Refresh Data", help="Clear cache and reload all data"):
st.cache_data.clear()
st.rerun()Effort: 2 hours
Impact: Gives users control over data freshness~~
Problem: Historical Data page filters could be more intuitive
Implementation (Completed):
- Added Quick Presets at the top of the sidebar with one-click filter shortcuts:
- Red Zone: Automatically sets yardline filter to 0-20 yards from opponent endzone
- 3rd & Short: Sets down filter to 3rd down and yards-to-go to 0-3 yards
- Pass Attempts Only: Checks the pass-only filter for pass play analysis
- Reset Presets button to uncheck all preset checkboxes
- Session state management to persist filter states and avoid widget conflicts
- Automatic filter updates when presets are checked (no manual slider adjustments needed)
Effort: 4-5 hours
Impact: Makes complex filtering more accessible - users can now quickly filter for common scenarios with one click
If users say:
- "I don't know if it's working" → Loading Progress (MUST HAVE)
- "I want to track my bets in Excel" → Data Export (HIGH VALUE)
- "Data seems stale" → Cache Management (QUICK WIN)
- "Filters are overwhelming" → Enhanced Filtering (NICE TO HAVE)
Estimated Timeline: 10-15 hours total development
Focus: Analytics and engagement features
Problem: Users don't know if predictions are actually accurate
~~Implementation:
# New tab in main app
with tab_performance:
st.write("### 📊 Model Performance Tracking")
# Load betting log with results
betting_log = pd.read_csv('data_files/betting_recommendations_log.csv')
# Overall metrics
col1, col2, col3, col4 = st.columns(4)
with col1:
st.metric("Total Bets", len(betting_log))
with col2:
win_rate = (betting_log['result'] == 'WIN').mean() * 100
st.metric("Win Rate", f"{win_rate:.1f}%")
with col3:
roi = calculate_roi(betting_log)
st.metric("ROI", f"{roi:.1f}%")
with col4:
st.metric("Units Won", f"+{betting_log['profit'].sum():.1f}")
# Performance by confidence tier
st.write("#### Performance by Confidence Level")
confidence_performance = betting_log.groupby('confidence_tier').agg({
'result': lambda x: (x == 'WIN').mean() * 100,
'profit': 'sum'
})
st.dataframe(confidence_performance)
# Week-over-week tracking
st.write("#### Weekly Performance")
weekly_data = betting_log.groupby('week').agg({
'result': lambda x: (x == 'WIN').mean() * 100,
'profit': 'sum'
})
st.line_chart(weekly_data)Effort: 6-8 hours
Impact: Builds trust and transparency~~
Problem: Users miss high-value betting opportunities
Implementation (deployed):
- Automatic in-app toasts for Elite (≥65%) and Strong (60–65%) opportunities. Toasts are deduplicated via
st.session_stateso the same game doesn't re-notify within a session. - Toasts are actionable and link to per-alert pages, reachable with the query parameter
?alert=<guid>; per-alert pages render friendly bet labels, team logos, gameday/time, and a small recommendation table. - The app attempts to detect its public base URL from the browser and persists it to
data_files/app_config.json;scripts/generate_rss.pyuses that value (if present) to builddata_files/alerts_feed.xmlwith working per-alert links. - The running app exposes a sidebar
"🔁 Rebuild RSS"button to re-generate the feed in-place and report success/errors.
Files & locations:
- Per-alert rendering:
predictions.py(readsdata_files/betting_recommendations_log.csvand responds to?alert=query param) - Persisted config:
data_files/app_config.json(contains{"app_base_url": "https://..."}when detected) - RSS generator:
scripts/generate_rss.py→ outputdata_files/alerts_feed.xml
Effort: ~3-6 hours (implemented, testing + UI polish)
Impact: Improves engagement and enables external alerting via RSS
Problem: Users don't know how much to bet on each game
~~Implementation:
# New tab for bankroll management
with tab_bankroll:
st.write("### 💰 Bankroll Management")
# User inputs
col1, col2 = st.columns(2)
with col1:
bankroll = st.number_input("Current Bankroll ($)", value=1000, step=100)
with col2:
risk_tolerance = st.select_slider(
"Risk Tolerance",
options=["Conservative", "Moderate", "Aggressive"],
value="Moderate"
)
# Kelly Criterion calculator
risk_multipliers = {
"Conservative": 0.25, # 1/4 Kelly
"Moderate": 0.5, # 1/2 Kelly
"Aggressive": 1.0 # Full Kelly
}
# Calculate bet sizes for each recommendation
st.write("#### Recommended Bet Sizes")
for _, bet in elite_bets.iterrows():
# Kelly formula: f = (bp - q) / b
# f = fraction of bankroll to bet
# b = odds received (decimal - 1)
# p = probability of winning
# q = probability of losing (1-p)
decimal_odds = american_to_decimal(bet['odds'])
b = decimal_odds - 1
p = bet['win_probability']
q = 1 - p
kelly_fraction = (b * p - q) / b
kelly_fraction = max(0, kelly_fraction) # Never negative
recommended_bet = bankroll * kelly_fraction * risk_multipliers[risk_tolerance]
st.write(f"**{bet['matchup']}**: Bet ${recommended_bet:.2f} ({recommended_bet/bankroll*100:.1f}% of bankroll)")Effort: 5-6 hours
Impact: Helps users bet responsibly and optimally~~
Problem: Users want to compare multiple games side-by-side
Implementation:
# Add comparison mode
with tab_compare:
st.write("### 🔍 Game Comparison Tool")
# Let users select 2-4 games to compare
available_games = predictions_df['matchup'].unique()
selected_games = st.multiselect(
"Select games to compare (max 4)",
options=available_games,
max_selections=4
)
if len(selected_games) >= 2:
comparison_df = predictions_df[predictions_df['matchup'].isin(selected_games)]
# Show side-by-side metrics
st.write("#### Head-to-Head Comparison")
metrics_to_compare = [
'spread_prediction', 'spread_confidence',
'moneyline_prediction', 'moneyline_confidence',
'total_prediction', 'over_under_confidence',
'expected_roi'
]
comparison_table = comparison_df.pivot_table(
index='matchup',
values=metrics_to_compare,
aggfunc='first'
)
st.dataframe(comparison_table.style.highlight_max(axis=0, color='lightgreen'))
# Recommendation summary
st.write("#### Best Betting Opportunities")
best_spread = comparison_df.loc[comparison_df['spread_confidence'].idxmax()]
best_moneyline = comparison_df.loc[comparison_df['moneyline_confidence'].idxmax()]
col1, col2 = st.columns(2)
with col1:
st.metric("Best Spread Bet", best_spread['matchup'],
f"{best_spread['spread_confidence']:.1f}% confidence")
with col2:
st.metric("Best Moneyline Bet", best_moneyline['matchup'],
f"{best_moneyline['moneyline_confidence']:.1f}% confidence")Effort: 4-5 hours
Impact: Helps users make informed decisions when choosing between games
Problem: Users want to inspect a single game's full context (predictions, play-by-play, team stats, and alert history) in one place.
Goal: Add a dedicated per-game page modeled on the alert/per-alert pages already implemented. The page should be reachable via a query parameter (e.g. ?game=<game_id>) or a friendly route, and provide a complete, shareable view of an individual matchup.
Key Features:
- Summary Header: Team names, logos, gameday/time, venue, spread, moneyline, total line, and quick confidence badges (Elite/Strong/Good).
- Model Predictions: Spread, Moneyline, and Totals probabilities with calibrated probabilities and the model's recommended action(s).
- Recent Betting History: Any historical alerts or betting-log entries for the game (reads from
data_files/betting_recommendations_log.csv). - Play-by-Play Viewer: Paginated play-by-play table for the game with filters (quarter, down, play type) and expandable details per play.
- Team Season Context: Side-by-side team stats (season averages, recent 3-game form, head-to-head) using the same memory-efficient dtype patterns.
- Edge & Expected Value: Calculation panel showing implied odds vs model probability, expected value, and suggested bet sizing (Kelly-inspired) when applicable.
- Shareable Alert Link: One-click copy link to the game's per-game page; compatible with the RSS/per-alert generator so external feeds can link directly.
- Export & Persist: Download game-specific CSV (predictions + pbp) and optionally persist a server-side snapshot under
data_files/exports/for auditability.
Implementation Notes:
- Use the same lazy-loading pattern (
@st.cache_data) and progress spinner as other pages. - Render the page as an independent Streamlit view that reads
st.experimental_get_query_params()forgameoralertparams. - Reuse the alert-rendering components and copy the toast/deduplication session-state behavior for in-app notifications.
- Keep the play-by-play viewer paginated and memory-efficient (views,
float32,Int8), and show a warning if the dataset for a single game is unexpectedly large.
Effort: 6-10 hours (including UI polish and testing)
Impact: Improves transparency and allows analysts to deep-dive on individual matchups, increases shareability of alerts, and provides a single-source-of-truth page for support and audit.
Recommended Priority:
- Model Performance Dashboard (MUST HAVE) - Builds trust
- In-App Notifications (HIGH VALUE) - Increases engagement
- Bankroll Management (UNIQUE FEATURE) - Differentiates from competitors
Estimated Timeline: 15-20 hours total development
Focus: Full production release with polish
- Complete documentation and help system
- User authentication (if needed for notifications)
- Per-Game Detail Page (Deployed): Implemented a
?game=<game_id>per-game view with matchup summary, model recommendations, shareable links, and lightweight pagination for play-by-play when explicitly requested. The page avoids loading the entire play-by-play dataset by default to preserve Streamlit Cloud memory. - UX & Navigation Improvements: Schedule rows now link to per-game pages using path-relative
?game=and open in the same tab (target="_self"). Return navigation replaced markdown links with explicit same-tab anchors. - Underdog Render Logic: Per-game header marks the underdog in bold using spread-based logic with a moneyline fallback.
- Season-aware Schedule Matching: Schedule→prediction matching updated to prefer candidate prediction rows with matching
seasonto avoid historical collisions. - Download Placeholder Pattern: Sidebar reserves lightweight placeholders for download controls and populates them after data load to avoid premature widget creation and UI flicker.
- Critical Fix: Corrected an inverted spread-model output by fixing a mislabeled target and flipping the predicted spread probability immediately after model prediction (
prob_underdogCovered = 1 - prob_underdogCovered). Full analysis and remediation steps are inMODEL_FIX_PLAN.md. - Impact: Backtests and immediate verification show a large improvement in betting performance (approx. -90% → +60% ROI), calibration improved, and many +EV opportunities surfaced (62 of 63 remaining games flagged profitable in the initial post-fix run).
- New Features Deployed: 18 features added to the pipeline (8 momentum, 5 rest-advantage, 3 weather-impact). See
NEW_FEATURES_DEC13.mdfor implementation details and rationale. - UI & Ops: Added EV explanation in the UI, adjusted spread-bet listing to date-ascending where appropriate, fixed unicode/icon issues, and improved PDF/CSV export UX.
These changes complete the short-term model stabilization work and enable optional next steps (hyperparameter tuning, ensembling) documented in MODEL_FIX_PLAN.md.
These updates complete several Beta 0.2/0.3 items earlier than planned and reduce Streamlit Cloud memory pressure while improving shareability and per-game analysis.
- Mobile-responsive design improvements
- A/B testing framework for UI improvements
- Analytics integration (PostHog, Mixpanel, or similar)
- Terms of service and responsible gambling disclaimers
- SEO optimization and landing page
- Social sharing features
| Enhancement | Build If... | Skip If... |
|---|---|---|
| Loading Progress | Users complain about "app hanging" | Load times consistently <5s |
| Data Export | Users ask "can I download this?" | No one mentions it after 2 weeks |
| Cache Management | Data freshness is critical | Data updated infrequently |
| Performance Dashboard | Users question accuracy | Models already trusted |
| Notifications | Engagement drops week-over-week | Users check app daily |
| Bankroll Management | Users ask about bet sizing | Users are experienced bettors |
- 10-20 active users
- <5 critical bugs reported
- Average session length >5 minutes
- At least 3 pieces of actionable feedback
- 50+ active users
- 20%+ increase in user retention
- <10 second average load time
- 80%+ of users engage with new features
- 100+ active users
- 50%+ weekly active users
- Positive feedback on prediction accuracy
- Users placing actual bets based on recommendations
- 500+ active users
- <1% error rate
- 4+ star average rating
- Documented success stories
- Ship fast, iterate faster - Weekly releases during beta
- Data-driven decisions - Build what users actually want
- Quality over features - Better to have 5 excellent features than 20 mediocre ones
- Performance first - Every feature must load <2 seconds
- User trust - Transparency about model performance and limitations
- Refactor after every 3 features
- Maintain <10% test coverage regression
- Document all new features in copilot-instructions.md
- Keep dependencies up-to-date monthly
- ✅ Lazy loading pattern crucial for Streamlit Cloud performance
- ✅ Git LFS essential for large datasets
- ✅ Module-level imports cause silent failures
- ✅ User-facing error messages need to be specific
⚠️ Watch out for data leakage in feature engineering
Thanks for testing NFL Predictions Beta 0.1! Quick questions:
1. What's the ONE feature you use most?
2. What's the ONE thing that frustrates you?
3. What feature would make you check this daily?
4. Would you recommend this to a friend? Why/why not?
5. How much would you pay for this? (Be honest!)
See individual feature implementation notes above. All enhancements should:
- Follow lazy loading pattern
- Include proper error handling
- Be documented in copilot-instructions.md
- Include user-facing help text
- Load in <2 seconds
Last Updated: November 5, 2025
Next Review: After Beta 0.1 user feedback (approx. November 20, 2025)
- Data Export (COMPLETED): Download helpers and CSV export buttons for predictions and the betting log were implemented. The UI uses lightweight sidebar placeholders that are populated with
st.download_buttoncontrols after data loading finishes, ensuring the sidebar renders immediately even when large datasets are being read. - Sidebar Placement: Export buttons are located in the sidebar to reduce main-page clutter. Note that the sidebar may be collapsed by default — expanding it reveals the download controls.
- Move Export Buttons: The export buttons were moved to the sidebar and the placeholder pattern was implemented to avoid render-order issues (previously downloads sometimes didn't appear because the sidebar rendered before data loaded).
- Smoke Test: Added
smoke_test.pyto validate imports and lazy-loading behavior in CI without launching the full Streamlit server. - Memory & Stability Work:
float32andInt8dtype changes, DataFrame view usage,@st.cache_datalazy loaders, and pagination are in place to keep memory usage compatible with Streamlit Cloud limits (~1.5GB observed during peak loads).
- Automated CI — Add a GitHub Action running
python smoke_test.pyfor PRs to catch regressions early. - Streamlit Staging Deploy — Deploy to Streamlit Cloud staging and monitor memory and session behavior with real users.
- Server-side Export Persistence (optional) — Save copies of user exports under
data_files/exports/with timestamps for auditing and support. - Sidebar UX — Consider defaulting to
initial_sidebar_state='expanded'inpredictions.pyto make exports discoverable for new users.