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

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

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.1
+
+- `--sub-format` flag on matchup (repeatable) - the API capability was
+  documented but unreachable from the CLI
+- Reference: honest per-command format coverage (meta and aggregate
+  commands don't cover gage; matchup and card commands do)
+- README: troubleshooting note for interrupted pip upgrades
+
+## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fablazing-cli
-Version: 0.3.0
+Version: 0.4.1
 Summary: Fablazing analytics from your terminal - Flesh and Blood matchups, meta, cards, and tournaments.
 Project-URL: Homepage, https://fablazing.com
 Author: Fablazing
@@ -58,6 +58,13 @@ one. Copy count filters work on matchup includes:
 Tables on a terminal. JSON when piped or with `--json`, CSV with `--csv`.
 Exit codes: 0 ok, 1 api error, 2 usage error, 3 quota exceeded.
 
+## Troubleshooting
+
+If an upgrade leaves `fabz` broken (interrupted pip uninstall can strand
+an empty `fablazing_cli` directory and `~ablazing_cli` backup folders):
+
+    pip install --force-reinstall fablazing-cli
+
 ## Tab completion
 
     fablazing --install-completion

{fablazing_cli-0.3.0 → fablazing_cli-0.4.1}/README.md

@@ -43,6 +43,13 @@ one. Copy count filters work on matchup includes:
 Tables on a terminal. JSON when piped or with `--json`, CSV with `--csv`.
 Exit codes: 0 ok, 1 api error, 2 usage error, 3 quota exceeded.
 
+## Troubleshooting
+
+If an upgrade leaves `fabz` broken (interrupted pip uninstall can strand
+an empty `fablazing_cli` directory and `~ablazing_cli` backup folders):
+
+    pip install --force-reinstall fablazing-cli
+
 ## Tab completion
 
     fablazing --install-completion

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

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

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

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

@@ -69,7 +69,9 @@ def cards(
             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 "-",
+            pct(c.get("play_rate")),
+            pct(c.get("block_rate")),
+            pct(c.get("pitch_rate")),
         ]
         for c in data.get("cards", [])
     ]
@@ -79,11 +81,21 @@ def cards(
         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,
-    )
+    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()

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

@@ -11,6 +11,7 @@ def matchup(
     hero1: str = typer.Argument(..., help="Deck 1 hero (id or name)", autocompletion=resolve.complete_hero),
     hero2: str = typer.Argument(..., help="Deck 2 hero (id or name)", autocompletion=resolve.complete_hero),
     format_type: str = typer.Option("cc", "--format"),
+    sub_formats: List[int] = typer.Option([], "--sub-format", help="Restrict to sub-format ids (repeatable), e.g. --sub-format 0 --sub-format 1 for cc without Open"),
     days: int = typer.Option(30, "--days", min=1, max=365),
     start_date: str = typer.Option(None, "--start", help="YYYY-MM-DD (overrides --days)"),
     end_date: str = typer.Option(None, "--end", help="YYYY-MM-DD"),
@@ -31,6 +32,7 @@ def matchup(
     h2 = resolve.hero_id(hero2)
     params = {
         "format": format_type,
+        "sub_formats": sub_formats or None,
         "days": days,
         "start_date": start_date,
         "end_date": end_date,

fablazing_cli-0.4.1/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.1/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.3.0 → fablazing_cli-0.4.1}/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
@@ -46,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.3.0 → fablazing_cli-0.4.1}/src/fablazing_cli/reference.py

@@ -23,7 +23,12 @@ analytics and paper tournament results for competitive Flesh and Blood.
   different cards and are counted separately everywhere.
 - Names are accepted anywhere an id is. Ambiguous names error out and
   list the matching ids (exit code 2).
-- Formats: `cc` (default), `blitz`, `ll`, `sage`, `gage`.
+- Formats: `cc` (default), `blitz`, `ll`, `sage`, `gage` - but coverage
+  is per command. matchup, hero cards, card pov and card analytics
+  accept all five. meta snapshot/movers cover cc, blitz, ll, sage.
+  hero aggregate and meta matrix cover cc, blitz, ll only (their
+  pre-computed stores don't process the rest). gage is a tiny corpus
+  (a few hundred games total) - expect thin samples everywhere.
 
 ## Data notes
 - win_rate fields are fractions between 0 and 1.
@@ -57,18 +62,32 @@ analytics and paper tournament results for competitive Flesh and Blood.
 - `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)
+  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. Narrow with repeatable `--sub-format`
+on matchup (e.g. `--sub-format 0 --sub-format 1` for cc without Open);
+the API parameter is `sub_formats`.
+
 ## 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

fablazing_cli-0.3.0/src/fablazing_cli/__init__.py

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