fablazing-cli 0.2.2__tar.gz → 0.4.0__tar.gz

{fablazing_cli-0.2.2 → fablazing_cli-0.4.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0
+
+- `fabz packages`: same-turn card pairs with lift, share, win rate and
+  typical assembly turn - new API endpoint
+- `fabz player search` / `player results`: paper tournament players
+- `fabz hero cards` now shows play/block/pitch usage rates and an
+  equipment table
+- Documented sub-format ids ("Open") in the reference
+- API: /llms.txt primer on the API domain; unhandled 500s are now
+  recorded server-side for review
+
+## 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

{fablazing_cli-0.2.2 → fablazing_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fablazing-cli
-Version: 0.2.2
+Version: 0.4.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.2 → fablazing_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fablazing-cli"
-version = "0.2.2"
+version = "0.4.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.4.0/src/fablazing_cli/__init__.py

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

{fablazing_cli-0.2.2 → fablazing_cli-0.4.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.2 → fablazing_cli-0.4.0}/src/fablazing_cli/commands/hero.py

@@ -42,6 +42,62 @@ 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}",
+            pct(c.get("play_rate")),
+            pct(c.get("block_rate")),
+            pct(c.get("pitch_rate")),
+        ]
+        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])})"
+    ]
+    tables = [("Cards", ["Card", "Freq", "N", "WR", "Wilson LB", "Copies", "Play", "Block", "Pitch"], rows)]
+    equipment = data.get("equipment") or []
+    if equipment:
+        equipment_rows = [
+            [
+                e.get("card_id", ""),
+                pct(e.get("frequency")),
+                e.get("matches", ""),
+                pct(e.get("win_rate")),
+                pct(e.get("wilson_lower_bound")),
+            ]
+            for e in equipment[:15]
+        ]
+        tables.append(("Equipment", ["Item", "Freq", "N", "WR", "Wilson LB"], equipment_rows))
+    emit(payload, tables=tables, summary=summary)
+
+
 @app.command()
 def aggregate(
     hero: str = typer.Argument(..., help="Hero id or name", autocompletion=resolve.complete_hero),

{fablazing_cli-0.2.2 → fablazing_cli-0.4.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.2 → fablazing_cli-0.4.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.4.0/src/fablazing_cli/commands/packages.py

@@ -0,0 +1,62 @@
+"""the packages command: same-turn card pairs with lift"""
+from typing import Optional
+
+import typer
+
+from .. import client, resolve
+from ..output import emit, set_mode
+
+
+def packages(
+    hero: str = typer.Argument(..., help="Hero id or name", autocompletion=resolve.complete_hero),
+    format_type: str = typer.Option("cc", "--format"),
+    opponent: Optional[str] = typer.Option(None, "--opponent", help="Rank against this opponent only"),
+    seed: Optional[str] = typer.Option(None, "--seed", help="Only packages containing this card"),
+    min_lift: float = typer.Option(1.4, "--min-lift"),
+    min_games: int = typer.Option(10, "--min-games"),
+    sort: str = typer.Option("usage", "--sort", help="usage | lift | win_rate | turn"),
+    limit: int = typer.Option(20, "--limit", min=1, max=200),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
+):
+    """Distinctive same-turn card pairs for a hero: how often they land
+    together, the lift over chance, and the win rate when they do."""
+    set_mode(as_json, as_csv)
+    hero_id = resolve.hero_id(hero)
+    params = {
+        "format": format_type,
+        "min_lift": min_lift,
+        "min_games": min_games,
+        "sort": sort,
+        "limit": limit,
+    }
+    if opponent:
+        params["opponent"] = resolve.hero_id(opponent)
+    if seed:
+        params["seed_card"] = resolve.card_id(seed)
+    payload = client.get(f"/packages/{hero_id}", params)
+    data = payload["data"]
+
+    rows = []
+    for p in data.get("packages", []):
+        pair = p.get("cards") or []
+        # the packages store reports pct_games/win_rate in 0-100 units,
+        # unlike the rest of the API's 0-1 fractions
+        rows.append([
+            " + ".join(pair),
+            p.get("games_together", ""),
+            f"{p.get('pct_games', 0):.1f}%",
+            f"{p.get('lift', 0):.2f}x",
+            f"{p.get('win_rate', 0):.1f}%",
+            p.get("typical_turn", ""),
+        ])
+    corpus = data.get("corpus") or {}
+    summary = [
+        f"[bold]{data.get('hero_name', hero_id)}[/bold] packages - {format_type}, "
+        f"{corpus.get('games', '?')} games in corpus, sorted by {sort}"
+    ]
+    emit(
+        payload,
+        tables=[("Packages", ["Pair", "Games", "Share", "Lift", "WR", "Turn"], rows)],
+        summary=summary,
+    )

fablazing_cli-0.4.0/src/fablazing_cli/commands/player.py

@@ -0,0 +1,52 @@
+"""paper tournament players: search + results"""
+import typer
+
+from .. import client
+from ..output import emit, set_mode
+
+app = typer.Typer(help="Paper tournament players")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Part of a player name"),
+    limit: int = typer.Option(25, "--limit", min=1, max=100),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
+):
+    """Search tournament players by name."""
+    set_mode(as_json, as_csv)
+    payload = client.get("/players/search", {"q": query, "limit": limit})
+    rows = [
+        [p.get("id", ""), p.get("player_name", ""), p.get("country", "")]
+        for p in payload["data"]
+    ]
+    emit(payload, tables=[("Players", ["ID", "Name", "Country"], rows)])
+
+
+@app.command()
+def results(
+    player_id: str = typer.Argument(..., help="Player id (from `player search`)"),
+    limit: int = typer.Option(25, "--limit", min=1, max=200),
+    as_json: bool = typer.Option(False, "--json"),
+    as_csv: bool = typer.Option(False, "--csv"),
+):
+    """A player's paper tournament results."""
+    set_mode(as_json, as_csv)
+    payload = client.get(f"/players/{player_id}/results", {"limit": limit})
+    rows = []
+    for r in payload["data"]:
+        wins, losses = r.get("wins"), r.get("losses")
+        record = f"{wins}-{losses}" if wins is not None and losses is not None else "-"
+        rows.append([
+            (r.get("created_at") or "")[:10],
+            r.get("tournament_name", ""),
+            r.get("format", ""),
+            r.get("hero_played") or "-",
+            record,
+            r.get("standing") or "-",
+        ])
+    emit(
+        payload,
+        tables=[("Results", ["Date", "Tournament", "Format", "Hero", "W-L", "Standing"], rows)],
+    )

{fablazing_cli-0.2.2 → fablazing_cli-0.4.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.2 → fablazing_cli-0.4.0}/src/fablazing_cli/main.py

@@ -5,8 +5,9 @@ import sys
 import typer
 
 from . import __version__
-from .commands import auth, card, hero, meta, tournaments
+from .commands import auth, card, hero, meta, player, tournaments
 from .commands.matchup import matchup
+from .commands.packages import packages
 from .config import load_config, save_config
 from .output import console, err_console
 from .reference import REFERENCE
@@ -27,8 +28,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()
@@ -47,7 +47,9 @@ app.add_typer(hero.app, name="hero")
 app.add_typer(meta.app, name="meta")
 app.add_typer(card.app, name="card")
 app.add_typer(tournaments.app, name="tournaments")
+app.add_typer(player.app, name="player")
 app.command()(matchup)
+app.command()(packages)
 
 
 @app.command()

{fablazing_cli-0.2.2 → fablazing_cli-0.4.0}/src/fablazing_cli/reference.py

@@ -56,18 +56,42 @@ 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: per-card WR, Wilson lower bound, copies, and
+  play/block/pitch usage rates, plus an equipment table (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`
 - `fablazing card popular --days 7`
+- `fablazing packages EVO001 --min-lift 1.5 --sort lift` - distinctive
+  same-turn card pairs: games together, lift over chance, win rate,
+  typical assembly turn. `--opponent` ranks vs one matchup, `--seed`
+  filters to pairs containing a card.
+- `fablazing player search "Emily"` / `player results <id>` - paper
+  tournament players and their event records.
 - `fablazing tournaments list --type Calling`
 - `fablazing tournaments show <id>` / `standings <id>` / `decklists <id>`
 - `fablazing reference` prints this text.
 
+## Sub-formats ("Open")
+Each format family maps to internal ids: cc = 0,1 plus Open 4; sage =
+14,15 plus Open 16; blitz = 2,3; ll = 8,11; gage = 18. All ids in a
+family are included by default. The API's matchup endpoint accepts
+`sub_formats` (repeatable int) to narrow, e.g. sub_formats=0&sub_formats=1
+for cc without Open.
+
 ## Output
 - 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.2/src/fablazing_cli/__init__.py

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