thoughtleaders-cli 0.7.3__tar.gz → 0.7.4__tar.gz

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.3
+Version: 0.7.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.7.3 → thoughtleaders_cli-0.7.4}/pyproject.toml

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

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/skills/tl/SKILL.md

@@ -150,6 +150,8 @@ Unless the user specifically asks for running a specific report or showing the r
 
    If the user says yes (or uses any of the save-trigger phrases, like `save it`, `save the list`, `make a report`, `persist this`, `turn this into a campaign`, `I want to come back to this`), invoke the `tl-save-report` skill — it owns the filter-vs-list decision flow, the FilterSet mapping, and the `tl reports create` / `tl reports save-list` save call. **Don't try to compose the report config yourself**; hand off to the skill.
 
+   **When the user already has specific IDs in hand** — "make a report of these sponsorship IDs", "save these exact channels", or a curated set you just resolved — that is always a **list-style** report: pin the IDs with `tl reports save-list <entity> --ids-file` (or add them to an existing report with `tl bulk-import <entity> -c <report-id>`). **Never** route an explicit-ID request through `tl reports create "<natural-language prompt>"` — the prompt path builds *predicate filters* and pins none of those IDs, so the report comes back showing unrelated records, not the ones the user named. After creating it, confirm the report actually contains those records before sharing the link.
+
    Skip the save offer when the result clearly doesn't fit a report type — a single scalar count, an aggregate roll-up across entity types, view-curve time series, schema introspection output, or anything that isn't a list of channels / brands / videos / sponsorships. A trailing offer on those would just be noise.
 
 Prefer writing shell code, `jq` commands, or `duckdb` commands that fetch or analysise large sets of data instead of analysing it yourself. On Mac and Linux, create temporary files in `/tmp` that can be analysed later in different ways. On Windows, create them in the directory pointed to by the `%TEMP%` environment variable. When coding, do it in Python.
@@ -765,7 +767,7 @@ tl channels similar 29834 msn:no --limit 30                  # non-MSN channels
 tl channels similar 29834 tpp:yes --limit 30                 # TPP (TL-managed) channels only
 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.
+**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. `tl channels show` returns a `tl_url` field — the canonical ThoughtLeaders web-app analysis page for the channel; use it verbatim when linking a user to the channel instead of constructing a URL by hand.
 
 ### "Browse the recommender" (categories, demographics, formats):
 ```bash

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/src/tl_cli/commands/channels.py

@@ -64,14 +64,6 @@ def show_cmd(
     client = get_client()
     try:
         data = client.get(f"/channels/{encoded_ref}")
-        for i, r in enumerate(data.get("results", []) if isinstance(data.get("results"), list) else []):
-            renamed = {}
-            for k, v in r.items():
-                if k == "id":
-                    renamed["channel_id"] = v
-                else:
-                    renamed[k] = v
-            data["results"][i] = renamed
         output_single(data, fmt)
         if fmt == "table" and data.get("show_cta"):
             record = data.get("results", data)

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/src/tl_cli/commands/reports.py

@@ -22,6 +22,71 @@ REPORT_TYPE_LABELS = {1: "Content", 2: "Brands", 3: "Channels", 8: "Sponsorships
 
 POLL_INTERVAL = 2  # seconds between server polls
 
+# Filterset keys that pin specific entities into a report (the curated-ID
+# lists). A report built from these holds exactly those records; a report built
+# from predicate filters re-evaluates against live data and pins nothing.
+_PIN_ENTITIES = ("channels", "brands", "sponsorships", "articles")
+# Filterset keys that are structural, not user-facing predicate filters.
+_NON_PREDICATE_KEYS = {"keyword_operator", "sort"}
+
+
+def _summarize_report_contents(config: dict) -> dict:
+    """Summarize what a saved report config actually contains.
+
+    Returns the report-type label, a per-entity count of *pinned* IDs (the
+    curated lists that freeze specific channels/brands/sponsorships/articles
+    into the report), and the active predicate-filter keys. Lets a caller —
+    human or agent — catch a filters-vs-pinned-IDs mismatch (or a wholly blank
+    report) before sharing the link: a report built from a natural-language
+    prompt yields predicate filters and pins *nothing*, so "pinned: none" is
+    the tell that it doesn't contain the specific records the user named.
+    """
+    filterset = config.get("filterset") or {}
+    pinned = {
+        entity: len(filterset[entity])
+        for entity in _PIN_ENTITIES
+        if isinstance(filterset.get(entity), list) and filterset[entity]
+    }
+    skip = set(_PIN_ENTITIES) | {f"exclude_{e}" for e in _PIN_ENTITIES} | _NON_PREDICATE_KEYS
+    filters = sorted(
+        key
+        for key, value in filterset.items()
+        if key not in skip and value not in (None, "", [], {}, False)
+    )
+    return {
+        "report_type": REPORT_TYPE_LABELS.get(config.get("report_type"), config.get("report_type")),
+        "pinned": pinned,
+        "filters": filters,
+    }
+
+
+def _render_contents_line(summary: dict) -> str:
+    """One-line human rendering of a `_summarize_report_contents` result."""
+    pinned = summary.get("pinned") or {}
+    pin_str = ", ".join(f"{count} {entity}" for entity, count in pinned.items()) if pinned else "none"
+    filters = summary.get("filters") or []
+    filt_str = ", ".join(filters) if filters else "none"
+    return f"Contents: {summary.get('report_type')} report · pinned: {pin_str} · filters: {filt_str}"
+
+
+def _print_contents_summary(summary: dict) -> None:
+    """Surface a saved report's contents on stderr (safe in every output mode).
+
+    A report with no pinned entities *and* no filters gets a loud warning —
+    that blank/default state is the failure behind "you sent me an empty
+    report". Otherwise a dim one-liner lets the caller confirm the report holds
+    what the user actually asked for.
+    """
+    line = _render_contents_line(summary)
+    if not summary.get("pinned") and not summary.get("filters"):
+        err.print(
+            f"[yellow]⚠ {line}\n"
+            f"  This report has no filters and no pinned entities — it will show "
+            f"a blank/default view.[/yellow]"
+        )
+    else:
+        err.print(f"[dim]{line}[/dim]")
+
 
 @app.callback(invoke_without_command=True)
 def reports(
@@ -330,6 +395,13 @@ def create_report(
     With a prompt, runs the AI Report Builder pipeline (keyword research, config
     generation, review) and saves the resulting campaign.
 
+    Have specific IDs already? A report of *exactly* the channels / brands /
+    sponsorships / articles you already have the IDs for is a different job —
+    use `tl reports save-list <entity> --ids-file` to pin those IDs into a new
+    report, or `tl bulk-import <entity> -c <report-id>` to add them to an
+    existing one. A natural-language prompt here builds *predicate filters* and
+    pins none of those IDs, so the report comes back showing unrelated records.
+
     With --config '<json>' or --config-file <path>, skips the orchestration
     pipeline and saves the provided config directly. Useful when an external
     agent (e.g. the tl-report-builder Claude Code skill) has already produced a
@@ -404,6 +476,13 @@ def create_report(
         report_url = result.get("report_url", "")
         campaign_id = result.get("campaign_id", "")
 
+        # Echo what the report actually contains. Surfaced even under
+        # --yes/--json (the agent path), so a report built from a prompt —
+        # which yields predicate filters and pins no specific IDs — can be
+        # spotted before its link is shared.
+        summary = _summarize_report_contents(config)
+        data["report_contents"] = summary
+
         if toon_output:
             print(toon_encode(data))
         elif json_output:
@@ -422,6 +501,8 @@ def create_report(
             if usage:
                 err.print(f"\n  [dim]{usage.get('credits_charged', 0)} credits · {usage.get('balance_remaining', '?')} remaining[/dim]")
 
+        _print_contents_summary(summary)
+
     except ApiError as e:
         handle_api_error(e)
     finally:
@@ -541,23 +622,26 @@ def save_list_cmd(
     finally:
         client.close()
 
+    summary = _summarize_report_contents(config)
+    data["report_contents"] = summary
+
     if fmt == "toon":
         print(toon_encode(data))
-        return
-    if fmt == "json":
+    elif fmt == "json":
         print(json.dumps(data, indent=2, default=str))
-        return
+    else:
+        results = data.get("results", [{}])
+        result = results[0] if results else {}
+        err.print()
+        err.print("[green bold]Report created![/green bold]")
+        err.print(f"  Campaign ID: {result.get('campaign_id', '?')}")
+        err.print(f"  URL: https://app.thoughtleaders.io{result.get('report_url', '')}")
+        err.print(
+            "\n[dim]Refine columns, widgets, title, or description with "
+            "`tl reports update <id>`.[/dim]"
+        )
 
-    results = data.get("results", [{}])
-    result = results[0] if results else {}
-    err.print()
-    err.print("[green bold]Report created![/green bold]")
-    err.print(f"  Campaign ID: {result.get('campaign_id', '?')}")
-    err.print(f"  URL: https://app.thoughtleaders.io{result.get('report_url', '')}")
-    err.print(
-        "\n[dim]Refine columns, widgets, title, or description with "
-        "`tl reports update <id>`.[/dim]"
-    )
+    _print_contents_summary(summary)
 
 
 @app.command("update")

{thoughtleaders_cli-0.7.3 → thoughtleaders_cli-0.7.4}/tests/test_reports.py

@@ -7,11 +7,68 @@ import pytest
 import typer
 from typer.testing import CliRunner
 
-from tl_cli.commands.reports import _parse_config_arg, app
+from tl_cli.commands.reports import (
+    _parse_config_arg,
+    _render_contents_line,
+    _summarize_report_contents,
+    app,
+)
 
 runner = CliRunner()
 
 
+# ---------------------------------------------------------------------------
+# _summarize_report_contents / _render_contents_line
+# ---------------------------------------------------------------------------
+
+
+class TestReportContentsSummary:
+    def test_filter_only_report_pins_nothing(self) -> None:
+        # The exact shape that caused the real bug: a sponsorships report the
+        # AI builder produced from a prompt — a generic format predicate, no
+        # pinned deals.
+        summary = _summarize_report_contents(
+            {"report_type": 8, "filterset": {"channel_formats": [4]}}
+        )
+        assert summary["report_type"] == "Sponsorships"
+        assert summary["pinned"] == {}
+        assert summary["filters"] == ["channel_formats"]
+
+    def test_pinned_ids_counted_per_entity(self) -> None:
+        summary = _summarize_report_contents(
+            {"report_type": 8, "filterset": {"sponsorships": [1, 2, 3, 4, 5]}}
+        )
+        assert summary["pinned"] == {"sponsorships": 5}
+        assert summary["filters"] == []
+
+    def test_blank_report_has_no_pins_and_no_filters(self) -> None:
+        summary = _summarize_report_contents({"report_type": 3, "filterset": {}})
+        assert summary["pinned"] == {}
+        assert summary["filters"] == []
+        line = _render_contents_line(summary)
+        assert "pinned: none" in line and "filters: none" in line
+
+    def test_structural_keys_are_not_counted_as_filters(self) -> None:
+        # keyword_operator / sort are structural, not user-facing predicates.
+        summary = _summarize_report_contents(
+            {"report_type": 3, "filterset": {"keyword_operator": "and", "sort": "x", "channels": [9]}}
+        )
+        assert summary["pinned"] == {"channels": 1}
+        assert summary["filters"] == []
+
+    def test_empty_and_falsey_filter_values_ignored(self) -> None:
+        summary = _summarize_report_contents(
+            {"report_type": 3, "filterset": {"languages": [], "is_offline": False, "reach_from": 1000}}
+        )
+        assert summary["filters"] == ["reach_from"]
+
+    def test_render_line_mentions_pins_and_filters(self) -> None:
+        line = _render_contents_line(
+            {"report_type": "Sponsorships", "pinned": {"sponsorships": 5}, "filters": ["channel_formats"]}
+        )
+        assert "5 sponsorships" in line and "channel_formats" in line
+
+
 # ---------------------------------------------------------------------------
 # _parse_config_arg
 # ---------------------------------------------------------------------------