thoughtleaders-cli 0.7.7__tar.gz → 0.7.8__tar.gz

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/.github/workflows/python-publish.yml

@@ -11,8 +11,8 @@ jobs:
   release-build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -30,7 +30,7 @@ jobs:
           python -m pip install --upgrade build
           python -m build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: release-dists
           path: dist/
@@ -44,7 +44,7 @@ jobs:
       name: pypi
       url: https://pypi.org/project/thoughtleaders-cli/${{ github.event.release.name }}
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: release-dists
           path: dist/

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.7
+Version: 0.7.8
 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
@@ -211,9 +211,9 @@ tl describe show sponsorships --filters    # Available filters for sponsorships
 tl balance                                 # Your credit balance
 ```
 
-`tl db pg` is priced **per-query**: a base rate plus a multiplier extra for every expensive table referenced, plus a flat per-row charge for every expensive column read. Sensitive fields (demographics, channel outreach emails) are expensive. Run `tl describe show db --json` to see the live `pg_expensive` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+`tl db pg` is priced **per-row**: the per-row rate is the **sum of the rates of the tables the query touches** (default 1.0/row; some tables are cheaper or dearer), plus a flat per-row charge for every expensive column read (demographics, channel outreach emails), all times the rows returned. Aggregate queries (`count`/`GROUP BY`) add a surcharge proportional to the rows they aggregate. Run `tl describe show db --json` to see the live `pg_pricing` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
 
-To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends are flat-rate (no per-column charges), so the estimate is the volume curve at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
+To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends have no per-table or per-column charges, so the estimate is the flat per-row rate at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
 
 # Terminology
 

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/README.md

@@ -183,9 +183,9 @@ tl describe show sponsorships --filters    # Available filters for sponsorships
 tl balance                                 # Your credit balance
 ```
 
-`tl db pg` is priced **per-query**: a base rate plus a multiplier extra for every expensive table referenced, plus a flat per-row charge for every expensive column read. Sensitive fields (demographics, channel outreach emails) are expensive. Run `tl describe show db --json` to see the live `pg_expensive` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
+`tl db pg` is priced **per-row**: the per-row rate is the **sum of the rates of the tables the query touches** (default 1.0/row; some tables are cheaper or dearer), plus a flat per-row charge for every expensive column read (demographics, channel outreach emails), all times the rows returned. Aggregate queries (`count`/`GROUP BY`) add a surcharge proportional to the rows they aggregate. Run `tl describe show db --json` to see the live `pg_pricing` map, and check `usage.credit_rate` in the response envelope after a query to see what your query was actually charged.
 
-To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends are flat-rate (no per-column charges), so the estimate is the volume curve at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
+To preview a query's cost **before** running it, add `--pricing`: `tl db pg "SELECT … LIMIT 100" --pricing` runs only the planner's `EXPLAIN`, prints the cost breakdown and an upper-bound estimate (at the query's `LIMIT`), and costs a flat **1 credit** — the query itself never executes. Works with `--json` too. `--pricing` is also available on `tl db fb` and `tl db es`; those backends have no per-table or per-column charges, so the estimate is the flat per-row rate at the query's row ceiling (`LIMIT` for Firebolt, `size` — or the aggregation doc cap — for Elasticsearch).
 
 # Terminology
 

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/pyproject.toml

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

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/skills/tl/SKILL.md

@@ -415,9 +415,9 @@ tl db pg "SELECT b.name, COUNT(*) AS deals
 
 If unsure about what information to find where, read the [references/postgresql-schema.md](references/postgresql-schema.md) file for instructions. Use just `tl pg schema` to see the entire SQL schema.
 
-**PG cost is per-query.** The credit cost for a `tl db pg` call is a base rate plus a multiplier extra for every expensive table referenced, plus a **flat per-row charge** for every expensive column read (an expensive column costs its configured value for every row returned). Most tables and columns are not expensive; sensitive ones (e.g. demographics, channel outreach emails) cost more. Run `tl describe show db --json` to see the live `pg_expensive` map, and check `usage.credit_rate` / `usage.pricing` in the response envelope after a query to see what your query was actually charged.
+**PG cost is per-row.** The credit cost for a `tl db pg` call is its per-row rate — the **sum of the rates of the tables the query touches** (default 1.0/row; some tables are cheaper or dearer) plus a **flat per-row charge** for every expensive column read — times the rows returned. So a join pays for each table it reads, and an expensive column costs its configured value for every row returned. Aggregate queries (`count`/`GROUP BY`) add a surcharge proportional to the estimated rows aggregated. Sensitive columns (e.g. demographics, channel outreach emails) cost more per row. Run `tl describe show db --json` to see the live `pg_pricing` map, and check `usage.credit_rate` / `usage.pricing` in the response envelope after a query to see what your query was actually charged.
 
-**Preview cost before running.** Add `--pricing` to estimate a query's cost without executing it: `tl db pg "SELECT … LIMIT 100" --pricing` runs only `EXPLAIN`, prints the multiplier + per-row breakdown and an upper-bound cost (at the query's LIMIT), and costs a flat 1 credit. Use this before large or expensive-column queries. Works with `--json`. `--pricing` also works on `tl db fb` and `tl db es` — those backends have no per-column charges, so the estimate is just the volume curve at the row ceiling (`LIMIT` for Firebolt; `size`, or the aggregation doc cap, for Elasticsearch).
+**Preview cost before running.** Add `--pricing` to estimate a query's cost without executing it: `tl db pg "SELECT … LIMIT 100" --pricing` runs only `EXPLAIN`, prints the per-row rate + per-row breakdown and an upper-bound cost (at the query's LIMIT), and costs a flat 1 credit. Use this before large or expensive-column queries. Works with `--json`. `--pricing` also works on `tl db fb` and `tl db es` — those backends have no per-table or per-column charges, so the estimate is just the flat per-row rate at the row ceiling (`LIMIT` for Firebolt; `size`, or the aggregation doc cap, for Elasticsearch).
 
 ### Three sources, each authoritative for different things
 

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/src/tl_cli/commands/describe.py

