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

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

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

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

@@ -20,7 +20,7 @@ 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`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). 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 "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based, and returns matching brand profiles alongside channels. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
+`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`)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.0
+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
@@ -109,8 +109,9 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 # `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 "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
-tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+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

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

@@ -82,8 +82,9 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 # `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 "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
-tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+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

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

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

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

@@ -95,7 +95,7 @@ When querying sponsorship bookings, query by `status:sold` and filter the the da
 
 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 "<tag>"` against the vector recommender — that's faster, ranked by category-strength, and returns both channels and matching brand profiles. Run `tl recommender tags` to discover the valid tag names.
+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
 
@@ -139,7 +139,9 @@ tl brands history <id-or-name>         # Sponsorship history (5 credits/result,
 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 "<tag>"             # Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
+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)
@@ -332,9 +334,9 @@ tl recommender tags cooking
 tl recommender tags "usa"
 
 # Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
-tl recommender top "Cooking" msn:yes --limit 50
-tl recommender top "Tech" --limit 30
-tl recommender top "USA share" mbn:yes --limit 50
+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
 ```
 
 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.
@@ -434,8 +436,8 @@ tl reports run 42 --json
 "Find Cooking channels with US-heavy mobile audiences":
 ```bash
 # Use the vector recommender for the topic, then narrow with structured filters / SQL on the IDs.
-tl recommender top "Cooking" msn:yes --limit 100 --json \
-  | jq -r '.results[] | select(.kind=="channel") | .channel_id' \
+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
@@ -467,9 +469,10 @@ tl channels similar 29834 min-subs:1000000 exclude:477487 --limit 15  # client-s
 ```bash
 tl recommender tags                                            # Full tag list (free)
 tl recommender tags cooking                                    # Search tag names by substring
-tl recommender top "Cooking" msn:yes --limit 50                # Top channels & profiles loaded on a tag (50 credits)
-tl recommender top "USA share" mbn:yes --limit 30              # Demographic tag — MBN brands only
-tl recommender top "Tech" exclude-for-profile:842              # Drop channels already proposed for profile 842
+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

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

@@ -117,8 +117,8 @@ Every Firebolt workflow has two steps:
 
 ```bash
 # Channels matching some category (vector recommender — preferred over content_category equality)
-tl recommender top "Tech" msn:yes --limit 50 --json \
-  | jq '.channels[].channel_id'
+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.6.0 → 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.6.0"
+__version__ = "0.6.1"

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.1}/src/tl_cli/commands/recommender.py

@@ -19,10 +19,12 @@ 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-by-tag, vector inspection, profile→channel similarity)")
+app = typer.Typer(help="Vector recommender (tags, top-channels/profiles/brands, vector inspection, profile→channel similarity)")
 
 
-TOP_COLUMNS = ["kind", "value", "channel_id", "profile_id", "name", "brand_name", "slug"]
+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"}}
 
 
@@ -70,7 +72,7 @@ def tags_cmd(
         tl recommender tags "age 18"
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
-    query = " ".join(args or []).strip()
+    query = _strip_quotes(" ".join(args or []).strip())
     params = {"q": query} if query else {}
     client = get_client()
     try:
@@ -78,7 +80,7 @@ def tags_cmd(
         output(
             data,
             fmt,
-            columns=["group", "field_name", "normalized_name"],
+            columns=["group", "field_name"],
             title="Recommender vector tags",
         )
     except ApiError as e:
@@ -87,36 +89,21 @@ def tags_cmd(
         client.close()
 
 
-@app.command("top")
-def top_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 per group (1-100)"),
-) -> None:
-    """Top channels and profiles loaded on a single vector tag.
+def _strip_quotes(value: str) -> str:
+    """Strip one matching pair of surrounding quotes if present.
 
-    Costs 50 credits per call. Intelligence plan required. Returns both
-    channels and profiles ranked by the tag's value (descending).
+    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
 
-    Filters:
-        msn:<yes|no|all>            MSN membership for channel rows (default: all)
-        mbn:<yes|no|all>            MBN membership for profile rows (default: all)
-        exclude-for-channel:<id>    Drop profiles already proposed for this channel
-        exclude-for-profile:<id>    Drop channels already proposed for this profile
 
-    Examples:
-        tl recommender top "Cooking"
-        tl recommender top "Tech" msn:yes --limit 30
-        tl recommender top "USA share" mbn:yes
-        tl recommender top "Cooking" exclude-for-profile:842
-    """
-    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+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
@@ -124,15 +111,12 @@ def top_cmd(
 
     client = get_client()
     try:
-        data = client.get("/recommender/top", params=params)
-        rows = data.get("results", [])
-        for r in rows:
-            r["name"] = r.get("channel_name") or r.get("profile_email") or ""
+        data = client.get(f"/recommender/top/{kind}", params=params)
         output(
             data,
             fmt,
-            columns=TOP_COLUMNS,
-            title=f"Top by tag: {tag}",
+            columns=columns,
+            title=title,
             column_config=TOP_COLUMN_CONFIG,
         )
     except ApiError as e:
@@ -141,6 +125,89 @@ def top_cmd(
         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)"),