thoughtleaders-cli 0.6.51__tar.gz → 0.6.52__tar.gz

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/AGENTS.md

@@ -117,7 +117,7 @@ The version string is defined in three files and all three must be updated toget
 
 * Do not reference internal architecture of the ThoughtLeaders app in comments or skills. Specifially: do not reference internal table names, field names, API endpoints, Python modules or functions (including the sanitizer).
 * Do not let server implementation details into skill files (anything under `skills/`). Skills describe *what the CLI does* from the user's seat — observable command surface, inputs, outputs, examples. Do not say "the server enforces X", "the API validates Y on its side", "the backend rejects Z" — those are mechanism notes that drift the moment the server changes. State the user-visible behaviour ("unknown keys come back as 400") without naming where it's enforced.
-* Place all imports at the start of the Python module file
+* **All `import` and `from X import Y` statements live at the top of the Python module file** — after the module docstring, before any code. No inline imports inside function bodies, no lazy imports for "speed" or "optional dependency" reasons. `from __future__ import …` goes at the very top (Python requires that). The only legitimate inline-import exception is **platform-conditional imports** that cannot succeed on the other platform (e.g. `import msvcrt` on Linux, `import termios`/`tty` on Windows) — those stay inside their `if sys.platform == …:` guard. If a circular-import problem makes a top-level import impossible, fix the circular dependency rather than working around it with an inline import.
 
 # Git commit rules
 

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.51
+Version: 0.6.52
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/pyproject.toml

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/skills/tl/SKILL.md

@@ -181,10 +181,6 @@ tl channels history <id-or-name>       # Sponsorship history
 tl channels similar <id-or-name>       # Similarity recommender (Intelligence plan)
 tl brands show <id-or-name>            # Brand detail
 tl brands find <query>                 # Resolve a string to {id, name}; matches name, slug, domain, or keyword
-tl brands history <id-or-name>         # Sponsorship history
-tl brands history <query> --channel <id>  # Brand mentions on specific channel
-tl brands history-stats <id-or-name>   # Aggregate roll-up: counts, total/avg/median views, first/last seen, by-year, top channels
-tl brands history-stats <q> --channel <id>  # Same roll-up, narrowed to one channel
 tl brands similar <id-or-name>         # Find similar brands via similarity search
 tl recommender tags [query]            # List similarity tag names — categories, demographics, formats
 tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (Intelligence)
@@ -595,9 +591,102 @@ tl db pg "SELECT al.id, al.weighted_price, al.purchase_date, b.name AS brand
           LIMIT 500 OFFSET 0" --json
 ```
 
-### "What channels does Nike sponsor?":
+### Brand sponsorship history — what channels does Nike sponsor?
+
+Resolve the brand to an ID, then probe ES for articles where the brand appears in `sponsored_brand_mentions`. Channel names live in PG (the ES article doc only carries `channel.id`), so the third call joins them in.
+
+```bash
+# 1. Resolve "Nike" → brand ID
+tl brands find Nike --json   # → results[0].id, say 21416
+
+# 2. Recent sponsored videos for that brand (sorted by publication_date desc)
+tl db es '{
+  "size": 50,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "sort": [{"publication_date": "desc"}],
+  "_source": ["title", "channel.id", "publication_date", "views"]
+}' --json > /tmp/nike_history.json
+
+# 3. Resolve channel.id → channel_name (one PG round-trip for the whole page)
+jq -r '[.results[].channel.id] | unique | map(tostring) | join(",")' /tmp/nike_history.json \
+  | xargs -I CH_IDS tl db pg "SELECT id, channel_name FROM thoughtleaders_channel WHERE id IN (CH_IDS)" --json
+
+# Narrow to a single channel:
+tl db es '{
+  "size": 50,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}},
+    {"term": {"channel.id": 5607}}
+  ]}},
+  "sort": [{"publication_date": "desc"}],
+  "_source": ["title", "publication_date", "views"]
+}'
+
+# Was the video a TL-brokered deal? Cross-check ES video_id against AdLink.article_id:
+tl db pg "SELECT article_id FROM thoughtleaders_adlink
+          WHERE article_id IN ('1247603:8LskGvKUA9I', '1247603:abc123')"
+```
+
+### Brand sponsorship roll-up — totals, first/last seen, top channels, by-year
+
+The same ES filter (`doc_type=article` + `sponsored_brand_mentions=<id>`) with `size:0` + aggregations replaces a roll-up call. ES accepts **one aggregation total per request** (top-level + sub-aggs all count), so what would be a single server-side roll-up here splits into a few `tl db es` calls and one client-side join.
+
 ```bash
-tl brands history Nike --json
+# Totals + time range (one aggregation total — the four metric aggs are siblings under aggs and bill as a single body)
+tl db es '{
+  "size": 0,
+  "track_total_hits": true,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "views_sum":  {"sum":   {"field": "views"}},
+    "views_avg":  {"avg":   {"field": "views"}},
+    "first_seen": {"min":   {"field": "publication_date"}},
+    "last_seen":  {"max":   {"field": "publication_date"}}
+  }
+}'
+
+# By-year breakdown (date_histogram only — no sub-agg, that would push over the one-agg cap)
+tl db es '{
+  "size": 0,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "by_year": {"date_histogram": {
+      "field": "publication_date", "calendar_interval": "year",
+      "format": "yyyy", "min_doc_count": 1
+    }}
+  }
+}'
+
+# Top channels by sponsored-video count (terms agg only — for views per channel, run a second call per channel)
+tl db es '{
+  "size": 0,
+  "query": {"bool": {"filter": [
+    {"term": {"doc_type": "article"}},
+    {"term": {"sponsored_brand_mentions": "21416"}}
+  ]}},
+  "aggs": {
+    "by_channel": {"terms": {"field": "channel.id", "size": 10, "order": {"_count": "desc"}}}
+  }
+}'
+
+# TL-brokered deal count for the brand (PG, not ES — adlinks where the brand is on the creator profile)
+tl db pg "SELECT COUNT(*) AS tl_brokered
+          FROM thoughtleaders_adlink al
+          JOIN thoughtleaders_profile p  ON p.id = al.creator_profile_id
+          JOIN thoughtleaders_profile_brands pb ON pb.profile_id = p.id
+          WHERE pb.brand_id = 21416 AND al.article_id IS NOT NULL"
 ```
 
 ### "Compare view curves for two videos":

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/bulk_import.py

@@ -11,6 +11,7 @@ import time
 from pathlib import Path
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 
 from tl_cli.client.errors import ApiError, handle_api_error
@@ -59,6 +60,7 @@ def bulk_import_command(
     ids_file: str | None = typer.Option(None, "--ids-file", "-f", help="Path to file with one identifier per line. Omit to read from stdin."),
     exclude: bool = typer.Option(False, "--exclude", help="Mark these identifiers as excluded from the report instead of included"),
     json_output: bool = typer.Option(False, "--json", help="JSON output (default)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Bulk-import entities into a report.
 
@@ -113,7 +115,9 @@ def bulk_import_command(
         client.close()
 
     output = {"task_id": task_id, **result}
-    if json_output or not sys.stdout.isatty():
+    if toon_output:
+        sys.stdout.write(toon_encode(output) + "\n")
+    elif json_output or not sys.stdout.isatty():
         json.dump(output, sys.stdout, indent=2)
         sys.stdout.write("\n")
     else:

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/credits.py

@@ -18,6 +18,7 @@ import webbrowser
 from decimal import Decimal, InvalidOperation
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.prompt import Prompt
 from rich.table import Table
@@ -34,6 +35,7 @@ err = Console(stderr=True)
 @app.command("pricing")
 def pricing_cmd(
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show the credit-to-USD rate, minimum purchase, and starter balance.
 
@@ -48,6 +50,10 @@ def pricing_cmd(
     finally:
         client.close()
 
+    if toon_output:
+        print(toon_encode(data))
+        return
+
     if json_output:
         print(json.dumps(data, indent=2, default=str))
         return
@@ -150,9 +156,10 @@ def history_cmd(
     limit: int = typer.Option(25, "--limit", help="Max rows to show"),
     offset: int = typer.Option(0, "--offset", help="Offset for pagination"),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show recent credit top-ups for your organization (free)."""
-    fmt = detect_format(json_output, False, False, False)
+    fmt = detect_format(json_output, False, False, toon_output)
     client = get_client()
     try:
         data = client.get("/credit-purchases", params={"limit": limit, "offset": offset})
@@ -166,6 +173,10 @@ def history_cmd(
         print(json.dumps(data, indent=2, default=str))
         return
 
+    if fmt == "toon":
+        print(toon_encode(data.get("results", [])))
+        return
+
     rows = data.get("results", [])
     if not rows:
         console.print("[dim]No credit purchases yet. Run `tl credits buy --amount-usd N`.[/dim]")

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/reports.py

@@ -4,6 +4,7 @@ import json
 import time
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
@@ -320,6 +321,7 @@ def create_report(
     ),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
     json_output: bool = typer.Option(False, "--json", help="Output raw JSON config"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
     timeout: int = typer.Option(300, "--timeout", help="Max orchestration time in seconds"),
 ) -> None:
     """Create a report from a natural-language prompt or a pre-built config.
@@ -366,14 +368,17 @@ def create_report(
             saved_prompts = [prompt]
 
         # --- Show preview ---
-        if json_output:
-            # Preview-only mode (--json without --yes): print the config and exit.
+        if json_output or toon_output:
+            # Preview-only mode (--json/--toon without --yes): print the config and exit.
             # With --yes, skip the preview emit entirely so the only thing on
-            # stdout is the single save-response JSON below — programmatic
-            # consumers can parse stdout with one json.loads() instead of having
+            # stdout is the single save-response payload below — programmatic
+            # consumers can parse stdout with one parser call instead of having
             # to split two documents.
             if not yes:
-                print(json.dumps(config, indent=2, default=str))
+                if toon_output:
+                    print(toon_encode(config))
+                else:
+                    print(json.dumps(config, indent=2, default=str))
                 raise typer.Exit(0)
         else:
             err.print()
@@ -398,7 +403,9 @@ def create_report(
         report_url = result.get("report_url", "")
         campaign_id = result.get("campaign_id", "")
 
-        if json_output:
+        if toon_output:
+            print(toon_encode(data))
+        elif json_output:
             print(json.dumps(data, indent=2, default=str))
         else:
             err.print()

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/schema.py

@@ -5,6 +5,7 @@ import re
 
 import typer
 import yaml
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.markdown import Markdown
 from rich.text import Text
@@ -79,11 +80,14 @@ def _try_render_yaml_tree(content: str) -> bool:
     return rendered
 
 
-def _show(db: str, json_output: bool, table: str | None = None) -> None:
+def _show(db: str, json_output: bool, table: str | None = None, toon_output: bool = False) -> None:
     client = get_client()
     try:
         params = {"table": table} if table else {}
         data = client.get(f"/raw/{db}/schema", params=params)
+        if toon_output:
+            print(toon_encode(data))
+            return
         if json_output:
             print(json.dumps(data, indent=2, default=str))
             return
@@ -108,6 +112,7 @@ def _show(db: str, json_output: bool, table: str | None = None) -> None:
 def pg_cmd(
     table: str = typer.Argument(None, help="Optional table name. When given, prints only that table's section in the same markdown format."),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show PostgreSQL schema reference (for `tl db pg`).
 
@@ -123,13 +128,14 @@ def pg_cmd(
         tl schema pg thoughtleaders_channel
         tl schema pg thoughtleaders_adlink --json
     """
-    _show("pg", json_output, table=table)
+    _show("pg", json_output, table=table, toon_output=toon_output)
 
 
 @app.command("fb")
 def fb_cmd(
     table: str = typer.Argument(None, help="Optional table name (`article_metrics` or `channel_metrics`). When given, prints only that table's section."),
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show Firebolt schema (live: tables and column types) for `tl db fb`.
 
@@ -144,12 +150,13 @@ def fb_cmd(
         tl schema fb article_metrics
         tl schema fb channel_metrics --json
     """
-    _show("fb", json_output, table=table)
+    _show("fb", json_output, table=table, toon_output=toon_output)
 
 
 @app.command("es")
 def es_cmd(
     json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
 ) -> None:
     """Show Elasticsearch document shape for `tl db es`."""
-    _show("es", json_output)
+    _show("es", json_output, toon_output=toon_output)

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/setup.py

@@ -13,6 +13,7 @@ import subprocess
 from pathlib import Path
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 
 from tl_cli import __version__
@@ -172,6 +173,7 @@ def _print_manual_instructions() -> None:
 @app.command("claude")
 def setup_claude(
     json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs, non-interactive)"),
 ) -> None:
     """Install the TL CLI plugin for Claude Code.
 
@@ -183,8 +185,8 @@ def setup_claude(
         tl setup claude
         tl setup claude --json
     """
-    if json_output:
-        _setup_noninteractive()
+    if json_output or toon_output:
+        _setup_noninteractive(fmt="toon" if toon_output else "json")
         return
 
     console.print()
@@ -283,8 +285,16 @@ def _install_standalone_skills_step(plugin_root: Path) -> None:
         console.print("  [yellow]![/yellow] No skills found to install")
 
 
-def _setup_noninteractive() -> None:
-    """Non-interactive setup for --json/agent usage."""
+def _emit_setup_result(result: dict, fmt: str) -> None:
+    """Emit a setup-status dict in JSON (default) or TOON."""
+    if fmt == "toon":
+        print(toon_encode(result))
+    else:
+        print(json.dumps(result, indent=2))
+
+
+def _setup_noninteractive(fmt: str = "json") -> None:
+    """Non-interactive setup for --json / --toon / agent usage."""
     result = {
         "cli_version": __version__,
         "marketplace_source": MARKETPLACE_SOURCE,
@@ -296,7 +306,7 @@ def _setup_noninteractive() -> None:
     if plugin_root is None:
         result["status"] = "error"
         result["error"] = "Plugin assets not found"
-        print(json.dumps(result, indent=2))
+        _emit_setup_result(result, fmt)
         raise SystemExit(1)
 
     claude_bin = _find_claude_binary()
@@ -326,7 +336,7 @@ def _setup_noninteractive() -> None:
     (version_dir / ".version").write_text(__version__)
 
     result["status"] = "ok"
-    print(json.dumps(result, indent=2))
+    _emit_setup_result(result, fmt)
 
 
 # --- OpenCode setup ---
@@ -375,6 +385,7 @@ def _setup_external_agent(
     target_dir: Path,
     post_install_lines: list[str] | None,
     json_output: bool,
+    toon_output: bool = False,
 ) -> None:
     """Shared body for the OpenCode / Gemini / Codex setup commands.
 
@@ -388,19 +399,20 @@ def _setup_external_agent(
     """
     plugin_root = _find_plugin_root()
 
-    if json_output:
+    if json_output or toon_output:
+        fmt = "toon" if toon_output else "json"
         result: dict = {"cli_version": __version__}
         if plugin_root is None:
             result["status"] = "error"
             result["error"] = "Plugin assets not found"
-            print(json.dumps(result, indent=2))
+            _emit_setup_result(result, fmt)
             raise SystemExit(1)
         result[f"{agent_binary}_detected"] = shutil.which(agent_binary) is not None
         count = _install_skill_trees(plugin_root, target_dir)
         result["skills_installed"] = count
         result["install_dir"] = str(target_dir)
         result["status"] = "ok"
-        print(json.dumps(result, indent=2))
+        _emit_setup_result(result, fmt)
         return
 
     console.print()
@@ -449,6 +461,7 @@ def _setup_external_agent(
 @app.command("opencode")
 def setup_opencode(
     json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs, non-interactive)"),
 ) -> None:
     """Install the TL CLI skills for OpenCode.
 
@@ -469,6 +482,7 @@ def setup_opencode(
             "The agent can use it when you ask about sponsorships, deals, channels, or brands.",
         ],
         json_output=json_output,
+        toon_output=toon_output,
     )
 
 
@@ -478,6 +492,7 @@ def setup_opencode(
 @app.command("gemini")
 def setup_gemini(
     json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs, non-interactive)"),
 ) -> None:
     """Install the TL CLI skills for the Gemini CLI.
 
@@ -496,12 +511,14 @@ def setup_gemini(
         target_dir=AGENTS_SKILLS_DIR,
         post_install_lines=None,
         json_output=json_output,
+        toon_output=toon_output,
     )
 
 
 @app.command("codex")
 def setup_codex(
     json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs, non-interactive)"),
 ) -> None:
     """Install the TL CLI skills for the Codex CLI.
 
@@ -520,4 +537,5 @@ def setup_codex(
         target_dir=AGENTS_SKILLS_DIR,
         post_install_lines=None,
         json_output=json_output,
+        toon_output=toon_output,
     )

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/commands/whoami.py

@@ -3,6 +3,7 @@
 import json
 
 import typer
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
@@ -206,8 +207,7 @@ def whoami(
         if fmt == "json":
             print(json.dumps(data, indent=2, default=str))
         elif fmt == "toon":
-            from pytoon import encode
-            print(encode(data))
+            print(toon_encode(data))
         elif fmt == "md":
             _render_whoami_md(data)
         else:

{thoughtleaders_cli-0.6.51 → thoughtleaders_cli-0.6.52}/src/tl_cli/output/formatter.py

@@ -11,6 +11,7 @@ import json
 import math
 import sys
 
+from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.table import Table
 
@@ -332,16 +333,14 @@ def _output_markdown(results: list[dict], columns: list[str], column_types: dict
 
 def _output_toon(results: list[dict], columns: list[str]) -> None:
     """TOON (Token-Oriented Object Notation) output for LLM consumption."""
-    from pytoon import encode
     # Build column-filtered rows for uniform tabular encoding
     rows = [{col: row.get(col) for col in columns} for row in results]
-    print(encode(rows))
+    print(toon_encode(rows))
 
 
 def _output_toon_single(record: dict) -> None:
     """TOON output for a single detail record."""
-    from pytoon import encode
-    print(encode(record))
+    print(toon_encode(record))
 
 
 _RIGHT_ALIGN_COLS = {"price", "cost", "cpm"}