slab-cli 0.18.0__tar.gz → 0.20.0__tar.gz

{slab_cli-0.18.0 → slab_cli-0.20.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.18.0
+Version: 0.20.0
 Summary: CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal.
 Author: dev_jeb
-Requires-Dist: slab-schemas>=0.32.0
+Requires-Dist: slab-schemas>=0.35.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: rich>=13.0
 Requires-Dist: inquirerpy>=0.3

{slab_cli-0.18.0 → slab_cli-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slab-cli"
-version = "0.18.0"
+version = "0.20.0"
 description = "CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal."
 readme = "README.md"
 authors = [{name = "dev_jeb"}]
@@ -9,7 +9,10 @@ dependencies = [
     # 0.31: CardSearchQuery.collapse_parallels — `card search` sends it on every query.
     # 0.32 adds CompOut.grade_unconfirmed (the comps table's grade-sanity "?" marker) and the
     # grading-desk models `slab card grade` / `slab collection grade` parse responses into.
-    "slab-schemas>=0.32.0",
+    # 0.34 reframes the grading desk from verdicts to break-even readings (BreakEvenRegion,
+    # GradingDesk.break_even) — the desk shows data, never tells the user to grade.
+    # 0.35 adds Liquidity/LiquidityLabel, which the market view's Sells column renders.
+    "slab-schemas>=0.35.0",
     "httpx>=0.27",
     "rich>=13.0",
     "InquirerPy>=0.3",

{slab_cli-0.18.0 → slab_cli-0.20.0}/src/slab_cli/commands/pricing.py

@@ -105,9 +105,9 @@ def _split_desk_flags(args: list[str]) -> tuple[list[str], float | None, str | N
 
 
 def cmd_grade(args: list[str]) -> None:
-    """Should I grade this card? Same player → set → card flow as `price`, then the grading desk:
-    what each grade nets after the fee, and how sure you'd need to be it gems before grading
-    beats keeping it raw. `--fee 19` prices at your rate; `--company SGC` switches grader."""
+    """The grading math for a card. Same player → set → card flow as `price`, then the grading
+    desk: what each grade nets after the fee and where break-even sits — the data to decide with;
+    the decision is yours. `--fee 19` prices at your rate; `--company SGC` switches grader."""
     args, fee, company = _split_desk_flags(args)
     card = _pick_card(args)
     if card is None:
@@ -116,8 +116,8 @@ def cmd_grade(args: list[str]) -> None:
 
 
 def cmd_grade_sweep(args: list[str]) -> None:
-    """Which of your raw cards are worth grading? Ranks every ungraded copy best-case first —
-    where the per-card bars become batch odds. `--fee 19` prices at your rate."""
+    """The grading math across your raw cards, biggest upside first — where the per-card
+    break-even bars become batch odds. `--fee 19` prices at your rate."""
     args, fee, company = _split_desk_flags(args)
     render_collection_grading_desk(
         ctx.client.get_collection_grading_desk(ctx.collector, fee=fee, company=company)

{slab_cli-0.18.0 → slab_cli-0.20.0}/src/slab_cli/commands/registry.py

@@ -59,7 +59,7 @@ GROUPS: list[Group] = [
         Command("search", "Search the catalog (player, set, team…)", catalog.cmd_search, "[query] [flags]"),
         Command("parallels", "Every parallel (the rainbow) of a card", catalog.cmd_rainbow, "<query>"),
         Command("price", "Market price + 7d/30d trend", pricing.cmd_price, "<query>"),
-        Command("grade", "Should I grade it? Payoffs, the bar, a verdict", pricing.cmd_grade, "<query> [--fee N]"),
+        Command("grade", "The grading math: payoffs per grade + break-even", pricing.cmd_grade, "<query> [--fee N]"),
         Command("comps", "Recent raw sales behind the price", pricing.cmd_comps, "<query>"),
         Command("history", "Price history over time", pricing.cmd_history, "<query>"),
     ]),
@@ -80,7 +80,7 @@ GROUPS: list[Group] = [
         Command("export", "Export a set to a printable checklist", export.cmd_export),
         Command("dashboard", "Overview: counts, value, composition", collection.cmd_dashboard),
         Command("portfolio", "Portfolio: cost basis vs FMV + top movers", pricing.cmd_portfolio),
-        Command("grade", "Which of your raw cards are worth grading", pricing.cmd_grade_sweep, "[--fee N]"),
+        Command("grade", "Grading math for every raw copy, best upside first", pricing.cmd_grade_sweep, "[--fee N]"),
     ]),
     Group("break", "case / box breaks", [
         Command("list", "Your breaks — pick one to see value vs cost + top pulls", breaks.cmd_break_list),

{slab_cli-0.18.0 → slab_cli-0.20.0}/src/slab_cli/display.py

@@ -20,7 +20,8 @@ from slab_schemas.community import (
 from slab_schemas.custom_sets import CustomSetDetail, CustomSetOut, CustomSetSearchResult
 from slab_schemas.dashboard import CatalogStats, DashboardStats, HighlightCard, LabeledCount
 from slab_schemas.grading_desk import CollectionGradingDesk, GradingDesk
-from slab_schemas.enums import Grade, GradingVerdict, SealedFormat
+from slab_schemas.enums import BreakEvenRegion, Grade, LiquidityLabel, SealedFormat
+from slab_schemas.liquidity import Liquidity
 from slab_schemas.pricing import CardComps, CardMarket, PortfolioSummary, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
 from slab_schemas.timeseries import CardPriceHistory
@@ -971,7 +972,8 @@ def render_card_market(m: CardMarket) -> None:
 
     # The Δ columns are FMV (appraisal) drift, not the window's sales — FMV smooths 90 days of
     # comps, so these lag the live market (two-lane rule, CLAUDE.md). Headers say FMV so a
-    # "+$5" cell reads as the appraisal moving, not as last week's market.
+    # "+$5" cell reads as the appraisal moving, not as last week's market. "Sells" is the other
+    # lane: real sale cadence from comps (liquidity), so the price and its pace sit side by side.
     table = slab_table([
         ("Grade", {"style": "slab.value"}),
         ("FMV", {"justify": "right"}),
@@ -979,6 +981,7 @@ def render_card_market(m: CardMarket) -> None:
         ("FMV Δ7d", {"justify": "right"}),
         ("FMV Δ30d", {"justify": "right"}),
         ("Comps", {"justify": "right", "style": "slab.dim"}),
+        ("Sells", {"style": "slab.dim"}),
     ])
 
     for pp in sorted(m.price_points, key=lambda p: (p.finish or "", p.grade_key)):
@@ -990,14 +993,39 @@ def render_card_market(m: CardMarket) -> None:
         if pp.price_low is not None and pp.price_high is not None:
             rng = f"${pp.price_low:,.0f} – ${pp.price_high:,.0f}"
         table.add_row(label, fmv, rng, signed_money(pp.price_change_7d),
-                      signed_money(pp.price_change_30d), str(pp.sample_size))
+                      signed_money(pp.price_change_30d), str(pp.sample_size),
+                      _liquidity_text(pp.liquidity))
 
     window = m.price_points[0].window_days
     console.print(heading("Market Price", f"{window}-day window, as of {m.as_of_date}"))
     console.print(table)
+    if any(pp.liquidity for pp in m.price_points):
+        console.print(
+            "  [slab.dim]Sells = how often this exact printing and grade actually sells — the "
+            "typical gap between real sales in the last 90 days, or the past year's count for "
+            "slow movers. A rare seller isn't bad; it means the price is an estimate you may "
+            "wait to realize.[/]"
+        )
     console.print()
 
 
+def _liquidity_text(liq: Liquidity | None) -> str:
+    """A liquidity reading as one short table cell — the pace, then the datum behind it.
+    Data statements only, mirroring the `liquidity.*` glossary."""
+    if liq is None:
+        return "—"
+    L = LiquidityLabel
+    if liq.median_days_between_sales is not None:
+        gap = liq.median_days_between_sales
+        word = {L.sells_daily: "~daily", L.sells_weekly: "~weekly"}.get(liq.label, "~monthly")
+        return f"{word} (every {gap}d)" if gap > 0 else f"{word} (several/day)"
+    if liq.label == L.too_new_to_say:
+        return f"too new to say ({liq.observed_days}d watched)"
+    if liq.label == L.no_recent_sales:
+        return "none this year"
+    return f"{liq.sales_365d}×/year"
+
+
 def _format_label(fmt: str) -> str:
     """SealedFormat value -> display label: hobby_box -> Hobby Box."""
     return fmt.replace("_", " ").title()
@@ -1142,36 +1170,41 @@ def render_comps(c: CardComps) -> None:
     console.print()
 
 
-def _desk_verdict_line(d: GradingDesk) -> str:
-    """The verdict as one plain sentence — the confidence-BAR framing (you grade a card once, so
-    the number is how good YOUR copy has to look, never "how often"). Wording mirrors the
-    `grading.verdict` glossary entry."""
+def _desk_reading_line(d: GradingDesk) -> str:
+    """Where the math lands, as one plain DATA sentence — never an instruction. slab's principle:
+    grading is subjective and the user is holding the card, so the desk states what the prices
+    show and leaves the send/keep decision with them. Wording mirrors the `grading.break_even`
+    glossary entry."""
     def payoff_of(grade_key: str | None):
         return next((l.payoff for l in d.lanes if l.grade_key == grade_key), None)
 
     gem = next((l for l in d.lanes if l.grade_key.startswith(f"{d.grading_company}-")), None)
-    if d.verdict == GradingVerdict.not_enough_data:
+    if d.break_even == BreakEvenRegion.not_enough_data:
         return ("[slab.dim]No graded market to read yet — nobody has sold graded copies of this "
                 "card recently. Not a no; an honest shrug.[/]")
-    if d.verdict == GradingVerdict.easy_no:
-        top = f"even a {gem.grade_key} only returns {signed_money(gem.payoff)}" if gem and             gem.payoff is not None else "no grade covers the fee"
-        return f"[slab.loss]Keep it raw[/] — {top} after the {money(d.fee)} fee."
+    if d.break_even == BreakEvenRegion.pays_at_no_grade:
+        top = f"even a {gem.grade_key} returns {signed_money(gem.payoff)}" if gem and             gem.payoff is not None else "no grade covers the fee"
+        return (f"[slab.loss]No grade covers the fee[/] — at today's prices {top} "
+                f"after the {money(d.fee)} fee.")
     miss_pay = payoff_of(d.miss_grade)
-    if d.verdict == GradingVerdict.easy_yes:
+    if d.break_even == BreakEvenRegion.pays_at_any_grade:
         miss_txt = (f"even a {d.miss_grade} nets {signed_money(miss_pay)}"
-                    if miss_pay is not None else "even a realistic miss beats staying raw")
-        return f"[slab.gain]Send it[/] — {miss_txt} after the {money(d.fee)} fee."
+                    if miss_pay is not None else "even a realistic miss nets more than staying raw")
+        return (f"[slab.gain]Every grade pays[/] — at today's prices {miss_txt} "
+                f"after the {money(d.fee)} fee.")
     pct = f"{d.ten_confidence_needed:.0%}"
     gem_txt = f"a {gem.grade_key} nets {signed_money(gem.payoff)}" if gem else "a gem pays"
     miss_txt = (f"a {d.miss_grade} comes back {signed_money(miss_pay)}"
                 if miss_pay is not None else f"a miss holds roughly raw value")
-    return (f"[slab.foil]Your call[/] — grade it only if you're more than {pct} sure it's a gem: "
-            f"{gem_txt}, {miss_txt}.")
+    return (f"[slab.foil]Depends on the grade[/] — {gem_txt}, {miss_txt}. Break-even sits at "
+            f"{pct}: below that chance of a gem, grading loses; above it, grading wins. "
+            f"You can see the card; that read is yours.")
 
 
 def render_grading_desk(d: GradingDesk) -> None:
-    """One card's grading decision: raw baseline, payoff per graded lane, and the verdict in the
-    bar framing. Every sentence traces to a `grading.*` glossary entry."""
+    """One card's grading math: raw baseline, payoff per graded lane, and where break-even lands.
+    Data to decide with, never a recommendation. Every sentence traces to a `grading.*` glossary
+    entry."""
     subjects = ", ".join(d.subjects) or "—"
     slot = f"{d.subset or '—'} · {d.finish}" if d.finish else (d.subset or "base")
     console.print()
@@ -1196,54 +1229,60 @@ def render_grading_desk(d: GradingDesk) -> None:
             ("Sells for", {"justify": "right", "style": "slab.foil"}),
             ("You clear", {"justify": "right"}),
             ("Sales", {"justify": "right", "style": "slab.dim"}),
+            ("Sells", {"style": "slab.dim"}),
         ])
         for l in d.lanes:
             n = f"{l.sample_size}!" if l.low_confidence else str(l.sample_size)
-            table.add_row(l.grade_key, money(l.fair_market_value), signed_money(l.payoff), n)
+            table.add_row(l.grade_key, money(l.fair_market_value), signed_money(l.payoff), n,
+                          _liquidity_text(l.liquidity))
         console.print(heading("Payoff per Grade", "after the fee, vs staying raw"))
         console.print(table)
         if any(l.low_confidence for l in d.lanes):
             console.print("  [slab.dim]! = priced off very few sales — an anecdote, "
                           "not a market.[/]")
+        if any(l.liquidity for l in d.lanes):
+            console.print("  [slab.dim]Sells = how often that grade actually trades — a payoff "
+                          "at a grade that sells twice a year is a longer wait than one that "
+                          "sells weekly.[/]")
 
     console.print()
-    console.print(f"  {_desk_verdict_line(d)}")
-    if d.verdict in (GradingVerdict.easy_yes, GradingVerdict.judgment_call) \
+    console.print(f"  {_desk_reading_line(d)}")
+    if d.break_even in (BreakEvenRegion.pays_at_any_grade, BreakEvenRegion.depends_on_grade) \
             and d.ten_confidence_needed_bad_day is not None and d.bad_day_grade:
         console.print(
             f"  [slab.dim]Cautious read: if misses come back {d.bad_day_grade} instead, "
-            f"the bar is {d.ten_confidence_needed_bad_day:.0%}.[/]"
+            f"break-even moves to {d.ten_confidence_needed_bad_day:.0%}.[/]"
         )
     if d.thin_data:
-        console.print("  [slab.warn]Thin data[/][slab.dim] — part of this verdict rests on "
+        console.print("  [slab.warn]Thin data[/][slab.dim] — part of this reading rests on "
                       "1-2 sales. Treat it as a hint, not a market reading.[/]")
     console.print()
 
 
 def render_collection_grading_desk(sweep: CollectionGradingDesk) -> None:
-    """The batch view: raw copies ranked best-case first. Here the per-card bars become real
-    odds — graded as a group, wins at these bars pay for the losses (the rip-EV logic)."""
+    """The batch view: raw copies with their grading math, biggest upside first. Here the per-card
+    bars become real odds — graded as a group, wins at these bars pay for the losses (the rip-EV
+    logic). Every cell is data; which cards to send, if any, stays the user's call."""
     console.print()
     covered = f"{sweep.deskable} of your {sweep.total_raw_copies} raw copies have a graded market to read"
     console.print(heading("Grading Desk", covered))
     if not sweep.entries:
         console.print("\n  [slab.dim]None of your raw cards have graded sales to compare "
-                      "against yet — no verdicts to give. That's the honest answer, not an "
+                      "against yet — no market to read. That's the honest answer, not an "
                       "error.[/]\n")
         return
 
     table = slab_table([
-        ("Verdict", {}),
         ("Card", {"no_wrap": False}),
         ("Raw", {"justify": "right", "style": "slab.dim"}),
         ("Gem pays", {"justify": "right"}),
-        ("Bar", {"justify": "right", "style": "slab.foil"}),
+        ("Miss pays", {"justify": "right"}),
+        ("Break-even", {"justify": "right", "style": "slab.foil"}),
         ("Qty", {"justify": "right", "style": "slab.dim"}),
     ])
-    VERDICT_TXT = {
-        GradingVerdict.easy_yes: "[slab.gain]send it[/]",
-        GradingVerdict.judgment_call: "[slab.foil]your call[/]",
-        GradingVerdict.easy_no: "[slab.loss]keep raw[/]",
+    BREAK_EVEN_TXT = {
+        BreakEvenRegion.pays_at_any_grade: "[slab.gain]any grade[/]",
+        BreakEvenRegion.pays_at_no_grade: "[slab.loss]no grade[/]",
     }
     for e in sweep.entries:
         d = e.desk
@@ -1252,23 +1291,25 @@ def render_collection_grading_desk(sweep: CollectionGradingDesk) -> None:
         gem = next((l for l in d.lanes
                     if l.grade_key.startswith(f"{d.grading_company}-") and l.payoff is not None),
                    None)
-        bar = "—"
-        if d.verdict == GradingVerdict.judgment_call and d.ten_confidence_needed is not None:
-            bar = f"{d.ten_confidence_needed:.0%}"
-        elif d.verdict == GradingVerdict.easy_yes:
-            bar = "any"
+        miss = next((l for l in d.lanes if l.grade_key == d.miss_grade), None)
+        if d.break_even == BreakEvenRegion.depends_on_grade and d.ten_confidence_needed is not None:
+            be = f"{d.ten_confidence_needed:.0%} gem"
+        else:
+            be = BREAK_EVEN_TXT.get(d.break_even, d.break_even.value)
         thin = " [slab.warn]!" if d.thin_data else ""
         table.add_row(
-            VERDICT_TXT.get(d.verdict, d.verdict.value) + thin, card,
+            card,
             money(d.raw.fair_market_value) if d.raw else "—",
             signed_money(gem.payoff) if gem else "[slab.dim]—[/]",
-            bar, str(e.quantity),
+            signed_money(miss.payoff) if miss and miss.payoff is not None else "[slab.dim]—[/]",
+            be + thin, str(e.quantity),
         )
     console.print(table)
     console.print(f"  [slab.dim]{sweep.fee_note}[/]")
-    console.print("  [slab.dim]Bar = how sure you'd need to be the card gems before grading "
-                  "beats keeping it raw. You can see its corners; slab can't. "
-                  "! = verdict rests on very few sales.[/]")
+    console.print("  [slab.dim]Break-even = the chance of a gem at which grading and staying raw "
+                  "pay the same — below it grading loses, above it grading wins; 'any grade' = "
+                  "even a miss pays, 'no grade' = even a gem doesn't. You can see each card's "
+                  "corners; slab can't — the call is yours. ! = rests on very few sales.[/]")
     console.print()