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.
- tubesentry/__init__.py +96 -0
- tubesentry/cli.py +180 -0
- tubesentry/contracts/__init__.py +51 -0
- tubesentry/contracts/exceptions.py +21 -0
- tubesentry/contracts/schemas.py +135 -0
- tubesentry/contracts/taxonomy.py +66 -0
- tubesentry/core/__init__.py +22 -0
- tubesentry/core/auditor.py +336 -0
- tubesentry/core/heuristics.py +238 -0
- tubesentry/core/seed_db.py +140 -0
- tubesentry/io/__init__.py +13 -0
- tubesentry/io/fixtures.py +202 -0
- tubesentry/io/ingestor.py +379 -0
- tubesentry/mcp_server.py +206 -0
- tubesentry/pro/__init__.py +8 -0
- tubesentry/pro/bridge.py +77 -0
- tubesentry/pro/installer.py +132 -0
- tubesentry/py.typed +1 -0
- tubesentry-0.1.0.dist-info/METADATA +234 -0
- tubesentry-0.1.0.dist-info/RECORD +23 -0
- tubesentry-0.1.0.dist-info/WHEEL +4 -0
- tubesentry-0.1.0.dist-info/entry_points.txt +3 -0
- tubesentry-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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)
|
tubesentry/mcp_server.py
ADDED
|
@@ -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()
|
tubesentry/pro/bridge.py
ADDED
|
@@ -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
|
+
)
|