thoughtleaders-cli 0.9.15__tar.gz → 0.9.16__tar.gz

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.15
+Version: 0.9.16
 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

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/pyproject.toml

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

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/skills/tl/references/business-glossary.md

@@ -112,6 +112,13 @@ AMs use "PV" loosely. There are three different DB fields, each meaning somethin
 
 When an AM says "what's the PV on this channel?" — they almost always mean `channel.projected_views`. When they say "what was the PV on this deal?" — they mean `adlink.projected_views_at_purchase_date`. When they say "did we hit the VG?" — they mean `adlink.view_guarantee_hit_date IS NOT NULL`.
 
+## Reads vs Sponsored Videos (Elasticsearch)
+
+| Business Term | DB Concept | Notes |
+|--------------|------------|-------|
+| **Read** (sponsored read) | A video with a `brand_mentions` element where, **on the same element**, `id = <brand_id>`, `type = "sponsored"` and `field = "transcript"` | The creator speaks the sponsorship out loud in the video ("this video is sponsored by…"). A brand link in the description with nothing said on camera is **not** a read. Must be a `nested` query — three separate top-level terms can match across different mentions. See [elasticsearch-schema.md](elasticsearch-schema.md#count-reads-for-a-brand-spoken-sponsorships). |
+| **Sponsored video** (all sponsored) | `sponsored_brand_mentions = <brand_id>` | Any sponsored detection, wherever it was found — includes link-only videos (`field = "summary"`, the description). A superset of reads; don't report it as a reads count. |
+
 ## Channel Sponsorship Signals
 
 Two derived metrics on the indexed channel doc that AMs use to qualify a channel before pitching. Both are pre-aggregated in the search index, computed against historical sponsored-content patterns.

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/skills/tl/references/elasticsearch-schema.md

@@ -165,6 +165,33 @@ tl db es '{
 }'
 ```
 
+This matches every sponsored detection, including link-only videos where the brand appears only in the description. For videos where the creator actually speaks the sponsorship, use the reads query below.
+
+### Count reads for a brand (spoken sponsorships)
+
+A **read** is a sponsored mention found in the transcript. All three conditions must hold on the **same** `brand_mentions` element, so they go inside one `nested` query:
+
+```bash
+tl db es '{
+  "size": 0,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"range": {"publication_date": {"gte": "2025-09-30", "lte": "2026-09-30"}}},
+    {"nested": {
+      "path": "brand_mentions",
+      "query": {"bool": {"filter": [
+        {"term": {"brand_mentions.id": 2403}},
+        {"term": {"brand_mentions.type": "sponsored"}},
+        {"term": {"brand_mentions.field": "transcript"}}
+      ]}}
+    }}
+  ]}}
+}'
+```
+
+Swap `"field": "transcript"` for `"summary"` to get description/link-only detections. Returned docs list all of their mentions, not just the matching one (see the `brand_mentions` row above).
+
 ### Search videos for a single channel
 
 ```bash

{thoughtleaders_cli-0.9.15 → thoughtleaders_cli-0.9.16}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.15"
+__version__ = "0.9.16"