tubesentry 0.1.0__py3-none-any.whl

tubesentry/__init__.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from tubesentry.contracts.schemas import AuditSummaryReport
+from tubesentry.core.auditor import run_free_audit
+from tubesentry.io.ingestor import load_placement_report
+from tubesentry.pro import bridge
+from tubesentry.pro.bridge import dispatch_pro_audit, is_pro_available
+from tubesentry.pro.installer import install_pro
+
+__version__ = "0.1.0"
+
+
+def audit_placements(
+    report: str | Path | pd.DataFrame,
+    target_languages: list[str] | None = None,
+    target_cpa: float | None = None,
+    api_key: str | None = None,
+    youtube_api_key: str | None = None,
+    export_exclusions_csv: str | None = None,
+    export_65k_shield_csv: str | None = None,
+    export_html_deck: str | None = None,
+    white_label_config: dict[str, Any] | None = None,
+    print_banner: bool = True,
+    ad_url: str | None = None,
+    ad_text: str | None = None,
+    gemini_api_key: str | None = None,
+) -> AuditSummaryReport:
+    """Audits Google Ads ('Where ads showed') or DV360 YouTube placement reports for ad waste.
+
+    - Free Mode (default): Computes exact waste totals across all 6 categories,
+      unmasks the Top 25 worst offending channels, and prints the diagnostic banner.
+    - Pro Mode (with valid `api_key` and `tubesentry_pro` installed): Uses the 250k
+      channel intelligence registry, 50-ID batch API enrichment, unmasks all channels,
+      evaluates Gemini creative targeting fit, and exports Google Ads Editor exclusion files & white-label HTML deck.
+    """
+    langs = target_languages or ["de", "en"]
+    df = load_placement_report(report) if not isinstance(report, pd.DataFrame) else report
+
+    effective_key = api_key or os.getenv("TUBESENTRY_API_KEY")
+
+    # If Pro is available and a license key is provided (or Pro exports requested)
+    if is_pro_available() and bridge.tubesentry_pro is not None and effective_key:
+        return dispatch_pro_audit(
+            df=df,
+            target_languages=langs,
+            target_cpa=target_cpa,
+            api_key=effective_key,
+            youtube_api_key=youtube_api_key,
+            export_exclusions_csv=export_exclusions_csv,
+            export_65k_shield_csv=export_65k_shield_csv,
+            export_html_deck=export_html_deck,
+            white_label_config=white_label_config,
+            ad_url=ad_url,
+            ad_text=ad_text,
+            gemini_api_key=gemini_api_key,
+        )
+
+    # If caller specifically requested Pro exports without Pro/license, route through dispatcher to surface upgrade error
+    if export_exclusions_csv or export_65k_shield_csv or export_html_deck or ad_url or ad_text:
+        return dispatch_pro_audit(
+            df=df,
+            target_languages=langs,
+            target_cpa=target_cpa,
+            api_key=effective_key,
+            youtube_api_key=youtube_api_key,
+            export_exclusions_csv=export_exclusions_csv,
+            export_65k_shield_csv=export_65k_shield_csv,
+            export_html_deck=export_html_deck,
+            white_label_config=white_label_config,
+            ad_url=ad_url,
+            ad_text=ad_text,
+            gemini_api_key=gemini_api_key,
+        )
+
+    return run_free_audit(
+        df=df,
+        target_languages=langs,
+        target_cpa=target_cpa,
+        print_banner=print_banner,
+    )
+
+
+__all__ = [
+    "AuditSummaryReport",
+    "__version__",
+    "audit_placements",
+    "install_pro",
+    "is_pro_available",
+    "load_placement_report",
+]

