thoughtleaders-cli 0.6.8__tar.gz → 0.6.10__tar.gz

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.8
+Version: 0.6.10
 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
@@ -21,8 +21,8 @@ Requires-Dist: authlib>=1.3
 Requires-Dist: httpx>=0.27
 Requires-Dist: keyring>=25.0
 Requires-Dist: rich>=13.0
-Requires-Dist: toon-format>=0.9.0b1
-Requires-Dist: typer[all]>=0.12
+Requires-Dist: toon-format==0.9.0b1
+Requires-Dist: typer>=0.16
 Description-Content-Type: text/markdown
 
 # tl cli
@@ -125,9 +125,10 @@ tl brands show Nike
 # Run a saved report
 tl reports run 42
 
-# Comments on a sponsorship
-tl comments list 12345
-tl comments add 12345 "Looks good"
+# Comments — available on sponsorships, channels, brands, and uploads
+tl sponsorships comment-list 12345
+tl sponsorships comment-add 12345 "Looks good"
+tl channels comment-add 7890 "Strong recent winners"
 
 # Show information about the logged-in user
 tl whoami

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/README.md

@@ -98,9 +98,10 @@ tl brands show Nike
 # Run a saved report
 tl reports run 42
 
-# Comments on a sponsorship
-tl comments list 12345
-tl comments add 12345 "Looks good"
+# Comments — available on sponsorships, channels, brands, and uploads
+tl sponsorships comment-list 12345
+tl sponsorships comment-add 12345 "Looks good"
+tl channels comment-add 7890 "Strong recent winners"
 
 # Show information about the logged-in user
 tl whoami

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/agents/tl-analyst.md

