fablazing-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0
+
+- `fabz hero cards`: most-used deck cards for a hero vs the whole field
+  (frequency, win rate, Wilson lower bound, copies) - new API endpoint
+- `fabz card pov`: a card's win-rate impact for a hero, overall and per
+  opponent - new API endpoint
+- 95% confidence intervals on matchup and hero-cards win rates
+- Tabular API endpoints accept ?output=csv (+ ?api_key= for spreadsheet
+  IMPORTDATA use)
+
+## 0.2.2
+
+- Reference: name the exact `meets_threshold` field on tech candidates and
+  document `data_through` on matchup responses (newest ingested match)
+
 ## 0.2.1
 
 - Matchup: when no card clears the tech-card significance bar (common in

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fablazing-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Fablazing analytics from your terminal - Flesh and Blood matchups, meta, cards, and tournaments.
 Project-URL: Homepage, https://fablazing.com
 Author: Fablazing

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fablazing-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Fablazing analytics from your terminal - Flesh and Blood matchups, meta, cards, and tournaments."
 readme = "README.md"
 requires-python = ">=3.10"

fablazing_cli-0.3.0/src/fablazing_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/commands/card.py

@@ -1,4 +1,4 @@
-"""Card search, metadata, trends, synergies, popularity."""
+"""card search / show / trends / synergies / popular"""
 import typer
 
 from .. import client, resolve
@@ -11,11 +11,11 @@ app = typer.Typer(help="Card catalog and analytics")
 def search(
     query: str = typer.Argument(..., help="Part of a card name"),
     limit: int = typer.Option(25, "--limit", min=1, max=100),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Search cards and equipment by name."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get("/cards/search", {"q": query, "limit": limit})
     rows = [
         [
@@ -34,11 +34,11 @@ def search(
 @app.command()
 def show(
     card: str = typer.Argument(..., help="Card id or name"),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Show one card's metadata."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     card_id = resolve.card_id(card)
     payload = client.get(f"/cards/{card_id}")
     data = payload["data"]
@@ -60,11 +60,11 @@ def trends(
     card: str = typer.Argument(..., help="Card id or name"),
     format_type: str = typer.Option("cc", "--format"),
     days: int = typer.Option(30, "--days", min=1, max=365),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Daily play-rate time series."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     card_id = resolve.card_id(card)
     payload = client.get(f"/cards/{card_id}/trends", {"format": format_type, "days": days})
     data = payload["data"]
@@ -92,11 +92,11 @@ def synergies(
     card: str = typer.Argument(..., help="Card id or name"),
     format_type: str = typer.Option("cc", "--format"),
     limit: int = typer.Option(20, "--limit", min=1, max=50),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Co-occurrence synergy partners, with scores."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     card_id = resolve.card_id(card)
     payload = client.get(f"/cards/{card_id}/synergies", {"format": format_type, "limit": limit})
     rows = [
@@ -112,16 +112,66 @@ def synergies(
     emit(payload, tables=[(f"Synergies for {card_id}", ["ID", "Name", "Score", "Co-occur", "Price"], rows)])
 
 
+@app.command()
+def pov(
+    hero: str = typer.Argument(..., help="Hero id or name", autocompletion=resolve.complete_hero),
+    card: str = typer.Argument(..., help="Card id or name"),
+    format_type: str = typer.Option("cc", "--format"),
+    days: int = typer.Option(30, "--days", min=1, max=90),
+    top: int = typer.Option(12, "--top", min=1, max=50, help="Matchup rows"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
+):
+    """Card point of view: does running this card change the hero's win
+    rate, overall and against which opponents."""
+    set_mode(as_json, as_csv)
+    hero_id = resolve.hero_id(hero)
+    card_id = resolve.card_id(card)
+    payload = client.get(
+        f"/card-pov/{hero_id}/{card_id}", {"format": format_type, "days": days}
+    )
+    data = payload["data"]
+    overall = data.get("overall_card_impact") or {}
+    summary = [
+        f"[bold]{card_id}[/bold] on [bold]{hero_id}[/bold] - {format_type}, {days}d, "
+        f"{data.get('total_matches_analyzed', overall.get('total_matches', '?'))} matches"
+    ]
+    if overall:
+        summary.append(
+            f"presence {pct(overall.get('presence_rate'))} | "
+            f"WR with {pct(overall.get('card_win_rate'))} vs without {pct(overall.get('without_card_win_rate'))} "
+            f"(impact {overall.get('presence_impact', 0) * 100:+.1f}%)"
+        )
+    impacts = data.get("matchup_impacts") or []
+    rows = [
+        [
+            m.get("opponent_hero_name", m.get("opponent_hero_id", "")),
+            m.get("total_matches", ""),
+            pct(m.get("card_presence_rate")),
+            pct(m.get("base_win_rate")),
+            pct(m.get("card_win_rate")),
+            pct(m.get("without_card_win_rate")),
+            f"{m.get('presence_impact', 0) * 100:+.1f}%",
+        ]
+        for m in impacts[:top]
+    ]
+    emit(
+        payload,
+        tables=[("Per-matchup impact", ["Opponent", "N", "Presence", "Base WR", "With", "Without", "Impact"], rows)],
+        summary=summary,
+    )
+
+
 @app.command()
 def popular(
     format_type: str = typer.Option("cc", "--format"),
     days: int = typer.Option(7, "--days", min=1, max=365),
     limit: int = typer.Option(25, "--limit", min=1, max=100),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Most-played cards over the window."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get("/cards/popular", {"format": format_type, "days": days, "limit": limit})
     rows = [
         [

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/commands/hero.py

@@ -42,6 +42,50 @@ def show(
     emit(payload, tables=[(data.get("hero_name", hero_id), ["Field", "Value"], rows)])
 
 
+@app.command()
+def cards(
+    hero: str = typer.Argument(..., help="Hero id or name", autocompletion=resolve.complete_hero),
+    format_type: str = typer.Option("cc", "--format"),
+    days: int = typer.Option(30, "--days", min=1, max=90),
+    min_freq: float = typer.Option(0.02, "--min-freq", help="Minimum deck frequency"),
+    limit: int = typer.Option(30, "--limit", min=1, max=300),
+    json_: bool = typer.Option(False, "--json"),
+    csv_: bool = typer.Option(False, "--csv"),
+):
+    """Most-used deck cards for a hero across the whole field: frequency,
+    win rate, Wilson lower bound, average copies."""
+    set_mode(json_, csv_)
+    hero_id = resolve.hero_id(hero)
+    payload = client.get(
+        f"/heroes/{hero_id}/cards",
+        {"format": format_type, "days": days, "min_frequency": min_freq, "limit": limit},
+    )
+    data = payload["data"]
+    rows = [
+        [
+            c.get("card_id", ""),
+            pct(c.get("frequency")),
+            c.get("matches", ""),
+            pct(c.get("win_rate")),
+            pct(c.get("wilson_lower_bound")),
+            f"{c.get('copies_avg', 0):.1f}",
+            f"${c['tcg_market_price']:.2f}" if c.get("tcg_market_price") else "-",
+        ]
+        for c in data.get("cards", [])
+    ]
+    ci = data.get("overall_win_rate_ci") or [None, None]
+    summary = [
+        f"[bold]{resolve.hero_names().get(hero_id, hero_id)}[/bold] vs the field - "
+        f"{format_type}, {days}d: {data.get('total_games', 0)} games, "
+        f"WR {pct(data.get('overall_win_rate'))} (95% CI {pct(ci[0])}-{pct(ci[1])})"
+    ]
+    emit(
+        payload,
+        tables=[("Cards", ["Card", "Freq", "N", "WR", "Wilson LB", "Copies", "Price"], rows)],
+        summary=summary,
+    )
+
+
 @app.command()
 def aggregate(
     hero: str = typer.Argument(..., help="Hero id or name", autocompletion=resolve.complete_hero),

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/commands/matchup.py

@@ -50,6 +50,11 @@ def matchup(
     summary = [
         f"[bold]{name1}[/bold] vs [bold]{name2}[/bold] - {format_type}, {total} matches"
     ]
+    ci1, ci2 = data.get("deck1_win_rate_ci"), data.get("deck2_win_rate_ci")
+    if ci1 and ci2:
+        summary.append(
+            f"95% CI: {name1} {pct(ci1[0])}-{pct(ci1[1])}, {name2} {pct(ci2[0])}-{pct(ci2[1])}"
+        )
     if total == 0:
         emit(payload, summary=summary + ["No matches found for these filters."])
         return

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/commands/meta.py

@@ -58,17 +58,17 @@ def movers(
         {"days": days, "format": format_type, "source": source, "limit": limit, "sort_by": sort_by},
     )
     arrows = {"up": "↑", "down": "↓", "stable": "→"}
-    rows = [
-        [
+    rows = []
+    for h in payload["data"].get("heroes", []):
+        trend = h.get("trend_direction", "")
+        rows.append([
             h.get("hero_name", h.get("hero_id", "")),
             h.get("hero_id", ""),
-            arrows.get(h.get("trend_direction", ""), h.get("trend_direction", "")),
+            arrows.get(trend, trend),
             f"{h.get('percent_change', 0):+.1f}%",
             f"{h.get('current_popularity', 0):.1f}%",
             f"{h.get('avg_popularity', 0):.1f}%",
-        ]
-        for h in payload["data"].get("heroes", [])
-    ]
+        ])
     emit(
         payload,
         tables=[("Movers", ["Hero", "ID", "Trend", "Change", "Now", "Avg"], rows)],

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/commands/tournaments.py

@@ -1,4 +1,4 @@
-"""Tournament events, final standings, decklists."""
+"""tournament events, standings, decklists"""
 import typer
 
 from .. import client
@@ -15,11 +15,11 @@ def list_tournaments(
     has_decklists: bool = typer.Option(None, "--has-decklists/--no-decklists"),
     limit: int = typer.Option(25, "--limit", min=1, max=100),
     offset: int = typer.Option(0, "--offset", min=0),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """List tournaments, newest first."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get(
         "/tournaments",
         {
@@ -53,11 +53,11 @@ def list_tournaments(
 @app.command()
 def show(
     event_id: str = typer.Argument(..., help="Tournament id (from `tournaments list`)"),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Show one tournament's details."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get(f"/tournaments/{event_id}")
     data = payload["data"]
     rows = [
@@ -74,11 +74,11 @@ def show(
 @app.command()
 def standings(
     event_id: str = typer.Argument(...),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Winner + top 8 from official final standings."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get(f"/tournaments/{event_id}/standings")
     data = payload["data"]
     rows = [
@@ -98,11 +98,11 @@ def standings(
 @app.command()
 def decklists(
     event_id: str = typer.Argument(...),
-    json_: bool = typer.Option(False, "--json"),
-    csv_: bool = typer.Option(False, "--csv"),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
 ):
     """Submitted decklists for a tournament."""
-    set_mode(json_, csv_)
+    set_mode(as_json, as_csv)
     payload = client.get(f"/tournaments/{event_id}/decklists")
     rows = [
         [

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/main.py

@@ -27,8 +27,7 @@ def _main():
 
 
 def _completion_tip():
-    """One-time hint about tab completion. Skipped during shell completion
-    itself and when not on a terminal."""
+    # one-time nudge; skip when running as a shell completer or piped
     if any(k.endswith("_COMPLETE") for k in os.environ):
         return
     cfg = load_config()

{fablazing_cli-0.2.1 → fablazing_cli-0.3.0}/src/fablazing_cli/reference.py

@@ -34,14 +34,16 @@ analytics and paper tournament results for competitive Flesh and Blood.
   in deck1_transform / deck2_transform.
 - Tech cards are Wilson-scored against the matchup baseline, so a lucky
   streak on a small sample doesn't make the list. In close matchups no
-  card may clear the bar - then `tech_candidates` lists the closest
-  near-misses with their scores, explicitly marked below-threshold.
+  card may clear the bar - then `deck{1,2}_tech_candidates` lists the
+  closest near-misses with their scores; each entry carries
+  `meets_threshold: false` (that field, exactly) and the response
+  includes a `deck{1,2}_tech_note` explaining the situation.
 - Tournament standings and decklists come from official paper events.
 - Freshness: `matchup` queries live match data (ingested every ~5
   minutes). Meta snapshot/movers and card trends/popular are daily
-  aggregates (previous day processed at 03:00 / 02:00 UTC) - their
-  responses carry `data_through` in meta so you can see exactly how
-  fresh the numbers are.
+  aggregates (previous day processed at 03:00 / 02:00 UTC). Every one of
+  these responses carries `data_through` in meta - for matchup it is the
+  newest ingested match, for aggregates the latest processed day.
 
 ## Commands
 - `fablazing matchup EVO001 "Jarl" --days 30`
@@ -54,6 +56,11 @@ analytics and paper tournament results for competitive Flesh and Blood.
   pairing of the top-N heroes, in one call (never loop matchup for this)
 - `fablazing hero list` / `hero show EVO001`
 - `fablazing hero aggregate EVO001 --period 14d --source online`
+- `fablazing hero cards MON119 --days 30` - most-used deck cards for a
+  hero vs the whole field, with per-card WR and Wilson lower bound
+  (deck cards only, no equipment; live aggregation cached up to 4h)
+- `fablazing card pov MON119 "Dread Screamer"` - does running the card
+  change the hero's win rate, overall and per opponent (cached up to 4h)
 - `fablazing card search "sink"` / `card show sink_below_red`
 - `fablazing card trends sink_below_red --days 30`
 - `fablazing card synergies sink_below_red`
@@ -66,6 +73,11 @@ analytics and paper tournament results for competitive Flesh and Blood.
 - Tables on a terminal, JSON when piped or with --json (the JSON is the
   full API payload, a superset of the tables), CSV of the primary table
   with --csv. Data goes to stdout, errors to stderr.
+- Matchup and hero-cards responses include 95% Wilson confidence
+  intervals (`*_win_rate_ci`) next to the win rates.
+- Spreadsheets can skip the CLI: tabular API endpoints accept
+  `?output=csv&api_key=fbl_live_...` for Google Sheets IMPORTDATA
+  (careful: the key is then visible in the sheet).
 
 ## Exit codes
 0 ok, 1 api error, 2 usage error, 3 quota exceeded

fablazing_cli-0.2.1/src/fablazing_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.1"