Tobaly commited on
Commit
db41bd7
·
verified ·
1 Parent(s): a833720

Create app.py

Browse files
Files changed (1) hide show
  1. app.py +732 -0
app.py ADDED
@@ -0,0 +1,732 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import pandas as pd
2
+ import numpy as np
3
+ import matplotlib.pyplot as plt
4
+ import seaborn as sns
5
+ from datetime import datetime, timedelta
6
+ from sklearn.linear_model import LinearRegression
7
+ import warnings
8
+ import re
9
+ import io
10
+ import time
11
+ from difflib import SequenceMatcher
12
+ import gradio as gr
13
+ import google.generativeai as genai
14
+ from typing import List, Dict, Tuple, Optional
15
+ import tempfile
16
+ import os
17
+
18
+ # Suppress warnings for a cleaner output
19
+ warnings.filterwarnings('ignore')
20
+
21
+ def get_now():
22
+ """A simple function to get the current time. Can be mocked for testing."""
23
+ return datetime.now()
24
+
25
+ class ComprehensivePodcastReport:
26
+ """
27
+ Generates a complete podcast performance report, combining overall analytics
28
+ with detailed daily and cumulative analysis of episodes within a specified period.
29
+ """
30
+
31
+ def __init__(self, client_name):
32
+ """Initialize the report generator."""
33
+ self.client_name = client_name
34
+ self.all_time_data = {}
35
+ self.period_data = {}
36
+ self.episode_specific_data = {}
37
+ self.unmatched_episode_csvs = []
38
+ self.title_translation_cache = {}
39
+ self.report_date = get_now().strftime("%B %d, %Y")
40
+ self.date_range_str = "All Time"
41
+ self.start_date = None
42
+ self.end_date = None
43
+ self.gemini_api_key = None
44
+
45
+ # --- DATA LOADING AND PREPARATION METHODS ---
46
+
47
+ def _fix_spotify_timestamps(self, timestamp_series):
48
+ """Fix Spotify's invalid '24:00:00' timestamps."""
49
+ return timestamp_series.astype(str).str.replace('24:00:00', '23:59:59')
50
+
51
+ def load_general_data(self, file_paths):
52
+ """Load all general CSV files (OnSpotify, EpisodeRankings, etc.)."""
53
+ print("📊 Loading and processing general data files...")
54
+ try:
55
+ self.all_time_data['time_series'] = pd.read_csv(file_paths['time_series'])
56
+ self.all_time_data['time_series']['Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['time_series']['Time (UTC)']))
57
+
58
+ self.all_time_data['episodes'] = pd.read_csv(file_paths['episodes'])
59
+ self.all_time_data['episodes']['Publish Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['episodes']['Publish Time (UTC)'])).dt.normalize()
60
+ except KeyError as e:
61
+ print(f"❌ Missing a required file: {e}. Please include OnSpotify and EpisodeRankings files.")
62
+ raise
63
+
64
+ # Optional Files
65
+ if 'streams' in file_paths:
66
+ self.all_time_data['streams'] = pd.read_csv(file_paths['streams'])
67
+ self.all_time_data['streams']['Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['streams']['Time (UTC)']))
68
+ streams_df = self.all_time_data['streams']
69
+ first_nonzero_idx = streams_df[streams_df['Streams & Downloads'] > 0].index.min()
70
+ if pd.notna(first_nonzero_idx):
71
+ self.all_time_data['streams'] = streams_df.loc[first_nonzero_idx:].reset_index(drop=True)
72
+
73
+ if 'geo' in file_paths: self.all_time_data['geo'] = pd.read_csv(file_paths['geo'])
74
+ if 'apps' in file_paths: self.all_time_data['apps'] = pd.read_csv(file_paths['apps'])
75
+ if 'devices' in file_paths: self.all_time_data['devices'] = pd.read_csv(file_paths['devices'])
76
+
77
+ self.period_data = {key: df.copy() for key, df in self.all_time_data.items()}
78
+ print(f"✅ General data loaded successfully for {self.client_name}")
79
+
80
+ def filter_data_by_date(self, start_date, end_date):
81
+ """Filter the loaded data to a specific date range."""
82
+ self.start_date = pd.to_datetime(start_date).normalize()
83
+ self.end_date = pd.to_datetime(end_date).normalize()
84
+ self.date_range_str = f"{self.start_date.strftime('%Y-%m-%d')} to {self.end_date.strftime('%Y-%m-%d')}"
85
+ print(f"🔎 Filtering data for period: {self.date_range_str}")
86
+
87
+ for key in ['time_series', 'streams']:
88
+ if key in self.period_data:
89
+ df = self.period_data[key]
90
+ self.period_data[key] = df[(df['Date'] >= self.start_date) & (df['Date'] <= self.end_date)]
91
+
92
+ # --- EPISODE-SPECIFIC ANALYSIS METHODS ---
93
+
94
+ def _normalize_text(self, text):
95
+ """Normalizes text for fuzzy string matching."""
96
+ text = re.sub(r'[^\u0590-\u05FFa-zA-Z0-9\-]', '', str(text).replace(':', '').replace(' ', ''))
97
+ return text.lower()
98
+
99
+ def identify_and_prompt_for_episodes(self):
100
+ """Identifies episodes in the period and prompts the user for their CSVs."""
101
+ episodes_df = self.all_time_data.get('episodes')
102
+ if episodes_df is None: return pd.DataFrame()
103
+
104
+ episodes_in_period = episodes_df[
105
+ (episodes_df['Publish Date'] >= self.start_date) &
106
+ (episodes_df['Publish Date'] <= self.end_date)
107
+ ].sort_values('Publish Date', ascending=False).reset_index(drop=True)
108
+
109
+ total_episodes = len(episodes_in_period)
110
+ if total_episodes == 0:
111
+ print("\n⚠️ No episodes found published in the selected period.")
112
+ else:
113
+ print(f"\n📺 Found {total_episodes} episodes published in the period:")
114
+ print("="*80)
115
+ for _, row in episodes_in_period.iterrows():
116
+ print(f" • {row['Episode Title'][:80]} (Published: {row['Publish Date']:%Y-%m-%d})")
117
+ print("="*80)
118
+ return episodes_in_period
119
+
120
+ def load_and_match_episode_csvs(self, uploaded_files, episodes_in_period):
121
+ """Matches and loads individual episode CSVs from uploaded files."""
122
+ print("\n🔍 Matching and loading individual episode CSVs...")
123
+ if episodes_in_period.empty:
124
+ print(" -> No episodes in period to match against. Skipping.")
125
+ return
126
+ episodes_in_period['normalized_title'] = episodes_in_period['Episode Title'].apply(self._normalize_text)
127
+
128
+ for filename, file_content in uploaded_files.items():
129
+ file_type = 'spotify' if 'OnSpotify' in filename else 'all_platforms' if 'StreamsAndDownloads' in filename else None
130
+ if not file_type: continue
131
+
132
+ clean_filename = re.sub(r'\s*\(\d+\)|\s+\d+(?=\.csv)', '', filename)
133
+ normalized_filename = self._normalize_text(clean_filename)
134
+ episodes_in_period['similarity'] = episodes_in_period['normalized_title'].apply(
135
+ lambda title: SequenceMatcher(None, normalized_filename, title).ratio()
136
+ )
137
+ best_match = episodes_in_period.loc[episodes_in_period['similarity'].idxmax()]
138
+
139
+ if best_match['similarity'] > 0.5:
140
+ episode_title = best_match['Episode Title']
141
+ print(f" ✅ Matched: {filename[:40]}... -> {episode_title[:40]}...")
142
+ try:
143
+ df = pd.read_csv(io.StringIO(file_content))
144
+ df['Date'] = pd.to_datetime(df['Time (UTC)'].str.split(',').str[0], errors='coerce').dt.normalize()
145
+ value_col = next((col for col in ['Plays', 'Streams & Downloads'] if col in df.columns), None)
146
+ if not value_col: continue
147
+ episode_df = df[['Date', value_col]].rename(columns={value_col: 'value'}).groupby('Date')['value'].sum().reset_index()
148
+ if episode_title not in self.episode_specific_data: self.episode_specific_data[episode_title] = {}
149
+ self.episode_specific_data[episode_title][file_type] = episode_df
150
+ except Exception as e:
151
+ print(f" -> Error processing file {filename}: {e}")
152
+ else:
153
+ self.unmatched_episode_csvs.append(filename)
154
+
155
+ # --- CORE ANALYTICS AND METRICS ---
156
+
157
+ def calculate_key_metrics(self, use_all_time=False):
158
+ """Calculate core performance metrics."""
159
+ data_scope = self.all_time_data if use_all_time else self.period_data
160
+ ts_data = data_scope.get('time_series', pd.DataFrame())
161
+ if ts_data.empty: return {}
162
+ ts_followers_cleaned = ts_data.dropna(subset=['Followers'])
163
+ current_followers = int(ts_followers_cleaned['Followers'].iloc[-1]) if not ts_followers_cleaned.empty else 0
164
+ total_plays = ts_data['Plays'].sum()
165
+ total_streams = ts_data['Streams'].sum()
166
+
167
+ metrics = {
168
+ 'total_plays': int(total_plays), 'total_streams': int(total_streams),
169
+ 'avg_daily_plays': ts_data['Plays'].mean(),
170
+ 'engagement_percentage': (total_streams / max(total_plays, 1)) * 100,
171
+ 'current_followers': current_followers
172
+ }
173
+ if use_all_time:
174
+ ep_data = self.all_time_data.get('episodes', pd.DataFrame())
175
+ metrics.update({
176
+ 'total_episodes': len(ep_data),
177
+ 'median_streams_per_episode': ep_data['Streams & Downloads'].median() if not ep_data.empty else 0,
178
+ 'performance_benchmark': ep_data['Streams & Downloads'].quantile(0.75) if not ep_data.empty else 0
179
+ })
180
+ else: # Period specific
181
+ ep_data_all = self.all_time_data.get('episodes', pd.DataFrame())
182
+ episodes_in_period = ep_data_all[(ep_data_all['Publish Date'] >= self.start_date) & (ep_data_all['Publish Date'] <= self.end_date)]
183
+ metrics['performance_benchmark_period'] = episodes_in_period['Streams & Downloads'].quantile(0.75) if not episodes_in_period.empty else 0
184
+ return metrics
185
+
186
+ def analyze_growth_trends(self, period_days=30):
187
+ """Analyze growth trends for the selected period."""
188
+ ts_data = self.period_data['time_series'].dropna(subset=['Plays', 'Followers']).sort_values('Date')
189
+ if len(ts_data) < period_days * 2: return {}
190
+ recent_period = ts_data.tail(period_days)
191
+ previous_period = ts_data.iloc[-(period_days*2):-period_days]
192
+ if recent_period.empty or previous_period.empty: return {}
193
+ recent_gain = recent_period['Followers'].iloc[-1] - recent_period['Followers'].iloc[0]
194
+ previous_gain = previous_period['Followers'].iloc[-1] - previous_period['Followers'].iloc[0]
195
+ return {
196
+ 'plays_growth_rate_median': ((recent_period['Plays'].median() - previous_period['Plays'].median()) / max(previous_period['Plays'].median(), 1)) * 100,
197
+ 'followers_gained': int(recent_gain),
198
+ 'follower_growth_rate': ((recent_gain - previous_gain) / max(abs(previous_gain), 1)) * 100 if previous_gain != 0 else float('inf')
199
+ }
200
+
201
+ def analyze_seasonal_patterns(self):
202
+ """Analyze weekly listening patterns."""
203
+ ts_data = self.period_data['time_series'].dropna(subset=['Plays'])
204
+ if len(ts_data) < 7: return {}
205
+ ts_data['DayOfWeek'] = ts_data['Date'].dt.day_name()
206
+ weekly_avg = ts_data.groupby('DayOfWeek')['Plays'].mean()
207
+ return {
208
+ 'best_day': weekly_avg.idxmax(), 'worst_day': weekly_avg.idxmin(),
209
+ 'weekly_consistency': (1 - (weekly_avg.std() / weekly_avg.mean())) * 100 if weekly_avg.mean() > 0 else 0
210
+ }
211
+
212
+ def _get_platform_share(self, platform_name):
213
+ """Helper to get platform share from all-time data."""
214
+ apps_df = self.all_time_data.get('apps')
215
+ if apps_df is None: return 0.0
216
+ platform_row = apps_df[apps_df['App'] == platform_name]
217
+ return platform_row['Percent of Plays'].iloc[0] * 100 if not platform_row.empty else 0.0
218
+
219
+ # --- PLOTTING AND VISUALIZATION METHODS ---
220
+
221
+ def _add_regression_line(self, ax, x_values, y_values, **kwargs):
222
+ """Helper to add a linear regression trendline to a plot."""
223
+ if len(x_values) < 2: return
224
+ x_numeric = np.arange(len(x_values))
225
+ model = LinearRegression().fit(x_numeric.reshape(-1, 1), y_values)
226
+ y_pred = model.predict(x_numeric.reshape(-1, 1))
227
+ label = f"{kwargs.get('label_prefix', 'Trend')} (Slope: {model.coef_[0]:.2f})"
228
+ ax.plot(x_values, y_pred, '--', color='red', alpha=0.7, label=label)
229
+
230
+ def generate_all_visualizations(self):
231
+ """Generates a comprehensive set of all overview plots."""
232
+ print("🎨 Generating all performance visualizations...")
233
+ plots = []
234
+ ts_data = self.period_data['time_series'].sort_values('Date')
235
+
236
+ # Daily Plays & Streams
237
+ if not ts_data.empty:
238
+ fig, ax = plt.subplots(figsize=(12, 6))
239
+ ax.plot(ts_data['Date'], ts_data['Plays'], label='Daily Plays (Spotify)', color='blue')
240
+ self._add_regression_line(ax, ts_data['Date'], ts_data['Plays'])
241
+ ax.set_title(f'{self.client_name} - Daily Plays (OnSpotify)', fontsize=14)
242
+ ax.grid(True, alpha=0.3)
243
+ ax.legend()
244
+ plt.tight_layout()
245
+ plots.append(('daily_plays', fig))
246
+
247
+ if 'streams' in self.period_data and not self.period_data['streams'].empty:
248
+ streams_data = self.period_data['streams'].sort_values('Date')
249
+ fig, ax = plt.subplots(figsize=(12, 6))
250
+ ax.plot(streams_data['Date'], streams_data['Streams & Downloads'], label='Daily Streams & Downloads', color='green')
251
+ self._add_regression_line(ax, streams_data['Date'], streams_data['Streams & Downloads'])
252
+ ax.set_title(f'{self.client_name} - Daily Streams & Downloads (All Platforms)', fontsize=14)
253
+ ax.grid(True, alpha=0.3)
254
+ ax.legend()
255
+ plt.tight_layout()
256
+ plots.append(('daily_streams', fig))
257
+
258
+ # Monthly Plots
259
+ graph_start = self.start_date.replace(day=1) if self.start_date.day != 1 else self.start_date
260
+ for key, col, color in [('time_series', 'Plays', 'skyblue'), ('streams', 'Streams & Downloads', 'lightgreen')]:
261
+ if key in self.all_time_data:
262
+ monthly_data = self.all_time_data[key]
263
+ monthly_data = monthly_data[(monthly_data['Date'] >= graph_start) & (monthly_data['Date'] <= self.end_date)]
264
+ if not monthly_data.empty:
265
+ monthly_data['YearMonth'] = monthly_data['Date'].dt.to_period('M')
266
+ monthly_values = monthly_data.groupby('YearMonth')[col].sum()
267
+ fig, ax = plt.subplots(figsize=(12, 6))
268
+ bars = ax.bar(np.arange(len(monthly_values)), monthly_values.values, color=color, edgecolor='navy')
269
+ self._add_regression_line(ax, np.arange(len(monthly_values)), monthly_values.values)
270
+ ax.set_xticks(np.arange(len(monthly_values)))
271
+ ax.set_xticklabels([str(p) for p in monthly_values.index], rotation=45)
272
+ ax.set_title(f'{self.client_name} - Monthly {col}', fontsize=14)
273
+ ax.legend()
274
+ plt.tight_layout()
275
+ current_month = pd.Period(get_now(), 'M')
276
+ if current_month in monthly_values.index:
277
+ bars[monthly_values.index.get_loc(current_month)].set_color('orange')
278
+ plots.append((f'monthly_{key}', fig))
279
+
280
+ # Advanced Metrics
281
+ follower_data = ts_data.dropna(subset=['Followers'])
282
+ if not follower_data.empty:
283
+ fig, ax = plt.subplots(figsize=(12, 6))
284
+ ax.plot(follower_data['Date'], follower_data['Followers'], label='Followers', color='purple')
285
+ self._add_regression_line(ax, follower_data['Date'], follower_data['Followers'], label_prefix="Follower Trend")
286
+ ax.set_title(f'{self.client_name} - Follower Growth', fontsize=14)
287
+ ax.grid(True, alpha=0.3)
288
+ ax.legend()
289
+ plt.tight_layout()
290
+ plots.append(('follower_growth', fig))
291
+
292
+ consump_data = ts_data.dropna(subset=['Consumption Hours'])
293
+ if not consump_data.empty and consump_data['Consumption Hours'].sum() > 0:
294
+ fig, ax = plt.subplots(figsize=(12, 6))
295
+ ax.plot(consump_data['Date'], consump_data['Consumption Hours'], label='Hours', color='teal')
296
+ self._add_regression_line(ax, consump_data['Date'], consump_data['Consumption Hours'], label_prefix="Consumption Trend")
297
+ ax.set_title(f'{self.client_name} - Daily Consumption Hours', fontsize=14)
298
+ ax.grid(True, alpha=0.3)
299
+ ax.legend()
300
+ plt.tight_layout()
301
+ plots.append(('consumption_hours', fig))
302
+
303
+ ratio_df = ts_data[['Date', 'Streams', 'Plays']].copy()
304
+ ratio_df['ratio'] = ratio_df['Streams'] / ratio_df['Plays'].replace(0, np.nan)
305
+ ratio_df['ratio_30d_avg'] = ratio_df['ratio'].rolling(30, min_periods=1).mean()
306
+ ratio_df.dropna(subset=['ratio_30d_avg'], inplace=True)
307
+ if not ratio_df.empty:
308
+ fig, ax = plt.subplots(figsize=(12, 6))
309
+ ax.plot(ratio_df['Date'], ratio_df['ratio_30d_avg'], label='30-Day Avg Stream/Play Ratio', color='orange')
310
+ self._add_regression_line(ax, ratio_df['Date'], ratio_df['ratio_30d_avg'], label_prefix="Ratio Trend")
311
+ ax.set_title(f'{self.client_name} - Stream/Play Ratio (30-Day Average)', fontsize=14)
312
+ ax.grid(True, alpha=0.3)
313
+ ax.legend()
314
+ plt.tight_layout()
315
+ plots.append(('stream_play_ratio', fig))
316
+
317
+ # Audience & Episode Distributions (All-Time)
318
+ if 'apps' in self.all_time_data:
319
+ fig, ax = plt.subplots(figsize=(8, 8))
320
+ self.all_time_data['apps'].head(5).plot.pie(y='Percent of Plays', labels=self.all_time_data['apps']['App'].head(5), autopct='%1.1f%%', ax=ax, legend=False)
321
+ ax.set_title(f'{self.client_name} - Platform Distribution', fontsize=14)
322
+ ax.set_ylabel('')
323
+ plt.tight_layout()
324
+ plots.append(('platform_dist', fig))
325
+
326
+ if 'devices' in self.all_time_data:
327
+ fig, ax = plt.subplots(figsize=(8, 8))
328
+ self.all_time_data['devices'].head(5).plot.pie(y='Percent of Plays', labels=self.all_time_data['devices']['Device'].head(5), autopct='%1.1f%%', ax=ax, legend=False)
329
+ ax.set_title(f'{self.client_name} - Device Distribution', fontsize=14)
330
+ ax.set_ylabel('')
331
+ plt.tight_layout()
332
+ plots.append(('device_dist', fig))
333
+
334
+ if 'geo' in self.all_time_data:
335
+ fig, ax = plt.subplots(figsize=(10, 6))
336
+ top_geo = self.all_time_data['geo'].head(10)
337
+ ax.barh(top_geo['Geo'], top_geo['Percent of Plays'] * 100, color='coral')
338
+ ax.set_title(f'{self.client_name} - Top 10 Geographic Markets', fontsize=14)
339
+ ax.invert_yaxis()
340
+ ax.grid(True, alpha=0.3, axis='x')
341
+ plt.tight_layout()
342
+ plots.append(('geo_markets', fig))
343
+
344
+ ep_data_all = self.all_time_data.get('episodes')
345
+ if ep_data_all is not None:
346
+ fig, ax = plt.subplots(figsize=(10, 6))
347
+ ax.hist(ep_data_all['Streams & Downloads'], bins=30, color='skyblue', edgecolor='navy')
348
+ ax.axvline(ep_data_all['Streams & Downloads'].mean(), color='red', linestyle='--', label='Mean')
349
+ ax.set_title(f'{self.client_name} - Episode Performance Distribution (All Time)', fontsize=14)
350
+ ax.legend()
351
+ plt.tight_layout()
352
+ plots.append(('ep_dist_all_time', fig))
353
+
354
+ episodes_in_period = ep_data_all[(ep_data_all['Publish Date'] >= self.start_date) & (ep_data_all['Publish Date'] <= self.end_date)]
355
+ if not episodes_in_period.empty:
356
+ fig, ax = plt.subplots(figsize=(10, 6))
357
+ ax.hist(episodes_in_period['Streams & Downloads'], bins=15, color='teal', edgecolor='darkslategray')
358
+ ax.axvline(episodes_in_period['Streams & Downloads'].mean(), color='red', linestyle='--', label='Mean')
359
+ ax.set_title(f'{self.client_name} - Episode Performance (Published in Period)', fontsize=14)
360
+ ax.legend()
361
+ plt.tight_layout()
362
+ plots.append(('ep_dist_period', fig))
363
+
364
+ return plots
365
+
366
+ def _translate_title(self, hebrew_title):
367
+ """Translates a Hebrew title to a short English legend title using Gemini."""
368
+ if hebrew_title in self.title_translation_cache:
369
+ return self.title_translation_cache[hebrew_title]
370
+
371
+ if not self.gemini_api_key:
372
+ return hebrew_title[:40] + '...'
373
+
374
+ try:
375
+ genai.configure(api_key=self.gemini_api_key)
376
+ model = genai.GenerativeModel('gemini-2.0-flash-exp')
377
+ prompt = f"""Analyze the Hebrew podcast title "{hebrew_title}". Generate a short, readable English legend title formatted as "[Guest Name] - #[Episode Number]". Transliterate the name. If there is no episode number, use only the name. If there is no name, create a concise English summary of the topic. If you recognize מהדורת מוסף in the title, then the output would be: "Investors Panel - #[Episode Number]".The final title must be under 5 words."""
378
+ response = model.generate_content(prompt)
379
+ time.sleep(1.5)
380
+ translated = response.text.strip()
381
+ self.title_translation_cache[hebrew_title] = translated
382
+ return translated
383
+ except Exception as e:
384
+ print(f" -> Gemini API Error: {e}")
385
+ return hebrew_title[:40] + '...'
386
+
387
+ def generate_episode_specific_plots(self, max_episodes=10):
388
+ """Generates the cumulative performance plots for individual episodes."""
389
+ print("🚀 Generating episode-specific cumulative plots...")
390
+ plots = []
391
+ if not self.episode_specific_data: return plots
392
+
393
+ for data_source in ['spotify', 'all_platforms']:
394
+ ep_data_source = {t: d[data_source] for t, d in self.episode_specific_data.items() if data_source in d}
395
+ if not ep_data_source: continue
396
+
397
+ ep_totals = {title: df['value'].sum() for title, df in ep_data_source.items()}
398
+ top_episodes = sorted(ep_totals, key=ep_totals.get, reverse=True)[:max_episodes]
399
+
400
+ date_index = pd.date_range(start=self.start_date, end=self.end_date, freq='D')
401
+ plot_df = pd.DataFrame(index=date_index)
402
+
403
+ for title in top_episodes:
404
+ plot_df = plot_df.join(ep_data_source[title].set_index('Date').rename(columns={'value': title}))
405
+
406
+ cumulative_df = plot_df.fillna(0).cumsum()
407
+ fig, ax = plt.subplots(figsize=(15, 8))
408
+
409
+ for h_title in cumulative_df.columns:
410
+ ax.plot(cumulative_df.index, cumulative_df[h_title], label=self._translate_title(h_title), linewidth=2.5)
411
+
412
+ ax.set_title(f'Cumulative Performance by Date ({data_source.replace("_", " ").title()})', fontsize=16)
413
+ ax.legend(bbox_to_anchor=(1.02, 1), loc='upper left')
414
+ plt.tight_layout()
415
+ plots.append((f'ep_cumul_date_{data_source}', fig))
416
+
417
+ airday_df = pd.DataFrame()
418
+ for title in top_episodes:
419
+ df = ep_data_source[title]
420
+ first_play = df[df['value'] > 0]['Date'].min()
421
+ if pd.isna(first_play): continue
422
+ df_after = df[df['Date'] >= first_play].copy()
423
+ airday_df[title] = df_after['value'].cumsum().reset_index(drop=True)
424
+
425
+ airday_df['Average'] = airday_df.mean(axis=1)
426
+ fig, ax = plt.subplots(figsize=(15, 8))
427
+
428
+ for h_title in top_episodes:
429
+ if h_title in airday_df.columns:
430
+ ax.plot(airday_df.index + 1, airday_df[h_title], label=self._translate_title(h_title), alpha=0.8)
431
+
432
+ ax.plot(airday_df.index + 1, airday_df['Average'], 'k--', label='Average', linewidth=2.5)
433
+ ax.set_title(f'Cumulative Performance by Air Day ({data_source.replace("_", " ").title()})', fontsize=16)
434
+ ax.set_xlabel('Days Since Release')
435
+ ax.legend(bbox_to_anchor=(1.02, 1), loc='upper left')
436
+ plt.tight_layout()
437
+ plots.append((f'ep_cumul_airday_{data_source}', fig))
438
+
439
+ return plots
440
+
441
+ # --- REPORTING AND ORCHESTRATION ---
442
+
443
+ def generate_executive_summary(self, all_time_metrics, period_metrics, trends, seasonal):
444
+ """Generates the final executive summary text."""
445
+ summary = f"""# {self.client_name} - Podcast Performance Report
446
+ *Generated on {self.report_date}*
447
+ ---
448
+ ## 📈 All-Time Performance Summary
449
+ *A high-level overview of the podcast's entire history.*
450
+
451
+ - **Total Plays**: {all_time_metrics.get('total_plays', 0):,}
452
+ - **Total Streams**: {all_time_metrics.get('total_streams', 0):,}
453
+ - **Total Episodes**: {all_time_metrics.get('total_episodes', 0)}
454
+ - **Most Recent Follower Count**: {all_time_metrics.get('current_followers', 0):,}
455
+ - **Median Streams per Episode**: {all_time_metrics.get('median_streams_per_episode', 0):,.0f}
456
+ - **Performance Benchmark (Top 25% of Episodes)**: > {all_time_metrics.get('performance_benchmark', 0):,.0f} streams
457
+ ---
458
+ ## 📊 Performance for Selected Period: {self.date_range_str}
459
+ *A detailed analysis of performance within the specified date range.*
460
+
461
+ ### Key Performance Indicators (Period)
462
+ - **Total Plays in Period**: {period_metrics.get('total_plays', 0):,}
463
+ - **Total Streams in Period**: {period_metrics.get('total_streams', 0):,}
464
+ - **Average Daily Plays**: {period_metrics.get('avg_daily_plays', 0):,.0f}
465
+ - **Engagement Rate (Streams/Plays)**: {period_metrics.get('engagement_percentage', 0):.1f}%
466
+ - **Performance Benchmark (Top 25% of Episodes in Period)**: > {period_metrics.get('performance_benchmark_period', 0):,.0f} streams
467
+ """
468
+ if trends:
469
+ summary += f"""
470
+ ### Growth Trends (Comparison of 30-Day Sub-periods)
471
+ - **Plays Growth (Median)**: {trends.get('plays_growth_rate_median', 0):+.1f}%
472
+ - **Followers Gained**: {trends.get('followers_gained', 0):+,}
473
+ - **Follower Growth Rate**: {trends.get('follower_growth_rate', 0):+.1f}% (vs. prior period)
474
+ """
475
+ if seasonal:
476
+ summary += f"""
477
+ ### Listening Patterns (Period)
478
+ - **Best Day for Plays**: {seasonal.get('best_day')}
479
+ - **Worst Day for Plays**: {seasonal.get('worst_day')}
480
+ - **Weekly Listening Consistency**: {seasonal.get('weekly_consistency', 0):.1f}%
481
+ """
482
+ summary += "\n### Audience Insights (All-Time)\n"
483
+ if 'geo' in self.all_time_data:
484
+ summary += f"- **Primary Market**: {self.all_time_data['geo'].loc[0, 'Geo']} ({self.all_time_data['geo'].loc[0, 'Percent of Plays'] * 100:.1f}% of plays)\n"
485
+ if 'apps' in self.all_time_data:
486
+ summary += f"- **Platform Mix**: {self._get_platform_share('Spotify'):.1f}% Spotify, {self._get_platform_share('Apple Podcasts'):.1f}% Apple Podcasts\n"
487
+
488
+ summary += "\n## 🏆 Top 5 Performing Episodes (All-Time)\n"
489
+ ep_data = self.all_time_data.get('episodes')
490
+ if ep_data is not None:
491
+ for i, (_, row) in enumerate(ep_data.nlargest(5, 'Streams & Downloads').iterrows(), 1):
492
+ summary += f"{i}. **{row['Episode Title'][:60]}...**\n {row['Streams & Downloads']:,} streams | {row['Publish Date']:%B %Y}\n\n"
493
+ return summary
494
+
495
+ def run_full_analysis(self, uploaded_episode_files, episodes_in_period, gemini_api_key=None):
496
+ """Orchestrates the entire analysis and report generation process."""
497
+ self.gemini_api_key = gemini_api_key
498
+ print("\n" + "="*60 + "\n🚀 STARTING FULL ANALYSIS & REPORT GENERATION\n" + "="*60)
499
+ self.load_and_match_episode_csvs(uploaded_episode_files, episodes_in_period)
500
+ all_time_metrics = self.calculate_key_metrics(use_all_time=True)
501
+ period_metrics = self.calculate_key_metrics(use_all_time=False)
502
+ trends = self.analyze_growth_trends()
503
+ seasonal = self.analyze_seasonal_patterns()
504
+ summary = self.generate_executive_summary(all_time_metrics, period_metrics, trends, seasonal)
505
+ print("\n" + "="*60 + "\n📋 EXECUTIVE SUMMARY\n" + "="*60)
506
+ print(summary)
507
+ all_plots = self.generate_all_visualizations() + self.generate_episode_specific_plots()
508
+ print("\n✅ Analysis Complete.")
509
+ return summary, all_plots
510
+
511
+
512
+ def process_uploaded_files(files):
513
+ """Process uploaded files and return file content dictionary."""
514
+ file_contents = {}
515
+ for file in files:
516
+ if file is not None:
517
+ # Read file content
518
+ content = file.read()
519
+ if isinstance(content, bytes):
520
+ content = content.decode('utf-8')
521
+ file_contents[file.name] = content
522
+ return file_contents
523
+
524
+
525
+ def run_podcast_analysis(client_name, date_from, date_to, gemini_api_key, *uploaded_files):
526
+ """Main function to run the podcast analysis with Gradio inputs."""
527
+ try:
528
+ print(f"🎙️ Starting analysis for: {client_name}")
529
+ print(f"📅 Date range: {date_from} to {date_to}")
530
+
531
+ # Process uploaded files
532
+ all_files = [f for f in uploaded_files if f is not None]
533
+ if not all_files:
534
+ return "❌ Error: No files uploaded. Please upload the required CSV files.", []
535
+
536
+ file_contents = process_uploaded_files(all_files)
537
+ print(f"📁 Processed {len(file_contents)} files")
538
+
539
+ # Separate general files from episode-specific files
540
+ file_patterns = {
541
+ 'time_series': 'OnSpotify',
542
+ 'episodes': 'EpisodeRankings',
543
+ 'geo': 'GeoLocation',
544
+ 'apps': 'PlaysByApp',
545
+ 'devices': 'PlaysByDevice',
546
+ 'streams': 'StreamsAndDownloads'
547
+ }
548
+
549
+ general_files = {}
550
+ episode_files = {}
551
+
552
+ for filename, content in file_contents.items():
553
+ is_general = False
554
+ for file_type, pattern in file_patterns.items():
555
+ if pattern in filename and not any(ep_pattern in filename for ep_pattern in ['episode', 'Episode']):
556
+ general_files[file_type] = io.StringIO(content)
557
+ is_general = True
558
+ break
559
+
560
+ if not is_general:
561
+ episode_files[filename] = content
562
+
563
+ if len(general_files) < 2: # At minimum need OnSpotify and EpisodeRankings
564
+ return "❌ Error: Missing required general files. Please ensure you upload OnSpotify and EpisodeRankings CSV files.", []
565
+
566
+ # Initialize analyzer
567
+ analyzer = ComprehensivePodcastReport(client_name)
568
+ analyzer.load_general_data(general_files)
569
+
570
+ # Set date range
571
+ if date_to:
572
+ end_date = pd.to_datetime(date_to)
573
+ else:
574
+ end_date = get_now()
575
+
576
+ if date_from:
577
+ if isinstance(date_from, str) and date_from.isdigit():
578
+ # If it's a number of days
579
+ start_date = end_date - timedelta(days=int(date_from))
580
+ else:
581
+ start_date = pd.to_datetime(date_from)
582
+ else:
583
+ # Use earliest episode date if no start date provided
584
+ start_date = analyzer.all_time_data['episodes']['Publish Date'].min()
585
+
586
+ analyzer.filter_data_by_date(start_date, end_date)
587
+
588
+ # Identify episodes in period
589
+ episodes_in_period = analyzer.identify_and_prompt_for_episodes()
590
+
591
+ # Run analysis
592
+ summary, plots = analyzer.run_full_analysis(episode_files, episodes_in_period, gemini_api_key)
593
+
594
+ # Convert plots to images for Gradio
595
+ plot_images = []
596
+ for plot_name, fig in plots:
597
+ # Save figure to temporary file
598
+ temp_file = tempfile.NamedTemporaryFile(delete=False, suffix='.png')
599
+ fig.savefig(temp_file.name, dpi=150, bbox_inches='tight')
600
+ plt.close(fig) # Close the figure to free memory
601
+ plot_images.append(temp_file.name)
602
+
603
+ return summary, plot_images
604
+
605
+ except Exception as e:
606
+ import traceback
607
+ error_msg = f"❌ Error during analysis: {str(e)}\n\nTraceback:\n{traceback.format_exc()}"
608
+ print(error_msg)
609
+ return error_msg, []
610
+
611
+
612
+ # Create Gradio Interface
613
+ def create_gradio_interface():
614
+ """Create the Gradio interface for the podcast analytics tool."""
615
+
616
+ with gr.Blocks(title="Valuebell Podcast Analytics", theme=gr.themes.Soft()) as demo:
617
+ gr.HTML("""
618
+ <div style="text-align: center; margin-bottom: 30px;">
619
+ <h1>🎙️ Valuebell Podcast Analytics Dashboard</h1>
620
+ <p style="font-size: 18px; color: #666;">
621
+ Upload your podcast CSV files to generate comprehensive performance reports
622
+ </p>
623
+ </div>
624
+ """)
625
+
626
+ with gr.Row():
627
+ with gr.Column(scale=1):
628
+ gr.HTML("<h3>📋 Configuration</h3>")
629
+
630
+ client_name = gr.Textbox(
631
+ label="Client/Podcast Name",
632
+ placeholder="Enter the podcast name...",
633
+ value="My Podcast"
634
+ )
635
+
636
+ with gr.Row():
637
+ date_from = gr.Textbox(
638
+ label="Start Date",
639
+ placeholder="YYYY-MM-DD or number of days (e.g., '60' for last 60 days)",
640
+ value="60"
641
+ )
642
+ date_to = gr.Textbox(
643
+ label="End Date (optional)",
644
+ placeholder="YYYY-MM-DD (leave empty for today)"
645
+ )
646
+
647
+ gemini_api_key = gr.Textbox(
648
+ label="Gemini API Key (optional)",
649
+ placeholder="For Hebrew title translation...",
650
+ type="password"
651
+ )
652
+
653
+ gr.HTML("<h3>📁 File Uploads</h3>")
654
+ gr.HTML("""
655
+ <div style="background-color: #f0f8ff; padding: 15px; border-radius: 8px; margin-bottom: 15px;">
656
+ <h4>Required Files:</h4>
657
+ <ul>
658
+ <li><strong>OnSpotify</strong> CSV (daily plays data)</li>
659
+ <li><strong>EpisodeRankings</strong> CSV (episode performance data)</li>
660
+ </ul>
661
+ <h4>Optional Files:</h4>
662
+ <ul>
663
+ <li><strong>StreamsAndDownloads</strong> CSV (all platforms data)</li>
664
+ <li><strong>GeoLocation</strong> CSV (geographic data)</li>
665
+ <li><strong>PlaysByApp</strong> CSV (platform distribution)</li>
666
+ <li><strong>PlaysByDevice</strong> CSV (device distribution)</li>
667
+ <li>Individual episode CSV files (for detailed episode analysis)</li>
668
+ </ul>
669
+ </div>
670
+ """)
671
+
672
+ # Multiple file upload components
673
+ files = []
674
+ for i in range(20): # Allow up to 20 file uploads
675
+ file_upload = gr.File(
676
+ label=f"Upload CSV File {i+1}" if i < 6 else None,
677
+ file_types=[".csv"],
678
+ visible=i < 6 # Show first 6 by default
679
+ )
680
+ files.append(file_upload)
681
+
682
+ analyze_btn = gr.Button("🚀 Generate Analytics Report", variant="primary", size="lg")
683
+
684
+ with gr.Column(scale=2):
685
+ gr.HTML("<h3>📊 Results</h3>")
686
+
687
+ summary_output = gr.Markdown(
688
+ label="Executive Summary",
689
+ value="Upload files and click 'Generate Analytics Report' to see results..."
690
+ )
691
+
692
+ plots_output = gr.Gallery(
693
+ label="Performance Visualizations",
694
+ show_label=True,
695
+ elem_id="plots-gallery",
696
+ columns=2,
697
+ rows=3,
698
+ height="auto"
699
+ )
700
+
701
+ # Set up the analysis function
702
+ analyze_btn.click(
703
+ fn=run_podcast_analysis,
704
+ inputs=[client_name, date_from, date_to, gemini_api_key] + files,
705
+ outputs=[summary_output, plots_output],
706
+ show_progress=True
707
+ )
708
+
709
+ gr.HTML("""
710
+ <div style="text-align: center; margin-top: 30px; padding: 20px; background-color: #f8f9fa; border-radius: 8px;">
711
+ <h4>💡 Tips for Best Results:</h4>
712
+ <ul style="text-align: left; display: inline-block;">
713
+ <li>Ensure your CSV files follow Spotify for Creators naming conventions</li>
714
+ <li>For Hebrew podcasts, provide a Gemini API key for title translation</li>
715
+ <li>Include episode-specific CSV files for detailed performance tracking</li>
716
+ <li>Use date ranges that cover complete weeks for better trend analysis</li>
717
+ </ul>
718
+ </div>
719
+ """)
720
+
721
+ return demo
722
+
723
+
724
+ if __name__ == "__main__":
725
+ # Create and launch the Gradio interface
726
+ demo = create_gradio_interface()
727
+ demo.launch(
728
+ share=True,
729
+ server_name="0.0.0.0",
730
+ server_port=7860,
731
+ show_error=True
732
+ )