@@ -124,11 +124,11 @@ def _summarise_modes(credits: dict) -> tuple[str, str, bool]:
       - 'free'                           → "free"
       - 'flat'                           → "<rate> per call"
       - 'linear-per-result' (one mode)   → "<rate> × n  (per result)"
-      - 'curve' (one mode, mult=R)       → "curve (×R)"
+      - 'per-row' (one mode, rate=R)     → "R/row"
       - mixed (e.g. channels has detail / history / similar at different rates)
                                          → per-mode "<mode> R" joined with commas
 
-    The typical-cost column uses the n=100 example for curve/per-result and
+    The typical-cost column uses the n=100 example for per-row/per-result and
     the flat rate for flat. Free shows '-'.
     """
     modes = _modes_block(credits)
@@ -163,8 +163,8 @@ def _format_single_mode_label(mode_name: str, payload: dict, *, terse: bool = Fa
         return f"{_fmt_credits(rate)}/call" if terse else f"{_fmt_credits(rate)} per call"
     if model == "linear-per-result":
         return f"{_fmt_credits(rate)}×n" if terse else f"{_fmt_credits(rate)} × n  (per result)"
-    if model == "curve":
-        return f"curve ×{rate}"
+    if model == "per-row":
+        return f"{_fmt_credits(rate)}/row"
     return f"{model} ({_fmt_credits(rate)})"
 
 
@@ -256,25 +256,25 @@ def _print_pricing_section(credits: dict) -> None:
             "Estimate using the examples above before running with a large limit."
         )
 
-    # Surface live PG expensive-items pricing when the server included it
-    # (db resource only).
-    _print_pg_expensive_section(credits.get("pg_expensive"))
+    # Surface live PG per-table / per-column pricing when the server included
+    # it (db resource only).
+    _print_pg_pricing_section(credits.get("pg_pricing"))
 
 
-def _print_pg_expensive_section(expensive: object) -> None:
-    """Render the `credits.pg_expensive` block as a flat dotted-path table.
+def _print_pg_pricing_section(pricing: object) -> None:
+    """Render the `credits.pg_pricing` block as a flat dotted-path table.
 
     The server emits a three-level nested structure
     ``{base: {pg: float}, tables: {name: float}, columns: {"t.c": float}}``;
-    flattening each leaf to ``<section>.<key>`` keeps the live extras
-    visible in one sorted scan, with the base rate clearly distinguished
-    from the per-table and per-column extras a query may or may not
-    incur.
+    flattening each leaf to ``<section>.<key>`` keeps the live rates visible
+    in one sorted scan, with the default per-row rate (``default.pg``)
+    distinguished from the per-table rates and per-column extras a query
+    may or may not incur.
     """
-    if not isinstance(expensive, dict) or not expensive:
+    if not isinstance(pricing, dict) or not pricing:
         return
     rows: list[tuple[str, float]] = []
-    for section, body in expensive.items():
+    for section, body in pricing.items():
         if not isinstance(body, dict):
             # Forward-compat: an unexpected leaf type — surface as-is
             # under the section name rather than dropping it silently.
@@ -284,15 +284,16 @@ def _print_pg_expensive_section(expensive: object) -> None:
             rows.append((f"{section}.{key}", val))
     if not rows:
         return
-    sub = Table(title="PG expensive items (live)")
+    sub = Table(title="PG per-row pricing (live)")
     sub.add_column("Path", style="bold")
-    sub.add_column("Extra", justify="right")
+    sub.add_column("Rate", justify="right")
     for path, val in sorted(rows):
         sub.add_row(path, _fmt_credits(val))
     console.print(sub)
     console.print(
-        "[dim]These are the rates, not a per-query total. For the actual cost "
-        "of a specific query (before running it), use[/dim] "
+        "[dim]These are the per-table / per-column rates, not a per-query total. "
+        "A query's per-row rate is the sum of the rates of the tables it touches. "
+        "For the actual cost of a specific query (before running it), use[/dim] "
         "[cyan]tl db pg \"SELECT ...\" --pricing[/cyan][dim].[/dim]"
     )
 

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/src/tl_cli/output/formatter.py

@@ -540,7 +540,7 @@ def output_pricing_estimate(data: dict, fmt: str) -> None:
 
     Firebolt and Elasticsearch have no per-column extras — their estimate
     carries `per_row_extra=0` and empty expensive-item maps, so the
-    breakdown table is skipped and only the volume-curve cost shows.
+    breakdown table is skipped and only the per-row cost shows.
     A `limit`/cost of `None` (e.g. a Firebolt query with no `LIMIT`) means
     the row count is unbounded and the cost can't be pinned ahead of time.
     """
@@ -567,24 +567,30 @@ def output_pricing_estimate(data: dict, fmt: str) -> None:
     else:
         console.print(
             "  Estimated cost: [yellow]depends on rows returned[/yellow] "
-            "(no row limit set — cost scales with the volume curve)"
+            "(no row limit set — cost is linear in rows returned)"
         )
-    console.print(f"  Multiplier (base + expensive tables): {multiplier}")
+    console.print(f"  Per-row rate (sum of table rates):    {multiplier}")
     console.print(f"  Per-row extra (expensive columns):    {per_row}")
+    agg_surcharge = est.get("agg_surcharge")
+    if agg_surcharge:
+        console.print(
+            f"  Aggregate surcharge (flat):           {agg_surcharge} "
+            f"[dim](≈{est.get('aggregated_rows', 0):,} rows aggregated)[/dim]"
+        )
     if planner_rows is not None:
         console.print(
             f"  [dim]Planner row estimate (pre-LIMIT): {planner_rows:,}[/dim]"
         )
 
-    tables = est.get("expensive_tables") or {}
+    tables = est.get("table_rates") or {}
     columns = est.get("expensive_columns") or {}
     if tables or columns:
-        sub = Table(title="Expensive items this query touches")
+        sub = Table(title="Per-row rates this query touches")
         sub.add_column("Item", style="bold")
         sub.add_column("Kind")
-        sub.add_column("Extra", justify="right")
+        sub.add_column("Rate", justify="right")
         for name, val in sorted(tables.items()):
-            sub.add_row(name, "table (multiplier)", _fmt_credits(val))
+            sub.add_row(name, "table (per row)", f"{_fmt_credits(val)}/row")
         for path, val in sorted(columns.items()):
             sub.add_row(path, "column (per row)", f"{_fmt_credits(val)}/row")
         console.print(sub)

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/tests/test_describe.py

@@ -1,13 +1,13 @@
 """Tests for `tl describe` output helpers."""
 
-from tl_cli.commands.describe import _print_pg_expensive_section
+from tl_cli.commands.describe import _print_pg_pricing_section
 
 
-# Sample shape that the server actually emits under `credits.pg_expensive`:
-# three sections (base / tables / columns), each a flat dict of leaves.
-_LIVE_PG_EXPENSIVE = {
-    "base": {"pg": 1.4},
-    "tables": {"thoughtleaders_channel": 3.0},
+# Sample shape that the server actually emits under `credits.pg_pricing`:
+# three sections (default / tables / columns), each a flat dict of leaves.
+_LIVE_PG_PRICING = {
+    "default": {"pg": 1.0},
+    "tables": {"thoughtleaders_adlink": 0.1, "thoughtleaders_channel": 3.0},
     "columns": {
         "thoughtleaders_channel.outreach_email": 80.0,
         "thoughtleaders_channel.demographic_male_share": 50.0,
@@ -18,21 +18,22 @@ _LIVE_PG_EXPENSIVE = {
 }
 
 
-class TestPrintPgExpensiveSection:
+class TestPrintPgPricingSection:
     def test_missing_block_renders_nothing(self, capsys):
-        _print_pg_expensive_section(None)
+        _print_pg_pricing_section(None)
         assert capsys.readouterr().out == ""
 
     def test_empty_dict_renders_nothing(self, capsys):
-        _print_pg_expensive_section({})
+        _print_pg_pricing_section({})
         assert capsys.readouterr().out == ""
 
     def test_nested_block_flattens_to_dotted_paths(self, capsys):
-        _print_pg_expensive_section(_LIVE_PG_EXPENSIVE)
+        _print_pg_pricing_section(_LIVE_PG_PRICING)
         out = capsys.readouterr().out
         # Section headers prefix every leaf key.
-        assert "base.pg" in out
+        assert "default.pg" in out
         assert "tables.thoughtleaders_channel" in out
+        assert "tables.thoughtleaders_adlink" in out
         assert "columns.thoughtleaders_channel.outreach_email" in out
         assert "columns.thoughtleaders_channel.demographic_male_share" in out
         # The numeric values pass through `_fmt_credits` (integer-valued
@@ -41,10 +42,10 @@ class TestPrintPgExpensiveSection:
         assert "50" in out
         assert "3" in out
         # Title appears.
-        assert "PG expensive items (live)" in out
+        assert "PG per-row pricing (live)" in out
 
     def test_directs_user_to_pricing_flag(self, capsys):
-        _print_pg_expensive_section(_LIVE_PG_EXPENSIVE)
+        _print_pg_pricing_section(_LIVE_PG_PRICING)
         out = capsys.readouterr().out
         # The note points at the per-query estimator and clarifies these
         # are rates, not a total.
@@ -53,18 +54,18 @@ class TestPrintPgExpensiveSection:
 
     def test_sections_sort_into_dotted_order(self, capsys):
         """Entries sort lexicographically by their flattened dotted path,