@@ -64,7 +64,7 @@ tl db pg "SELECT a.id, a.send_date, a.publish_status, b.name AS brand, ch.channe
           ORDER BY a.send_date
           LIMIT 100 OFFSET 0"
 ```
-Then suggest `tl comments add <id> "..."` for each.
+Then suggest `tl sponsorships comment-add <id> "..."` for each.
 
 ### Multi-step research (mix raw + similarity)
 "Find channels similar to the ones Nike sponsors and compare their pricing"

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/docs/architecture.md

@@ -56,8 +56,9 @@ All data commands use explicit subcommands: `list`, `show`, `create`/`add`. Runn
 | `tl brands similar <brand>` | Find similar brands (similarity search, 25 credits) |
 | `tl snapshots channel <id>` | Channel metrics over time (Firebolt channel_metrics) |
 | `tl snapshots video <id> --channel <id>` | Video view curve (Firebolt article_metrics, --channel required) |
-| `tl comments list <adlink-id>` | List comments on a sponsorship (free) |
-| `tl comments add <adlink-id> "message"` | Add a comment (free) |
+| `tl <entity> comment-list <id>` | List comments on a sponsorship/channel/brand/upload (free) |
+| `tl <entity> comment-add <id> "message"` | Add a comment (free) |
+| `tl <entity> comment-edit <comment-id> "message"` | Edit one of your own comments (author or superuser; free) |
 
 ### Raw database access (escape hatch for joins / aggregations / complex filters)
 
@@ -180,7 +181,7 @@ tools: [Bash, Read]
 
 What the agent does:
 - **Multi-step research**: "Find channels similar to the ones Nike sponsors and compare their pricing" → `tl brands show Nike --json` → extract initial channel IDs → `tl channels similar <initial-id> --json` for each (enriched with cpm) → union + dedupe → compile comparison table
-- **Cross-resource analysis**: "Show me deal slippage and add comments" → `tl sponsorships status:pending send-date-end:2026-03 --json` → identify slipping sponsorships → `tl comments add <id> "flagged for slippage"` for each
+- **Cross-resource analysis**: "Show me deal slippage and add comments" → `tl sponsorships status:pending send-date-end:2026-03 --json` → identify slipping sponsorships → `tl sponsorships comment-add <id> "flagged for slippage"` for each
 - **Report comparison**: "Compare my Q1 report to Q4" → `tl reports run <id> --since 2026-01 --until 2026-03 --json` → `tl reports run <id> --since 2025-10 --until 2025-12 --json` → synthesize
 - **Discovery workflows**: "What's my best performing brand this quarter" → `tl sponsorships status:sold purchase-date-start:2026-01 --json` → aggregate by brand → `tl brands show <top_brand> --json` → full picture
 - **Credit-aware**: checks balance before multi-query workflows, estimates total cost, asks user to confirm if expensive
@@ -315,7 +316,7 @@ tl-cli/
 │   │   ├── brands.py                 # tl brands (show/history/similar)
 │   │   ├── snapshots.py              # tl snapshots (Firebolt metrics)
 │   │   ├── reports.py                # tl reports / tl reports run
-│   │   ├── comments.py               # tl comments (list/add)
+│   │   ├── _comments_common.py       # comment-list/add/edit subcommands shared across entity apps
 │   │   ├── db.py                     # tl db pg|fb|es (raw read-only queries)
 │   │   ├── schema.py                 # tl schema pg|fb|es (live schema docs)
 │   │   ├── describe.py               # tl describe list/show (schema/filter/pricing discovery)
@@ -394,8 +395,9 @@ Most CLI endpoints can reuse existing views/utilities rather than being built fr
 | **`GET /api/cli/v1/snapshots/video/<id>`** | `api/v2/article-history` (`ArticleHistoryView`) — already queries Firebolt `article_metrics` with pagination, enforces `channel_id:article_id` format. | Direct reuse — already enforces channel_id requirement |
 | **`GET /api/cli/v1/reports`** | `api/campaigns` (`CampaignViewSet.list`) — returns user's saved campaigns with ownership filtering | Filter to user's campaigns, add CLI envelope |
 | **`GET /api/cli/v1/reports/<id>/run`** | `api/campaigns/<id>` detail + the view's existing data loading via `load_campaign_data()` in `data_api_utils.py` — campaigns store their filter config, which gets passed to the appropriate data view (SponsorshipsView, ArticlesView, ThoughtleadersView) | Load campaign config → dispatch to appropriate existing view → wrap results |
-| **`GET /api/cli/v1/comments/<adlink_id>`** | `api/comments/adlink/<id>` (`CommentsView` GET) — already paginated with read status | Add CLI envelope |
-| **`POST /api/cli/v1/comments/<adlink_id>`** | `api/comments/adlink/<id>` (`CommentsView` POST) — creates comment | Pass through |
+| **`GET /api/cli/v1/<entity_type>/<entity_id>/comments`** | Same query against the `Comment` table; entity_type ∈ {sponsorship, channel, brand, upload} | List comments scoped to caller's organization |
+| **`POST /api/cli/v1/<entity_type>/<entity_id>/comments`** | Insert into `Comment` with the matching FK column | Create comment for the named entity |
+| **`PATCH /api/cli/v1/comment/<comment_id>`** | Update `Comment.content` after author/superuser check | Edit a single comment by ID |
 | **`GET /api/cli/v1/whoami`** | New — reads Profile, Organization, brands M2M | New (joins Profile → User, Organization → Plan, Profile.brands → ChannelList) |
 | **`GET /api/cli/v1/balance`** | New — reads `CliCreditAccount` | New (simple model read) |
 | **`GET /api/cli/v1/describe`** | New — static metadata | New (hardcoded resource definitions) |
@@ -563,7 +565,7 @@ Build each command + its server endpoint together:
 11. `tl snapshots video abc --channel 12345` returns view curve
 12. `tl reports` lists saved reports (free)
 13. `tl reports run 789` executes saved report (credits based on results)
-14. `tl comments list 12345` lists comments (free)
+14. `tl sponsorships comment-list 12345` lists comments (free) — same shape under `tl channels`, `tl brands`, `tl uploads`
 15. `tl sponsorships create --channel 1 --brand 2` creates proposal (free)
 16. `tl setup claude` installs plugin
 17. Claude Code skill triggers on data questions, uses `tl describe` for discovery

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.6.8"
+version = "0.6.10"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"
@@ -23,12 +23,19 @@ classifiers = [
     "Topic :: Office/Business",
 ]
 dependencies = [
-    "typer[all]>=0.12",
+    # `typer` >= 0.16 made click/rich/shellingham required — the `[all]` extra
+    # was removed and uv warns about it. Drop the extra to silence the warning;
+    # behaviour is identical because the bundled deps are pulled either way.
+    "typer>=0.16",
     "rich>=13.0",
     "httpx>=0.27",
     "keyring>=25.0",
     "authlib>=1.3",
-    "toon-format>=0.9.0b1",
+    # `toon-format` only publishes pre-releases (0.9.0b1 is the only modern
+    # release; 0.1.0 is the lone stable). pip/pipx accept `>=0.9.0b1` and pull
+    # the beta, but uv refuses pre-releases under `>=` when a stable exists.
+    # An exact pin is the one form uv will resolve without `--prerelease=allow`.
+    "toon-format==0.9.0b1",
 ]
 
 [project.scripts]

{thoughtleaders_cli-0.6.8 → thoughtleaders_cli-0.6.10}/skills/tl/SKILL.md

@@ -5,24 +5,17 @@ description: Query and analyze ThoughtLeaders business data using the `tl` CLI.
 
 # ThoughtLeaders Data Analyst
 
-You have access to the `tl` CLI which queries ThoughtLeaders' sponsorship platform data. Run it to answer questions about deals, channels, brands, uploads, metrics, and more.
+Run the `tl` CLI to query ThoughtLeaders' sponsorship platform data. Use it to answer questions about deals, channels, brands, uploads, metrics, etc.
 
 ## Core Principles
 
-**You are the intelligence layer.** Don't use `tl ask` — that's a server-side LLM fallback for users without Claude. Translate the user's question into the right `tl` invocation yourself.
+**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es`. Avoid the structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.).
 
-**Default to raw database queries.** For anything beyond a trivially simple lookup, reach for `tl db pg|fb|es` first. The structured `tl <resource>` commands (`sponsorships list`, `channels show`, `brands history`, etc.) are convenient shorthands for single-record lookups and plain filtered lists — but the moment the question involves joins, aggregations, multi-condition filtering, or anything you'd otherwise post-process client-side, the right tool is a single raw query. One server-side aggregation beats N paginated client-side roll-ups on cost, latency, and the `from+size = 10000` ES cap.
+Always run `tl schema pg|fb|es` before writing a raw query.
 
-Decision rule:
+**When you only need the schema of one table, you MUST call `tl schema pg <table>` (or `tl schema fb <table>`) — never the unscoped form**, to reduce token counts. ES has no per-table form (the index is a single document shape) — `tl schema es` is the only call there.
 
-- **Trivially simple** (use a structured command): "show sponsorship 12345", "list deals for Nike", "show channel 5607", "run report 42".
-- **Anything else** (use `tl db pg|fb|es`): aggregations, joins, conditions the structured filters don't expose, comparing across resources, computing rates / shares / percentiles, anything that would otherwise need a paginated walk + client-side reduce.
-
-Always run `tl describe show <resource>` before using a structured command, and `tl schema pg|fb|es` before writing a raw query.
-
-**When you only need the schema of one table, you MUST call `tl schema pg <table>` (or `tl schema fb <table>`) — never the unscoped form.** The unscoped `tl schema pg` returns *every* table visible to your role, which is dozens of tables and tens of thousands of tokens; the single-table form returns only the section you need, in the same markdown layout. Reaching for the unscoped form when you already know the table name is a tokens/latency tax with zero benefit. ES has no per-table form (the index is a single document shape) — `tl schema es` is the only call there.
-
-**Process data with shell tools, not your context window.** Don't pull large result sets into your reasoning context just to filter, sort, count, or extract a field — that wastes tokens and slows you down. Pipe `tl … --json` (or `--csv`) into `jq`, `yq`, `rg`, or `duckdb` and read only the answer back. Pick the tool by shape:
+**Process data with shell tools, not your context window.** Don't pull large result sets into your reasoning context just to filter, sort, count, or extract a field — that wastes tokens and slows you down. Pipe `tl … --json` (or `--csv`, or `--toon`) into `jq`, `yq`, `rg`, or `duckdb`, as appropriate, and read only the answer back. Pick the tool by shape:
 
 - **`jq`** — filter, project, and transform JSON. The default for `tl … --json` post-processing.
   ```bash
@@ -68,6 +61,13 @@ Other key concepts:
 - **Reports** — saved report configurations that can be re-run
 - **Comments** — notes attached to sponsorships
 - **Adspots** — types of ads a channel carries (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost.
+- **Profiles** — per-organization actors that own sponsorship records on behalf of either side of a deal. A profile is buyer-side or seller-side:
+  - *Buyer-side (brand) profiles* — represent a sponsoring brand. Each brand profile has an M2M link to at most one `Brand` record (which are the actual advertiser identities). On a sponsorship, `creator_profile` is the buyer-side profile.
+  - *Seller-side (publisher) profiles* — attached to a `Publication`, which in turn owns one or more `Channel` records. A channel's adspots therefore inherit ownership through `channel.publication.profile`.
+  - **How to tell them apart** — three signals on the `thoughtleaders_profile` row, used in this order:
+    1. **`persona`** (canonical) — `1=Brand`, `4=Media Agency`, `3=Talent Manager` are buyer-side; `2=Creator`, `5=Creator Service` are seller-side. May be null on legacy rows.
+    2. **`is_advertiser` / `is_publisher`** booleans — feature flags; either or both can be true for staff-style profiles, but on normal user profiles they reliably mark side.
+  - Org scoping for sponsorships is profile-mediated: a sponsorship belongs to your org if **either** `creator_profile.organization` (brand side) **or** `ad_spot.channel.publication.profile.organization` (publisher side) matches yours.
 - **MSN** (Media Selling Network) — the ~11k 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 smaller, exclusive ~169 channels TL manages directly. A channel is in the TPP group if the `channel.is_tl_channel` is True.
@@ -169,26 +169,16 @@ tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) load
 tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (25 credits; Intelligence)
 tl recommender inspect-brand <ref>     # Show a brand profile's ideal similarity-profile breakdown (25 credits; Intelligence)
 tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal profile (25 credits; Intelligence)
-tl snapshots channel <id>              # Channel metrics over time — list curve, mult 1.2 (Firebolt-backed)
-tl snapshots video <id> --channel <id> # Video view curve — list curve, mult 1.2 (--channel required!)
-tl reports                             # List saved reports — list curve, mult 1.3
+tl snapshots channel <id>              # Channel metrics over time (Firebolt-backed)
+tl snapshots video <id> --channel <id> # Video view curve (--channel required!)
+tl reports                             # List saved reports
 tl reports run <id>                    # Run a saved report (credits vary)
-tl comments list <adlink-id>           # List comments — list curve, mult 1.0
-tl comments add <adlink-id> "msg"      # Add comment (free)
+tl <entity> comment-list <id>          # List comments on a sponsorship/channel/brand/upload
+tl <entity> comment-add <id> "msg"     # Add a comment (free)
+tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or superuser; free)
 ```
 
-**"List curve"** above means non-linear pricing: `cost = 1 + mult × 0.126 × n^1.2`. The flat 1-credit setup applies to every list call; the `mult` reflects per-resource complexity. `tl db {pg,fb,es}` shares the same curve at mult=1.4. Concrete totals:
-
-| Rows | mult=1.0 (comments, uploads, sponsorships) | mult=1.2 (snapshots) | mult=1.3 (reports) | mult=1.4 (db.pg / db.fb / db.es) |
-|---:|---:|---:|---:|---:|
-| 1 | 1 | 1 | 1 | 1 |
-| 10 | 3 | 3 | 4 | 4 |
-| 50 | 15 | 18 | 19 | 20 |
-| 100 | 33 | 39 | 42 | 45 |
-| 200 | 74 | 88 | 96 | 103 |
-| 500 | 219 | 263 | 285 | 307 |
-
-The marginal per-row cost is exactly proportional to `mult` — a 1.4× resource costs 1.4× the row part of a 1.0× resource at any size. Splitting a 500-row pull into ten 50-row calls saves ~30% but burns 10 setup floors instead of 1; "narrow the query" is almost always the better move than "fragment the pagination."
+**Credit costs are server-authoritative — run `tl describe` (overview) or `tl describe show <resource>` (one resource) to see the current rates and multipliers for every endpoint. Do not memorise rate values — they change.**
 
 ### Updating records