slab-cli 0.17.0__tar.gz → 0.19.0__tar.gz

{slab_cli-0.17.0 → slab_cli-0.19.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.17.0
+Version: 0.19.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.34.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: rich>=13.0
 Requires-Dist: inquirerpy>=0.3

{slab_cli-0.17.0 → slab_cli-0.19.0}/pyproject.toml

@@ -1,15 +1,17 @@
 [project]
 name = "slab-cli"
-version = "0.17.0"
+version = "0.19.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"}]
 requires-python = ">=3.13"
 dependencies = [
     # 0.31: CardSearchQuery.collapse_parallels — `card search` sends it on every query.
-    # 0.32 adds CompOut.grade_unconfirmed; older schemas drop the field on parse and the
-    # comps table silently loses its grade-sanity "?" marker.
-    "slab-schemas>=0.32.0",
+    # 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.
+    # 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.
+    "slab-schemas>=0.34.0",
     "httpx>=0.27",
     "rich>=13.0",
     "InquirerPy>=0.3",

{slab_cli-0.17.0 → slab_cli-0.19.0}/src/slab_cli/client.py

@@ -49,6 +49,7 @@ from slab_schemas.custom_sets import (
     CustomSetUpdate,
 )
 from slab_schemas.dashboard import CatalogStats, DashboardStats
+from slab_schemas.grading_desk import CollectionGradingDesk, GradingDesk
 from slab_schemas.pricing import CardComps, CardMarket, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
 from slab_schemas.timeseries import CardPriceHistory
@@ -125,6 +126,31 @@ class SlabClient:
         resp = self._request("GET", f"/cards/{card_uuid}/comps", params=params)
         return CardComps.model_validate(resp.json())
 
+    def get_grading_desk(
+        self, card_uuid: str, fee: float | None = None, company: str | None = None
+    ) -> GradingDesk:
+        params: dict[str, str] = {}
+        if fee is not None:
+            params["fee"] = str(fee)
+        if company:
+            params["company"] = company
+        resp = self._request("GET", f"/cards/{card_uuid}/grading-desk", params=params)
+        return GradingDesk.model_validate(resp.json())
+
+    def get_collection_grading_desk(
+        self, collector_uuid: str, fee: float | None = None,
+        company: str | None = None, limit: int = 50,
+    ) -> CollectionGradingDesk:
+        params: dict[str, str] = {"limit": str(limit)}
+        if fee is not None:
+            params["fee"] = str(fee)
+        if company:
+            params["company"] = company
+        resp = self._request(
+            "GET", f"/collectors/{collector_uuid}/collection/grading-desk", params=params
+        )
+        return CollectionGradingDesk.model_validate(resp.json())
+
     def get_card_price_history(
         self,
         card_uuid: str,

{slab_cli-0.17.0 → slab_cli-0.19.0}/src/slab_cli/commands/pricing.py

@@ -11,7 +11,9 @@ from ..context import MissingCollector, ctx
 from ..display import (
     console,
     render_card_market,
+    render_collection_grading_desk,
     render_comps,
+    render_grading_desk,
     render_portfolio,
     render_price_history,
     render_sealed_price_history,
@@ -77,6 +79,51 @@ def cmd_comps(args: list[str]) -> None:
     render_comps(ctx.client.get_card_comps(card.uuid))
 
 
+def _split_desk_flags(args: list[str]) -> tuple[list[str], float | None, str | None]:
+    """Pull `--fee <amount>` and `--company <name>` out of a grading query. Hand-rolled (the
+    shared flag grammar is search-specific); an unparseable fee errors loudly rather than
+    silently pricing off the default."""
+    rest: list[str] = []
+    fee: float | None = None
+    company: str | None = None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--fee" and i + 1 < len(args):
+            try:
+                fee = float(args[i + 1].lstrip("$"))
+            except ValueError:
+                raise SystemExit(f"--fee expects a number, got {args[i + 1]!r}")
+            i += 2
+        elif a == "--company" and i + 1 < len(args):
+            company = args[i + 1]
+            i += 2
+        else:
+            rest.append(a)
+            i += 1
+    return rest, fee, company
+
+
+def cmd_grade(args: list[str]) -> None:
+    """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:
+        return
+    render_grading_desk(ctx.client.get_grading_desk(card.uuid, fee=fee, company=company))
+
+
+def cmd_grade_sweep(args: list[str]) -> None:
+    """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)
+    )
+
+
 def _fetch_all_copies(page: int = 200, cap: int = 5000) -> tuple[list, PortfolioSummary | None]:
     """Page through the whole collection for the per-set/mover/break breakdowns, and grab the
     server's summary block (full-result aggregates, identical on every page) from the first page —

{slab_cli-0.17.0 → slab_cli-0.19.0}/src/slab_cli/commands/registry.py

@@ -59,6 +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", "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>"),
     ]),
@@ -79,6 +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", "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.17.0 → slab_cli-0.19.0}/src/slab_cli/display.py

@@ -19,7 +19,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.enums import Grade, SealedFormat
+from slab_schemas.grading_desk import CollectionGradingDesk, GradingDesk
+from slab_schemas.enums import BreakEvenRegion, Grade, SealedFormat
 from slab_schemas.pricing import CardComps, CardMarket, PortfolioSummary, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
 from slab_schemas.timeseries import CardPriceHistory
@@ -1141,6 +1142,143 @@ def render_comps(c: CardComps) -> None:
     console.print()
 
 
+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.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.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.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 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]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 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()
+    console.print(_card_headline(d.card_number, subjects, d.set_name, slot))
+
+    if d.raw is None:
+        console.print("\n  [slab.dim]This card has no raw market price yet, so there is no "
+                      "baseline to grade against.[/]\n")
+        return
+
+    console.print(
+        f"\n  Raw value: [slab.value]{money(d.raw.fair_market_value)}[/] "
+        f"[slab.dim](from {d.raw.sample_size} sales) · {d.grading_company} fee assumed: "
+        f"{money(d.fee)}"
+        + (" — pass --fee to use your rate" if d.fee_source == "default" else " (your rate)")
+        + "[/]"
+    )
+
+    if d.lanes:
+        table = slab_table([
+            ("If it grades", {}),
+            ("Sells for", {"justify": "right", "style": "slab.foil"}),
+            ("You clear", {"justify": "right"}),
+            ("Sales", {"justify": "right", "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)
+        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.[/]")
+
+    console.print()
+    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"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 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 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 market to read. That's the honest answer, not an "
+                      "error.[/]\n")
+        return
+
+    table = slab_table([
+        ("Card", {"no_wrap": False}),
+        ("Raw", {"justify": "right", "style": "slab.dim"}),
+        ("Gem pays", {"justify": "right"}),
+        ("Miss pays", {"justify": "right"}),
+        ("Break-even", {"justify": "right", "style": "slab.foil"}),
+        ("Qty", {"justify": "right", "style": "slab.dim"}),
+    ])
+    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
+        who = ", ".join(d.subjects) or f"#{d.card_number}"
+        card = f"{who} · {d.set_name or '—'}" + (f" · {d.finish}" if d.finish else "")
+        gem = next((l for l in d.lanes
+                    if l.grade_key.startswith(f"{d.grading_company}-") and l.payoff is not None),
+                   None)
+        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(
+            card,
+            money(d.raw.fair_market_value) if d.raw else "—",
+            signed_money(gem.payoff) if gem else "[slab.dim]—[/]",
+            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]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()
+
+
 def _render_portfolio_by_set(by_set: list | None) -> None:
     """Per-set breakdown, most valuable first. Highlights the top set and shows comp coverage."""
     if not by_set: