thoughtleaders-cli 0.5.2__tar.gz → 0.6.1__tar.gz

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/AGENTS.md

@@ -1,6 +1,6 @@
 # Project Overview
 
-**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
+**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports, vector recommender). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
 
 # Architecture
 
@@ -20,6 +20,8 @@ When adding a new data command, follow this pattern. See `sponsorships.py` for t
 
 `deals`, `matches`, and `proposals` are shortcut commands that delegate to sponsorships' `do_list`/`do_show`/`do_create` with a pre-set status filter. They reject explicit `status:` filters — users should use `tl sponsorships list` for finer-grained status filtering.
 
+`recommender` (`commands/recommender.py`) wraps the vector-recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
+
 ## Filter Parsing (`filters.py`)
 
 `parse_filters()` handles `key:value` and `key:"quoted value"` syntax. Returns `dict[str, str]` passed as query params. Date filter keys (listed in `DATE_FILTER_KEYS` — e.g. `since`, `created-at`, `created-at-start`, `publish-date-end`) accept keywords `today`, `yesterday`, `tomorrow`. Sponsorship date fields (`created-at`, `publish-date`, `purchase-date`, `send-date`) each expose three filter shapes: bare `<field>:<date>` matches within that date/period, and `<field>-start:` / `<field>-end:` give inclusive lower/upper bounds (both sides inclusive; partial dates expand to the whole period). Empty-string values result in `IS NULL` queries on the backend.

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.5.2
+Version: 0.6.1
 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
@@ -81,13 +81,16 @@ tl uploads list q:code --csv
 # Show upload details (supports colon-containing IDs)
 tl uploads show 1174310:0BehkmVa7ak
 
-# Search channels. msn and tpp are tri-state filters (yes/no/both; default 'both').
-# msn = opted-in to receive sponsorship offers; tpp = exclusively TL-managed.
-# Both are also returned as boolean fields on every channel response.
-tl channels list category:cooking min-subs:100k
-tl channels list msn:yes                  # MSN channels only (~11k)
-tl channels list tpp:yes                  # TPP channels only (~169)
-tl channels list msn:no min-subs:500k     # big non-MSN channels
+# Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
+# (run `tl schema pg` once to confirm the live column set).
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND total_views >= 100000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
+tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
+          WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
+# MSN status (media_selling_network_join_date) is scrubbed from the
+# advertiser sandbox view — for MSN-only / non-MSN lookups, the
+# structured filter is the right tool: `tl channels list msn:yes|no`.
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -102,6 +105,17 @@ tl channels show "Economics Explained"
 tl channels similar 12345 --limit 10
 tl channels similar "Tremending girls" min-score:0.85 --limit 5
 
+# Vector recommender — discovery by category/demographic tag (Intelligence plan).
+# `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
+tl recommender tags                              # List every tag (free)
+tl recommender tags cooking                      # Search tag names by substring
+tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
+tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
+tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
+tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
+tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
+tl recommender similar-to-profile 842            # Channels closest to a brand profile
+
 # Brand intelligence
 tl brands show Nike
 

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/README.md

@@ -54,13 +54,16 @@ tl uploads list q:code --csv
 # Show upload details (supports colon-containing IDs)
 tl uploads show 1174310:0BehkmVa7ak
 
-# Search channels. msn and tpp are tri-state filters (yes/no/both; default 'both').
-# msn = opted-in to receive sponsorship offers; tpp = exclusively TL-managed.
-# Both are also returned as boolean fields on every channel response.
-tl channels list category:cooking min-subs:100k
-tl channels list msn:yes                  # MSN channels only (~11k)
-tl channels list tpp:yes                  # TPP channels only (~169)
-tl channels list msn:no min-subs:500k     # big non-MSN channels
+# Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
+# (run `tl schema pg` once to confirm the live column set).
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND total_views >= 100000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
+tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
+          WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
+# MSN status (media_selling_network_join_date) is scrubbed from the
+# advertiser sandbox view — for MSN-only / non-MSN lookups, the
+# structured filter is the right tool: `tl channels list msn:yes|no`.
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -75,6 +78,17 @@ tl channels show "Economics Explained"
 tl channels similar 12345 --limit 10
 tl channels similar "Tremending girls" min-score:0.85 --limit 5
 
+# Vector recommender — discovery by category/demographic tag (Intelligence plan).
+# `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
+tl recommender tags                              # List every tag (free)
+tl recommender tags cooking                      # Search tag names by substring
+tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
+tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
+tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
+tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
+tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
+tl recommender similar-to-profile 842            # Channels closest to a brand profile
+
 # Brand intelligence
 tl brands show Nike
 

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/commands/tl.md

