Metadata-Version: 2.5
Name: tubesentry
Version: 0.1.0
Summary: Local-First YouTube & Performance Max Placement Waste Auditor & MCP Server
Project-URL: Homepage, https://tubesentry.dev
Project-URL: Documentation, https://tubesentry.dev/docs
Project-URL: Repository, https://github.com/flovv/tubesentry
Project-URL: Changelog, https://github.com/flovv/tubesentry/releases
Author: TubeSentry Core Team
License: MIT
License-File: LICENSE
Keywords: claude-desktop,dv360,google-ads,made-for-kids,mcp-server,model-context-protocol,performance-max,placement-exclusions,youtube-ads
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp<2.0.0,>=1.2.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# TubeSentry 🛡️

**The Agentic-First YouTube & Performance Max Placement Waste Auditor, Creative Targeting Engine & FastMCP Server**

[![CI Tests](https://github.com/flovv/tubesentry/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/flovv/tubesentry/actions/workflows/ci_tests.yml)
[![Docs & GitHub Pages](https://github.com/flovv/tubesentry/actions/workflows/deploy_docs.yml/badge.svg)](https://flovv.github.io/tubesentry/)
[![PyPI version](https://img.shields.io/pypi/v/tubesentry.svg)](https://pypi.org/project/tubesentry/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![MCP Server](https://img.shields.io/badge/MCP-FastMCP-purple.svg)](https://modelcontextprotocol.io/)

---

### [📖 Interactive Documentation & Live Guide](https://flovv.github.io/tubesentry/)

---

## 💡 Why TubeSentry?

When running video campaigns on **Google Ads**, **Performance Max (PMax)**, **Demand Gen**, or **DV360**, algorithmic automated placement expansion routinely wastes **20% to 50%+** of advertising spend on low-intent, accidental, or non-human impressions:

* 👶 **Made-for-Kids & Toddler Brainrot:** CoComelon, Baby Shark, nursery rhymes, and toddler sing-alongs streamed on parent iPads (severe bounce rates and COPPA / GDPR-K regulatory risk).
* 🎧 **Passive Background Audio Streams:** 24/7 Lofi beats, sleep music, rain sounds, and meditation loops with zero active visual attention.
* 🎮 **Underage Minor Gaming Drains:** Roblox, Minecraft, Brawl Stars, and Skibidi Toilet mobile livestreams tapped accidentally by young children.
* 🌍 **Foreign Script Geo-Leakage:** Mismatched Cyrillic, Hindi, Arabic, Thai, or Asian broadcast TV channels consuming spend in local EU/US campaigns.
* 🤖 **AI Slop & Content Farms:** Split-screen Subway Surfers + synthetic voiceover shorts and click arbitrage farms with anomalous CTR and zero conversions.
* 🕳️ **Performance Sinkholes:** Placements burning $>3\times$ target CPA with 0 conversions.
* 🎯 **Creative Intent vs. Delivery Reality Gap:** Even clean channels often deliver far outside your creative brief. TubeSentry includes a **Gemini Creative Profiler** to evaluate your ad video URL or brief, extract your Ideal Customer Profile (ICP), and contrast **Expectation vs. Delivery Reality**.

TubeSentry is **100% local-first and privacy-preserving**: your placement CSV reports never leave your machine.

---

## ⚡ Quickstart

### Installation

```bash
pip install tubesentry
```

### 1. Test Drive with 25,000 Synthetic Placements

Generate a realistic 25,000-row Google Ads placement report and run an instant audit diagnostic:

```bash
tubesentry demo --out-dir ./demo_youtube
```

### 2. Audit Your Google Ads / DV360 Placement Report

Export your placement report from Google Ads (*Reports $\rightarrow$ Predefined reports $\rightarrow$ Other $\rightarrow$ Where ads showed $\rightarrow$ Download `.csv`*) or DV360 and run:

```bash
tubesentry audit where_ads_showed.csv --lang de,en --cpa 45.0
```

### 3. Profile Creative Targeting Fit (Gemini Multimodal)

Pass your YouTube Ad URL or creative brief to compare your campaign intent against algorithmic delivery:

```bash
tubesentry audit where_ads_showed.csv \
  --ad-url "https://youtube.com/watch?v=your_ad_video" \
  --ad-text "B2B enterprise cloud security platform for CISOs and DevSecOps teams" \
  --html audit_deck.html
```

---

## 🐍 Python SDK API

TubeSentry seamlessly auto-detects multi-language CSV exports (**English, German, Spanish, French, Italian, Dutch**):

```python
import tubesentry as ts

# Run instant placement audit
report = ts.audit_placements(
    report="where_ads_showed.csv",
    target_languages=["de", "en"],
    target_cpa=40.0,
    ad_url="https://youtube.com/watch?v=demo_video",
    ad_text="Enterprise Kubernetes automation for DevOps and SRE teams.",
)

print(f"Audited Spend:   €{report.total_spend:,.2f}")
print(f"Wasted Spend:    €{report.total_wasted_spend:,.2f} ({report.wasted_spend_percentage:.1f}%)")
print(f"Quality Score:   {report.weighted_quality_score:.1f} / 10.0")

if report.creative_alignment:
    print(f"Targeting Fit:   {report.creative_alignment.overall_alignment_score:.1f} / 10.0")
    print(f"Off-Target Bleed: €{report.creative_alignment.off_target_spend:,.2f}")
```

---

## 🤖 Claude Desktop, Claude Code & Cursor MCP Server

TubeSentry includes a native **Model Context Protocol (FastMCP)** server. AI coding assistants and chat environments can audit placements and inspect channels directly in natural language.

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tubesentry": {
      "command": "tubesentry-mcp"
    }
  }
}
```

Or run without installation via `uvx`:

```json
{
  "mcpServers": {
    "tubesentry": {
      "command": "uvx",
      "args": ["--from", "tubesentry", "tubesentry-mcp"]
    }
  }
}
```

### Cursor IDE Configuration

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tubesentry": {
      "command": "tubesentry-mcp"
    }
  }
}
```

### Example Natural Language Prompts
* *"Audit my Google Ads placement report at `~/Downloads/pmax_october.csv` for toddler brainrot and passive music streams."*
* *"Profile this YouTube video ad URL with Gemini: `https://youtube.com/watch?v=...` and tell me what contextual topics and negative exclusions to set in Google Ads."*
* *"Inspect these 5 YouTube channels for COPPA and background audio risk: `UCbCmjCuTUZos6Inko4u57UQ`, `UCSJ4gkVC6NrvII8umztf0Ow`."*

---

## 📊 Open-Core vs. TubeSentry Pro

| Feature | Open-Core `tubesentry` (Free) | `tubesentry_pro` (Licensed) |
| :--- | :---: | :---: |
| **Exact Category Spend & % Waste Breakdown** | ✅ Full Visibility | ✅ Full Visibility |
| **Impression-Weighted Quality Score (1–10)** | ✅ Included | ✅ Included |
| **Top 25 Worst Offender Channels** | ✅ Unmasked | ✅ Unmasked |
| **Tail Offender Channels ($c_{26} \dots c_M$)** | 🔒 Masked (`UC••••••••••••`) | ✅ 100% Unmasked |
| **Bundled Waste Seed Dictionary** | 2,500 Notorious Channels | **250,000 Pre-Classified Registry** |
| **Long-Tail Unknown Channel Enrichment** | Regex Heuristics | **Async 50-ID Batch YouTube API v3 Resolver** |
| **Google Ads 65,000 Exclusion Shield CSV** | ❌ | ✅ 1-Click Ready (`google_ads_65k_full_shield.csv`) |
| **DV360 SDF Exclusion Chunks** | ❌ | ✅ 10,000-Row SDF Blocks |
| **Gemini Creative Targeting Fit Engine** | ✅ Core Matching | ✅ Multimodal Deep Profiler |
| **CFO / Client Brand-Safety HTML Audit Deck** | ❌ | ✅ White-Label Interactive Chart.js Deck |

---

## 🔑 Activating TubeSentry Pro

Obtain an instant Single Audit Pass (€199) or Agency Unlimited Key via [Polar Checkout](https://buy.polar.sh/polar_cl_lRuifr3uJS0LR0k6frhg3JEKBRZNQq75hv7cS2am9cX):

[![Buy TubeSentry Pro on Polar](https://img.shields.io/badge/Polar.sh-Buy%20TubeSentry%20Pro-0062FF?style=for-the-badge&logo=polar&logoColor=white)](https://buy.polar.sh/polar_cl_lRuifr3uJS0LR0k6frhg3JEKBRZNQq75hv7cS2am9cX)

```bash
tubesentry auth --key TS_PRO_YOUR_POLAR_KEY
```

Or via Python:

```python
import tubesentry as ts
ts.install_pro(api_key="TS_PRO_...")
```

---

## 🛡️ Privacy & Security Guarantee

* **Local-First:** All CSV ingestion, regex scoring, and database lookups run 100% locally on your machine.
* **Zero Cloud Ingestion:** Your clients' placement data, budgets, and impressions are never uploaded to any third-party server.
* **Serverless Architecture:** 0€ infrastructure overhead.

---

## 📜 License

MIT License. See [LICENSE](LICENSE) for details.
