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

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

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.6.23",
+  "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.23 → thoughtleaders_cli-0.6.25}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.6.23"
+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.23 → 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).
@@ -270,6 +281,7 @@ Common hallucinations the agent has tried in real runs (each wasted a round-trip
 Cited regression markers from real runs:
 - AI/marketing channels run: tried `thoughtleaders_topic` (singular — table doesn't exist), then `WHERE is_active = TRUE`. Three round-trips before consulting `information_schema`.
 - Travel/digital-nomad run: tried `SELECT id, name, type, parent_id FROM thoughtleaders_topics WHERE name ILIKE ANY(...)`.
+- **Name-pattern WHERE-clause loop (general pattern)**: when the user's niche has no obvious curated topic, agents have run progressively broader name-pattern `WHERE` queries against this table — typically two or three rounds of `WHERE name ILIKE '%<term1>%' OR name ILIKE '%<term2>%' OR ...`, sometimes interleaved with an `information_schema.columns` inspection between them — each returning zero rows. The correct path is one canonical fetch (above) + the matcher's `summary.no_match: true` verdict for the off-taxonomy case. **A zero-row canonical fetch (no WHERE clause) is a data-plane failure, NOT off-taxonomy** — surface the failure rather than silently falling through to keyword_research.
 
 If a query against this table errors with *"column '\<X\>' does not exist"*, that's the regression marker — go back to the verbatim fetch above.
 

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

@@ -321,11 +321,16 @@ USER_QUERY
 │     • Type-8: count_sponsorships, sum_price (axis branches on          │
 │       publish_status — send_date for proposals, purchase_date for sold)│
 │     • histogram_bucket_size set per date range                         │
+│     • Generate report_title + report_description from final config     │
+│       (must happen BEFORE validation — both fields are mandatory       │
+│        on save and the validation step below checks for them)          │
 │     • PERFORM FINAL JSON-SHAPE VALIDATION of the campaign config:      │
 │         – All Phase 2 + Phase 3 + Phase 4 outputs compose validly      │
 │         – API-contract pre-check (type=2 DYNAMIC, valid report_type,   │
-│           non-empty columns, sort references an emitted column)        │
-│     • Generate report_title + report_description from final config     │
+│           non-empty columns, sort references an emitted column,        │
+│           report_title ≤60 chars non-empty, report_description         │
+│           1–3 sentences non-empty — both mandatory on save; CLI        │
+│           rejects with HTTP 400 if either is missing)                  │
 │     • Compose key takeaway insights                                    │
 │                                                                          │
 │   ↘ FOLLOW-UP TRIGGERS:                                                 │
@@ -474,7 +479,13 @@ Each tool fires only when its criteria are explicitly met (no automatic / specul
 ### T1 — `tools/topic_matcher.md`
 **Fires when**: `ReportType ∈ {1, 2, 3}` AND USER_QUERY mentions a topic concept that could plausibly map to a curated topic in `thoughtleaders_topics`.
 **Skipped when**: `ReportType == 8` (sponsorships don't use topic matching at the SQL level) OR USER_QUERY is purely an entity-name lookup ("emails for these channels").
-**How to fetch the live topics**: see the `tl-cli:tl` skill's Postgres-schema reference — [`tl/references/postgres-schema.md` → `thoughtleaders_topics`](../tl/references/postgres-schema.md#thoughtleaders_topics-curated-topic-taxonomy). That's the canonical home for the fetch query, column list, and "do not guess" regression markers. Don't restate the SQL here.
+**How to fetch the live topics**: use the canonical fetch SQL documented at [`tl/references/postgres-schema.md` → `thoughtleaders_topics` → Fetch query](../tl/references/postgres-schema.md#fetch-query-canonical--use-verbatim). Single query, no `WHERE` clause; table has <20 rows so client-side filtering after the full fetch is free.
+
+**Agent-behaviour rules** (encoded in [`tools/topic_matcher.md`](tools/topic_matcher.md); regression markers catalogued in the schema reference's "Cited regression markers" list):
+
+- Don't push name-pattern `WHERE` clauses into the fetch query — agents have burnt credits + round-trips on this in multiple real runs.
+- Don't run `information_schema.columns` to inspect the table.
+- **Empty fetch ≠ off-taxonomy.** A zero-row result from the canonical (no-`WHERE`) fetch is a data-plane failure — surface it rather than silently falling through to T2. Off-taxonomy is when the fetch returns rows but the matcher emits `summary.no_match: true`.
 **Output**: per-topic verdicts (strong/weak/none) + summary. If `summary.strong_matches` non-empty, the topic's curated `keywords[]` array drives the FilterSet's `keywords` field (with per-position `content_fields` set via `keyword_content_fields_map` when a keyword targets a non-default match surface). Phase 2 may also emit the matched topic IDs directly via the FilterSet's `topics` field — both paths are valid; pick by intent.
 
 **Narrow-first FilterSet assembly (mandatory — applies to topic-strong + keyword_research paths both)**: Phase 2c MUST assemble the FilterSet with the **narrowest viable shape first**, then validate. Expand only if the count is below the type's narrow threshold. The two narrowing levers, **ranked by impact on noisy-niche / multilingual runs**:
@@ -1468,7 +1479,9 @@ Phase 4 is the terminal phase. It picks widgets, performs FINAL JSON-shape valid
 ### Process
 
 1. **Pick widgets via `tools/widget_builder.md`.** Inject `REPORT_TYPE`, `FILTERSET`, `COLUMNS`, `ROUTING_METADATA`, and the matching widget schema (`references/intelligence_widget_schema.json` for types 1/2/3; `references/sponsorship_widget_schema.json` for type 8). The builder emits `{ widgets, histogram_bucket_size, _widget_metadata }`. **The selection rule is: emit only widgets that add value to the user's original prompt.** A widget earns its slot if it answers a question the user implicitly cares about (intent), surfaces a metric tied to a filter the user named (niche), or shows a trend over the date scope they specified. Don't pad to hit 6 — emit fewer (down to 4) if the extras don't answer something. The builder handles type-8 axis branching and intent-driven swaps per the schema's `_tl_intent_overrides`.
-2. **FINAL JSON-shape validation pass.** Verify the composed config:
+2. **Generate `report_title` and `report_description`** from the FilterSet + the user's original NL request. Title ≤ 60 chars; description 1–3 sentences summarizing intent + key filters. **Do this BEFORE step 3's validation pass** — both fields are mandatory on save, so the validation in step 3 needs to see them populated.
+3. **FINAL JSON-shape validation pass.** Verify the composed config:
+   - **`report_title` is a non-empty string ≤ 60 chars AND `report_description` is a non-empty 1–3 sentences.** Both fields are **MANDATORY** on `tl reports create` — the CLI rejects with HTTP 400 `Missing required field: report_title` (or `report_description`) if either is missing. If step 2 (title/description generation) hasn't run yet, run it FIRST, then come back to this check. Verbatim regression marker (real run, LATAM cooking 2026-05-11): saved config omitted `report_title`; first `tl reports create --config-file <path> --yes` returned `Error (400): Missing required field: report_title` and the agent had to edit the transport file and retry. **Fail closed at this validation step rather than discovering the missing field at save time** — a save-side 400 wastes a CLI round-trip and a credit charge.
    - Every field in `filterset` exists in the schema and matches its declared type.
    - Every column in `columns` is in the type's column file.
    - Every aggregator in `widgets` is in the matching catalog (intelligence for 1/2/3, sponsorship for 8).
@@ -1477,7 +1490,6 @@ Phase 4 is the terminal phase. It picks widgets, performs FINAL JSON-shape valid
    - When `cross_references` is present, `report_type ∈ {1, 3}`.
    - When `filters_json.similar_to_channels` is present, no overlapping `keywords` / `topics` fields.
    - `type = 2` (DYNAMIC) and `report_type ∈ {1, 2, 3, 8}` — Campaign-model contract for the API endpoint.
-3. **Generate `report_title` and `report_description`** from the FilterSet + the user's original NL request. Title ≤ 60 chars; description 1–3 sentences summarizing intent + key filters.
 4. **Compose key takeaway insights** — see "Takeaway-composition rules" below. These are the headline observations the user reads in the Phase 4 message. The `_validation` block from Phase 2 carries through here — narrow-result notes, sample_judge reasoning, and validation_concerns are all surfaced as takeaways.
 5. **Emit the final deliverable.**
 
@@ -1596,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.23 → thoughtleaders_cli-0.6.25}/skills/tl-report-builder/tools/topic_matcher.md

@@ -26,7 +26,23 @@ The orchestration injects two values:
 
 ### How to fetch the topics
 
-The fetch query, the column list, and the negative-column regression markers all live in the canonical Postgres-schema reference in the `tl-cli:tl` skill: **[`tl/references/postgres-schema.md` → `thoughtleaders_topics`](../../tl/references/postgres-schema.md#thoughtleaders_topics-curated-topic-taxonomy)**. Schema-shaped facts belong in that reference, not in tool text. Use the verbatim fetch query documented there. **Do not restate or paraphrase the schema here.** If you find yourself about to type `SELECT … FROM thoughtleaders_topics …` from memory, stop and consult the reference file instead. This tool's job is to score topics against the user query; the schema reference's job is to say what the underlying table looks like.
+Use the canonical fetch SQL from the schema reference: **[`tl/references/postgres-schema.md` → `thoughtleaders_topics` → Fetch query](../../tl/references/postgres-schema.md#fetch-query-canonical--use-verbatim)**. The table has fewer than 20 rows; client-side filtering after the full fetch is free — **filter the results in your head, not in SQL.** Column catalogue and "do not exist" markers live in the same reference; consult it when you need column-level facts.
+
+**Agent-behaviour rules** (these are agent-side, not schema-shaped — the failure modes pinned here are catalogued in the schema reference's "Cited regression markers" list):
+
+- ❌ Don't push a name-pattern `WHERE` clause into the query (e.g. `WHERE name ILIKE '%crypto%' OR name ILIKE '%web3%' OR ...`). Whatever the user said, the right path is fetch-all → match in your head.
+- ❌ Don't run `information_schema.columns` to inspect the table. If you need column names, read the schema reference linked above.
+- ❌ Don't retry the canonical fetch with broader patterns or different fields when the matcher reads the fetched rows and emits `summary.no_match: true` — that's off-taxonomy. Fall through to keyword_research (T2).
+
+**Interpreting the fetch result:**
+
+| Fetch result | Meaning | Next step |
+|---|---|---|
+| Non-empty, matcher emits ≥1 `strong` / `weak` verdict | Curated match found | Use the matched topic's `keywords[]` array in the FilterSet (topic-strong path) |
+| Non-empty, matcher emits all `none` verdicts (`summary.no_match: true`) | **Off-taxonomy** — niche has no curated topic | Fall through to keyword_research (T2) |
+| **Empty (zero rows returned)** | **Data-plane failure or empty taxonomy — NOT off-taxonomy.** The canonical fetch has no `WHERE` clause; an empty result means either the table is empty, the database returned an error, or the request was truncated. | Surface the failure rather than silently falling through to T2. If a re-fetch also returns empty, escalate to the user — silently bypassing curated topic matching on a real data-plane failure would mask the bug. |
+
+The "Cited regression markers" section in the schema reference catalogues the anti-pattern shapes that have occurred in practice. Read it when you recognise the failure-mode shape in your own output.
 
 ---
 

{thoughtleaders_cli-0.6.23 → 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.23"
+__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.23 → 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