tubesentry 0.1.0__tar.gz

tubesentry-0.1.0/.github/workflows/ci_tests.yml

@@ -0,0 +1,41 @@
+name: CI Test Suite & Code Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with Ruff
+        run: |
+          ruff check tubesentry tests
+
+      - name: Type Check with Mypy
+        run: |
+          mypy tubesentry
+        continue-on-error: true
+
+      - name: Run Pytest with Coverage
+        run: |
+          pytest -v --tb=short --cov=tubesentry --cov-report=term-missing tests/

tubesentry-0.1.0/.github/workflows/deploy_docs.yml

@@ -0,0 +1,57 @@
+name: Deploy VitePress Documentation & WASM Dropzone
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy_docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies & Build
+        run: |
+          npm install -D vitepress
+          npx vitepress build docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

tubesentry-0.1.0/.github/workflows/publish_pypi.yml

@@ -0,0 +1,33 @@
+name: Publish tubesentry to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

tubesentry-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+demo_youtube/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/

tubesentry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TubeSentry Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tubesentry-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+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.

tubesentry-0.1.0/README.md

@@ -0,0 +1,196 @@
+# 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.

tubesentry-0.1.0/docs/.vitepress/config.mjs

@@ -0,0 +1,58 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: "TubeSentry",
+  description: "Agentic-First YouTube & Performance Max Placement Waste Auditor & MCP Server",
+  base: "/tubesentry/",
+  head: [
+    ['link', { rel: 'icon', href: '/tubesentry/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#0284c7' }]
+  ],
+  themeConfig: {
+    logo: '🛡️',
+    siteTitle: 'TubeSentry',
+    nav: [
+      { text: 'Guide', link: '/guide/quickstart' },
+      { text: 'Creative Profiler', link: '/guide/creative-profiler' },
+      { text: 'MCP Server', link: '/guide/mcp-server' },
+      { text: 'CLI Reference', link: '/guide/cli' },
+      { text: 'TubeSentry Pro', link: '/guide/pro' },
+      { text: 'Buy Pro ↗', link: 'https://buy.polar.sh/polar_cl_lRuifr3uJS0LR0k6frhg3JEKBRZNQq75hv7cS2am9cX' },
+      { text: 'GitHub', link: 'https://github.com/flovv/tubesentry' }
+    ],
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Overview', link: '/guide/quickstart' },
+          { text: 'Waste Categories', link: '/guide/waste-categories' }
+        ]
+      },
+      {
+        text: 'Core Features',
+        items: [
+          { text: 'Creative Targeting Fit (Gemini)', link: '/guide/creative-profiler' },
+          { text: 'Claude & Cursor MCP Server', link: '/guide/mcp-server' },
+          { text: 'CLI Reference', link: '/guide/cli' },
+          { text: 'Python SDK', link: '/guide/python-sdk' }
+        ]
+      },
+      {
+        text: 'Commercial Edition',
+        items: [
+          { text: 'TubeSentry Pro & 65k Shield', link: '/guide/pro' }
+        ]
+      }
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/flovv/tubesentry' }
+    ],
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2026 TubeSentry Core Contributors'
+    },
+    search: {
+      provider: 'local'
+    }
+  }
+})

tubesentry-0.1.0/docs/audit.md

@@ -0,0 +1,14 @@
+# Zero-Upload Browser WASM Auditor (`tubesentry.dev/audit`)
+
+For agency media buyers and PPC analysts on restricted corporate laptops where terminal or Python access is locked down, **TubeSentry** provides a 100% client-side WebAssembly auditor powered by Pyodide and DuckDB-WASM.
+
+## Privacy Guarantee: 100% Local Execution
+* **Zero Cloud Upload:** Your Google Ads / DV360 CSV never leaves your browser sandbox.
+* **No Server Storage:** Client data and financial spend figures are processed locally in memory.
+* **Instant Processing:** Parses and audits 50,000 placements in $<200\text{ms}$.
+
+## Workflow
+1. Drag and drop your Google Ads *"Where ads showed"* CSV export into the dropzone.
+2. The WebAssembly engine scans the file, matches channels against the embedded intelligence database, and renders an instant interactive spend waterfall.
+3. Review your Top 25 worst offending channels and total wasted spend breakdown.
+4. Enter your TubeSentry Pro license key to unlock the 65,000-channel Google Ads Editor exclusion CSV and white-label client pitch deck.