thoughtleaders-cli 0.6.24__tar.gz → 0.6.25__tar.gz

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.24
+Version: 0.6.25
 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.24 → thoughtleaders_cli-0.6.25}/pyproject.toml

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

thoughtleaders_cli-0.6.25/skills/bulk-import/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: bulk-import
+description: Bulk-add or exclude a list of channels, brands, articles, or sponsorships from a ThoughtLeaders report (campaign). Superuser-only. Use when a request asks to import / add / exclude a batch of identifiers against a specific report ID — phrasings like "import these channels into report 1234", "add brands to campaign 5678", "exclude these channels from report Z".
+---
+
+# Bulk Import
+
+Wraps `tl bulk-import` — submits a list of identifiers against a report and polls until the import finishes. Reports which entities landed and which were skipped or newly created.
+
+## When to use
+
+Trigger on requests like:
+
+- "Import @mkbhd, @veritasium into report 1234"
+- "Add these brands to campaign 5678"
+- "Bulk-add this list of channels to report 999"
+- "Exclude these channels from report Z"
+
+If a single identifier is asked for, `tl bulk-import` still works (it accepts one). The reason to keep this skill separate from other report-edit flows: it's the only path that auto-creates channels from YouTube URLs / handles and brands from website domains.
+
+## Inputs to gather
+
+Before running the command, confirm:
+
+1. **Report ID** (`--campaign`) — required. If the user pastes a TL URL (e.g. `https://app.thoughtleaders.io/#/thoughtleaders?campaign=23859&...`), the integer after `campaign=` is the ID.
+2. **Entity type** — one of `channels`, `brands`, `articles`, `sponsorships`. Infer from context:
+   - YouTube URLs / handles / `UC…` IDs → `channels`
+   - Domains / brand slugs → `brands`
+   - Video URLs / IDs → `articles`
+   - AdLink integer IDs → `sponsorships`
+3. **Identifiers** — the actual list. Accepted shapes per entity:
+   - **channels**: numeric DB IDs, YouTube channel IDs (`UC…`), `@handles`, full YouTube URLs (`/@…`, `/channel/UC…`, `/user/…`)
+   - **brands**: numeric IDs, slugs, websites/domains (`example.com`)
+   - **articles**: video IDs or video URLs
+   - **sponsorships**: AdLink IDs (numeric only)
+4. **Include vs exclude** — default is include (add to the report). Pass `--exclude` only if the user explicitly wants to remove from the report.
+
+## How to invoke
+
+The command reads identifiers from a file (`--ids-file`) or stdin. For lists of more than a handful, write to a temp file:
+
+```bash
+# small list — stdin
+echo '@mkbhd
+@veritasium
+@lemmino' | tl bulk-import channels --campaign 1234
+
+# larger list — file
+tl bulk-import channels --campaign 1234 --ids-file ./channels.txt
+
+# exclusion
+tl bulk-import brands --campaign 5678 -f ./brands.txt --exclude
+```
+
+Short flags: `-c` for `--campaign`, `-f` for `--ids-file`.
+
+## Output
+
+JSON envelope on stdout:
+
+```json
+{
+  "task_id": "...",
+  "success_ids": [<int>, ...],
+  "success_ids_count": <int>,
+  "failed_ids": [...],
+  "failed_ids_count": <int>,
+  "newly_created_ids": [<int>, ...],
+  "not_created_channels_count": <int>
+}
+```
+
+Surface to the user:
+
+- **`success_ids_count`** — how many identifiers landed in the report.
+- **`newly_created_ids`** — channels/brands that didn't exist before and were created by this import. Mention that enrichment (subscriber stats, AI description, demographics for channels; logo/website metadata for brands) is queued and will populate over the next few minutes.
+- **`failed_ids` / `not_created_channels_count`** — anything that couldn't be resolved or created. Show them so the user can fix and retry.
+
+## Errors
+
+- **403** → caller isn't a superuser. Stop and tell the user; this skill is gated.
+- **400** → bad input. Show the `detail` verbatim (usually missing field, unknown entity, or all-empty identifiers).
+- **402** → out of credits. Tell the user to top up.
+- **Connection failed** → transient network issue. Retry once; if it persists, ask the user.
+
+## What this skill does NOT do
+
+- Doesn't create reports — that's a separate skill (`tl-report-builder`).
+- Doesn't change report metadata (title, description, columns, filters).
+- Doesn't validate identifiers ahead of time — let `tl bulk-import` do the lookup and report back which ones failed. Pre-checking via `tl channels show` is wasteful.

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/skills/tl/references/postgres-schema.md

@@ -207,6 +207,17 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 | `description` | text | LLM-generated description of the channel. Sometimes useful as a regex-target for thematic filtering when the integer category is too coarse (e.g. filtering "Technology" cat 15 down to actual tech reviewers via keywords like `tech|gadget|review|software`). |
 | `evergreenness` | float | Cached evergreen score |
 
+#### Hallucination shapes to avoid
+
+When composing `SELECT ... FROM thoughtleaders_channel ...`, do not improvise column names from semantic intuition — consult the column table above. Failed guesses return *"column '\<name\>' does not exist"* and cost a round-trip. Recurring shapes:
+
+- ❌ **Suffix/qualifier variants of date columns** (e.g. an `_max` / `latest_` / `_date` form when the canonical column has neither). Date columns above use bare names.
+- ❌ **Platform-name-prefixed ID forms** (e.g. a platform-name prefix when the canonical column uses a neutral `external_` prefix). See the column table for the actual ID column.
+- ❌ **Bare-noun forms without the table-prefix** (e.g. `name` instead of `channel_name`). This table prefixes its display fields with `channel_` to avoid SQL keyword collisions and ambiguity in joins.
+- ❌ **User-facing-term forms used as SQL column names** (the user-facing word is sometimes different from the SQL column name; consult [business-glossary](business-glossary.md) for the canonical mapping when the two diverge).
+
+When the canonical column you need isn't obvious from the table above, consult the column table first. Do **not** rely on a 400 to correct you, and do **not** fall back to `information_schema.columns` as the recovery path — that's a regression marker too.
+
 #### `content_category` Constants
 
 Source of truth: `thoughtleaders.taxonomies.ContentCategory` (Django `IntEnum` in the main `thoughtleaders` repo).

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/skills/tl-report-builder/SKILL.md

@@ -1608,6 +1608,8 @@ Render as Markdown links in the table cell — *not* the bare ID, *not* the YouT
 
 If the slug is missing or empty for a row, fall back to the ID-based path the platform exposes (e.g. `https://app.thoughtleaders.io/youtube/id-<channel_id>`); never fall back to the YouTube URL — that takes the user *away* from TL. The Phase 2 sample query must include the slug column alongside the rendered fields, otherwise the table can't link properly.
 
+**Sample-row enrichment column names — read from the canonical schema, do NOT improvise.** When the rendered table needs columns beyond what the initial ES sample returned (typically a slug for the hyperlink and a "last published" date), look up the column names in [`tl/references/postgres-schema.md` → `thoughtleaders_channel`](../tl/references/postgres-schema.md#thoughtleaders_channel-youtube-channels) before composing the PG query. Agents have improvised semantically-plausible column names from intuition (date-shape variants, platform-name-prefixed ID forms, bare-noun forms without table prefix, user-facing-term forms), hit a 400 with *"column '\<name\>' does not exist"*, then run an `information_schema.columns` fishing query to recover — a wasted round-trip that the canonical column catalogue eliminates. **If you find yourself about to write a `SELECT ... FROM thoughtleaders_channel WHERE ...` query and you're not sure of a column name, consult the schema reference first** — do not guess and rely on the 400 to correct you, and do not fall back to `information_schema.columns` as the recovery path. See the schema reference's "Hallucination shapes to avoid" subsection for the recurring guess patterns.
+
 21. **No side-channel deliverables.** The skill produces exactly two output shapes: (a) a saved TL Campaign + a campaign URL (save mode), or (b) an in-chat preview with the sample-rows table + takeaways + save tail (preview mode). It does NOT write CSVs, Markdown reports, or any other "data dump" file to disk as a deliverable. A real run for FRÉ Skincare wrote a CSV to `<temp>\fre-skincare-shortlist.csv` and pointed the user at it as the "full list" — that's a fabricated alternative deliverable that bypasses the TL report-creation flow. If the user wants more than the preview shows, the answer is "save it as a campaign and run it" — not "I'll dump CSV". The only filesystem write the skill is allowed to make is the `<system-temp>/tl-report-builder-<slug>.json` transport file used in step 1 of the save mechanics, and even that is a transport (deleted whenever) — never a deliverable.
 22. **Phases 1–4 always run; the skill never short-circuits to a chat-only data answer.** When the skill is invoked, the output is **always** a Campaign (save mode) or a Phase-4 preview (preview mode). Bypassing Phase 1–4 to produce a verification table, an analyst summary, a list cross-check, or any other "I'll just answer this directly in chat" deliverable is a regression bug. Real example to internalise: a prompt of *"Brands sponsoring Linus Tech Tips in the past 6 months: dbrand, Private Internet Access, Squarespace, Vessi, Secretlab, UGREEN, Odoo, Dell, Razer, Saily"* should route through Phase 1 → Type 2 brands report scoped to channel 1788 + last 180 days → Phases 2/3/4 → preview with the user's seed brands as a starting filter and the takeaways calling out *"your seed list is accurate but incomplete — TL data shows 60 distinct sponsors over 131 videos; top missing are War Thunder (7), Boot.dev (6), DeleteMe (6)…"*. Instead, a recent run produced exactly that analytical content **as a free-floating markdown table in chat** — no FilterSet emitted, no columns picked, no widgets, no save option. The analytical insight is welcome as a takeaway; it is **not** a substitute for the report. If you find yourself replying with a markdown table directly, ask: am I about to ship a Phase-4 preview, or am I bypassing the phases? The answer must always be the former.
 23. **No ad-hoc data-engineering pipelines.** The skill does NOT write Python consolidation scripts, multi-stage CSV merge tools, dedupe scripts, false-positive filters as standalone files, or any other custom data pipeline as part of producing the deliverable. The data plane is fixed: `tl db pg` (PG), `tl db es` (ES), `tl db fb` (Firebolt). Phase 2 issues queries against these directly to compose a FilterSet and validate it; that's the entire data-side surface. A real aviation/non-MSN run produced this anti-pattern: the agent issued five separate PG queries each writing a CSV (`/tmp/aviation_by_name.csv`, `/tmp/aviation_desc.csv`, `/tmp/aviation_desc2.csv`, `/tmp/aviation_desc3.csv`, `/tmp/aviation_pilot_desc.csv`), wrote a `consolidate_aviation.py` script to merge + dedupe + filter false positives, hit a Windows-vs-Linux `/tmp/` path mismatch, debugged it with `cygpath`, eventually rewrote the script to use `%LOCALAPPDATA%\Temp`, then produced `aviation_consolidated.csv` as the "full list". **None of this is the skill's job.** The right shape: one ES query with `terms` / `bool.should` filters covering the niche keywords + the `creator_countries` filter + `msn_channels_only: false` + `is_active: true` → get count + sample → emit the FilterSet → preview. If the skill's narration is starting to read like a data engineer's bash session ("Run consolidation script", "Try /tmp path resolution", "Resolve /tmp via cygpath", "Find where /tmp files actually are"), stop — the skill has gone off the rails. Restart from Phase 1 with a single composed query.

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.6.25/src/tl_cli/commands/bulk_import.py

@@ -0,0 +1,120 @@
+"""tl bulk-import - bulk-add or exclude entities from a report.
+
+Superuser-only on the server side. Submits a list of identifiers
+(channels / brands / articles / sponsorships) against a target report
+and polls until the import completes.
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+
+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
+
+err = Console(stderr=True)
+
+POLL_INTERVAL_SEC = 2
+POLL_TIMEOUT_SEC = 600
+VALID_ENTITIES = ("channels", "brands", "articles", "sponsorships")
+
+
+def _read_ids(ids_file: str | None) -> list[str]:
+    if ids_file:
+        text = Path(ids_file).read_text()
+    elif not sys.stdin.isatty():
+        text = sys.stdin.read()
+    else:
+        err.print("[red]Provide --ids-file or pipe identifiers via stdin.[/red]")
+        raise typer.Exit(2)
+    ids = [line.strip() for line in text.splitlines() if line.strip()]
+    if not ids:
+        err.print("[red]No identifiers found.[/red]")
+        raise typer.Exit(2)
+    return ids
+
+
+def _poll_until_done(client, task_id: str) -> dict:
+    deadline = time.time() + POLL_TIMEOUT_SEC
+    with err.status(f"[bold blue]Importing... (task {task_id})[/bold blue]"):
+        while time.time() < deadline:
+            time.sleep(POLL_INTERVAL_SEC)
+            data = client.get(f"/bulk-import/poll/{task_id}")
+            if data.get("finished"):
+                if data.get("error"):
+                    err.print(f"[red]Import failed: {data.get('error')}[/red]")
+                    raise typer.Exit(1)
+                return data.get("end_result") or {}
+    err.print(f"[red]Polling timed out after {POLL_TIMEOUT_SEC}s. Task still running: {task_id}[/red]")
+    raise typer.Exit(3)
+
+
+def bulk_import_command(
+    entity: str = typer.Argument(..., help=f"Entity type: one of {', '.join(VALID_ENTITIES)}"),
+    campaign: int = typer.Option(..., "--campaign", "-c", help="Target report ID"),
+    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)"),
+) -> None:
+    """Bulk-import entities into a report.
+
+    Accepts a list of identifiers per entity:
+      channels      -> numeric IDs, YouTube channel IDs (UC...), @handles, full URLs
+      brands        -> numeric IDs, slugs, websites/domains
+      articles      -> video IDs or URLs
+      sponsorships  -> AdLink IDs (numeric)
+
+    Submits the list and polls until the import completes. Channels/brands
+    that aren't already on file get auto-created from YouTube / their
+    website. Enrichment (metadata, AI description, demographics) is queued
+    and lands a few minutes after the import returns.
+
+    Examples:
+        tl bulk-import channels --campaign 23859 --ids-file ./channels.txt
+        echo "@mkbhd" | tl bulk-import channels -c 23859
+        tl bulk-import brands -c 23859 -f ./brands.txt --exclude
+
+    Requires superuser permission - non-superusers get a 403.
+    """
+    if entity not in VALID_ENTITIES:
+        err.print(f"[red]entity must be one of: {', '.join(VALID_ENTITIES)}[/red]")
+        raise typer.Exit(2)
+
+    ids = _read_ids(ids_file)
+
+    body = {
+        "campaign_id": campaign,
+        "entity": entity,
+        "entity_ids": ids,
+        "include": not exclude,
+    }
+
+    err.print(f"[dim]Submitting {len(ids)} {entity} to report {campaign} (include={not exclude})...[/dim]")
+
+    client = get_client()
+    try:
+        submit = client.post("/bulk-import", json_body=body)
+    except ApiError as e:
+        handle_api_error(e)
+        raise typer.Exit(1)
+
+    task_id = submit.get("task_id")
+    if not task_id:
+        err.print(f"[red]No task_id in submit response: {submit}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        result = _poll_until_done(client, task_id)
+    finally:
+        client.close()
+
+    output = {"task_id": task_id, **result}
+    if json_output or not sys.stdout.isatty():
+        json.dump(output, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        Console().print_json(json.dumps(output))

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.25}/src/tl_cli/main.py

@@ -16,6 +16,7 @@ from tl_cli.commands.ask import app as ask_app
 from tl_cli.commands.balance import app as balance_app
 from tl_cli.commands.changelog import changelog_command
 from tl_cli.commands.brands import app as brands_app
+from tl_cli.commands.bulk_import import bulk_import_command
 from tl_cli.commands.channels import app as channels_app
 from tl_cli.commands.db import app as db_app
 from tl_cli.commands.deals import app as deals_app
@@ -93,6 +94,10 @@ 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")
+# Direct command (not a sub-Typer) so `tl bulk-import <entity> --campaign <id>`
+# parses ENTITY as the positional and --campaign as a command option, instead
+# of Typer treating `--campaign` as a group-level flag that has to come first.
+app.command(name="bulk-import")(bulk_import_command)
 app.add_typer(db_app, name="db")
 
 # Discoverability