@@ -18,8 +18,8 @@ The user wants to query ThoughtLeaders data. Translate their request into the ri
 ## Examples
 
 - "/tl sold sponsorships for Nike in Q1" → `tl sponsorships list status:sold brand:"Nike" purchase-date-start:2026-01-01 purchase-date-end:2026-03-31`
-- "/tl cooking channels over 100k subs" → `tl channels list category:cooking min-subs:100000`
-- "/tl mobile-first US cooking channels" → `tl channels list category:cooking primary-device:mobile min-us-share:50`
+- "/tl cooking channels over 100k subs" → `tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND total_views >= 100000 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
+- "/tl mobile-first US cooking channels" → `tl db pg "SELECT id, channel_name, demographic_usa_share FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND demographic_device_primary = 'mobile' AND demographic_usa_share >= 50 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
 - "/tl Nike's sponsorship activity" → `tl brands show Nike`
 - "/tl run my Q1 report" → `tl reports --json` then `tl reports run <id>`
 - "/tl check my balance" → `tl balance`

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/docs/architecture.md

@@ -75,7 +75,12 @@ Filters are passed as `key:value` pairs after `list`:
 tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
 tl sponsorships list status:pending send-date:2026-03
 tl uploads list channel:12345 type:longform since:2026-03
-tl channels list category:cooking min-subs:100k language:en
+# Channel discovery is raw SQL — the structured `tl channels list` covers
+# only narrow lookups. Default to:
+tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
+          WHERE content_category = <COOKING_CODE> AND language = 'en'
+            AND total_views >= 1000000
+          ORDER BY total_views DESC LIMIT 50 OFFSET 0"
 ```
 
 Sponsorship date filtering (on `created-at`, `publish-date`, `purchase-date`, `send-date`) exposes three shapes per field:

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/pyproject.toml

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

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/skills/tl/SKILL.md

@@ -51,12 +51,12 @@ ThoughtLeaders is a sponsorship marketplace connecting **Brands** (advertisers /
 
 The centre of the data model is **Sponsorships** — business relationships between brands and channels. Sponsorships have a funnel of types, from broad to narrow:
 
-- **Sponsorships** — the broadest category, encompassing all stages
+- **Sponsorships** — the broadest category, encompassing all stages, stored in the `thoughtleaders_adlink` table.
   - **Matches** — possible brand-channel pairings that ThoughtLeaders thinks could work
   - **Proposals** — matches that have been proposed to both sides to consider
   - **Deals** — contractually agreed-upon sponsorships (sold), either in production or published
 
-Sponsorships are sometimes called "Ads" or "Ad campaigns".
+Sponsorships are sometimes called "Ads" or "Ad campaigns". An obsolete name for "sponsorship" is an "adlink".
 
 The CLI has shortcut commands for each type: `tl matches`, `tl proposals`, `tl deals`. These filter `tl sponsorships` by status.
 
@@ -66,15 +66,15 @@ Other key concepts:
 - **Reports** — saved report configurations that can be re-run
 - **Comments** — notes attached to sponsorships
 - **Adspots** — types of ads a channel carries (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost.
-- **MSN** (Media Selling Network) — the ~11k YouTube channels that have opted in to receive sponsorship offers. Returned as a boolean `msn` field on every channel response (list, detail, similar). Derived server-side from whether `Channel.media_selling_network_join_date` is non-null — the timestamp itself isn't exposed over the CLI, just the boolean. Filterable via `msn:` tri-state: `msn:yes` (MSN only — the default on `similar`; on `list` the default is `both`), `msn:no` (non-MSN only), `msn:both` (no filter).
-- **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the smaller, exclusive ~169 channels TL manages directly. Returned as the `tpp` boolean field on every channel response (list, detail, similar). Filterable via `tpp:` with the same tri-state vocabulary: `tpp:yes` / `tpp:no` / `tpp:both` (default `both`).
+- **MSN** (Media Selling Network) — the ~11k YouTube channels that have opted in to receive sponsorship offers. A channels is in the MSN group if the `channel.media_selling_network_join_date` field is not null.
+- **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the smaller, exclusive ~169 channels TL manages directly. A channel is in the TPP group if the `channel.is_tl_channel` is True.
 - **`demographics_updated_at`** (on channel detail) — ISO timestamp of when demographic screenshots were last uploaded and processed via OCR. If non-null, the channel has demographics screenshots on file. If null, no screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
 - **`impression`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed.
 - **`views`** (on sponsorships) — actual view count of the sold and published sponsored video, accessible when `article_id` is set.
 - **`impressions_guarantee`** (on sponsorships) — projected/guaranteed impressions for the sponsorship. Numeric; rounded to int in list output.
 - **Sponsorship detail fields** (returned by `tl sponsorships show <id> --json`) — in addition to the list-view columns, the detail payload includes `integration` (raw int), `publish_count`, `common_name`, `outreach_email`, nested `publisher` (`first_name`, `last_name`, `email`), nested `brand_contact` (`first_name`, `last_name`, `email`), and `brand.organization_name`. Use these when generating IOs, contracts, or outreach.
 - **CPM** has two distinct meanings depending on level — pick the one the user actually wants:
-  - **Channel CPM** = `(adspot.price / channel.impression) × 1000` — projected price per thousand projected views. Used for pricing decisions **before** a sponsorship is sold. Available for channels with active adspots via `tl channels show <channel_id>`.
+  - **Channel CPM** = `(adspot.price / channel.impression) * 1000` — projected price per thousand projected views. Used for pricing decisions **before** a sponsorship is sold. Available for channels with active adspots via `tl channels show <channel_id>`.
   - **Sponsorship CPM** = calculated in either of two ways: if `views` is present, then CPM is `(sponsorship.price / sponsorship.views) × 1000`, meaning realized cost per thousand actual views, computed post-publication. If `views` is null, Compute from the sponsorship's `price` and the channel's `impression` fields.
   - **CPM does not have a range filter.** To find sponsorships in a CPM range (e.g. "around $15"), fetch the record set with other filters first, then apply the CPM range in post-processing (jq, Python, etc.) on the returned `cpm` field. Plan queries and pagination accordingly — the server cannot reduce the result count based on CPM.
 - **Sponsorship dates** — each sponsorship has four distinct dates, useful for different queries:
@@ -87,23 +87,23 @@ Other key concepts:
 Users see data scoped by their organization and plan:
 - **Media buyers** see sponsorships where their org is the brand. They see `price` but never `cost`.
 - **Media sellers** see sponsorships where their org is the publisher. They see `cost` but never `price`.
-- **Intelligence plan** is required for `tl brands`, full channel search, and full uploads.
+- **Intelligence plan** is required for accessing information not strictly related to the user's organisation.
 
 When querying sponsorship bookings, query by `status:sold` and filter the the date range only by `purchase_date`. Otherwise, query for state:sold by `created_at`.
 
-An obsolete name for "sponsorship" is an "adlink".
-
 ## Methodology
 
 Where possible, if searching for a sponsorship match between channels and brands, first search for what do similar brands sponsor / which brands is the channel usually sponsored by. The similarity judgement should be preferably based on similar topics, similar upload frequency, similar channel sizes, and only after all that, on demographics.
 
+Use the `tl channels similar` and `tl brands similar` commands to explore 1:1 similarity between known channels or brands. For category- or topic-driven discovery (e.g. "find me Cooking channels", "who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`/`top-profiles`) against the vector recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
+
 ## Workflow
 
 At the start of session, always run a `tl help` command to find out which commands are available, and the `tl whoami` command to find out what you have access to.
 
 Unless the user specifically asks for running a specific report or showing the result of a specific report, find the data by using other, low-level commands.
 
-1. **Discover first**: Run `tl describe show <resource> --json` to learn available fields, filters, and credit costs before querying
+1. **Discover first**: Run `tl describe show <resource> --json` to learn available fields, filters, and credit costs before querying. Use `tl schema pg`, `tl schema es`, and `tl schema fb` to find information about the main database (pg), the articles / uploads database (es), and the channel metrics database (fb).
 2. **Check saved reports**: Run `tl reports --json` to see if the user has a saved report that already answers their question
 3. **Check credits**: Run `tl balance --json` before expensive queries. Warn the user if a query will cost many credits.
 4. **Query with filters**: Use `key:value` filter syntax for structured queries
@@ -138,6 +138,13 @@ tl brands show <id-or-name>            # Brand detail (1 credit)
 tl brands history <id-or-name>         # Sponsorship history (5 credits/result, linear)
 tl brands history <query> --channel <id>  # Brand mentions on specific channel
 tl brands similar <id-or-name>         # Find similar brands via profile vector KNN (50 credits flat)
+tl recommender tags [query]            # List vector tag names — categories, demographics, formats (free)
+tl recommender top-channels "<tag>"    # Top channels loaded on a vector tag (50 credits; Intelligence)
+tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a vector tag (50 credits)
+tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a vector tag (50 credits)
+tl recommender inspect-channel <ref>   # Show a channel's feature-vector breakdown (50 credits; Intelligence)
+tl recommender inspect-brand <ref>     # Show a brand profile's ideal-vector breakdown (50 credits; Intelligence)
+tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal vector (50 credits; Intelligence)
 tl snapshots channel <id>              # Channel metrics over time — list curve, mult 1.2 (Firebolt-backed)
 tl snapshots video <id> --channel <id> # Video view curve — list curve, mult 1.2 (--channel required!)
 tl reports                             # List saved reports — list curve, mult 1.3