tubesentry/cli.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+import tubesentry
+from tubesentry.contracts.exceptions import ProLicenseError
+from tubesentry.io.fixtures import generate_synthetic_placement_csv
+from tubesentry.pro.installer import install_pro
+
+app = typer.Typer(
+    name="tubesentry",
+    help="TubeSentry — Local-First YouTube & PMax Ad Placement Waste Auditor & MCP Server",
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.command()
+def demo(
+    out_dir: Path = typer.Option(
+        Path("./demo_youtube"),
+        "--out-dir",
+        "-o",
+        help="Directory to save the generated synthetic placement CSV report.",
+    ),
+    rows: int = typer.Option(
+        25000,
+        "--rows",
+        "-n",
+        help="Number of synthetic placement rows to generate.",
+    ),
+    lang: str = typer.Option(
+        "de",
+        "--lang",
+        "-l",
+        help="Localized number and text formatting ('de' or 'en').",
+    ),
+) -> None:
+    """Generates a realistic 25,000-row Google Ads PMax/YouTube placement CSV and runs an immediate audit."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    csv_file = out_dir / "google_ads_where_ads_showed_sample.csv"
+
+    console.print(
+        f"[bold blue][*] Generating {rows:,} synthetic Google Ads placement rows...[/bold blue]"
+    )
+    generate_synthetic_placement_csv(
+        output_path=csv_file,
+        num_rows=rows,
+        language=lang,
+    )
+    console.print(f"[bold green][OK] Saved synthetic report to:[/bold green] {csv_file}")
+    console.print("[bold yellow][*] Running immediate TubeSentry diagnostic pass...[/bold yellow]\n")
+
+    tubesentry.audit_placements(
+        report=csv_file,
+        target_languages=["de", "en"] if lang == "de" else ["en"],
+        print_banner=True,
+    )
+
+
+@app.command()
+def audit(
+    report_csv: Path = typer.Argument(
+        ...,
+        help="Path to Google Ads or DV360 placement CSV/TSV export file.",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    lang: str = typer.Option(
+        "de,en",
+        "--lang",
+        "-l",
+        help="Comma-separated target languages for geotargeting verification (e.g. 'de,en').",
+    ),
+    cpa: float | None = typer.Option(
+        None,
+        "--cpa",
+        help="Target CPA in account currency to evaluate Performance Sinkhole bleed.",
+    ),
+    key: str | None = typer.Option(
+        None,
+        "--key",
+        "-k",
+        help="TubeSentry Pro Polar.sh API key (or set TUBESENTRY_API_KEY).",
+    ),
+    out_exclusions: Path | None = typer.Option(
+        None,
+        "--out-exclusions",
+        help="Path to export reactive Google Ads Editor exclusion CSV (Pro feature).",
+    ),
+    out_65k: Path | None = typer.Option(
+        None,
+        "--out-65k",
+        help="Path to export full 65,000-channel protection shield CSV (Pro feature).",
+    ),
+    html: Path | None = typer.Option(
+        None,
+        "--html",
+        help="Path to export interactive white-label HTML audit deck (Pro feature).",
+    ),
+    ad_url: str | None = typer.Option(
+        None,
+        "--ad-url",
+        help="YouTube Ad video URL or creative link to profile targeting fit using Gemini.",
+    ),
+    ad_text: str | None = typer.Option(
+        None,
+        "--ad-text",
+        help="Ad copy, transcript, or campaign brief to profile ICP intent.",
+    ),
+) -> None:
+    """Audits a Google Ads or DV360 YouTube placement report for wasted ad spend."""
+    target_languages = [s.strip().lower() for s in lang.split(",") if s.strip()]
+
+    try:
+        tubesentry.audit_placements(
+            report=report_csv,
+            target_languages=target_languages,
+            target_cpa=cpa,
+            api_key=key,
+            export_exclusions_csv=str(out_exclusions) if out_exclusions else None,
+            export_65k_shield_csv=str(out_65k) if out_65k else None,
+            export_html_deck=str(html) if html else None,
+            print_banner=True,
+            ad_url=ad_url,
+            ad_text=ad_text,
+        )
+    except Exception as e:
+        err_console.print(f"[bold red]Audit error:[/bold red] {e}")
+        raise typer.Exit(code=1) from e
+
+
+@app.command()
+def mcp() -> None:
+    """Starts the FastMCP stdio server for Claude Desktop, Claude Code, and Cursor."""
+    from tubesentry.mcp_server import main as run_mcp
+
+    run_mcp()
+
+
+@app.command()
+def auth(
+    key: str | None = typer.Option(
+        None,
+        "--key",
+        "-k",
+        help="TubeSentry Pro license key from Polar.sh (e.g. 'TS_PRO_...').",
+    ),
+) -> None:
+    """Validates a Polar.sh license key and installs/activates TubeSentry Pro."""
+    license_key = key
+    if not license_key:
+        license_key = typer.prompt("TubeSentry Pro license key", hide_input=True)
+
+    console.print("[bold blue][*] Validating license key with Polar.sh...[/bold blue]")
+    try:
+        success = install_pro(license_key)
+        if success:
+            console.print(
+                "[bold green][OK] License validated successfully! TubeSentry Pro is active.[/bold green]"
+            )
+        else:
+            console.print("[bold red][FAIL] Installation failed.[/bold red]")
+            raise typer.Exit(code=1)
+    except ProLicenseError as e:
+        console.print(f"[bold red][FAIL] License validation error:[/bold red] {e}")
+        raise typer.Exit(code=1) from e
+    except Exception as e:
+        console.print(f"[bold red][FAIL] Error installing Pro extension:[/bold red] {e}")
+        raise typer.Exit(code=1) from e
+
+
+if __name__ == "__main__":
+    app()

tubesentry/contracts/__init__.py

@@ -0,0 +1,51 @@
+from tubesentry.contracts.exceptions import (
+    MalformedPlacementCSVError,
+    ProFeatureNotInstalledError,
+    ProLicenseError,
+    QuotaExceededError,
+    TubeSentryError,
+)
+from tubesentry.contracts.schemas import (
+    AuditSummaryReport,
+    ClassifiedChannelRecord,
+    StandardizedPlacementRow,
+    WasteCategoryBreakdown,
+    WasteCategoryType,
+)
+from tubesentry.contracts.taxonomy import (
+    BITMASK_ANIMATION,
+    BITMASK_EDUCATION,
+    BITMASK_ENTERTAINMENT,
+    BITMASK_GAMING,
+    BITMASK_KIDS,
+    BITMASK_LIFESTYLE,
+    BITMASK_MUSIC,
+    BITMASK_NEWS,
+    CATEGORY_DESCRIPTIONS,
+    FREEBASE_TOPIC_MAPPINGS,
+    WasteCategory,
+)
+
+__all__ = [
+    "BITMASK_ANIMATION",
+    "BITMASK_EDUCATION",
+    "BITMASK_ENTERTAINMENT",
+    "BITMASK_GAMING",
+    "BITMASK_KIDS",
+    "BITMASK_LIFESTYLE",
+    "BITMASK_MUSIC",
+    "BITMASK_NEWS",
+    "CATEGORY_DESCRIPTIONS",
+    "FREEBASE_TOPIC_MAPPINGS",
+    "AuditSummaryReport",
+    "ClassifiedChannelRecord",
+    "MalformedPlacementCSVError",
+    "ProFeatureNotInstalledError",
+    "ProLicenseError",
+    "QuotaExceededError",
+    "StandardizedPlacementRow",
+    "TubeSentryError",
+    "WasteCategory",
+    "WasteCategoryBreakdown",
+    "WasteCategoryType",
+]

tubesentry/contracts/exceptions.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+class TubeSentryError(Exception):
+    """Base exception for all TubeSentry errors."""
+
+
+class MalformedPlacementCSVError(TubeSentryError):
+    """Raised when an uploaded placement report CSV/TSV has invalid structure or missing columns."""
+
+
+class QuotaExceededError(TubeSentryError):
+    """Raised when YouTube Data API v3 daily quota limit is reached."""
+
+
+class ProFeatureNotInstalledError(TubeSentryError):
+    """Raised when a Pro feature is accessed without `tubesentry_pro` installed."""
+
+
+class ProLicenseError(TubeSentryError):
+    """Raised when Polar.sh license validation fails or license key is revoked/missing."""

tubesentry/contracts/schemas.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+WasteCategoryType = Literal[
+    "CLEAN",
+    "MADE_FOR_KIDS",
+    "PASSIVE_AUDIO_MUSIC",
+    "LOW_AGE_GAMING",
+    "FOREIGN_SCRIPT_LEAK",
+    "AI_SLOP_CLICK_FARM",
+    "PERFORMANCE_SINKHOLE",
+]
+
+
+class StandardizedPlacementRow(BaseModel):
+    """Normalized row extracted from Google Ads or DV360 placement report."""
+    raw_placement: str = Field(..., description="Original placement URL or string from CSV")
+    channel_id: str | None = Field(default=None, pattern=r"^UC[a-zA-Z0-9_-]{22}$")
+    handle_or_video_id: str | None = Field(default=None)
+    channel_title: str | None = Field(default=None)
+    placement_type: str = Field(default="YouTube channel")
+    impressions: int = Field(default=0, ge=0)
+    views: int = Field(default=0, ge=0)
+    clicks: int = Field(default=0, ge=0)
+    cost: float = Field(default=0.0, ge=0.0)
+    conversions: float = Field(default=0.0, ge=0.0)
+    currency_code: str = Field(default="EUR")
+
+
+class ClassifiedChannelRecord(BaseModel):
+    """Enriched and scored YouTube channel record."""
+    channel_id: str
+    channel_title: str
+    waste_category: WasteCategoryType
+    waste_confidence: float = Field(..., ge=0.0, le=1.0)
+    made_for_kids_official: bool = False
+    is_young_kids: bool = False
+    granular_sub_category: str | None = None
+    thumbnail_url: str | None = None
+    detected_language: str | None = None
+    detected_country: str | None = None
+    topic_categories: list[str] = Field(default_factory=list)
+    cost: float
+    impressions: int
+    views: int
+    clicks: int
+    conversions: float
+    reason_summary: str
+    is_masked: bool = False
+
+
+class WasteCategoryBreakdown(BaseModel):
+    """Spend and channel count summary for an individual waste category."""
+    category: WasteCategoryType
+    wasted_spend: float = 0.0
+    wasted_spend_percentage: float = 0.0
+    channel_count: int = 0
+    impressions: int = 0
+    views: int = 0
+    clicks: int = 0
+    conversions: float = 0.0
+    description: str = ""
+
+
+class CreativeTargetingProfile(BaseModel):
+    """Ideal targeting persona and contextual boundaries extracted from an ad creative."""
+    ad_url: str | None = None
+    ad_title: str | None = None
+    brand_or_product: str = "Advertiser Campaign"
+    target_persona: str = Field(..., description="Target audience / Ideal Customer Profile (ICP)")
+    target_intent: str = Field(default="", description="Core value proposition and intent")
+    recommended_contextual_topics: list[str] = Field(
+        default_factory=list,
+        description="Ideal YouTube topic/category entities (e.g. Cloud computing, Enterprise software)",
+    )
+    negative_anti_personas: list[str] = Field(
+        default_factory=list,
+        description="Incompatible audiences/categories (e.g. Children, Toddlers, Gaming, Passive Audio)",
+    )
+    recommended_languages: list[str] = Field(default_factory=lambda: ["en", "de"])
+    profiling_source: str = "gemini"  # 'gemini' | 'heuristic' | 'brief'
+    summary: str = ""
+
+
+class ExpectationVsRealityItem(BaseModel):
+    """Individual dimension contrast comparing creative intent against actual delivery."""
+    dimension: str
+    creative_expectation: str
+    delivery_reality: str
+    alignment_status: Literal["ON_TARGET", "NEUTRAL", "MISALIGNED", "CRITICAL_WASTE"]
+
+
+class CreativeAlignmentSummary(BaseModel):
+    """Comparison of creative targeting expectations vs actual ad placement delivery."""
+    profile: CreativeTargetingProfile
+    overall_alignment_score: float = Field(..., ge=0.0, le=10.0, description="1-10 alignment score")
+    alignment_verdict: str = Field(..., description="High-level narrative verdict")
+    on_target_spend: float = 0.0
+    on_target_percentage: float = 0.0
+    off_target_spend: float = 0.0
+    off_target_percentage: float = 0.0
+    neutral_spend: float = 0.0
+    neutral_percentage: float = 0.0
+    top_misaligned_channels: list[dict[str, Any]] = Field(default_factory=list)
+    expectation_vs_reality: list[ExpectationVsRealityItem] = Field(default_factory=list)
+    strategic_recommendations: list[str] = Field(default_factory=list)
+
+
+class AuditSummaryReport(BaseModel):
+    """Comprehensive executive audit report generated from placement analysis."""
+    total_placements_audited: int
+    total_spend: float
+    total_wasted_spend: float
+    wasted_spend_percentage: float
+    total_waste_channels: int
+    total_impressions_audited: int = 0
+    total_wasted_impressions: int = 0
+    wasted_impressions_percentage: float = 0.0
+    weighted_quality_score: float = 10.0
+    top_topic_categories: list[dict[str, Any]] = Field(default_factory=list)
+    currency_code: str = "EUR"
+    category_breakdowns: dict[str, WasteCategoryBreakdown]
+    top_offenders: list[ClassifiedChannelRecord]
+    masked_offenders_count: int = 0
+    is_pro_audit: bool = False
+    coppa_kids_risk_spend: float = 0.0
+    annualized_recoverable_runrate: float = 0.0
+    exclusions_csv_path: str | None = None
+    shield_65k_csv_path: str | None = None
+    html_report_path: str | None = None
+    upgrade_prompt: str | None = None
+    creative_alignment: CreativeAlignmentSummary | None = None

tubesentry/contracts/taxonomy.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WasteCategory(str, Enum):
+    """Canonical 6-Vector Waste Taxonomy for YouTube Placement Audits."""
+    CLEAN = "CLEAN"
+    MADE_FOR_KIDS = "MADE_FOR_KIDS"
+    PASSIVE_AUDIO_MUSIC = "PASSIVE_AUDIO_MUSIC"
+    LOW_AGE_GAMING = "LOW_AGE_GAMING"
+    FOREIGN_SCRIPT_LEAK = "FOREIGN_SCRIPT_LEAK"
+    AI_SLOP_CLICK_FARM = "AI_SLOP_CLICK_FARM"
+    PERFORMANCE_SINKHOLE = "PERFORMANCE_SINKHOLE"
+
+
+# Freebase topic IDs and Wikipedia ontology mappings from YouTube Data API v3
+FREEBASE_TOPIC_MAPPINGS = {
+    # Music topics
+    "/m/04rlf": "Music",
+    "/m/02mscn": "Christian music",
+    "/m/0ggq0m": "Classical music",
+    "/m/01lyv": "Country",
+    "/m/02lkt": "Electronic music",
+    "/m/0g293": "Music of Latin America",
+    "/m/064t9": "Pop music",
+    "/m/06cq9": "Reggae",
+    "/m/06j6l": "Rhythm and blues",
+    "/m/06by7": "Rock music",
+    "/m/0gywn": "Soul music",
+    "/m/0zdp4": "Hip hop music",
+    # Gaming topics
+    "/m/0bzvm2": "Gaming",
+    "/m/025zzc": "Action game",
+    "/m/02ntfj": "Action-adventure game",
+    "/m/0b1vjn": "Casual game",
+    "/m/0403hg": "Role-playing video game",
+    "/m/02hygl": "Simulation video game",
+    "/m/04q1x3q": "Sports game",
+    "/m/01sjng": "Strategy video game",
+    # Children & Animation topics
+    "/m/0164x2": "Children's music",
+    "/m/03k3r": "Animated cartoon",
+    "/m/019_rr": "Lifestyle",
+    "/m/028sqc": "Music of Asia",
+}
+
+# Bitmask constants for compressed 250k registry
+BITMASK_MUSIC = 1 << 0
+BITMASK_GAMING = 1 << 1
+BITMASK_KIDS = 1 << 2
+BITMASK_ANIMATION = 1 << 3
+BITMASK_ENTERTAINMENT = 1 << 4
+BITMASK_EDUCATION = 1 << 5
+BITMASK_NEWS = 1 << 6
+BITMASK_LIFESTYLE = 1 << 7
+
+CATEGORY_DESCRIPTIONS: dict[WasteCategory, str] = {
+    WasteCategory.CLEAN: "Verified clean audience placement with standard engagement.",
+    WasteCategory.MADE_FOR_KIDS: "Toddler & COPPA nursery rhymes, unboxing, cartoons, and child-directed channels.",
+    WasteCategory.PASSIVE_AUDIO_MUSIC: "Background audio, lofi beats, sleep music, rain noise, and zero-attention streams.",
+    WasteCategory.LOW_AGE_GAMING: "Underage gameplay (Roblox, Minecraft, Brawl Stars, Skibidi, Gacha) with accidental child taps.",
+    WasteCategory.FOREIGN_SCRIPT_LEAK: "Foreign language and non-Latin script leakage mismatched with campaign geotargeting.",
+    WasteCategory.AI_SLOP_CLICK_FARM: "High-frequency synthetic AI content farms, faceless TTS shorts, and click arbitrage.",
+    WasteCategory.PERFORMANCE_SINKHOLE: "Empirical budget bleed placements exceeding 3x Target CPA with zero conversions.",
+}

tubesentry/core/__init__.py

@@ -0,0 +1,22 @@
+from tubesentry.core.auditor import run_free_audit
+from tubesentry.core.heuristics import (
+    compute_non_latin_ratio,
+    evaluate_heuristics,
+    is_ai_slop_text,
+    is_low_age_gaming_text,
+    is_made_for_kids_text,
+    is_passive_music_text,
+)
+from tubesentry.core.seed_db import SEED_CHANNELS, lookup_seed_channel
+
+__all__ = [
+    "SEED_CHANNELS",
+    "compute_non_latin_ratio",
+    "evaluate_heuristics",
+    "is_ai_slop_text",
+    "is_low_age_gaming_text",
+    "is_made_for_kids_text",
+    "is_passive_music_text",
+    "lookup_seed_channel",
+    "run_free_audit",
+]