thoughtleaders-cli 0.9.22__tar.gz → 0.9.24__tar.gz

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.22
+Version: 0.9.24
 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.9.22 → thoughtleaders_cli-0.9.24}/pyproject.toml

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

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl/SKILL.md

@@ -95,7 +95,7 @@ Other key concepts:
   - Org scoping for sponsorships is profile-mediated: a sponsorship belongs to your org if **either** `advertiser_profile.organization` (brand side) **or** the adspot seller's organization — `ad_spot.publisher` → that user's profile → `organization` (publisher side) — matches yours. Representing the channel does not surface its deals.
 - **MSN** (Media Selling Network) — the ~12k YouTube channels that have opted in to receive sponsorship offers. A channels is in the MSN group if the `channel.media_selling_network_join_date` field is not null.
 - **MBN** (Media Buying Network) — the brand-side counterpart to MSN: brand profiles that have opted in to receive proposed sponsorships. A profile is in the MBN group if the `profile.media_buying_network_join_date` field is not null.
-- **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the ~170 channels TL has the closest working relationship with. A channel is in the TPP group if `channel.is_tpp` is True. **Prefer TPP channels when booking**: they respond fastest, are the easiest to close, and don't need an outreach round-trip — treat them as immediately bookable. TPP is a strict subset of MSN, so the same booking rules (one active mention adspot, etc.) apply.
+- **TPP** (ThoughtLeaders Partner Program, a.k.a. "TL channels") — the ~170 channels TL has the closest working relationship with. A channel is in the TPP group if `channel.is_tpp` is True. **Prefer TPP channels when booking**: they respond fastest, are the easiest to close, and don't need an outreach round-trip — treat them as immediately bookable. TPP is a strict subset of MSN, so the same booking rules (one preferred mention adspot, etc.) apply.
 - **`demographics_updated_at`** (on channels) — If non-null, the channel has demographics screenshots on file. If null, no demographics screenshots have been uploaded. Use this to check whether a channel has demographics data from screenshots.
 - **`subscribers`** (on channels) — the channel's subscriber count.
 - **`projected_views`** (on channels) — projected views per video on that channel. Forward-looking estimate. May be null when not yet computed. ⚠️ NOT actual views and NOT ad-industry "impressions" (ads served).
@@ -103,7 +103,7 @@ Other key concepts:
 - **`views_guarantee`** (on sponsorships) — projected/guaranteed impressions for the sponsorship. Numeric.
 - **Sponsorship detail fields** (returned by `tl sponsorships show <id> --json`) — the detail payload includes `integration` (raw int), `publish_count`, `common_name`, `outreach_email`, nested `publisher` (`first_name`, `last_name`, `email`), nested `brand_contact` (`first_name`, `last_name`, `email`), and `brand.organization_name`. Use these when generating IOs, contracts, or outreach.
 - **CPM** has two distinct meanings depending on level — pick the one the user actually wants:
-  - **Channel CPM** = `(adspot.price / channel.projected_views) * 1000` — projected price per thousand projected views. Used for pricing decisions **before** a sponsorship is sold. Available for channels with active adspots via `tl channels show <channel_id>`.
+  - **Channel CPM** = `(adspot.price / channel.projected_views) * 1000` — projected price per thousand projected views. Used for pricing decisions **before** a sponsorship is sold. Available for channels with preferred adspots via `tl channels show <channel_id>`.
   - **Sponsorship CPM** = calculated in either of two ways: if `views` is present, then CPM is `(sponsorship.price / sponsorship.views) × 1000`, meaning realized cost per thousand actual views, computed post-publication. If `views` is null, Compute from the sponsorship's `price` and the channel's `projected_views` fields.
   - Where possible, calculate the correct CPM in a SQL expression.
 - **Sponsorship dates** — each sponsorship has four distinct dates, useful for different queries:

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl/references/business-glossary.md

@@ -56,7 +56,7 @@ Maps business terms to database concepts.
 - A channel can have **multiple ad spots** because different people sell the same channel (talent manager, direct, multiple agencies)
 - Ad spots are the **catalogue** — adlinks are **instances** of catalogue items
 - Price/cost on adspot = list/catalog values; price/cost on adlink = actual deal values
-- **Only one active adspot with integration=mention per channel at any time** (MSN rule)
+- **Only one preferred adspot with integration=mention per channel at any time** (MSN rule)
 
 ## Ownership & Accountability
 
@@ -79,7 +79,7 @@ Maps business terms to database concepts.
 - Key data: **who is the contact** to buy the ad from
 - `thoughtleaders_channel.media_selling_network_join_date` = when channel joined MSN
 - `thoughtleaders_channel.is_tpp` = TPP channel — TL's closest partners, a strict subset of MSN. **Prefer when booking**: fastest response, easiest to close. Not a gating flag; not a process barrier.
-- **Rule:** Only one active adspot with `integration=mention` per channel at any time
+- **Rule:** Only one preferred adspot with `integration=mention` per channel at any time
 - MSN quality depends on having current, accurate contact info
 
 ## Channels & Audience

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl/references/postgres-schema.md

@@ -165,8 +165,9 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 | `channel_id` | int FK | → `thoughtleaders_channel.id` |
 | `price` | numeric | List/catalogue price |
 | `cost` | numeric | List/catalogue cost |
-| `integration` | int | 1=YouTube Mentions (live reads). Only one active mention-type adspot per channel. |
-| `is_active` | boolean | Active flag |
+| `integration` | int | 1=YouTube Mentions (live reads). Only one preferred mention-type adspot per channel. |
+| `is_preferred` | boolean | The channel's preferred spot, the one new proposals are booked on |
+| `is_active` | boolean | False = deactivated, unusable, kept only for its AdLinks. Client sandboxes never show deactivated spots or their AdLinks |
 | `publisher_id` | int FK | → `auth_user.id` (NOT `thoughtleaders_profile.id` — see gotcha below) |
 
 ### Key columns for the `thoughtleaders_channel` table

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl-keyword-research/SKILL.md

@@ -23,6 +23,33 @@ description: |
   common is X". Also invoke for HELP asks about this skill — "help", "how
   does keyword research work", "what are my options", "describe this skill" —
   answered free from the built-in guide, no queries run.
+output-schema:
+  type: object
+  required: [keyword_groups, keyword_operator, assumptions]
+  properties:
+    keyword_groups:
+      type: array
+      items:
+        type: object
+        required: [text]
+        properties:
+          text: {type: string}
+          content_fields:
+            type: array
+            items: {type: string}
+          exclude: {type: boolean}
+    keyword_operator: {type: string, enum: [OR, AND]}
+    assumptions:
+      type: array
+      items: {type: string}
+    dropped:
+      type: array
+      items:
+        type: object
+        required: [text, reason]
+        properties:
+          text: {type: string}
+          reason: {type: string}
 ---
 
 # tl-keyword-research — topic → validated filter set + the results you choose
@@ -69,6 +96,33 @@ verbatim via `search_channels.py --group` / `search_videos.py --group`.
 
 `<SKILL_DIR>` below is this skill's directory (the one holding `SKILL.md`).
 
+## On the ThoughtLeaders platform
+
+The same skill also runs on the ThoughtLeaders platform, when a user starts
+keyword research from their dashboard. You are on the platform when the tools
+`kw_probe` and `kw_validate` are available. The method in this file applies
+unchanged, with these differences:
+
+- **No shell and no sub-agents.** Stages that run a script or an agent carry
+  an *On the platform* note naming the tool to use instead.
+- **Nobody to ask.** The task gives you the path (quick or deep) and the
+  deliverable. Make every scope call yourself and record it in `assumptions`.
+  Run the deep path autonomously: no checkpoint after round 3.
+- **Titles and summaries only.** Search the `title` and `summary` fields,
+  never `transcript`.
+- **Stop after Stage 4.** The platform builds the trend data, channel tiers,
+  report link and previews from your final groups, so skip Stage 5 and the
+  scripts in Stage 6.
+- **Decide, don't count.** Finish with `submit_result`, shaped by this
+  skill's `output-schema`: the final keyword groups, the operator, your
+  assumptions, and the groups you dropped with a reason. Never put counts or
+  channel figures in the result.
+- **Narrate with `report_progress`.** Call it at the start of each stage with
+  the stage name exactly as the pipeline table writes it (`Set up`, `Expand`,
+  `Probe`, `Validate keywords`, `Refine`), instead of messaging the user.
+- **References.** Read `references/elasticsearch-content-search.md` with
+  `read_skill_file`.
+
 ## When to invoke / skip
 
 Invoke when the user wants **videos or channels by content** (topics, concepts,
@@ -234,6 +288,10 @@ index's samples, and every web-sourced name earns its place through the same
 probe + validation as any other candidate (no benefit of the doubt; a
 hallucinated name probes to `count: 0` and drops).
 
+*On the platform:* use `web_search` (at most two searches) in place of the
+`keyword-entity-resolver` agent, then add each name and its spelling variants
+to your candidates yourself, following Stage 1's rules.
+
 ### Stage 1 — Expand: go wide, go deep, go creative
 
 A shallow synonym list is the #1 failure mode. Coverage is won or lost here.
@@ -271,6 +329,11 @@ Rules:
 
 ### Stage 2 — Probe (`probe.py`)
 
+*On the platform:* call `kw_probe` with the candidates and the same options
+`probe.py` takes (`level`, `mode`, `fields`, `samples`, `content_type`,
+`since`, `until`). It returns the counts; the samples stay with the platform
+for `kw_validate`.
+
 One ES query per candidate → counts + samples for validation:
 
 ```bash
@@ -322,6 +385,11 @@ surviving variants before delivery.
 This fixes "the word is there but the topic isn't" — the step that separates
 this skill from a free YouTube search.
 
+*On the platform:* call `kw_validate` on the probe with the verbatim intent. It
+runs the relevance check and the strict-majority rule, and returns the kept
+and dropped keywords. Scope calls are yours: decide them and record them in
+`assumptions`.
+
 **Inline (≤ ~15 candidates):** read each keyword's `samples` against the
 verbatim intent. Drop off-intent keywords, `count: 0`, and redundant
 `subsumed_by` duplicates.
@@ -448,8 +516,14 @@ then fold the answers into the groups and the validators' TOPIC/NOT lines.
 run ≥3 rounds, stop when fitness stops improving (sane cap ~6 rounds), note
 that you ran autonomously.
 
+*On the platform:* always run autonomously, measuring with `kw_probe` (mode
+`sqs`) and re-validating with `kw_validate`.
+
 ### Stage 5 — Materialize the chosen deliverables
 
+*On the platform:* skip this stage. The platform builds the deliverables from
+your final groups.
+
 Everything here takes the final filter verbatim via `--group`, so what you
 deliver is exactly what the filter selects.
 
@@ -541,6 +615,11 @@ on-topic uploads. Tell the user when one channel dominates and offer
 
 ### Stage 6 — Deliver (`build_report.py`)
 
+*On the platform:* don't run `build_report.py` and don't offer to save. Call
+`submit_result` with the groups in the same shape (`text`, plus
+`content_fields` / `exclude` where needed); the platform prunes them,
+translates them into the report grammar and builds the link.
+
 Hand the validated groups to the builder — start from `select_keywords.py
 --apply`'s `groups`, adding per-group `content_fields` / `exclude` as needed:
 

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl-keyword-research/scripts/build_report.py

@@ -39,7 +39,15 @@ Input (stdin JSON):
     }
 
 Output (stdout): a single JSON object — see OUTPUT CONTRACT at the bottom.
+
+Library use: the file is import-safe (standard library only, nothing runs at import),
+so another Python program can load it by path and call `build(spec, *, app_url=...)`.
+`spec` is the parsed input object above; the return value is the object the command
+prints. `build` leaves `spec` untouched and returns fresh structures. A bad spec raises
+`ReportSpecError` (a `ValueError`). Library functions never print, read stdin or exit.
 """
+from __future__ import annotations
+
 import argparse
 import json
 import re
@@ -116,6 +124,10 @@ DEFAULT_FIELDS = {
 }
 
 
+class ReportSpecError(ValueError):
+    """The spec handed to `build` is unusable."""
+
+
 def tokens(text):
     return _TOKEN_RE.findall(text.lower())
 
@@ -389,33 +401,23 @@ def build_report_config(filter_set, report_type_int, title, description):
     }
 
 
-def main():
-    ap = argparse.ArgumentParser(
-        description="Build the keyword-research deliverable (filter set + report link) from validated groups."
-    )
-    ap.add_argument("--app-url", default=DEFAULT_APP_URL, help=f"App base URL (default {DEFAULT_APP_URL})")
-    args = ap.parse_args()
-
-    if sys.stdin.isatty():
-        sys.exit("pipe a JSON spec on stdin (see module docstring)")
-    try:
-        spec = json.loads(sys.stdin.read())
-    except json.JSONDecodeError as exc:
-        sys.exit(f"invalid JSON on stdin: {exc}")
-
-    operator = (spec.get("operator") or "OR").upper()
+def build(spec, *, app_url=DEFAULT_APP_URL):
+    """Build the deliverable (filter set, report link, report config) from a spec; raises ReportSpecError."""
+    if not isinstance(spec, dict):
+        raise ReportSpecError("spec must be a JSON object")
+    operator = str(spec.get("operator") or "OR").upper()
     if operator not in ("AND", "OR"):
-        sys.exit("operator must be AND or OR")
-    report_type = (spec.get("report_type") or "channels").lower()
+        raise ReportSpecError("operator must be AND or OR")
+    report_type = str(spec.get("report_type") or "channels").lower()
     if report_type not in REPORT_TYPES:
-        sys.exit(f"report_type must be one of {sorted(REPORT_TYPES)}")
+        raise ReportSpecError(f"report_type must be one of {sorted(REPORT_TYPES)}")
     slug, report_type_int = REPORT_TYPES[report_type]
     default_fields = spec.get("default_content_fields") or DEFAULT_FIELDS[report_type]
 
     groups = spec.get("groups") or []
-    groups = [g for g in groups if isinstance(g, dict) and str(g.get("text", "")).strip()]
+    groups = [dict(g) for g in groups if isinstance(g, dict) and str(g.get("text", "")).strip()]
     if not groups:
-        sys.exit("provide at least one group with non-empty 'text'")
+        raise ReportSpecError("provide at least one group with non-empty 'text'")
     for g in groups:
         g["text"] = str(g["text"]).strip()
 
@@ -426,7 +428,7 @@ def main():
         used_fields.update(g.get("content_fields") or [])
     unknown = sorted(f for f in used_fields if f not in VALID_CONTENT_FIELDS)
     if unknown:
-        sys.exit(
+        raise ReportSpecError(
             f"unknown content_fields {unknown}; use recognized content field names "
             f"(e.g. title, summary, transcript, channel_description, "
             f"channel_topic_description) — not raw ES paths. Valid: {sorted(VALID_CONTENT_FIELDS)}"
@@ -443,18 +445,18 @@ def main():
         try:
             app_text = sqs_to_app_syntax(g["text"])
         except ValueError as exc:
-            sys.exit(f"group {g['text']!r}: {exc}")
+            raise ReportSpecError(f"group {g['text']!r}: {exc}")
         if app_text != g["text"]:
             translated.append({"from": g["text"], "to": app_text})
             g["text"] = app_text
 
     filter_set = build_filter_set(kept, operator, default_fields)
-    report_link = build_inline_link(kept, operator, slug, default_fields, args.app_url)
+    report_link = build_inline_link(kept, operator, slug, default_fields, app_url)
     title = spec.get("title") or f"{report_type.title()} — keyword search"
     description = spec.get("description") or ""
     report_config = build_report_config(filter_set, report_type_int, title, description)
 
-    print(json.dumps({
+    return {
         "report_type": report_type,
         "operator": operator,
         "expression": render_expression(kept, operator),
@@ -463,7 +465,28 @@ def main():
         "report_config": report_config,
         "pruned": pruned,
         "translated": translated,
-    }, ensure_ascii=False, indent=2))
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Build the keyword-research deliverable (filter set + report link) from validated groups."
+    )
+    ap.add_argument("--app-url", default=DEFAULT_APP_URL, help=f"App base URL (default {DEFAULT_APP_URL})")
+    args = ap.parse_args()
+
+    if sys.stdin.isatty():
+        sys.exit("pipe a JSON spec on stdin (see module docstring)")
+    try:
+        spec = json.loads(sys.stdin.read())
+    except json.JSONDecodeError as exc:
+        sys.exit(f"invalid JSON on stdin: {exc}")
+
+    try:
+        out = build(spec, app_url=args.app_url)
+    except ReportSpecError as exc:
+        sys.exit(str(exc))
+    print(json.dumps(out, ensure_ascii=False, indent=2))
 
 
 # OUTPUT CONTRACT (stdout, single JSON object):

{thoughtleaders_cli-0.9.22 → thoughtleaders_cli-0.9.24}/skills/tl-keyword-research/scripts/expand_entities.py

@@ -33,8 +33,19 @@ Usage:
     python3 expand_entities.py --existing "cannes lions" "advertising awards" < resolver.json > expanded.json
     # pipe the candidates straight into probe.py:
     python3 expand_entities.py --probe-batch < resolver.json | python3 probe.py --samples 5
+
+Library use: the file is import-safe (standard library only, nothing runs at import),
+so another Python program can load it by path and call `expand(resolver_reply, *,
+existing=None)` (what the default mode prints) or `probe_batch(resolver_reply, *,
+existing=None)` (what `--probe-batch` prints). `resolver_reply` is the parsed resolver
+JSON; `existing` lists the candidates already brainstormed. Both return fresh structures
+that share nothing with the input. Bad input raises `ExpandInputError` (a `ValueError`).
+Library functions never print, read stdin or exit.
 """
+from __future__ import annotations
+
 import argparse
+import copy
 import json
 import re
 import sys
@@ -80,6 +91,10 @@ def solid(text):
     return _NONWORD_RE.sub("", text)
 
 
+class ExpandInputError(ValueError):
+    """The resolver reply or options handed to the expander are unusable."""
+
+
 def _norm(text):
     """Case/space-insensitive key for dedupe."""
     return re.sub(r"\s+", " ", text.strip().lower())
@@ -156,8 +171,25 @@ def _collect_names(resolver, max_insider):
     return fams
 
 
-def expand(resolver, existing, max_insider):
-    """Build probe candidates + family detail from a resolver JSON object."""
+def check_resolver(resolver_reply):
+    """Raise ExpandInputError unless the resolver reply is a JSON object."""
+    if not isinstance(resolver_reply, dict):
+        raise ExpandInputError("resolver JSON must be an object")
+
+
+def expand(resolver_reply, *, existing=None, max_insider=MAX_INSIDER_DEFAULT):
+    """Build probe candidates + family detail from a resolver JSON object (what the default mode prints).
+
+    `existing` lists candidates already brainstormed; matching forms are dropped.
+    `max_insider` caps the insider terms folded in. Raises ExpandInputError.
+    """
+    check_resolver(resolver_reply)
+    resolver = resolver_reply
+    existing = [] if existing is None else existing
+    if not isinstance(existing, (list, tuple)) or not all(isinstance(x, str) for x in existing):
+        raise ExpandInputError("existing must be a list of strings")
+    if max_insider < 0:
+        raise ExpandInputError("--max-insider must be >= 0")
     seen = {_norm(x) for x in existing}          # forms already covered → skip
     deduped = []
 
@@ -211,7 +243,7 @@ def expand(resolver, existing, max_insider):
     )
     collisions = [c for c in (resolver.get("collisions", []) or []) if isinstance(c, dict)]
 
-    return {
+    result = {
         "probe_candidates": probe_candidates,
         "families": families,
         "aliases": aliases,
@@ -228,6 +260,12 @@ def expand(resolver, existing, max_insider):
             "deduped": len(deduped),
         },
     }
+    return copy.deepcopy(result)   # the caller's input is never shared with the output
+
+
+def probe_batch(resolver_reply, *, existing=None, max_insider=MAX_INSIDER_DEFAULT):
+    """Just the probe_candidates array (what --probe-batch prints), ready for probe.py."""
+    return expand(resolver_reply, existing=existing, max_insider=max_insider)["probe_candidates"]
 
 
 def load_resolver():
@@ -240,8 +278,10 @@ def load_resolver():
         data = json.loads(raw)
     except json.JSONDecodeError as exc:
         sys.exit(f"invalid resolver JSON on stdin: {exc}")
-    if not isinstance(data, dict):
-        sys.exit("resolver JSON must be an object")
+    try:
+        check_resolver(data)
+    except ExpandInputError as exc:
+        sys.exit(str(exc))
     return data
 
 
@@ -259,7 +299,11 @@ def main():
     if args.max_insider < 0:
         sys.exit("--max-insider must be >= 0")
 
-    out = expand(load_resolver(), args.existing, args.max_insider)
+    resolver = load_resolver()
+    try:
+        out = expand(resolver, existing=args.existing, max_insider=args.max_insider)
+    except ExpandInputError as exc:
+        sys.exit(str(exc))
     if args.probe_batch:
         print(json.dumps(out["probe_candidates"], ensure_ascii=False))
     else: