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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.1
+Version: 0.6.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
@@ -83,14 +83,17 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
+# NOTE: For topic / category discovery, prefer the vector recommender over
+# `content_category` equality — `tl recommender top-channels "<tag>"`
+# returns channels ranked by how strongly they load on the topic, not just
+# rows where the single category code matches exactly.
 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`.
+# MSN status: filter on `media_selling_network_join_date IS [NOT] NULL`
+# in the same raw SQL query (column is scrubbed from advertiser sandboxes).
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list

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

@@ -56,14 +56,17 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
+# NOTE: For topic / category discovery, prefer the vector recommender over
+# `content_category` equality — `tl recommender top-channels "<tag>"`
+# returns channels ranked by how strongly they load on the topic, not just
+# rows where the single category code matches exactly.
 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`.
+# MSN status: filter on `media_selling_network_join_date IS [NOT] NULL`
+# in the same raw SQL query (column is scrubbed from advertiser sandboxes).
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list

{thoughtleaders_cli-0.6.1 → thoughtleaders_cli-0.6.2}/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 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 cooking channels over 100k subs" → `tl recommender top-channels "cooking" --limit 50` (then post-filter by `subscribers >= 100000` on the resulting IDs)
+- "/tl mobile-first US cooking channels" → `tl recommender top-channels "cooking" --limit 100` (then narrow by `demographic_device_primary = 'mobile'` / `demographic_usa_share >= 50` with raw SQL on the resulting IDs)
 - "/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.6.1 → thoughtleaders_cli-0.6.2}/docs/architecture.md

@@ -48,7 +48,6 @@ All data commands use explicit subcommands: `list`, `show`, `create`/`add`. Runn
 | `tl proposals create --channel <id> --brand <id>` | Create a proposal (free) |
 | `tl uploads list [filters...]` | List video uploads (ES) |
 | `tl uploads show <id> [<id>...]` | Show upload detail(s) by ID |
-| `tl channels list [filters...]` | Search channels. Responses carry boolean `msn` (Media Selling Network) and `tpp` (TL-managed) fields; filterable via `msn:` / `tpp:` tri-state (`yes` / `no` / `both`, default `both`). |
 | `tl channels show <id-or-name>` | Channel detail, including active adspots with price/cost/CPM |
 | `tl channels history <id-or-name>` | Sponsorship history (videos with detected sponsors) |
 | `tl channels similar <id-or-name>` | Vector-similarity recommender. 50 credits; Intelligence plan. Tri-state `msn:` (default `yes`) and `tpp:` (default `both`) filters. Ambiguous names return 400 + candidates list. Hidden `look-alike` alias. |
@@ -75,8 +74,10 @@ 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
-# Channel discovery is raw SQL — the structured `tl channels list` covers
-# only narrow lookups. Default to:
+# Channel discovery is raw SQL — default to:
+# (For topic/category lookups, `tl recommender top-channels "<tag>"` is a
+# better starting point than `content_category` equality — it ranks by
+# how strongly each channel loads on the topic, not exact-match.)
 tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
           WHERE content_category = <COOKING_CODE> AND language = 'en'
             AND total_views >= 1000000
@@ -387,7 +388,6 @@ Most CLI endpoints can reuse existing views/utilities rather than being built fr
 | **`POST /api/cli/v1/sponsorships`** | `api/create-bulk-proposal` (`CreateBulkProposalView`) + MCP `save_proposals_for_email` in `mcp/proposals.py` | Adapt for single-proposal creation from CLI params |
 | **`GET /api/cli/v1/uploads`** | `api/articles` (`ArticlesView`) — full ES article search with configurable columns, filters, aggregation. Already handles channel format, brand filters, content type. | Translate CLI filters → ArticlesView params. Restrict to VIDEO format. |
 | **`GET /api/cli/v1/uploads/<id>`** | `api/articles/<id>` (`SingleArticleView`) | Add CLI envelope |
-| **`GET /api/cli/v1/channels`** | `api/v2/external-youtube-thoughtleaders` (`ExternalYoutubeThoughtleadersView`) — rich ES-powered channel search with configurable columns, aggregation. Also `api/v1/channels/dropdown` for simple name search. | Translate CLI filters → existing view params |
 | **`GET /api/cli/v1/channels/<id>`** | `api/v1/channels/<id>` (`ChannelAPIViewSet.retrieve`) — returns channel detail with loyalty metrics | Add CLI envelope + breadcrumbs linking to snapshots |
 | **`GET /api/cli/v1/brands/<query>`** | `api/v1/brands` (`BrandsViewSet`) for brand lookup + `api/articles` with `sponsored_brand_mentions` filter for intelligence data. Also `api/brand/<id>/matcher` (`BrandChannelMatcherAPI`) for channel discovery. | Combine brand lookup + ES brand mention query |
 | **`GET /api/cli/v1/snapshots/channel/<id>`** | `api/v2/channel-history` (`ChannelHistoryView`) — already queries Firebolt `channel_metrics` with pagination, uses `get_firebolt_query_results()` utility. Also `api/v2/external-channel-total-views` for time-series with granularity. | Direct reuse — just translate params + add CLI envelope |

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

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

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

@@ -130,8 +130,7 @@ tl proposals show <id>                 # Proposal detail (2 credits)
 tl proposals create --channel <id> --brand <id>  # Create proposal (free)
 tl uploads list [filters...]           # Video uploads from ES — list curve, mult 1.0
 tl uploads show <id>                   # Upload detail (2 credits)
-tl channels list [filters...]          # Channel search — list curve, mult 1.0
-tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name)
+tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
 tl channels history <id-or-name>       # Sponsorship history (5 credits/result, linear)
 tl channels similar <id-or-name>       # Vector-similarity recommender (50 credits flat; Intelligence plan)
 tl brands show <id-or-name>            # Brand detail (1 credit)
@@ -155,7 +154,7 @@ tl comments add <adlink-id> "msg"      # Add comment (free)
 
 **"List curve"** above means non-linear pricing: `cost = 1 + mult × 0.126 × n^1.2`. The flat 1-credit setup applies to every list call; the `mult` reflects per-resource complexity. `tl db {pg,fb,es}` shares the same curve at mult=1.4. Concrete totals:
 
-| Rows | mult=1.0 (channels, brands, comments, uploads, sponsorships) | mult=1.2 (snapshots) | mult=1.3 (reports) | mult=1.4 (db.pg / db.fb / db.es) |
+| Rows | mult=1.0 (comments, uploads, sponsorships) | mult=1.2 (snapshots) | mult=1.3 (reports) | mult=1.4 (db.pg / db.fb / db.es) |
 |---:|---:|---:|---:|---:|
 | 1 | 1 | 1 | 1 | 1 |
 | 10 | 3 | 3 | 4 | 4 |
@@ -360,7 +359,7 @@ tl db pg "SELECT id, channel_name, demographic_device_primary, total_views
 
 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.
+**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. For MSN-only / non-MSN lookups, run the same raw SQL with `media_selling_network_join_date IS [NOT] NULL` from a context that has access to it (full-access role), or rely on the recommender's MSN-aware filters: `tl recommender top-channels "<tag>" msn:yes|no|all`.
 
 ### Output flags
 - `--json` — structured JSON (use this for parsing)
@@ -398,7 +397,7 @@ Every query costs credits. Before running expensive queries:
 Users only see data their plan allows:
 - **Media buyers** see deals where their org is the brand. They see `price` but never `cost`.
 - **Media sellers** see deals where their org is the publisher. They see `cost` but never `price`.
-- **Intelligence plan** required for `tl brands`, full `tl channels list` search, and full `tl uploads list`.
+- **Intelligence plan** required for `tl brands`, the full `tl recommender` surface, and full `tl uploads list`.
 - **Paid plan** required for `tl snapshots`.
 
 ## Important: Status Labels

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

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

{thoughtleaders_cli-0.6.1 → thoughtleaders_cli-0.6.2}/src/tl_cli/commands/channels.py

@@ -11,7 +11,7 @@ from tl_cli.filters import parse_filters
 from tl_cli.hints import detail_hint
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="YouTube channels (search, detail, and similar-channel recommendations)")
+app = typer.Typer(help="YouTube channels (detail, history, and similar-channel recommendations)")
 
 # Columns for the `similar` endpoint result table. The server enriches every
 # row so the user can size up each suggestion without follow-up queries.
@@ -25,50 +25,6 @@ SIMILAR_COLUMN_CONFIG = {
 }
 
 
-@app.callback(invoke_without_command=True)
-def channels(ctx: typer.Context) -> None:
-    """YouTube channels — search and detail."""
-    if ctx.invoked_subcommand is None:
-        ctx.invoke(list_cmd, args=[], json_output=False, csv_output=False, md_output=False, limit=50, offset=0)
-
-
-@app.command("list")
-def list_cmd(
-    args: list[str] = typer.Argument(None, help="Filters (key:value pairs). Run 'tl describe show channels' for available filters."),
-    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"),
-    offset: int = typer.Option(0, "--offset", help="Pagination offset"),
-) -> None:
-    """Search channels with optional filters.
-
-    Examples:
-        tl channels list                                  # List channels
-        tl channels list category:cooking min-subs:100k   # Search with filters
-    """
-    fmt = detect_format(json_output, csv_output, md_output, toon_output)
-    filters = parse_filters(args or [])
-
-    client = get_client()
-    try:
-        params = {**filters, "limit": str(limit), "offset": str(offset)}
-        data = client.get("/channels", params=params)
-        for r in data.get("results", []):
-            r["channel_id"] = r.pop("id", None)
-        output(
-            data,
-            fmt,
-            columns=["channel_id", "name", "url", "msn", "tpp", "subscribers", "gender", "countries", "category", "sponsorship_score", "trend"],
-            title="Channels",
-        )
-    except ApiError as e:
-        handle_api_error(e)
-    finally:
-        client.close()
-
-
 @app.command("show")
 def show_cmd(
     channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),