thoughtleaders-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/.gitignore

@@ -6,4 +6,6 @@ dist/
 build/
 .pytest_cache/
 .ruff_cache/
-.vscode/
+.vscode/
+env
+.claude/settings.local.json

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/AGENTS.md

@@ -53,7 +53,7 @@ This repo is also a Claude Code plugin, and can directly be installed as one.
 
 - **`tl`** — the main skill for querying ThoughtLeaders data. Default for any sponsorship / channel / brand / upload / report question.
 - **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. Returns `{operator, keywords:[{keyword,count}]}` from a ranked ES probe over `title` / `summary` / `transcript`; the caller then runs the actual content search with the surviving high-count terms. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
-- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`** — narrower workflows; the skill files document their own triggers.
+- **`tl-import`**, **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`**, **`tl-top-partnerships`** — narrower workflows; the skill files document their own triggers. `tl-top-partnerships` is brand-user-facing: ranks a brand's sold sponsorships by live eCPM vs the sold-date projection and delivers a two-tab Google Sheet via `gws`.
 
 ### Skill content boundaries
 

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.0
+Version: 0.7.2
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -68,7 +68,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [duckdb](https://duckdb.org/)
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
-For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
+For automated installs on MacOS, prefer installing Python and the requirements on Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv`.
 
 ## Install
 
@@ -280,6 +280,7 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
+- **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
 ## Output Formats
 

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/README.md

@@ -40,7 +40,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [duckdb](https://duckdb.org/)
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
-For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
+For automated installs on MacOS, prefer installing Python and the requirements on Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv`.
 
 ## Install
 
@@ -252,6 +252,7 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
+- **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
 ## Output Formats
 

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/agents/youtube-comment-classifier.md

@@ -2,7 +2,7 @@
 name: youtube-comment-classifier
 description: >
   Classifies a batch of YouTube comments as organic vs bot/spam/template for
-  the channel-authenticity skill's fake-engagement detection. Use when you
+  the tl-channel-authenticity skill's fake-engagement detection. Use when you
   have a JSON array of scraped comments and need a fast, cheap per-comment
   authenticity judgment. Returns strict JSON only.
 model: haiku
@@ -14,7 +14,7 @@ color: yellow
 
 You judge whether YouTube comments come from a real, engaged human audience or
 from engagement padding (bots, comment farms, generic filler). You are used by
-the `channel-authenticity` skill to vet channels before ThoughtLeaders books a
+the `tl-channel-authenticity` skill to vet channels before ThoughtLeaders books a
 paid sponsorship, so false "organic" verdicts cost real money — be skeptical.
 
 ## Input

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.7.0"
+version = "0.7.2"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/skills/tl/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tl
+tl-blurb: data analyst (smart query router)
 description: |
   Query and analyze YouTube sponsorship data using the `tl` CLI. Use this skill for finding channels, brands and sponsorships, and for data exploration, including counts, metrics, trends, time-series, distributions, single-record drill-downs, revenue / pipeline-weighting math, view-curve analysis, cross-source business questions. Examples: "How many deals did we close last quarter?", "What's the weighted pipeline by sales owner?", "Show me the view curve for video X", "Find mentions of Surfshark in transcripts", "Investigate this video", "Find channels...", "Find brands...".
 ---
@@ -433,6 +434,8 @@ If unsure about what information to find where, read the [references/postgresql-
 
 If a user asks for one of the **Unavailable** items, say so explicitly and propose the closest `tl`-based approximation rather than silently degrading.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### Discovery & system
 ```bash
 tl describe                            # List all resources with credit costs (free)

{thoughtleaders_cli-0.7.0/skills/channel-authenticity → thoughtleaders_cli-0.7.2/skills/tl-channel-authenticity}/SKILL.md

@@ -1,5 +1,6 @@
 ---
-name: channel-authenticity
+name: tl-channel-authenticity
+tl-blurb: vet a channel for fake views
 description: >
   Detect non-organic views / fake engagement / bot comments on a YouTube
   channel before booking (or after delivering) a sponsorship. Use when asked
@@ -33,7 +34,7 @@ investigations.
 ## Setup check
 
 ```bash
-cd .claude/skills/channel-authenticity/scripts
+cd .claude/skills/tl-channel-authenticity/scripts
 python3 tl_cli.py preflight        # must print "OK"
 ```
 If this errors with `cli_unavailable`, tell the user to run `tl auth login`

{thoughtleaders_cli-0.7.0/skills/channel-authenticity → thoughtleaders_cli-0.7.2/skills/tl-channel-authenticity}/scripts/_io_utf8.py

@@ -1,4 +1,4 @@
-"""Shared UTF-8 I/O setup for the channel-authenticity scripts.
+"""Shared UTF-8 I/O setup for the tl-channel-authenticity scripts.
 
 YouTube data is full of non-ASCII: channel names, comment text, emoji.
 On POSIX the default I/O encoding is already UTF-8, but on Windows the

{thoughtleaders_cli-0.7.0/skills/channel-authenticity → thoughtleaders_cli-0.7.2/skills/tl-channel-authenticity}/scripts/analyze_channel.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""channel-authenticity orchestrator — two-phase (subagent in the middle).
+"""tl-channel-authenticity orchestrator — two-phase (subagent in the middle).
 
 Phase 1 (collect):
     analyze_channel.py "<ref>"
@@ -128,7 +128,7 @@ def finalize(state_path: str, llm_paths: list[str]) -> dict:
 
 
 def main() -> None:
-    ap = argparse.ArgumentParser(description="channel-authenticity orchestrator")
+    ap = argparse.ArgumentParser(description="tl-channel-authenticity orchestrator")
     ap.add_argument("ref", nargs="?", help="channel handle/url/id or adlink:<id>")
     ap.add_argument(
         "--finalize",

{thoughtleaders_cli-0.7.0/skills/channel-authenticity → thoughtleaders_cli-0.7.2/skills/tl-channel-authenticity}/scripts/report.py

@@ -120,7 +120,7 @@ def render(state: dict) -> str:
     L.append("")
     L.append("---")
     L.append(
-        "_Generated by the `channel-authenticity` skill. Data via the "
+        "_Generated by the `tl-channel-authenticity` skill. Data via the "
         "ThoughtLeaders CLI; comments scraped fresh from YouTube._"
     )
     return "\n".join(L)

{thoughtleaders_cli-0.7.0/skills/channel-authenticity → thoughtleaders_cli-0.7.2/skills/tl-channel-authenticity}/scripts/tl_cli.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Single data-access seam for the channel-authenticity skill.
+"""Single data-access seam for the tl-channel-authenticity skill.
 
 Every TL data getter shells out to the ``tl`` CLI (``tl db pg/fb/es``,
 ``tl channels similar``), so the skill works for anyone with a ThoughtLeaders

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/skills/tl-import/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tl-import
+tl-blurb: bulk-import lists into a report
 description: Import a list of channels, brands, uploads (videos), or sponsorships into a ThoughtLeaders report — either an existing report (caller supplies `campaign_id` or a TL report URL) or a fresh new one (skill creates a minimal container, then populates). Superuser-only. **Trigger on explicit intent to import the listed entities into a report**, NOT on the mere presence of a list (a user can paste a list and want analysis, comparison, or similar-channel discovery — those go to `tl-cli:tl`). The deciding question is: *would the user be satisfied if those exact entities ended up as the report's contents, no transformation?* If yes, this is the skill. Phrasings: "import these channels into report 1234", "add brands to campaign 5678", "exclude these channels from report Z", "bulk-add these videos to report X", "create a new report with these channels: <list>", "make a campaign containing these brands: <list>".
 ---
 

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/skills/tl-keyword-research/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tl-keyword-research
+tl-blurb: rank content-search keywords
 description: |
   Broaden and rank a set of content-search keywords. Invoke when the user wants to find videos or channels by content keywords (topics, concepts, niches) — not by ID or exact name. Takes one or more seed keywords (or an NL phrase), proposes related candidates, probes Elasticsearch for each one against the `title` / `summary` / `transcript` fields, and returns a strict JSON object `{"keywords":[{"keyword","count"},...]}` sorted descending by document count. The output is meant to feed the next step (typically a `tl db es` content search with the surviving high-count keywords).
 ---
@@ -163,3 +164,4 @@ Each probe is `size:0` + `track_total_hits:true` with no aggregations — no row
 5. `keywords` array is sorted descending by `count`.
 6. Each entry has exactly `keyword` (string) and `count` (integer).
 7. The seed keyword(s) appear in the output.
+8. If the user requests a chart, create it as a SVG graphic

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/skills/tl-report-builder/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tl-report-builder
+tl-blurb: build a TL report from scratch
 description: |
   **MANUAL-INVOCATION-ONLY skill — do NOT auto-trigger on natural-language report requests.** This skill is invoked explicitly by the user (via the `/tl-report-builder` slash command, by naming the skill directly, or via some other unambiguous indication). Phrases like "build me a report", "make a campaign", "find me channels with filters Y", or "save this as a report" do NOT route here automatically. Those phrases go to other skills: the `tl` skill (for analysis / exploration of channels / brands / videos / sponsorships), `tl-save-report` (for persisting an in-chat session's result set as a saved report — filter-style or list-style), or `tl-import` (for adding identifiers to an existing report). This skill itself builds a brand-new TL report config from scratch through a heavy four-phase orchestration (routing → schema + validation → columns → widgets), covering the four report types: content/videos (1), brands (2), channels (3), sponsorships/deals (8). Only fire it when the user has explicitly chosen this path — there's almost always a lighter skill that's the right answer.
 

{thoughtleaders_cli-0.7.0 → thoughtleaders_cli-0.7.2}/skills/tl-save-report/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tl-save-report
+tl-blurb: save a session as a report
 description: |
   Save the results of an in-chat data-exploration session as a TL report. Triggers when the user wants to persist a channels / brands / videos (uploads) / sponsorships list or filtered set they've been working with — phrases like "save this as a report", "save the list", "turn this into a campaign", "persist this", "make a report from what you found", "save the result", "I want to come back to this".
 ---
@@ -502,6 +503,8 @@ Echo the saved URL + ID, plus a follow-up offer for refinement:
 
 The follow-up offer matters because **FilterSet changes (keywords, demographics, M2M lists) can't be patched in place** via `tl reports update` — they require saving a new variant. Surface that limitation only if the user actually asks to change FilterSet fields.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### On failure
 
 If the command exits non-zero, the CLI prints the error on stderr (shape: `Error (NNN): <detail>` for most codes; specific lines for 401/402/403). **Surface the error verbatim** — do NOT silently report success.

thoughtleaders_cli-0.7.2/skills/tl-top-partnerships/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: tl-top-partnerships
+description: External brand-user performance report. Ranks a brand's sponsorships by effective CPM once the sponsored videos went live, and compares live eCPM against the sold-date projection. Use whenever a brand user asks "which of my sponsorships performed best", "top partnerships this year", "best ROI deals", "effective CPM on my deals", "which sponsorships overperformed", "/top-partnerships", or any variation of "show me my best-performing sponsorships". This is the brand-side equivalent of internal performance reporting — fire it eagerly any time a brand wants to look back at their booked deals through a performance lens, even if they don't say the words "CPM" or "eCPM".
+---
+
+# Top Partnerships (Brand-side)
+
+Helps a brand look back at their sold sponsorships and see which ones delivered the lowest effective CPM (eCPM) once the videos went live, vs the projection at sale.
+
+## Triggers
+
+- `/top-partnerships` — defaults to calendar YTD
+- `/top-partnerships <range>` — e.g. `/top-partnerships 2025`, `/top-partnerships "last 12 months"`, `/top-partnerships "Q1 2026"`
+- Natural language: "top partnerships this year", "best sponsorships", "which deals performed best", "effective CPM on my deals", "show me my best ROI sponsorships"
+
+## What this skill computes
+
+For every sold sponsorship the brand has where the video has actually gone live (has a `publish_date` and a non-null live `views` count):
+
+- **Sold-date eCPM** = `price / projected_views_at_purchase_date * 1000`
+  - The projection captured on the adlink at the moment the deal was sold. This is the eCPM the brand "agreed to."
+- **Live eCPM** = `price / views * 1000`
+  - The actual eCPM now that the video has accumulated views.
+- **View ratio** = `views / projected_views_at_purchase_date`
+  - >1 means the video out-delivered its projection.
+- **Delta** = `live_eCPM - sold_date_eCPM`
+  - Negative delta = the deal got *cheaper* per view than promised (good for the brand). Positive delta = the deal underdelivered.
+
+It also pulls **future bookings** — any sponsorship with status sold / proposal_approved / pending and a send date strictly after today — and tags each deal and each channel with the earliest future send date, or "Re-book - no future spot" if none exists. This turns the report into an actionable list, not just a backward look.
+
+## Output
+
+A Google Sheet with two tabs, owned by the caller's Google account:
+
+- **By Deal** — one row per sponsorship, ranked by live eCPM (best first). Columns: rank, channel, title, video_url, send_date, publish_date, price, promised_views, live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, measurable, next_booking.
+- **By Channel** — one row per channel, aggregated across all that channel's deals in range. Combined live eCPM is `sum(price) / sum(live_views) * 1000` (volume-weighted, not an average of CPMs). Sorted by combined live eCPM. Columns: channel, deals, measurable_deals, total_price_usd, total_promised_views, total_live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, next_booking.
+
+In chat: a short summary + top-10 channels table + the sheet URL.
+
+## Workflow
+
+### Step 1 — Resolve the brand
+
+Run `tl whoami --json` and read the `brands` array.
+
+- One brand → use it silently.
+- Zero brands → tell the user this skill is for brand-user profiles and stop.
+- Multiple brands → ask which one. Don't guess.
+
+### Step 2 — Resolve the time range
+
+Default = calendar YTD (Jan 1 of the current year through today).
+
+Accept these forms in the user's input:
+
+- `2025` or `"2024"` → that full calendar year
+- `"last 12 months"` → trailing 12 months ending today
+- `"Q1 2026"`, `"Q4 2025"` → that quarter
+- `"YTD"` → explicit current YTD
+- Anything else → ask the user to clarify, don't silently pick
+
+Convert to a `send-date-start` / `send-date-end` pair (YYYY-MM-DD strings). Use `send_date` as the time anchor because that is when the sponsorship actually ran for the brand — purchase_date can be months earlier.
+
+### Step 3 — Run the script
+
+```bash
+python3 <SKILL_DIR>/scripts/top_partnerships.py \
+  --brand "<BRAND_NAME>" \
+  --send-date-start <YYYY-MM-DD> \
+  --send-date-end <YYYY-MM-DD>
+```
+
+`<SKILL_DIR>` resolves to this skill's directory at invocation time (same convention as `tl-views-guarantee`, `tl-keyword-research`).
+
+The script does everything: pulls sold deals in range (paginated), pulls all future bookings, computes per-deal and per-channel metrics, creates a Google Sheet with two tabs, shares it back to the caller, and prints a markdown summary plus the sheet URL.
+
+It uses `tl` for data and `gws` for sheet creation. Both must be on PATH and authed.
+
+### Step 4 — Present the result
+
+Take the script's stdout as-is. It already contains:
+
+1. **Summary line** — total sold deals, measurable count, median live eCPM, count overperforming.
+2. **Top 10 channels by combined live eCPM** — markdown table with the Next booking column bolded when it says "Re-book."
+3. **Sheet URL** — point the user at the two tabs.
+
+If more than half the top-10 channels show "Re-book", call that out in one sentence as the headline action item. If most of the top channels already have follow-ups booked, congratulate briefly and stop.
+
+Keep the writeup tight. No em dashes, no "just wanted to", no hedging. The data does the talking.
+
+## Brand-user mode notes
+
+- This skill assumes a brand-user `tl` auth. It uses only public CLI commands (`tl whoami`, `tl sponsorships list`) — no `tl db pg` and no Elasticsearch.
+- The `tl sponsorships list` endpoint already filters to deals the calling profile is allowed to see, so passing `brand:"<name>"` is a belt-and-braces filter rather than a privacy boundary.
+- View counts come from TL's own tracking on the `views` field returned by the CLI. They're the same numbers the brand sees in the TL dashboard, so the eCPMs are reconcilable with what they see in-app.
+- Don't include creators' contact emails, internal notes, or owner_* fields in the brand-facing output. The script already drops them from the CSV.
+
+## Edge cases worth mentioning to the user (only if they apply)
+
+- A deal that ran very recently (last 14-28 days) may show a misleadingly high Live eCPM because views are still accumulating. Mention this only if more than half the top-10 deals have a send date inside the last 28 days.
+- If the brand has zero measurable deals in the range, say so plainly and suggest broadening the range (e.g., last 12 months).