@@ -278,10 +285,10 @@ See [references/business-glossary.md](references/business-glossary.md) for reven
 
 | Capability | Status | Workaround |
 |---|---|---|
-| Arbitrary read-only `SELECT` on Postgres | **Available** via `tl db pg`. | SELECT-only, mandatory `LIMIT ≤ 500` + `OFFSET`, function allowlist, no `::reg*` casts. See `references/postgres-schema.md`. |
-| Cross-reference helpers ("channels proposed to brand X", "channels sponsored by MBN brands in last N days") | **Unavailable** — these were stacked PG joins. | Approximate with `tl brands history <brand>` (videos where the brand was detected → extract channel IDs) and `tl sponsorships list brand:<name> status:<...>`. Won't perfectly match (e.g. `media_buying_network_join_date` isn't exposed). |
-| **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a free *proposal* between a channel and a brand. It does not let you set price/cost/owner_sales_id/send_date/etc. | Done in the app or by a human with DB access. |
-| Pre-insert validation queries (joining `adspot ↔ channel ↔ profile ↔ org` to confirm MSN, integration=1, persona, plan) | **Unavailable** as a single query (needs PG joins). | Partial: `tl channels show <id>` exposes `msn`, `tpp`, and active adspots with `integration` codes. Persona/plan/profile-level checks aren't surfaced. |
+| Arbitrary read-only `SELECT` on Postgres | **Available** via `tl db pg`. | SELECT-only, mandatory `LIMIT ≤ 500` + `OFFSET`, only certain SQL forms are allowed. See `references/postgres-schema.md`. |
+| Cross-reference helpers ("channels proposed to brand X", "channels sponsored by MBN brands in last N days") | **Available** via `tl db pg`. | Write the join: `thoughtleaders_adlink` ↔ `adspot` ↔ `channel` ↔ `profile` ↔ `profile_brands` ↔ `brand`. Filter by `publish_status` for proposed/sold and by date range as needed. See `references/postgres-schema.md` for the exact column names. |
+| **AdLink INSERT** with custom price/cost/owner/`weighted_price`/`created_where` | **Unavailable** — `tl sponsorships create` exists but only creates a free *proposal* between a channel and a brand. The `tl db pg` sanitizer accepts SELECT only — no INSERT/UPDATE. | Done in the app or by a human with DB access. |
+| Pre-insert validation queries (joining `adspot ↔ channel ↔ profile ↔ org` to confirm MSN, integration=1, persona, plan) | **Available** via `tl db pg`. | One SELECT joining the four tables. Use `thoughtleaders_channel.media_selling_network_join_date IS NOT NULL` for MSN, `thoughtleaders_adspot.integration = 1` for mention adspots, `thoughtleaders_profile.persona` for the persona code (see persona constants in `references/postgres-schema.md`). |
 | Firebolt cross-table or join queries; filtering on non-indexed columns in WHERE | **Unavailable** — not accepted. | Fetch a wider slice keyed on `channel_id` (and optionally `id`), filter the rest in `jq`/Python. |
 | ES `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, parent/child joins; any `script_*`; multiple aggregations in one body | **Unavailable** — not accepted. | Rewrite using `term`/`terms`/`match`/`bool`/`nested`. For multi-agg dashboards, run multiple `tl db es` calls and combine client-side. For "similar"-style queries, try `tl channels similar` / `tl brands similar` (vector KNN, server-implemented). |
 | ES deep pagination beyond `from+size = 10,000` | **Unavailable** via raw — `scroll` and `pit` aren't allowlisted; `search_after` is allowed but `from` is still capped. | Use `search_after` with `sort` to walk past 10k. For huge sweeps, narrow with `publication_date` ranges. |
@@ -309,43 +316,52 @@ tl changelog --md > CHANGELOG.md       # Capture for a doc
 `tl changelog` summaries are LLM-generated server-side from full commit messages and cached per version, so repeat calls are fast and don't re-bill the LLM. The release date and a 2–4 sentence prose summary come back per version.
 
 ### Filter syntax
-All list commands accept `key:value` filters:
+Structured list commands accept `key:value` filters (use them for trivially simple lookups):
 ```bash
 tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
 tl uploads list channel:12345 type:longform
-tl channels list category:cooking min-subs:100k language:en
-tl channels list tpp:yes                       # list all TPP (TL-managed) channels
-tl channels list tpp:no primary-device:mobile  # mobile-first channels that aren't in TPP
-tl channels list msn:yes category:tech         # Media Selling Network channels in tech
-tl channels list msn:no min-subs:500k          # big non-MSN channels (not yet opted in)
 ```
 
 Date filters accept keywords: `today`, `yesterday`, `tomorrow`.
 
-#### Channel demographic filters
+#### Channel discovery — recommender first, raw SQL second
+
+For category- or demographic-driven discovery, **use the vector recommender, not `content_category` SQL.** The recommender ranks channels by how strongly they load on a category/demographic tag (cosine-style scores), instead of forcing exact equality on a single integer code. It also returns the matching brand profiles alongside the channels — useful when the user actually wants to know "who buys this kind of inventory."
+
+```bash
+# Discover the right tag name first (free)
+tl recommender tags cooking
+tl recommender tags "usa"
+
+# Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
+tl recommender top-channels "Cooking" msn:yes --limit 50
+tl recommender top-channels "Tech" --limit 30
+tl recommender top-brands "USA share" mbn:yes --limit 50
+```
 
-These filters apply to both `tl channels list` and `tl sponsorships list` (the latter filters by the associated channel's demographics):
+Use `tl db pg` only for predicates the recommender can't express — pure attribute filters (`is_tl_channel`, `language`, `demographic_device_primary`), aggregations, and joins. Run `tl schema pg` once to confirm the live column set; the columns referenced below are stable.
 
 ```bash
-# Primary device type
-tl channels list primary-device:mobile
-tl channels list primary-device:desktop
-tl channels list primary-device:tablet
-
-# Minimum device audience share (0–100)
-tl channels list min-mobile-share:60
-tl channels list min-desktop-share:30
-tl channels list min-tablet-share:10
-
-# Minimum geo share (0–100, ISO country codes lowercase)
-tl channels list min-us-share:70
-tl channels list min-gb-share:25
-
-# Combine with other filters
-tl channels list category:tech primary-device:mobile min-us-share:50 min-subs:100k
-tl sponsorships list status:sold primary-device:mobile min-us-share:60
+# All TPP (TL-managed) channels — pure attribute filter, not a category query
+tl db pg "SELECT id, channel_name, content_category, total_views
+          FROM thoughtleaders_channel
+          WHERE is_tl_channel = TRUE
+          ORDER BY total_views DESC
+          LIMIT 200 OFFSET 0"
+
+# Mobile-first non-TPP channels — device share, not topic
+tl db pg "SELECT id, channel_name, demographic_device_primary, total_views
+          FROM thoughtleaders_channel
+          WHERE is_tl_channel = FALSE
+            AND demographic_device_primary = 'mobile'
+          ORDER BY total_views DESC
+          LIMIT 100 OFFSET 0"
 ```
 
+For per-country share beyond the recommender's "USA share" tag, use the `demographic_geo` jsonb in raw SQL: `(demographic_geo->>'gb')::int >= 25`. Same pattern with `demographic_device->>'mobile'` for non-primary device shares.
+
+**MSN status (`media_selling_network_join_date`) is scrubbed from the advertiser sandbox view.** Raw SQL can't filter on it from an advertiser context; use the structured `tl channels list msn:yes|no|both` for MSN-specific lookups, then drop down to SQL on the resulting IDs (`WHERE id IN (...)`) for further analysis.
+
 ### Output flags
 - `--json` — structured JSON (use this for parsing)
 - `--csv` — CSV output
@@ -417,9 +433,19 @@ tl reports --json  # Find the report ID first
 tl reports run 42 --json
 ```
 
-"Find mobile-first US channels in cooking":
+"Find Cooking channels with US-heavy mobile audiences":
 ```bash
-tl channels list category:cooking primary-device:mobile min-us-share:50 --json
+# Use the vector recommender for the topic, then narrow with structured filters / SQL on the IDs.
+tl recommender top-channels "Cooking" msn:yes --limit 100 --json \
+  | jq -r '.results[].channel_id' \
+  | paste -sd, - \
+  | xargs -I {} tl db pg "SELECT id, channel_name, total_views, demographic_usa_share
+                          FROM thoughtleaders_channel
+                          WHERE id IN ({})
+                            AND demographic_device_primary = 'mobile'
+                            AND demographic_usa_share >= 50
+                          ORDER BY total_views DESC
+                          LIMIT 50 OFFSET 0" --json
 ```
 
 "Show sold sponsorships targeting mobile US audiences":