-        so `base.*` rows precede `columns.*`, which precede `tables.*`."""
-        _print_pg_expensive_section(_LIVE_PG_EXPENSIVE)
+        so `columns.*` rows precede `default.*`, which precede `tables.*`."""
+        _print_pg_pricing_section(_LIVE_PG_PRICING)
         out = capsys.readouterr().out
-        base_pos = out.index("base.pg")
         cols_pos = out.index("columns.thoughtleaders_channel.outreach_email")
+        default_pos = out.index("default.pg")
         tables_pos = out.index("tables.thoughtleaders_channel")
-        assert base_pos < cols_pos < tables_pos
+        assert cols_pos < default_pos < tables_pos
 
     def test_unexpected_leaf_type_surfaces_under_section_name(self, capsys):
         """Forward-compat: if a future server adds a non-dict section
         we render it as-is rather than dropping it silently."""
-        _print_pg_expensive_section({"scalar_section": 42, "tables": {"t": 1.0}})
+        _print_pg_pricing_section({"scalar_section": 42, "tables": {"t": 1.0}})
         out = capsys.readouterr().out
         assert "scalar_section" in out
         assert "tables.t" in out

{thoughtleaders_cli-0.7.7 → thoughtleaders_cli-0.7.8}/tests/test_output.py

@@ -377,10 +377,10 @@ class TestPgPricingEstimate:
 
     _SAMPLE = {
         "pricing_estimate": {
-            "base": 1.4,
+            "default": 1.4,
             "multiplier": 4.4,
             "per_row_extra": 280.0,
-            "expensive_tables": {"thoughtleaders_channel": 3.0},
+            "table_rates": {"thoughtleaders_channel": 3.0},
             "expensive_columns": {
                 "thoughtleaders_channel.outreach_email": 80.0,
                 "thoughtleaders_channel.demographic_male_share": 50.0,
@@ -404,7 +404,7 @@ class TestPgPricingEstimate:
         assert "280" in out          # per-row extra
         assert "thoughtleaders_channel.outreach_email" in out
         assert "80/row" in out
-        assert "table (multiplier)" in out
+        assert "table (per row)" in out
 
     def test_json_mode_dumps_full_envelope(self, capsys):
         import json
@@ -430,8 +430,8 @@ class TestPgPricingEstimate:
         from tl_cli.output.formatter import output_pricing_estimate
         data = {
             "pricing_estimate": {
-                "base": 1.4, "multiplier": 1.4, "per_row_extra": 0.0,
-                "expensive_tables": {}, "expensive_columns": {},
+                "default": 1.4, "multiplier": 1.4, "per_row_extra": 0.0,
+                "table_rates": {}, "expensive_columns": {},
                 "limit": 10, "planner_estimated_rows": 3,
                 "estimated_cost_at_limit": 3.8,
             },
@@ -447,8 +447,8 @@ class TestPgPricingEstimate:
         from tl_cli.output.formatter import output_pricing_estimate
         data = {
             "pricing_estimate": {
-                "base": 1.4, "multiplier": 1.4, "per_row_extra": 0.0,
-                "expensive_tables": {}, "expensive_columns": {},
+                "default": 1.4, "multiplier": 1.4, "per_row_extra": 0.0,
+                "table_rates": {}, "expensive_columns": {},
                 "limit": None, "planner_estimated_rows": None,
                 "estimated_cost_at_limit": None,
             },