thoughtleaders-cli 0.8.1__tar.gz → 0.9.0__tar.gz

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/AGENTS.md

@@ -52,7 +52,7 @@ This repo is also a Claude Code plugin, and can directly be installed as one.
 ### Bundled skills — when to invoke
 
 - **`tl`** — the main skill for querying ThoughtLeaders data. Default for any sponsorship / channel / brand / upload / report question.
-- **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. It researches the topic by composing a boolean keyword query (`--any` OR-groups AND'd together, `--not` exclusions) over **≥3 refinement rounds**, returning a **CNF (Conjunctive Normal Form) keyword expression** as the reusable headline artifact alongside the ranked, sponsorability-flagged channels it selects. **Interactive by default** — checkpoints with the user after round 3 unless told to "run autonomously" (or invoked with `autonomous` / `--auto`). The keyword-distribution shape (`{operator, keywords:[{keyword,count}]}`) is an **opt-in mode**, produced only when the user explicitly asks for keyword counts / distribution. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
+- **`tl-keyword-research`** — invoke whenever the user wants to find videos or channels by **content keywords** (topics, concepts, niches) that aren't covered by a curated recommender tag, OR to validate that a candidate channel's content actually touches a given topic. It expands the topic deeply (entity families, ES tokenization variants, a gated web lookup for post-cutoff names), probes each candidate (counts + samples), validates matches against the user's intent with cheap sub-agents, refines a boolean filter over **≥3 rounds**, and context-validates the channels the filter selects. Deliverable: a **validated keyword-group filter set + a clickable report link**, plus whichever results the user chooses (it asks when the request doesn't say): **trend data** — the matching videos/uploads sortable by date/views with prevalence numbers — and/or **channel targets** classified by topic intensity (core / recurring / occasional / one-off, so niche topics with no wholly-dedicated channels still get a real market: the recurring-coverage tier), sponsorability-flagged, with the rendered boolean expression recorded for reproducibility. **The user picks the path** — a quick single pass or a deep ≥3-round refinement: honor whichever the request names, ask when it names neither (never silently default); `autonomous` / `--auto` runs the deep path without pauses (otherwise it checkpoints after round 3). The keyword-distribution shape (`{operator, keywords:[{keyword,count}, …]}`) is an **opt-in mode**, produced only when the user explicitly asks for keyword counts / distribution. It also explains itself on request — "help" / "how does this work" / "what are my options" gets the built-in user guide, free, no queries run. **Do not compose keyword sets by hand for `tl db es` content searches — delegate to this skill first.** See `skills/tl/SKILL.md` → *Channel & video discovery* for the four-path decision tree and when to use this vs the recommender / raw SQL.
 - **`tl-save-report`**, **`adapt-tl-data`**, **`tl-views-guarantee`**, **`tl-top-partnerships`** — narrower workflows; the skill files document their own triggers. `tl-top-partnerships` is brand-user-facing: ranks a brand's sold sponsorships by live eCPM vs the sold-date projection and delivers a two-tab Google Sheet via `gws`.
 
 ### Skill content boundaries

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.8.1
+Version: 0.9.0
 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
@@ -278,7 +278,7 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
 - **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
-- **`tl-keyword-research`** — broadens and ranks content-search keywords by Elasticsearch document count before a `tl db es` content search, so finding videos or channels by topic isn't bottlenecked on hand-guessed terms.
+- **`tl-keyword-research`** — turns a topic into a validated keyword-group filter set + a clickable report link, plus the results it selects — context-validated channels with sponsorability flags, or the matching videos/uploads for trend reports — refining a boolean filter over the live index instead of hand-guessing terms. Keyword-distribution counts remain as an opt-in mode.
 - **`tl-save-report`** — persists the result set from an in-chat exploration session as a saved TL report ("save this as a report", "turn this into a campaign").
 - **`tl-channel-authenticity`** — vets a YouTube channel for non-organic views and bot/spam comments before booking (or after delivering) a sponsorship.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/README.md

@@ -250,7 +250,7 @@ Each agent discovers the skill automatically and uses it when you ask about spon
 The plugin ships several focused skills (installed by all the `tl setup *` commands):
 
 - **`tl`** — the data-analyst skill. Defaults to raw database queries via `tl db pg|fb|es` for anything non-trivial; uses the structured `tl <resource> show` / `find` / `similar` commands for single-record lookups and similarity / ID-resolution special cases. Comes with full schema references for Postgres, Elasticsearch, and Firebolt under `references/`.
-- **`tl-keyword-research`** — broadens and ranks content-search keywords by Elasticsearch document count before a `tl db es` content search, so finding videos or channels by topic isn't bottlenecked on hand-guessed terms.
+- **`tl-keyword-research`** — turns a topic into a validated keyword-group filter set + a clickable report link, plus the results it selects — context-validated channels with sponsorability flags, or the matching videos/uploads for trend reports — refining a boolean filter over the live index instead of hand-guessing terms. Keyword-distribution counts remain as an opt-in mode.
 - **`tl-save-report`** — persists the result set from an in-chat exploration session as a saved TL report ("save this as a report", "turn this into a campaign").
 - **`tl-channel-authenticity`** — vets a YouTube channel for non-organic views and bot/spam comments before booking (or after delivering) a sponsorship.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.

thoughtleaders_cli-0.8.1/skills/tl-keyword-research/references/context-classifier.md → thoughtleaders_cli-0.9.0/agents/keyword-context-classifier.md

@@ -1,21 +1,18 @@
-# Keyword Context Classifier (cheap / Haiku)
-
-This is the prompt for the per-channel context check. The orchestrator spawns one
-cheap agent (e.g. **model `haiku`**) per batch of channels with the System role set
-to everything below, then puts the `TOPIC` line + the indexed evidence JSON in the
-user message, and runs batches in parallel.
-
-**The orchestrator MUST anchor completeness in the user message** — state the exact
-count and the last id, e.g.:
-`There are exactly 50 channels (indices 0–49). Return exactly 50 objects. The last channel_id is 778812.`
-and **after** collecting results, verify every `channel_id` came back and re-send any
-missing ones. Cheap models drop the tail of long lists; steering reduces it, the
-re-send guarantees it.
-
-On promotion to `tl-cli` this can be registered as a subagent
-(`agents/keyword-context-classifier.md`, `model: haiku`, `tools: Read`).
-
 ---
+name: keyword-context-classifier
+description: >
+  Judges whether candidate YouTube channels genuinely cover a topic, or only
+  use the topic's keyword(s) in an unrelated sense, from keyword-in-context
+  snippets gathered by the tl-keyword-research skill's fetch_context step.
+  Use when you have a JSON array of per-channel snippet evidence and need a
+  fast, cheap per-channel on_topic / mixed / off_topic verdict plus adjacent
+  discovery terms. Returns strict JSON only.
+model: haiku
+tools: Read
+color: yellow
+---
+
+# Keyword Context Classifier
 
 You decide whether a YouTube channel genuinely covers a topic, or only mentions the
 topic's keyword(s) in an **unrelated sense**. ThoughtLeaders uses your verdict to

thoughtleaders_cli-0.9.0/agents/keyword-entity-resolver.md

@@ -0,0 +1,113 @@
+---
+name: keyword-entity-resolver
+description: >
+  Resolves a content topic into the real-world proper nouns needed to search for
+  it — entity families (company → product line → model/version → codename →
+  sibling), post-cutoff launch/rename facts, and insider community vocabulary —
+  by running a few narrow web lookups and returning ONLY a compact JSON of names
+  to probe. Used by the tl-keyword-research skill's Step 0 / Phase 1 when a topic
+  postdates the knowledge cutoff, was recently renamed, is a live trend, or is
+  insider-jargon-dense. Returns strict JSON only.
+model: sonnet
+tools: WebSearch, WebFetch
+color: green
+---
+
+# Keyword Entity Resolver
+
+You turn a content topic into the **real-world proper nouns and insider
+vocabulary** a downstream Elasticsearch search needs — the names a model's own
+memory cannot be trusted to enumerate because the topic is newer than its
+knowledge cutoff, was recently renamed, is a live trend, or is dense with
+community jargon. You are used by the `tl-keyword-research` skill. Your output is
+**not** the final keyword set — every name you return is treated as an
+**unvalidated probe candidate** that must still pass an ES probe and on-topic
+sample validation. So your job is *recall of real names*, not judgement of fit.
+
+## Input
+
+A short brief, e.g.:
+
+```
+topic: Cannes Lions 2026
+intent: YouTube videos about the Cannes Lions advertising/creativity festival — winners, campaigns, talks, recaps
+level: topic            # or channel
+known: ["cannes lions", "cannes lions festival"]   # names the caller already has; do NOT just repeat these
+```
+
+`known` is what the caller already brainstormed — your value is the names it is
+**missing**, so dedupe against it and spend your effort on the gaps.
+
+## Method (cheap and bounded)
+
+1. Run **1–2 `WebSearch` queries** to establish the entity and its current facts
+   (e.g. `"Cannes Lions 2026" award categories winners`, `"<product>" launch
+   model names siblings`). Read snippets first.
+2. **At most 1–2 `WebFetch`** of an *authoritative* page only when snippets are
+   insufficient — an official site, a Wikipedia article (use its infobox,
+   navbox, and "See also"), or a single curated community glossary / wiki /
+   tool-roundup. Do **not** open-ended browse, and never fetch random blogs,
+   autocomplete, or "related searches".
+3. Extract names. Stop — do not keep researching for completeness beyond the cap.
+
+## What to extract — and what NOT to
+
+Extract **only literal proper nouns and named terms tied to THIS topic**:
+
+- **Entity family** — company, product line, model/version names and numbers,
+  codenames, and **sibling products shipped or named alongside** the headline
+  one. (The classic miss: resolving a launch to its company name only and missing
+  the actual product, its version, and its sibling — return the whole family.)
+- **Aliases** — old ↔ new names for any rename/rebrand/relaunch/successor, with
+  the change date if you can find it. Return **both** so a search spans the
+  pre- and post-rename eras.
+- **Insider vocabulary** — up to **40** community/jargon terms, named sub-areas,
+  tools-of-the-niche, award/category names, recurring named events. Pull these
+  from curated glossaries / wikis / taxonomy pages, not from your own synonym
+  brainstorming.
+- **Hashtags / handles** — the literal hashtag or handle form a community uses
+  (e.g. `#canneslions`).
+- **Known collisions** — if a term obviously also means something else (a game,
+  a different festival, a foreign institution), note it so the caller can exclude
+  that polluter later.
+
+Hard prohibitions (these would violate the skill's purpose):
+
+- **No synonyms, adjectives, descriptors, or phrasings.** You return *names*, not
+  reworded versions of the topic. "creative advertising awards" is not a name;
+  "Cannes Lions Grand Prix" is.
+- **No bare over-broad roots.** For "Cannes Lions" do not return "cannes" (the
+  city / film festival) or "lions" alone.
+- **No specific YouTube channel names** and **no brands invented from free text** —
+  return only brands that genuinely appear as named entities in the topic.
+- **Tie every name to the topic.** If you cannot say *why* a name belongs to this
+  topic from a source, drop it. A name you are unsure about is worse than a gap —
+  it wastes a probe or pollutes the result.
+
+## Output — STRICT
+
+Return ONLY this JSON object, no prose, no markdown fence:
+
+```json
+{
+  "entities": [
+    {"name": "Cannes Lions Grand Prix", "kind": "category", "note": "top award at the festival"}
+  ],
+  "insider_terms": ["Titanium Lion", "Film Craft", "Outdoor Lions", "..."],
+  "aliases": [{"old": "Cannes Advertising Festival", "new": "Cannes Lions", "since": "2011"}],
+  "hashtags": ["#canneslions"],
+  "collisions": [{"term": "cannes", "other_meaning": "Cannes Film Festival / the city"}],
+  "recency": {"is_post_cutoff": true, "as_of": "2026-06", "note": "2026 edition is current"},
+  "notes": "one or two sentences on what you found / any uncertainty",
+  "sources": ["https://...", "https://..."]
+}
+```
+
+- `kind` is one of `company | product | model | version | codename | sibling |
+  event | category | tool | other`.
+- Every array may be empty (`[]`) if nothing applies; never omit a key.
+- `name` values are bare literal strings — no quoting, no boolean operators. The
+  caller's script generates spelling/spacing variants and boolean grouping; you
+  supply the canonical names only.
+- Keep it tight: quality and topic-tie matter more than volume (except
+  `insider_terms`, where up to 40 is fine if they are genuinely on-topic).

thoughtleaders_cli-0.9.0/agents/keyword-relevance-validator.md

@@ -0,0 +1,70 @@
+---
+name: keyword-relevance-validator
+description: >
+  Judges whether sampled YouTube documents (videos or channels) returned by a
+  keyword probe are genuinely about the user's intended topic, for the
+  tl-keyword-research skill's validation step. Use when you have a JSON array of
+  sample docs (title/summary, or channel name/topic) and need a fast, cheap
+  per-sample on-topic / off-topic verdict. Returns strict JSON only.
+model: haiku
+tools: Read
+color: cyan
+---
+
+# Keyword Relevance Validator
+
+You decide whether each sampled document actually concerns the user's intended
+topic, or merely contains the keyword incidentally. You are used by the
+`tl-keyword-research` skill to confirm that a candidate keyword brings back
+on-topic content before it goes into a customer's filter set, so a wrong
+"relevant" verdict pollutes the result — be strict.
+
+## Input
+
+A single leading line states the intent, then a JSON array of samples:
+
+```
+intent: <one sentence describing what the user is really looking for>
+[{"i": 0, "keyword": "<candidate that matched this doc>", "title": "...", "summary": "..."}, ...]
+```
+
+Each item has an integer `i`, the `keyword` that produced the match, and content
+fields. For **videos** these are `title` and `summary`; for **channels** they
+are `name` and `topic` (the channel's AI topic description). Some fields may be
+empty or in another language — judge on whatever is present.
+
+## How to judge
+
+Mark `relevant: true` only when the document is genuinely **about** the intent —
+the topic is the subject of the video/channel, not a passing mention.
+
+- A clear match **in the title** is strong evidence of relevance — titles state
+  what the content is about.
+- A keyword that appears only as an offhand aside, idiom, or different sense of
+  the word is **not** relevant. Example — intent "stock/finance investing":
+  "I'm investing in my relationship with my partner" → `relevant: false` (the
+  word is there, the topic isn't).
+- Judge against the **intent**, not the bare keyword string. The keyword may be
+  broad ("tiktok") while the intent is narrow ("TikTok Shop selling"); a doc
+  about TikTok dances does not serve a TikTok-Shop intent → `relevant: false`.
+- When genuinely unsure from the fields present, prefer `relevant: false`.
+
+## Completeness — NON-NEGOTIABLE
+
+You MUST return exactly one object for **every** input sample — same `i`
+values, same order, from index 0 through the last one. Do not stop early,
+summarize, or write `...`. A long input is not a reason to shorten the
+output; per-item brevity is how you finish the list, not dropping items.
+Before you finish: count your objects — if the count is less than the input
+length, continue from where you stopped. (The caller diffs your `i` values
+against the batch and re-sends anything missing, so a truncated reply only
+wastes a round-trip.)
+
+## Output — STRICT
+
+Return ONLY a JSON array, no prose, no markdown fence:
+
+`[{"i": 0, "relevant": true}, {"i": 1, "relevant": false}, ...]`
+
+One object per input sample, same `i` values, same length. No extra keys.
+If the input array is empty, return `[]`.

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/pyproject.toml

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

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/skills/tl/SKILL.md

@@ -555,13 +555,7 @@ Use `tl recommender top` for category/topic discovery (it's ranked) and `tl chan
 - **Channel–brand fit check** — does this candidate channel's content actually touch the brand's category? (Use with `channel.id` filter on the downstream ES query.)
 - **Validating a recommender / SQL shortlist** — sample-check that the top-N channels really cover the niche.
 
-**Do NOT compose keyword sets by hand for `tl db es`.** Always run the skill's script first. It broadens the user input, probes each candidate via `multi_match phrase`, and returns ranked counts:
-
-```json
-{"operator": "OR", "keywords": [{"keyword": "crypto", "count": 18742}, {"keyword": "bitcoin", "count": 15103}, {"keyword": "rugpull", "count": 0}]}
-```
-
-Then run the actual content search via `tl db es` (`multi_match` on the `title`, `summary`, `transcript` fields) with the surviving high-count keywords. The skill's full procedure (Phase 1 = seed expansion by you; Phase 2 = the script) is in the `tl-keyword-research` skill file.
+**Do NOT compose keyword sets by hand for `tl db es`.** Always invoke the whole skill. It expands the topic deeply (entity families, tokenization variants, a gated web lookup for post-cutoff names), probes each candidate (document count **+ distinct-channel count + sample docs**), **validates the samples against the user's intent** with cheap sub-agents (so incidental "the word is there but the topic isn't" matches are dropped, not counted), refines a boolean filter over **≥3 rounds**, context-validates the channels the filter selects, and delivers a **validated keyword-group filter set + a clickable report link + the ranked channels with sponsorability flags** — not just counts. The full procedure (expand → probe → validate → refine → channels → deliver) and the ES Boolean/field reference live in the `tl-keyword-research` skill. Keyword-distribution counts remain available as the skill's opt-in mode when the question is literally "how common is X".
 
 **Path 4. Pure attribute filter** — user wants channels filtered by metadata like: `is_tpp`, `language`, `demographic_device_primary`, country share in `demographic_geo` JSON, aggregations, joins. Use `tl db pg` with a SELECT on `thoughtleaders_channel`. Run `tl schema pg thoughtleaders_channel` once to confirm the live column set; the columns in the examples are stable.
 

{thoughtleaders_cli-0.8.1 → thoughtleaders_cli-0.9.0}/skills/tl/references/elasticsearch-schema.md

@@ -24,9 +24,10 @@ See the output of `tl db es`" for the object schema. Highlights:
 - **Top-level keys** accepted: `query`, `aggs`/`aggregations`, `sort`, `_source`, `size`, `from`, `search_after`, `track_total_hits`, `highlight`, `fields`, `min_score`, `timeout`, `collapse`, `post_filter`. Anything else (incl. `scroll`, `pit`, `runtime_mappings`, `knn`) is not accepted.
 - `size` ≤ 10,000. `from + size` ≤ 10,000 — to page past 10,000 hits use `search_after` (see *Deep pagination* below), not `from`.
 - `search_after` must be a non-empty array of ≤ 10 scalar sort values, requires an explicit `sort`, and `from` must be 0 or omitted.
-- **Accepted query types** include `term`/`terms`/`match`/`bool`/`nested`/`range`/`exists`/`match_phrase`. `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, `has_child`, `has_parent`, `parent_id` are not accepted.
+- **Accepted query types** include `term`/`terms`/`match`/`bool`/`nested`/`range`/`exists`/`match_phrase`/`simple_query_string` (the sanctioned rich-Boolean text surface — `+` required, `|` OR, `-` NOT, `"phrase"`, `"phrase"~N` slop, trailing-`*` prefix, `~N` fuzzy, `(...)` grouping, per-field `^boosts`; always set `default_operator: "and"` and an explicit `fields` list or counts balloon). `query_string`, `regexp`, `wildcard`, `fuzzy`, `more_like_this`, `has_child`, `has_parent`, `parent_id` are not accepted.
 - **No scripts** — keys that start with `script` (e.g. `script_fields`, `script_score`, `scripted_metric`) or end with `_script` (e.g. `bucket_script`) are not accepted. A field whose name merely contains `script` as a substring (e.g. `transcript`, `description`) is fine.
-- **At most one aggregation total** counted recursively (top-level + sub-agg = 2 = not accepted). Run multiple calls for multi-metric work.
+- **Aggregations are bounded, not forbidden**: up to ~50 agg nodes per body, bucket nesting ≤ 3 levels deep (single-bucket framing aggs like `filter`/`nested`/`missing` count toward depth), terms-like bucket `size` ≤ 10,000, and a worst-case total bucket count cap — so a `filter` agg wrapping a `cardinality` (the common counts-plus-recency shape) is fine in one call. Heavy/experimental agg types (e.g. `significant_terms`, script-based pipeline aggs) are not accepted.
+- **`highlight` is accepted in the body but highlight fragments are not returned** — result rows carry only `_id`, `_score`, and the `_source` fields. Request the `_source` fields you need for validation samples instead.
 
 ### ElasticSearch document structure ("articles")