@@ -438,3 +464,17 @@ tl channels similar 29834 tpp:yes --limit 30                 # TPP (TL-managed)
 tl channels similar 29834 min-subs:1000000 exclude:477487 --limit 15  # client-side filters
 ```
 **Both `tl channels show` and `tl channels similar` accept either a numeric channel ID or a channel name.** Name arguments are case-insensitive partial matches; if more than one active channel matches, the command prints a candidates table (channel_id, subscribers, name) and exits 1 so you can retry with a specific ID. The `msn` filter on `similar` is tri-state: `yes` (only MSN channels — the default), `no` (only non-MSN channels), `both` (no MSN filter). `tl channels look-alike` is a hidden alias for `similar` that matches the internal "look-alike channels" terminology.
+
+"Browse the vector recommender" (categories, demographics, formats — `tl recommender tags` is free):
+```bash
+tl recommender tags                                            # Full tag list (free)
+tl recommender tags cooking                                    # Search tag names by substring
+tl recommender top-channels "Cooking" msn:yes --limit 50       # Top channels loaded on a tag (50 credits)
+tl recommender top-profiles "Cooking" --limit 30               # Top brand profiles for the tag
+tl recommender top-brands "USA share" mbn:yes --limit 30       # Top brands (deduped) — demographic tag, MBN only
+tl recommender top-channels "Tech" exclude-for-profile:842     # Drop channels already proposed for profile 842
+tl recommender inspect-channel 29834                           # Per-tag breakdown of a channel's vector
+tl recommender inspect-brand Nike                              # Per-tag breakdown of a brand's ideal vector
+tl recommender similar-to-profile 842 --limit 30               # Channels closest to a brand profile's ideal vector
+```
+Use `tl recommender top` for category/topic discovery (it's ranked) and `tl channels similar` / `tl brands similar` for 1:1 lookalike searches.

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/skills/tl/references/firebolt-schema.md

@@ -49,7 +49,7 @@ Tracks YouTube video metrics over time. Each row = one scrape of one video on on
 | Column | Type | Description |
 |--------|------|-------------|
 | `id` | TEXT | YouTube video ID (e.g., `'dQw4w9WgXcQ'`). **Bare YouTube ID** — NOT the compound `<channel_id>:<youtube_id>` form used in PG `adlink.article_id` and ES `_id`. |
-| `channel_id` | INT | TL channel ID (matches the channel ID returned by `tl channels list`) |
+| `channel_id` | INT | TL channel ID (matches `thoughtleaders_channel.id` in Postgres) |
 | `channel_format` | INT | Platform format (4 = YouTube) |
 | `publication_date` | DATE | When the video was published |
 | `scrape_date` | DATE | When this data point was captured |
@@ -85,8 +85,8 @@ Firebolt's **only advantage** is historical metric snapshots. For everything els
 | Current view count on a video | **Elasticsearch** (`tl uploads show` or `tl db es`) |
 | Current subscriber count | **Elasticsearch** (`tl channels show`) |
 | Video metadata (title, tags, duration) | **Elasticsearch** |
-| Find channels by criteria | **`tl channels list`** (Postgres) |
-| Deal / pipeline / sponsorship data | **`tl sponsorships`** etc. (Postgres) |
+| Find channels by criteria | **`tl db pg`** against `thoughtleaders_channel` |
+| Deal / pipeline / sponsorship data | **`tl db pg`** against `thoughtleaders_adlink` (joins to `adspot`/`channel`/`profile`/`brand`) |
 | View curve over time (age 7→30→90→180) | **Firebolt** ✅ |
 | Views at age 30 vs age 180 (evergreenness) | **Firebolt** ✅ |
 | Channel subscriber growth trend | **Firebolt** ✅ |
@@ -116,8 +116,9 @@ Every Firebolt workflow has two steps:
 **Step 1 — get `channel_id` and (optionally) video IDs from PG/ES.**
 
 ```bash
-# Channels matching some criterion (PG side)
-tl channels list category:tech --json --limit 50 | jq '.results[].id'
+# Channels matching some category (vector recommender — preferred over content_category equality)
+tl recommender top-channels "Tech" msn:yes --limit 50 --json \
+  | jq '.results[].channel_id'
 
 # Or videos for a specific brand's deals (Postgres side, via tl sponsorships)
 tl deals list brand:"Nike" --json --limit 500 \

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.6.1/src/tl_cli/commands/recommender.py

@@ -0,0 +1,314 @@
+"""tl recommender — Vector-recommender introspection and discovery.
+
+Surfaces the channel/profile feature-vector machinery that powers the
+"Recommender Insights" web view: list the vector tags (categories,
+demographics, formats, etc.), find the top channels and profiles loaded
+on a given tag, inspect a single channel or brand vector, or fetch
+channels similar to a brand profile's ideal vector.
+
+For 1:1 similarity use `tl channels similar` and `tl brands similar`.
+"""
+
+import urllib.parse
+
+import typer
+from rich.console import Console
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.filters import parse_filters
+from tl_cli.output.formatter import detect_format, output, output_single
+
+app = typer.Typer(help="Vector recommender (tags, top-channels/profiles/brands, vector inspection, profile→channel similarity)")
+
+
+TOP_CHANNEL_COLUMNS = ["value", "channel_id", "channel_name", "slug"]
+TOP_PROFILE_COLUMNS = ["value", "profile_id", "profile_email", "brand_name", "brand_slug"]
+TOP_BRAND_COLUMNS = ["value", "brand_slug", "brand_name", "profile_id"]
+TOP_COLUMN_CONFIG = {"value": {"justify": "right"}}
+
+
+def _handle_recommender_error(e: ApiError) -> None:
+    """Show ambiguity candidates inline; otherwise default handler."""
+    if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
+        err = Console(stderr=True)
+        err.print(f"[yellow]{e.detail}[/yellow]")
+        err.print()
+        err.print("[bold]Candidates:[/bold]")
+        for c in e.raw["candidates"]:
+            cid = c.get("channel_id") or c.get("brand_id") or "?"
+            name = c.get("name", "")
+            extra = c.get("website") or c.get("subscribers") or ""
+            err.print(f"  {cid:>10}  {name}  [dim]{extra}[/dim]")
+        raise typer.Exit(1)
+    handle_api_error(e)
+
+
+@app.callback(invoke_without_command=True)
+def recommender(ctx: typer.Context) -> None:
+    """Vector recommender."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
+@app.command("tags")
+def tags_cmd(
+    args: list[str] = typer.Argument(None, help="Optional substring (matches tag or normalized name)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """List vector tag names (free).
+
+    Use this to discover the tag names accepted by `tl recommender top`.
+    Each tag is one dimension of a channel/profile feature vector —
+    e.g. content categories like "Cooking", demographic buckets like
+    "Age 18-24", device shares, country shares.
+
+    Examples:
+        tl recommender tags
+        tl recommender tags cooking
+        tl recommender tags "age 18"
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    query = _strip_quotes(" ".join(args or []).strip())
+    params = {"q": query} if query else {}
+    client = get_client()
+    try:
+        data = client.get("/recommender/tags", params=params)
+        output(
+            data,
+            fmt,
+            columns=["group", "field_name"],
+            title="Recommender vector tags",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+def _strip_quotes(value: str) -> str:
+    """Strip one matching pair of surrounding quotes if present.
+
+    Lets users paste an example like `tl recommender top-channels "cooking"`
+    where the shell already strips quotes, but also tolerates a layer of
+    extra quoting from agents or scripts that re-wrap the literal.
+    """
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+        return value[1:-1]
+    return value
+
+
+def _do_top(kind: str, tag: str, args: list[str], fmt: str, limit: int, columns: list[str], title: str) -> None:
+    tag = _strip_quotes(tag)
+    filters = parse_filters(args or [])
+    server_keys = {"msn", "mbn", "exclude-for-channel", "exclude-for-profile"}
+    params = {k: v for k, v in filters.items() if k in server_keys}
+    params["tag"] = tag
+    params["limit"] = str(limit)
+
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/top/{kind}", params=params)
+        output(
+            data,
+            fmt,
+            columns=columns,
+            title=title,
+            column_config=TOP_COLUMN_CONFIG,
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("top-channels")
+def top_channels_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top channels loaded on a single vector tag.
+
+    Costs 50 credits per call. Intelligence plan required.
+
+    Filters:
+        msn:<yes|no|all>            MSN membership (default: all)
+        exclude-for-profile:<id>    Drop channels already proposed for this profile
+
+    Examples:
+        tl recommender top-channels "Cooking"
+        tl recommender top-channels "Tech" msn:yes --limit 30
+        tl recommender top-channels "Cooking" exclude-for-profile:842
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("channels", tag, args or [], fmt, limit, TOP_CHANNEL_COLUMNS, f"Top channels: {tag}")
+
+
+@app.command("top-profiles")
+def top_profiles_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top brand profiles loaded on a single vector tag.
+
+    Costs 50 credits per call. Intelligence plan required. Profiles can
+    represent the same brand more than once (one brand → multiple
+    profiles); use `top-brands` for brand-deduplicated results.
+
+    Filters:
+        mbn:<yes|no|all>            MBN membership (default: all)
+        exclude-for-channel:<id>    Drop profiles already proposed for this channel
+
+    Examples:
+        tl recommender top-profiles "Cooking"
+        tl recommender top-profiles "USA share" mbn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("profiles", tag, args or [], fmt, limit, TOP_PROFILE_COLUMNS, f"Top profiles: {tag}")
+
+
+@app.command("top-brands")
+def top_brands_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top brands loaded on a single vector tag (deduplicated from profiles).
+
+    Costs 50 credits per call. Intelligence plan required. Server-side
+    aggregates the underlying profile rows by brand, keeping the
+    highest-scoring profile per brand.
+
+    Filters:
+        mbn:<yes|no|all>            MBN membership of the underlying profile (default: all)
+        exclude-for-channel:<id>    Drop brands already proposed for this channel
+
+    Examples:
+        tl recommender top-brands "Cooking"
+        tl recommender top-brands "USA share" mbn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("brands", tag, args or [], fmt, limit, TOP_BRAND_COLUMNS, f"Top brands: {tag}")
+
+
+@app.command("inspect-channel")
+def inspect_channel_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show a channel's feature vector grouped by category.
+
+    Costs 50 credits per call. Intelligence plan required. Returns the
+    grouped sparse vector (active dimensions only) and the magnitude.
+
+    Examples:
+        tl recommender inspect-channel 12345
+        tl recommender inspect-channel "MrBeast"
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    encoded = urllib.parse.quote(channel_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/channels/{encoded}/inspect")
+        output_single(data, fmt)
+    except ApiError as e:
+        _handle_recommender_error(e)
+    finally:
+        client.close()
+
+
+@app.command("inspect-brand")
+def inspect_brand_cmd(
+    brand_ref: str = typer.Argument(..., help="Brand ID (numeric) or name (partial match, must be unique)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show a brand profile's ideal feature vector grouped by category.
+
+    Costs 50 credits per call. Intelligence plan required. Resolves the
+    brand to its (preferred MBN) profile and inspects that profile's
+    aggregated vector.
+
+    Examples:
+        tl recommender inspect-brand 287
+        tl recommender inspect-brand Nike
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    encoded = urllib.parse.quote(brand_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/brands/{encoded}/inspect")
+        output_single(data, fmt)
+    except ApiError as e:
+        _handle_recommender_error(e)
+    finally:
+        client.close()
+
+
+@app.command("similar-to-profile")
+def similar_to_profile_cmd(
+    profile_id: int = typer.Argument(..., help="Profile ID (numeric)"),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Channels closest to a brand profile's ideal vector.
+
+    Costs 50 credits per call. Intelligence plan required. Channels the
+    brand has already worked with or been proposed are excluded.
+
+    Filters:
+        language:<iso>      Content language (default: en)
+        msn:<yes|no>        Restrict to MSN channels (default: no)
+
+    Examples:
+        tl recommender similar-to-profile 842
+        tl recommender similar-to-profile 842 msn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    filters = parse_filters(args or [])
+    params = {k: v for k, v in filters.items() if k in {"language", "msn"}}
+    params["limit"] = str(limit)
+    client = get_client()
+    try:
+        data = client.get(f"/recommender/profiles/{profile_id}/similar", params=params)
+        for r in data.get("results", []):
+            score = r.get("score")
+            if isinstance(score, (int, float)) and fmt in ("table", "md"):
+                r["score"] = f"{score * 100:.1f}%"
+        output(
+            data,
+            fmt,
+            columns=["score", "channel_id", "channel_name", "slug"],
+            title=f"Channels similar to profile {profile_id}",
+            column_config={"score": {"justify": "right"}},
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/src/tl_cli/main.py

@@ -27,6 +27,7 @@ from tl_cli.commands.db import app as db_app
 from tl_cli.commands.deals import app as deals_app
 from tl_cli.commands.matches import app as matches_app
 from tl_cli.commands.proposals import app as proposals_app
+from tl_cli.commands.recommender import app as recommender_app
 from tl_cli.commands.sponsorships import app as sponsorships_app
 from tl_cli.commands.describe import app as describe_app
 from tl_cli.commands.schema import app as schema_app
@@ -95,6 +96,7 @@ app.add_typer(deals_app, name="deals")
 app.add_typer(uploads_app, name="uploads")
 app.add_typer(channels_app, name="channels")
 app.add_typer(brands_app, name="brands")
+app.add_typer(recommender_app, name="recommender")
 app.add_typer(snapshots_app, name="snapshots")
 app.add_typer(reports_app, name="reports")
 app.add_typer(comments_app, name="comments")

{thoughtleaders_cli-0.5.2 → thoughtleaders_cli-0.6.1}/uv.lock

@@ -387,8 +387,8 @@ wheels = [
 ]
 
 [[package]]
-name = "tl-cli"
-version = "0.4.19"
+name = "thoughtleaders-cli"
+version = "0.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },