thoughtleaders-cli 0.6.3__tar.gz → 0.6.4__tar.gz

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.3
+Version: 0.6.4
 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.6.3 → thoughtleaders_cli-0.6.4}/pyproject.toml

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

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/skills/tl/references/elasticsearch-schema.md

@@ -90,7 +90,21 @@ Raw mappings (read-only links — out of band, not via `tl`):
 | `banner_ads` | object | Banner ad data |
 | `not_sponsored_by` | object | Explicitly not sponsored by |
 
-#### Channel Fields (on video docs via `channel.id`, or on channel parent docs)
+#### Channel Fields
+
+> ⚠️ **The embedded `channel.*` object on video (article) docs is a denormalized SUBSET — NOT the full channel schema.** The full field list below exists only on **channel parent docs** (`doc_type: "channel"`). On article docs, `channel.*` contains at most **6 fields**: `id`, `country`, `language`, `content_category`, `format`, `publication_id`. **`reach`, `subscribers`, `impression`, `channel_name`, `sponsorship_score`, `is_tl_channel`, etc. are NOT on the embedded object.** Filtering article docs by `channel.reach` returns zero results silently — query the parent channel doc, or join PG `thoughtleaders_channel` for those fields.
+>
+> Also: `channel.country` is missing on ~14% of article docs even when `channel` itself exists, so a bare `{"term": {"channel.country": "US"}}` filter silently drops those rows. **A bare `exists` clause does NOT fix this** — in a filter context it also rejects missing values, just explicitly. To include the missing-country rows alongside US (treat them as "country unknown"), use a `should` split:
+> ```json
+> {"bool": {"should": [
+>   {"term": {"channel.country": "US"}},
+>   {"bool": {"filter": [{"exists": {"field": "channel.id"}}],
+>             "must_not": [{"exists": {"field": "channel.country"}}]}}
+> ], "minimum_should_match": 1}}
+> ```
+> To **separately count** the missing rows, use a `filters` aggregation with `exists` / `must_not exists` branches.
+
+The full table below applies to **channel parent docs only**:
 
 | Field | Type | Description |
 |-------|------|-------------|

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/skills/tl/references/postgres-schema.md

@@ -56,8 +56,8 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 | `draft_expected_date` | date | Expected draft delivery |
 | `actual_end_date` | timestamptz | Actual end date |
 | `scheduled_end_date` | timestamptz | Scheduled end date |
-| `rejection_reason` | int | Rejection reason code |
-| `rejection_reason_details` | text | Free-text rejection details |
+| `rejection_reason` | int | Rejection reason code (1–24). See "`rejection_reason` Constants" below for the code → label mapping. Set when `publish_status IN (4, 5, 9)` (closed-lost). |
+| `rejection_reason_details` | text | Free-text rejection details. Often empty (~78% of lost deals). When populated, contains AM/agency notes like *"english content only"*, *"isn't talking about stocks"*, *"channel does not exist"*. Use as supplementary context, not primary classification. |
 | `payment_status` | int | 0=Unpaid, 1=Paid |
 | `performance_grade` | int | Performance rating (see business-glossary) |
 | `article_id` | varchar | Compound `<channel_id>:<youtube_id>` — links to ES `_id` and ES `id` field |
@@ -82,6 +82,66 @@ The main deals table. Each row = one sponsorship deal between a brand and a YouT
 | -1 | CLIENT_SIDE_AVAILABLE | Client Side Available | — |
 | -2 | CLIENT_SIDE_TAKEN | Client Side Taken | — |
 
+#### `rejection_reason` Constants
+
+Source of truth: `thoughtleaders.models.AdLink.REJECTION_REASON` (Django `IntegerField` choices in the main `thoughtleaders` repo).
+
+**Storage model:** `thoughtleaders_adlink.rejection_reason` is an `IntegerField`. **Postgres stores only the integer code.** The labels live in the Django `IntegerField.choices` tuple in application code — they are NOT a queryable column or a join key. The integer is the only thing you can `WHERE` against; the labels below are display mappings only.
+
+The **Enum Label** column is the verbatim string from the Django choices tuple (some have typos / internal vocabulary). The **AM-friendly label** is the recommended phrasing for AM-facing reports and proposals — use it when surfacing rejection reasons in any human-readable output.
+
+**Grouping — be careful, codes 18–24 are NOT homogeneous:**
+- **Codes 1–9** — brand-side rejections (brand said no)
+- **Codes 10–17** — publisher-side rejections (channel said no)
+- **Code 18 (`DEMOGRAPHICS_NO_MATCH`)** — audience-fit mismatch. Neither side is "wrong"; the channel may be excellent but its audience doesn't align with the brand's target. Don't bucket as "channel quality."
+- **Codes 19, 21, 22, 24** (`NOT_BRAND_SAFE`, `HIGH_VOLATILITY`, `LOW_ENGAGEMENT`, `NO_FACE_ON_SCREEN`) — channel-quality / channel-performance signals (production and delivery).
+- **Code 20 (`POOR_BRAND_HISTORY`)** — **brand-quality**, NOT channel quality. The brand has a poor sponsorship track record (e.g., known to ghost / pay late / be difficult). Do not include when reporting on channel quality.
+- **Code 23 (`DUPLICATE_PROPOSAL`)** — **process/timing**, NOT channel quality. Channel was pitched too recently. Outreach-cadence issue.
+
+⚠️ Naïve "codes 18–24 = channel quality" bucketing will misattribute brand-quality (20), audience-fit (18), and process (23) failures to channel quality and skew rejection-rate analysis.
+
+| Code | Constant | Enum Label (verbatim from Django) | AM-friendly label |
+|------|----------|---------------------|-------------------|
+| 1 | OTHER | Other (brand) | Brand declined — other reason |
+| 2 | COMPETITOR | Channel works with competitor (brand) | Channel runs a competitor |
+| 3 | NO_MATCH | Doesn't fit together (brand) | Brand says channel isn't a fit |
+| 4 | DISLIKE | Doesn't like the channel | Brand doesn't want this channel |
+| 5 | PRICING | Price is unreasonable | Brand says price is too high |
+| 6 | WORKING_TOGETHER | Already working together with the channel | Already running with this channel |
+| 7 | TIMING | Timing is off (brand) | Brand timing — not now |
+| 8 | NO_RESPONSE | Channel did not respond | Channel never replied |
+| 9 | DO_NOT_CONTACT | Do not contact channel | Channel is on do-not-contact list |
+| 10 | PUBLISHER_OTHER | Other (publisher) | Channel declined — other reason |
+| 11 | PUBLISHER_COMPETITOR | Works with competitor (publisher) | Channel already runs the competitor |
+| 12 | PUBLISHER_NO_MATCH | Doesn't fit together (publisher) | Channel says brand isn't a fit |
+| 13 | PUBLISHER_DISLIKE | Doesn't like the brand | Channel doesn't want this brand |
+| 14 | PUBLISHER_PRICING | Brand Price is too low | Channel says price is too low |
+| 15 | PUBLISHER_WORKING_TOGETHER | Already working together with the brand | Channel already running with brand |
+| 16 | PUBLISHER_TIMING | Timing is off (publisher) | Channel timing — not now |
+| 17 | PUBLISHER_NO_RESPONSE | Brand did not respond | Brand never replied |
+| 18 | DEMOGRAPHICS_NO_MATCH | Demographics don't fit | Audience demographics don't match |
+| 19 | NOT_BRAND_SAFE | Not brand safe | Brand-safety concern |
+| 20 | POOR_BRAND_HISTORY | Poor brand sponsorship history | Brand has a poor sponsorship track record |
+| 21 | HIGH_VOLATILITY | High Volatility | Channel views are too volatile |
+| 22 | LOW_ENGAGEMENT | Low engagement/Low views | Low engagement or low views |
+| 23 | DUPLICATE_PROPOSAL | Duplicate proposal | Already pitched recently |
+| 24 | NO_FACE_ON_SCREEN | No face on screen | Channel doesn't show a host on screen |
+
+#### Which date column for which question?
+
+`thoughtleaders_adlink` has multiple timestamps. Picking the wrong one silently distorts trend analysis (e.g. grouping by `created_at` mixes outreach-blast batches with steady-state activity; grouping by `purchase_date` drops everything that didn't sell because rejected/pipeline rows have NULL `purchase_date`).
+
+| Question | Use |
+|---|---|
+| "How many deals **sold** in year X?" | `purchase_date` (only set on sold/transacted deals) |
+| "How many deals **created** in year X?" (incl. pipeline + lost) | `created_at` |
+| "How much was **active outreach** in window X?" | `outreach_date` (sparse — falls back to `created_at` if null) |
+| "When did the ad **go live on YouTube**?" | `publish_date` — null means not yet published; sold deals can still be canceled until this is set |
+| "Latest activity / pipeline aging" | `updated_at` |
+| "When was the deal **proposed/presented/rejected**?" | `proposal_approved_date` / `presented_date` / `rejected_date` (each only set when that stage was reached) |
+
+**Default for "deals over time" reporting:** `created_at` if you want all flow, `purchase_date` if you want only revenue.
+
 #### Pipeline Stages
 
 - **Active pipeline** = statuses with weight > 0: 0, 2, 6, 7, 8.

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.3 → thoughtleaders_cli-0.6.4}/uv.lock

@@ -388,7 +388,7 @@ wheels = [
 
 [[package]]
 name = "thoughtleaders-cli"
-version = "0.6.3"
+version = "0.6.4"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },