tubesentry 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,379 @@
1
+ from __future__ import annotations
2
+
3
+ import io
4
+ import re
5
+ from pathlib import Path
6
+ from typing import BinaryIO, TextIO
7
+
8
+ import pandas as pd
9
+
10
+ from tubesentry.contracts.exceptions import MalformedPlacementCSVError
11
+
12
+ # Regex patterns for Channel and Video IDs
13
+ CHANNEL_ID_REGEX = re.compile(r"UC[a-zA-Z0-9_-]{22}")
14
+ DIRECT_CHANNEL_ID_REGEX = re.compile(r"^UC[a-zA-Z0-9_-]{22}$")
15
+ URL_CHANNEL_ID_REGEX = re.compile(r"youtube\.com/channel/(UC[a-zA-Z0-9_-]{22})")
16
+ URL_HANDLE_REGEX = re.compile(r"(?:youtube\.com/)?@([a-zA-Z0-9_.-]+)")
17
+ URL_VIDEO_REGEX = re.compile(
18
+ r"(?:youtube\.com/(?:watch\?v=|video/|shorts/)|youtu\.be/)([a-zA-Z0-9_-]{11})"
19
+ )
20
+
21
+ # Canonical Column Alias Dictionary (lowercase stripped for robust matching)
22
+ COLUMN_ALIASES: dict[str, list[str]] = {
23
+ "raw_placement": [
24
+ "placement",
25
+ "placement url",
26
+ "where ads showed",
27
+ "emplazamiento",
28
+ "emplacement",
29
+ "posizionamento",
30
+ "plaatsing",
31
+ "youtube channel",
32
+ "app/url",
33
+ "wo anzeigen geschaltet wurden",
34
+ ],
35
+ "channel_title": [
36
+ "placement name",
37
+ "name des placements",
38
+ "nombre del emplazamiento",
39
+ "channel name",
40
+ "nom de l'emplacement",
41
+ "nome del posizionamento",
42
+ "plaatsingsnaam",
43
+ "channel",
44
+ "kanalname",
45
+ ],
46
+ "cost": [
47
+ "cost",
48
+ "kosten",
49
+ "coste",
50
+ "coût",
51
+ "cout",
52
+ "costo",
53
+ "media cost",
54
+ "spend",
55
+ "revenue (adv currency)",
56
+ "ausgaben",
57
+ ],
58
+ "impressions": [
59
+ "impr.",
60
+ "impressions",
61
+ "impressionen",
62
+ "impresiones",
63
+ "impressies",
64
+ "impressioni",
65
+ ],
66
+ "views": [
67
+ "views",
68
+ "aufrufe",
69
+ "visualizaciones",
70
+ "vues",
71
+ "trueview views",
72
+ "visualizzazioni",
73
+ "weergaven",
74
+ ],
75
+ "clicks": [
76
+ "clicks",
77
+ "klicks",
78
+ "clics",
79
+ "clic",
80
+ "klikken",
81
+ ],
82
+ "conversions": [
83
+ "conversions",
84
+ "conv.",
85
+ "konversionen",
86
+ "conversiones",
87
+ "conversies",
88
+ ],
89
+ }
90
+
91
+
92
+ def extract_youtube_identifiers(
93
+ placement: str,
94
+ ) -> tuple[str | None, str | None]:
95
+ """Extracts canonical 24-character YouTube Channel ID or handle/video ID.
96
+
97
+ Returns:
98
+ tuple[channel_id, handle_or_video_id]
99
+ """
100
+ if not placement or not isinstance(placement, str):
101
+ return None, None
102
+
103
+ cleaned = placement.strip()
104
+
105
+ # 1. Direct 24-char UC channel ID
106
+ if DIRECT_CHANNEL_ID_REGEX.match(cleaned):
107
+ return cleaned, None
108
+
109
+ # 2. URL containing /channel/UC...
110
+ match_url_ch = URL_CHANNEL_ID_REGEX.search(cleaned)
111
+ if match_url_ch:
112
+ return match_url_ch.group(1), None
113
+
114
+ # 3. Embedded UC regex search anywhere in placement
115
+ match_ch = CHANNEL_ID_REGEX.search(cleaned)
116
+ if match_ch:
117
+ return match_ch.group(0), None
118
+
119
+ # 4. Handle fallback (@name)
120
+ match_handle = URL_HANDLE_REGEX.search(cleaned)
121
+ if match_handle:
122
+ return None, f"@{match_handle.group(1)}"
123
+
124
+ # 5. Video ID fallback
125
+ match_vid = URL_VIDEO_REGEX.search(cleaned)
126
+ if match_vid:
127
+ return None, match_vid.group(1)
128
+
129
+ return None, None
130
+
131
+
132
+ def parse_localized_numeric(val: object) -> float:
133
+ """Parses numeric values supporting European ('1.450,20') and Anglo ('1,450.20') formats."""
134
+ if val is None or pd.isna(val):
135
+ return 0.0
136
+
137
+ if isinstance(val, (int, float)):
138
+ return float(val)
139
+
140
+ s = str(val).strip()
141
+ if not s or s in ("--", "-", "null", "None", "< 10%", "auto"):
142
+ return 0.0
143
+
144
+ # Strip currency signs, quotes and whitespace
145
+ s = re.sub(r"[€$£CHF¥\s%\"']", "", s)
146
+
147
+ # Detect delimiter structure
148
+ # e.g., 1.450,20 (European: dot thousand, comma decimal)
149
+ # vs 1,450.20 (Anglo: comma thousand, dot decimal)
150
+ if "," in s and "." in s:
151
+ last_comma = s.rfind(",")
152
+ last_dot = s.rfind(".")
153
+ if last_comma > last_dot:
154
+ # European: remove dots, change comma to dot
155
+ s = s.replace(".", "").replace(",", ".")
156
+ else:
157
+ # Anglo: remove commas
158
+ s = s.replace(",", "")
159
+ elif "," in s:
160
+ # Could be decimal comma '1450,20' or thousands '1,450'
161
+ parts = s.split(",")
162
+ if len(parts) == 2 and len(parts[1]) in (1, 2, 4): # e.g. currency cents
163
+ s = s.replace(",", ".")
164
+ elif len(parts) == 2 and len(parts[1]) == 3: # thousands like 1,000
165
+ s = s.replace(",", "")
166
+ else:
167
+ s = s.replace(",", "")
168
+
169
+ try:
170
+ return float(s)
171
+ except ValueError:
172
+ return 0.0
173
+
174
+
175
+ def _detect_encoding_and_content(source: str | Path | BinaryIO | TextIO) -> tuple[str, str]:
176
+ """Reads source text detecting UTF-8, UTF-8-SIG, UTF-16LE, or Latin-1 encodings."""
177
+ raw_bytes: bytes
178
+
179
+ if isinstance(source, (str, Path)):
180
+ p = Path(source)
181
+ if not p.exists():
182
+ raise FileNotFoundError(f"Placement report file not found: {source}")
183
+ raw_bytes = p.read_bytes()
184
+ elif hasattr(source, "read"):
185
+ content = source.read()
186
+ if isinstance(content, str):
187
+ return "utf-8", content
188
+ raw_bytes = content
189
+ else:
190
+ raise MalformedPlacementCSVError(f"Unsupported source type: {type(source)}")
191
+
192
+ # Try encodings in order
193
+ for enc in ["utf-8-sig", "utf-8", "utf-16le", "utf-16", "latin-1"]:
194
+ try:
195
+ decoded = raw_bytes.decode(enc)
196
+ return enc, decoded
197
+ except (UnicodeDecodeError, LookupError):
198
+ continue
199
+
200
+ return "latin-1", raw_bytes.decode("latin-1", errors="replace")
201
+
202
+
203
+ def _find_header_row_offset(lines: list[str]) -> tuple[int, str]:
204
+ """Scans the first 15 lines of CSV/TSV to discover header offset and delimiter."""
205
+ for idx, line in enumerate(lines[:15]):
206
+ line_clean = line.strip().lower()
207
+ if not line_clean:
208
+ continue
209
+
210
+ # Check potential delimiters
211
+ for delim in [",", "\t", ";"]:
212
+ tokens = [t.strip().strip('"').strip("'") for t in line_clean.split(delim)]
213
+
214
+ has_placement = any(
215
+ any(alias == t or alias in t for alias in COLUMN_ALIASES["raw_placement"])
216
+ for t in tokens
217
+ )
218
+ has_metric = any(
219
+ any(
220
+ alias == t or alias in t
221
+ for alias in (COLUMN_ALIASES["cost"] + COLUMN_ALIASES["impressions"])
222
+ )
223
+ for t in tokens
224
+ )
225
+
226
+ if has_placement and has_metric:
227
+ return idx, delim
228
+
229
+ raise MalformedPlacementCSVError(
230
+ "Could not detect valid Google Ads or DV360 placement tabular header row within first 15 lines. "
231
+ "Ensure the file includes placement and cost/impression columns."
232
+ )
233
+
234
+
235
+ def load_placement_report(
236
+ path_or_df: str | Path | pd.DataFrame | TextIO | BinaryIO,
237
+ ) -> pd.DataFrame:
238
+ """Auto-detects Google Ads or DV360 CSV header offsets across EN/DE/ES/FR/IT/NL,
239
+ extracts canonical 24-char YouTube Channel IDs, and normalizes spend and metrics.
240
+
241
+ Returns:
242
+ pd.DataFrame with columns:
243
+ - raw_placement: str
244
+ - channel_id: Optional[str] (24-char UC...)
245
+ - handle_or_video_id: Optional[str]
246
+ - channel_title: str
247
+ - placement_type: str
248
+ - impressions: int
249
+ - views: int
250
+ - clicks: int
251
+ - cost: float
252
+ - conversions: float
253
+ - currency_code: str
254
+ """
255
+ if isinstance(path_or_df, pd.DataFrame):
256
+ df_raw = path_or_df.copy()
257
+ else:
258
+ _encoding, text = _detect_encoding_and_content(path_or_df)
259
+ lines = [line for line in text.splitlines() if line.strip()]
260
+ if not lines:
261
+ raise MalformedPlacementCSVError("Placement report is empty.")
262
+
263
+ offset, delim = _find_header_row_offset(lines)
264
+ csv_buffer = io.StringIO("\n".join(lines[offset:]))
265
+ try:
266
+ df_raw = pd.read_csv(csv_buffer, sep=delim, dtype=str, on_bad_lines="skip")
267
+ except Exception as e:
268
+ raise MalformedPlacementCSVError(f"Failed to parse placement CSV: {e}") from e
269
+
270
+ # Map column headers to canonical names (exact match first, then substring fallback)
271
+ matched_cols: dict[str, str] = {}
272
+ normalized_col_map = {str(c).strip().lower(): c for c in df_raw.columns}
273
+
274
+ # Pass 1: Exact matches
275
+ for canonical_name, aliases in COLUMN_ALIASES.items():
276
+ for alias in aliases:
277
+ for norm_c, orig_c in normalized_col_map.items():
278
+ if norm_c == alias and orig_c not in matched_cols.values():
279
+ matched_cols[canonical_name] = orig_c
280
+ break
281
+ if canonical_name in matched_cols:
282
+ break
283
+
284
+ # Pass 2: Substring matches for unmapped columns
285
+ for canonical_name, aliases in COLUMN_ALIASES.items():
286
+ if canonical_name in matched_cols:
287
+ continue
288
+ for alias in aliases:
289
+ for norm_c, orig_c in normalized_col_map.items():
290
+ if alias in norm_c and orig_c not in matched_cols.values() and len(norm_c) < len(alias) + 12:
291
+ matched_cols[canonical_name] = orig_c
292
+ break
293
+ if canonical_name in matched_cols:
294
+ break
295
+
296
+ if "raw_placement" not in matched_cols:
297
+ raise MalformedPlacementCSVError(
298
+ f"Missing required placement column. Detected columns: {list(df_raw.columns)}"
299
+ )
300
+
301
+ # Filter out footer rows (e.g. Total, Gesamt, Summe)
302
+ raw_col = matched_cols["raw_placement"]
303
+ df_filtered = df_raw[df_raw[raw_col].notna()].copy()
304
+ df_filtered[raw_col] = df_filtered[raw_col].astype(str).str.strip()
305
+
306
+ footer_pattern = re.compile(
307
+ r"^(?:total|gesamt|summe|resumen|subtotal|all|account total|campaign total|group total)",
308
+ re.IGNORECASE,
309
+ )
310
+ df_filtered = df_filtered[~df_filtered[raw_col].str.contains(footer_pattern)]
311
+ df_filtered = df_filtered[df_filtered[raw_col] != ""]
312
+
313
+ if df_filtered.empty:
314
+ raise MalformedPlacementCSVError("Report contains no valid placement rows after removing footers.")
315
+
316
+ # Build standardized dataframe
317
+ rows: list[dict] = []
318
+ title_col = matched_cols.get("channel_title")
319
+ cost_col = matched_cols.get("cost")
320
+ impr_col = matched_cols.get("impressions")
321
+ views_col = matched_cols.get("views")
322
+ clicks_col = matched_cols.get("clicks")
323
+ conv_col = matched_cols.get("conversions")
324
+
325
+ for _, row in df_filtered.iterrows():
326
+ raw_val = str(row[raw_col]).strip()
327
+ ch_id, handle_or_vid = extract_youtube_identifiers(raw_val)
328
+
329
+ title_val = ""
330
+ if title_col and pd.notna(row.get(title_col)):
331
+ title_val = str(row[title_col]).strip()
332
+ if not title_val:
333
+ title_val = raw_val
334
+
335
+ cost_val = parse_localized_numeric(row.get(cost_col)) if cost_col else 0.0
336
+ impr_val = round(parse_localized_numeric(row.get(impr_col))) if impr_col else 0
337
+ views_val = round(parse_localized_numeric(row.get(views_col))) if views_col else 0
338
+ clicks_val = round(parse_localized_numeric(row.get(clicks_col))) if clicks_col else 0
339
+ conv_val = parse_localized_numeric(row.get(conv_col)) if conv_col else 0.0
340
+
341
+ rows.append(
342
+ {
343
+ "raw_placement": raw_val,
344
+ "channel_id": ch_id,
345
+ "handle_or_video_id": handle_or_vid,
346
+ "channel_title": title_val,
347
+ "placement_type": "YouTube channel" if (ch_id or "youtube.com" in raw_val) else "Website/App",
348
+ "impressions": impr_val,
349
+ "views": views_val,
350
+ "clicks": clicks_val,
351
+ "cost": round(cost_val, 2),
352
+ "conversions": round(conv_val, 2),
353
+ "currency_code": "EUR",
354
+ }
355
+ )
356
+
357
+ return pd.DataFrame(rows)
358
+
359
+
360
+ def sample_by_impressions(
361
+ df: pd.DataFrame,
362
+ n: int = 100,
363
+ random_state: int | None = 42,
364
+ ) -> pd.DataFrame:
365
+ """Samples n rows proportional to impression volume (prob = impressions / sum(impressions)).
366
+
367
+ Adapted from agency audit methodologies to prioritize high-spend waste channels
368
+ statistically when audit API quotas or processing limits apply.
369
+ """
370
+ if df.empty or len(df) <= n:
371
+ return df.copy()
372
+
373
+ impr_series = df["impressions"].fillna(0).clip(lower=0)
374
+ total_impr = impr_series.sum()
375
+ if total_impr <= 0:
376
+ return df.sample(n=min(n, len(df)), random_state=random_state)
377
+
378
+ weights = impr_series / total_impr
379
+ return df.sample(n=min(n, len(df)), weights=weights, random_state=random_state)
@@ -0,0 +1,206 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ try:
8
+ from mcp.server.fastmcp import FastMCP
9
+ except ModuleNotFoundError:
10
+ from mcp.server.mcpserver import MCPServer as FastMCP # type: ignore[import-not-found,no-redef]
11
+
12
+ import tubesentry
13
+ from tubesentry.contracts.exceptions import ProLicenseError
14
+ from tubesentry.core.heuristics import evaluate_heuristics
15
+ from tubesentry.core.seed_db import lookup_seed_channel
16
+ from tubesentry.io.ingestor import extract_youtube_identifiers
17
+ from tubesentry.pro import bridge
18
+ from tubesentry.pro.bridge import is_pro_available
19
+ from tubesentry.pro.installer import install_pro
20
+
21
+ mcp = FastMCP("TubeSentry YouTube Placement Auditor")
22
+
23
+
24
+ @mcp.tool()
25
+ def audit_placement_report(
26
+ csv_path: str,
27
+ target_languages: list[str] | None = None,
28
+ target_cpa: float | None = None,
29
+ api_key: str | None = None,
30
+ output_dir: str | None = None,
31
+ ad_url: str | None = None,
32
+ ad_text: str | None = None,
33
+ gemini_api_key: str | None = None,
34
+ ) -> dict[str, Any]:
35
+ """Audits a Google Ads ('Where ads showed') or DV360 YouTube placement CSV report for wasted ad spend
36
+ on Made-for-Kids, Passive Music, Underage Gaming, Foreign Script Leakage, and AI Slop channels.
37
+
38
+ If a valid TubeSentry Pro api_key is provided (or installed), automatically writes the 65,000-channel
39
+ Google Ads Editor exclusion CSV and white-label HTML client audit report to output_dir.
40
+
41
+ Optionally pass ad_url or ad_text to profile creative targeting intent with Gemini and correlate
42
+ Expectation vs Reality delivery fit.
43
+ """
44
+ if target_languages is None:
45
+ target_languages = ["de", "en"]
46
+ path = Path(csv_path)
47
+ if not path.exists():
48
+ return {"error": f"CSV file not found at: {csv_path}"}
49
+
50
+ out_exclusions = None
51
+ out_65k = None
52
+ out_html = None
53
+
54
+ effective_key = api_key or os.getenv("TUBESENTRY_API_KEY")
55
+ if output_dir and (is_pro_available() and bridge.tubesentry_pro is not None and effective_key):
56
+ out_p = Path(output_dir)
57
+ out_p.mkdir(parents=True, exist_ok=True)
58
+ out_exclusions = str(out_p / "google_ads_reactive_exclusions.csv")
59
+ out_65k = str(out_p / "google_ads_65k_full_shield.csv")
60
+ out_html = str(out_p / "youtube_waste_audit.html")
61
+
62
+ try:
63
+ report = tubesentry.audit_placements(
64
+ report=csv_path,
65
+ target_languages=target_languages,
66
+ target_cpa=target_cpa,
67
+ api_key=api_key,
68
+ export_exclusions_csv=out_exclusions,
69
+ export_65k_shield_csv=out_65k,
70
+ export_html_deck=out_html,
71
+ print_banner=False,
72
+ ad_url=ad_url,
73
+ ad_text=ad_text,
74
+ gemini_api_key=gemini_api_key,
75
+ )
76
+ return report.model_dump()
77
+ except Exception as e:
78
+ return {"error": str(e)}
79
+
80
+
81
+ @mcp.tool()
82
+ def profile_creative_intent(
83
+ ad_url: str | None = None,
84
+ ad_text: str | None = None,
85
+ gemini_api_key: str | None = None,
86
+ ) -> dict[str, Any]:
87
+ """Analyzes a YouTube video ad URL or creative brief with Gemini to determine the Ideal Customer Profile (ICP),
88
+ recommended YouTube contextual topic entities, and negative anti-persona exclusions.
89
+ """
90
+ try:
91
+ from tubesentry_pro.creative_profiler import profile_ad_creative # type: ignore[import-not-found,import-untyped]
92
+
93
+ profile = profile_ad_creative(
94
+ ad_url=ad_url,
95
+ ad_text=ad_text,
96
+ gemini_api_key=gemini_api_key,
97
+ )
98
+ return profile.model_dump()
99
+ except Exception as e:
100
+ return {"error": str(e)}
101
+
102
+
103
+ @mcp.tool()
104
+ def inspect_youtube_channels(
105
+ channel_ids_or_urls: list[str],
106
+ target_languages: list[str] | None = None,
107
+ api_key: str | None = None,
108
+ ) -> list[dict[str, Any]]:
109
+ """Looks up specific YouTube Channel IDs or URLs in the TubeSentry Intelligence Database
110
+ to check madeForKids status, audio language, topic categories, and waste risk score.
111
+ """
112
+ if target_languages is None:
113
+ target_languages = ["de", "en"]
114
+ results: list[dict[str, Any]] = []
115
+
116
+ # Check if Pro classifier is available
117
+ pro_classifier = None
118
+ if is_pro_available():
119
+ try:
120
+ import tubesentry_pro.classifier as pro_classifier # type: ignore[no-redef]
121
+ except Exception:
122
+ pass
123
+
124
+ for item in channel_ids_or_urls:
125
+ ch_id, _handle = extract_youtube_identifiers(item)
126
+ lookup_id = ch_id or item
127
+
128
+ # Check Seed DB
129
+ seed = lookup_seed_channel(lookup_id) if ch_id else None
130
+ if seed:
131
+ results.append({
132
+ "input": item,
133
+ "channel_id": seed["channel_id"],
134
+ "channel_title": seed["title"],
135
+ "waste_category": seed["category"],
136
+ "waste_confidence": seed["confidence"],
137
+ "reason_summary": seed["reason"],
138
+ "database_source": "seed_db",
139
+ })
140
+ continue
141
+
142
+ # Check Pro registry if available
143
+ if pro_classifier and hasattr(pro_classifier, "lookup_registry"):
144
+ reg_entry = pro_classifier.lookup_registry(lookup_id)
145
+ if reg_entry:
146
+ results.append({
147
+ "input": item,
148
+ "channel_id": reg_entry.get("channel_id", lookup_id),
149
+ "channel_title": reg_entry.get("title", item),
150
+ "waste_category": reg_entry.get("category", "CLEAN"),
151
+ "waste_confidence": reg_entry.get("confidence", 0.95),
152
+ "reason_summary": "Matched in TubeSentry Pro 250k Registry",
153
+ "database_source": "pro_250k_registry",
154
+ })
155
+ continue
156
+
157
+ # Heuristic fallback
158
+ cat, conf, reason = evaluate_heuristics(
159
+ channel_title=item,
160
+ raw_placement=item,
161
+ target_languages=target_languages,
162
+ )
163
+ results.append({
164
+ "input": item,
165
+ "channel_id": ch_id or lookup_id,
166
+ "channel_title": item,
167
+ "waste_category": cat,
168
+ "waste_confidence": conf,
169
+ "reason_summary": reason,
170
+ "database_source": "heuristics",
171
+ })
172
+
173
+ return results
174
+
175
+
176
+ @mcp.tool()
177
+ def activate_tubesentry_pro(api_key: str) -> dict[str, Any]:
178
+ """Validates a Polar.sh TubeSentry Pro license key (TS_PRO_...) and installs the compiled
179
+ tubesentry_pro binary wheel and 250k channel database.
180
+ """
181
+ try:
182
+ success = install_pro(api_key)
183
+ if success:
184
+ return {
185
+ "status": "success",
186
+ "message": "TubeSentry Pro successfully activated and installed.",
187
+ "pro_available": is_pro_available(),
188
+ }
189
+ return {
190
+ "status": "failed",
191
+ "message": "Installation failed without error details.",
192
+ "pro_available": is_pro_available(),
193
+ }
194
+ except ProLicenseError as e:
195
+ return {"status": "license_error", "message": str(e)}
196
+ except Exception as e:
197
+ return {"status": "error", "message": str(e)}
198
+
199
+
200
+ def main() -> None:
201
+ """CLI entrypoint for running the MCP server."""
202
+ mcp.run()
203
+
204
+
205
+ if __name__ == "__main__":
206
+ main()
@@ -0,0 +1,8 @@
1
+ from tubesentry.pro.bridge import dispatch_pro_audit, is_pro_available
2
+ from tubesentry.pro.installer import install_pro
3
+
4
+ __all__ = [
5
+ "dispatch_pro_audit",
6
+ "install_pro",
7
+ "is_pro_available",
8
+ ]
@@ -0,0 +1,77 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from typing import Any
5
+
6
+ import pandas as pd
7
+
8
+ from tubesentry.contracts.exceptions import ProFeatureNotInstalledError, ProLicenseError
9
+ from tubesentry.contracts.schemas import AuditSummaryReport
10
+
11
+ # Attempt dynamic import of compiled tubesentry_pro package
12
+ try:
13
+ import tubesentry_pro # type: ignore[import-not-found,import-untyped]
14
+ HAS_PRO = True
15
+ except ImportError:
16
+ tubesentry_pro = None # type: ignore[assignment]
17
+ HAS_PRO = False
18
+
19
+
20
+ def is_pro_available() -> bool:
21
+ """Returns True if the tubesentry_pro proprietary binary package is installed."""
22
+ return HAS_PRO
23
+
24
+
25
+ def dispatch_pro_audit(
26
+ df: pd.DataFrame,
27
+ target_languages: list[str] | None = None,
28
+ target_cpa: float | None = None,
29
+ api_key: str | None = None,
30
+ youtube_api_key: str | None = None,
31
+ export_exclusions_csv: str | None = None,
32
+ export_65k_shield_csv: str | None = None,
33
+ export_html_deck: str | None = None,
34
+ white_label_config: dict[str, Any] | None = None,
35
+ ad_url: str | None = None,
36
+ ad_text: str | None = None,
37
+ gemini_api_key: str | None = None,
38
+ ) -> AuditSummaryReport:
39
+ """Safely dispatches placement audit to compiled `tubesentry_pro` binary.
40
+
41
+ Raises:
42
+ ProFeatureNotInstalledError: If tubesentry_pro is not installed.
43
+ ProLicenseError: If license validation fails or key is missing.
44
+ """
45
+ if not HAS_PRO or tubesentry_pro is None:
46
+ raise ProFeatureNotInstalledError(
47
+ "🔒 TubeSentry Pro is required to unlock all flagged channels, generate the 65,000-channel "
48
+ "Google Ads Editor exclusion file, batch-enrich unknown channels, and compile the HTML deck.\n"
49
+ "To install the Pro binary:\n"
50
+ " >>> import tubesentry as ts\n"
51
+ " >>> ts.install_pro(api_key='TS_PRO_...')\n"
52
+ "Or run CLI:\n"
53
+ " $ tubesentry auth --key TS_PRO_...\n"
54
+ "Obtain a key at https://buy.polar.sh/polar_cl_lRuifr3uJS0LR0k6frhg3JEKBRZNQq75hv7cS2am9cX"
55
+ )
56
+
57
+ effective_key = api_key or os.getenv("TUBESENTRY_API_KEY", "")
58
+ if not effective_key:
59
+ raise ProLicenseError(
60
+ "🔒 TubeSentry Pro license key required. Pass `api_key='TS_PRO_...'` or set TUBESENTRY_API_KEY.\n"
61
+ "Obtain a key at https://buy.polar.sh/polar_cl_lRuifr3uJS0LR0k6frhg3JEKBRZNQq75hv7cS2am9cX"
62
+ )
63
+
64
+ return tubesentry_pro.audit_placements_pro(
65
+ df=df,
66
+ target_languages=target_languages,
67
+ target_cpa=target_cpa,
68
+ api_key=effective_key,
69
+ youtube_api_key=youtube_api_key,
70
+ export_exclusions_csv=export_exclusions_csv,
71
+ export_65k_shield_csv=export_65k_shield_csv,
72
+ export_html_deck=export_html_deck,
73
+ white_label_config=white_label_config,
74
+ ad_url=ad_url,
75
+ ad_text=ad_text,
76
+ gemini_api_key=gemini_api_key,
77
+ )