fplkit 2.5.0__tar.gz → 2.6.1__tar.gz

{fplkit-2.5.0 → fplkit-2.6.1}/CHANGELOG.md

@@ -1,6 +1,56 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [2.6.0] - 2026-09-07
+
+### Bug Fixes
+
+- drop ratings update's dead -v hint for a kept prior (#311)
+- carry the --format json envelope through a relative FPL_CLI_* rejection (#312)
+- derive `fpl doctor`'s season from GW1's deadline like `fpl status` (#314)
+- warn in the saved review when the summary came back empty (#313)
+
+### Features
+
+- join Understat rows for players the two sources spell differently (#315)
+
+## [2.5.0] - 2026-09-07
+
+### Bug Fixes
+
+- stop the fpl-mate output style calling ep_next prior-informed (#261)
+- restore xG enrichment for players with an apostrophe in their name (#268)
+- keep coverage readable when one ledger file is damaged (#271)
+- stop the review scrubber deleting sentences naming full names (#270)
+- recap the last completed gameweek once the next one has kicked off (#274)
+- stop fpl xg table output crashing when custom analysis is off (#275)
+- cap httpx, pydantic and click below their next majors (#278)
+- stop a truncated LLM summary being saved without a warning (#276)
+- stop a draft replay erasing the league positions it recorded (#280)
+- validate FPL_CLI_DATA_DIR and FPL_CLI_CACHE_DIR eagerly like FPL_CLI_CONFIG_DIR (#281)
+- raise the click floor to 8.2 so the test suite can capture stderr (#283)
+- collapse a league-wide captain tie into one recap line (#282)
+- fill the blank Source column in a review's Standout Performers (#284)
+- exit 1 with the real reason when review or recap cannot run (#285)
+- point doctor's draft ID fix hints at `fpl init` (#288)
+- keep the current table's points out of a replayed gameweek's recap (#293)
+- report a failure the same way whatever the output format (#292)
+- keep league positions when one manager's replay data is partial (#295)
+- stop a replay renaming the player a stored red-card fine names (#290)
+- ground the review's "Next Week" advice in next gameweek's fixtures (#291)
+- rebuild the ratings prior when a football-data key appears (#289)
+- record the club a player played for in a replayed gameweek (#296)
+- keep `review --summarise` running when an LLM key is missing (#297)
+- derive season labels from GW1's deadline instead of the clock (#299)
+- correct award move direction and free-agent mislabelling (#302)
+
+### Features
+
+- flag stale quality-score calibration in `fpl doctor` (#298)
+- hand the league-recap editorial every manager's transfers (#300)
+- give the draft recap editorial every waiver and free-agent move (#303)
+- give the season-opener recap each manager's prior FPL seasons (#304)
+
 ## [2.4.1] - 2026-09-05
 
 ### Bug Fixes

{fplkit-2.5.0 → fplkit-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fplkit
-Version: 2.5.0
+Version: 2.6.1
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli

{fplkit-2.5.0 → fplkit-2.6.1}/docs/architecture.md

@@ -434,7 +434,7 @@ classDiagram
 
 All providers share the `LLMResponse` contract. `OpenAICompatProvider` supports OpenAI, Groq, Together, Ollama via configurable `base_url`. Provider selection configured in settings.
 
-`stop_reason` carries the provider's own verdict on why generation ended, verbatim in whichever vocabulary it used — Anthropic's `stop_reason`, an OpenAI-compatible API's `finish_reason`. `stopped_early` reads it against `NORMAL_STOP_REASONS`, a single set covering both dialects (the vocabularies do not collide), and every provider announces an abnormal one at WARNING via `log_abnormal_stop` — the same reason `_http` announces its retries there, so a truncation is visible on any command that talks to an LLM. `None` means the provider said nothing, which is never treated as evidence of truncation. Without this a cut-off response and a complete one were indistinguishable downstream, which is how a saved gameweek review shipped missing a whole format's verdict at exit 0 (#266).
+`stop_reason` carries the provider's own verdict on why generation ended, verbatim in whichever vocabulary it used — Anthropic's `stop_reason`, an OpenAI-compatible API's `finish_reason`. `stopped_early` reads it against `NORMAL_STOP_REASONS`, a single set covering both dialects (the vocabularies do not collide), and every provider announces an abnormal one at WARNING via `log_abnormal_stop` — the same reason `_http` announces its retries there, so a truncation is visible on any command that talks to an LLM. `None` means the provider said nothing, which is never treated as evidence of truncation. Without this a cut-off response and a complete one were indistinguishable downstream, which is how a saved gameweek review shipped missing a whole format's verdict at exit 0 (#266). `log_textless_response` is its companion for the other half of that failure: a reasoning model that reaches the ceiling mid-thought returns content with no text block in it at all, so the concatenated prose is `""` — honest, but indistinguishable from a model with nothing to say until the non-text blocks that did arrive are named (#306). Unlike `log_abnormal_stop` this one is Anthropic-only, because only the Messages API returns typed content blocks — an OpenAI-compatible reply carries a plain `message.content` string, so there is nothing to name when it comes back empty. What catches an empty answer whatever produced it is `check_synthesis_completeness`'s `empty` flag, one layer along, which reads the string the report would carry rather than the envelope it arrived in.
 
 Both HTTP providers post through `_http.post_json_with_retry`, the one place their error handling lives: it retries an HTTP 429 with `RetryPolicy` (exponential backoff with jitter, `Retry-After` honoured, the whole wait bounded by one budget, each retry announced at WARNING) and raises `RateLimitError` — a `ProviderError` subclass carrying the server's `retry_after` — once the attempts are spent, and turns every other error status, a timeout, or a non-JSON body into a sanitised `ProviderError`. That is the same 429-is-transient distinction `DatasetFetcher` draws for the historical datasets. The module also holds `QueryPacer`, which keeps request starts a configured interval apart for a caller that fires several queries at once; `fpl returnees --enrich` pairs it with an in-flight cap, reads the typed error to re-query only the rate-limited subset of its shortlist once, and reports a still-refused player as rate-limited rather than unanswered.
 
@@ -555,7 +555,7 @@ fpl_cli/
 │   ├── historical.py             # HistoricalDataProvider (composition: vaastav + Core-Insights) + historical_season_windows() (the disjoint source allocation) + merge_season_histories()
 │   ├── football_data.py          # FootballDataClient (standings, match results)
 │   └── providers/                # LLM provider abstraction
-│       ├── _models.py            # LLMResponse (incl. stop_reason/stopped_early), TokenUsage, NORMAL_STOP_REASONS, log_abnormal_stop, ProviderError, RateLimitError
+│       ├── _models.py            # LLMResponse (incl. stop_reason/stopped_early), TokenUsage, NORMAL_STOP_REASONS, log_abnormal_stop, log_textless_response, ProviderError, RateLimitError
 │       ├── _http.py              # Shared HTTP plumbing: 429 backoff (RetryPolicy, post_with_retry), the providers' one error path (post_json_with_retry), QueryPacer for batching callers
 │       ├── anthropic.py          # AnthropicProvider
 │       ├── openai_compat.py      # OpenAICompatProvider (OpenAI, Groq, Together, Ollama)
@@ -572,7 +572,7 @@ fpl_cli/
 │   │   ├── shrinkage.py          # Single-GW early-season shrinkage + the shared hold-out helpers
 │   │   └── data_prep.py          # ScoringContext / ScoringData + prepare_scoring_data()
 │   ├── player_prior.py           # Player prior (Bayesian early-season confidence)
-│   ├── team_ratings.py           # TeamRatingsService + Calculator (1-7 scale)
+│   ├── team_ratings.py           # TeamRatingsService + Calculator (1-7 scale). The service judges the file's `metadata.season` stamp against the season it is told is in progress, discarding a previous season's ratings outright (they rate relegated clubs, and serving them is worse than serving none) — which means the season it uses has to be the resolved one, not the clock: an overrunning season had its own live ratings thrown away from 1 July, dropping every fixture to a neutral 4.0 mid-season (#318). `ensure_fresh(client)` resolves it from GW1's deadline before anything else and re-reads if a property access already forced a load on the clock; `fpl doctor` passes the label it resolved; writes are stamped with the same season, so a file written during an overrun is not stamped into the future
 │   ├── team_ratings_prior.py     # Previous-season prior + Bayesian blending (cutoff GW12); every pool it reads (the PL pool from either source, the Championship division) takes full-season records only, and every club's basis is written to the cache as `inputs`. The cache is invalidated by the methodology version, the league's club list, and a one-directional provenance check (`_inputs_have_improved`) that rebuilds only when an input the cached run lacked is available now — so setting `FOOTBALL_DATA_API_KEY` reaches the promoted sides without the file being deleted (#112). A rebuild is then held to `_is_worse_than_cache` (source rank and count of clubs on an estimate) before it may replace the cached prior, and `_record_attempt` stamps the file either way so a down provider costs one retry, not one per command
 │   ├── matchup.py                # Fixture matchup scoring (0-10)
 │   ├── fixture_predictions.py    # BGW/DGW predictions from YAML + live detection, plus the point-in-time "did his club have a fixture, and how many" read a past gameweek needs
@@ -602,7 +602,7 @@ fpl_cli/
 ├── scraper/
 │   └── fpl_prices.py             # FPLPriceScraper (needs FPL_EMAIL/FPL_PASSWORD; behind TLS-inspecting proxies: FPL_BROWSER_IGNORE_CERTS=1 for cert MITM, or FPL_BROWSER_EXECUTABLE/CHANNEL/ARGS to swap the browser when the ClientHello itself is rejected)
 ├── paths.py                      # SHIPPED_CONFIG_DIR, TEMPLATE_DIR, user_config_dir(), user_data_dir(), user_cache_dir() — each user_* dir overridable via FPL_CLI_CONFIG_DIR / FPL_CLI_DATA_DIR / FPL_CLI_CACHE_DIR (absolute paths only; a relative one raises UserDirError rather than resolving against the cwd)
-├── season.py                     # season_label() (+ vaastav_season() alias), previous_season_year()/previous_season_label() (the newest *completed* season, one expression for the player prior, the calibration script's default and doctor's frozen-anchor check), understat_season(), core_insights_season(), TOTAL_GAMEWEEKS, CHIP_SPLIT_GW, PROMOTED_CLUBS_PER_SEASON. season_year_from_gameweeks() derives the year from GW1's deadline rather than the July-cutover clock (#91); resolve_season_year() composes it with the clock — GW1's year while its season is still live, the clock's once that season has fully concluded and the calendar has moved past it (the close-season gap before the next one's fixtures publish, when bootstrap-static keeps serving the finished season's events untouched). FPLClient.get_season_year() wraps resolve_season_year(), and review/league-recap/preview/status pass the result through explicitly so a season overrunning the cutover (2019-20, delayed into July 2020) still resolves to the year it started; league-fines, which reads the ledger with no network, instead defaults to services/league_history.py's most_recent_captured_season() so its default agrees with whatever league-recap actually wrote
+├── season.py                     # season_label() (+ vaastav_season() alias), previous_season_year()/previous_season_label() (the newest *completed* season, one expression for the player prior, the calibration script's default and doctor's frozen-anchor check), understat_season(), core_insights_season(), TOTAL_GAMEWEEKS, CHIP_SPLIT_GW, PROMOTED_CLUBS_PER_SEASON. season_year_from_gameweeks() derives the year from GW1's deadline rather than the July-cutover clock (#91); resolve_season_year() composes it with the clock — GW1's year while its season is still live, the clock's once that season has fully concluded and the calendar has moved past it (the close-season gap before the next one's fixtures publish, when bootstrap-static keeps serving the finished season's events untouched). FPLClient.get_season_year() wraps resolve_season_year(), and review/league-recap/preview/status/doctor pass the result through explicitly so a season overrunning the cutover (2019-20, delayed into July 2020) still resolves to the year it started -- doctor falls back to the clock only when the API is unreachable, and `fpl doctor --providers` reads the season off the bootstrap its FPL probe already fetched rather than downloading it twice. is_previous_season_year() is the ordered counterpart the staleness checks compare a timestamp's cutover year with: during an overrun a July timestamp lands a year *ahead* of the season it was written in, so exact comparison would call live data a previous season's (#308); league-fines, which reads the ledger with no network, instead defaults to services/league_history.py's most_recent_captured_season() so its default agrees with whatever league-recap actually wrote
 ├── constants.py                  # MIN_MINUTES_FOR_PER90
 └── utils/
     ├── gameweek.py                # is_opening_gameweek(gw) — shared GW1 check (transfers, waivers and league tables don't exist yet)

{fplkit-2.5.0 → fplkit-2.6.1}/docs/command-reference.md

@@ -96,6 +96,15 @@ about: the block is read on nearly every command, so the envelope naming it can
 from `fpl status` or `fpl league-recap` as readily as from `fpl league-fines`, and the
 message names the rule and the valid set.
 
+A relative `FPL_CLI_CONFIG_DIR` / `FPL_CLI_DATA_DIR` / `FPL_CLI_CACHE_DIR` override is
+rejected before any command runs, so this one case has no parsed `--format` to read when it
+fails — the CLI scans the raw command line for `--format json` instead. The envelope's
+`command` names your subcommand where that is unambiguous (`fpl status`, or a bare group like
+`fpl chips`), and falls back to `"fpl"` for a subgroup's own subcommand (`fpl chips timing`,
+`fpl squad grid`, `fpl intel show`) or a line that was nothing but options — those commands
+don't name their own envelope after either word you typed, and guessing wrong would be worse
+than saying so.
+
 **Table mode splits the same way.** Without `--format json` the output you asked for goes
 to stdout and everything else goes to stderr — warnings, progress notices, and the reason
 a command exited nonzero. `fpl squad grid 2>/dev/null` prints a grid or prints nothing;
@@ -403,7 +412,7 @@ A club that has played only one venue is rated on it. Once GW1 finishes, every c
 
 Early-season results are shrunk toward that previous-season prior, by the automatic refresh and by `fpl ratings update` alike: a one-gameweek sample carries 1/7 of the weight, six gameweeks half, and the prior drops out entirely once GW12 has completed. Shrinkage is gated on how far the season has run, so a narrow window late on is not blended -- `--since-gw 30` at GW34 saves recent form alone. Inside the early-season window the weight follows the size of that window rather than the gameweek number, so `--since-gw 8` at GW10 is weighted as three gameweeks of evidence. Blended files are stamped `calculated_blended` / `understat_xg_blended` / `auto_calculated_blended` so `fpl ratings` shows that shrinkage was applied. While the sample is shorter than six gameweeks the prior still carries most of the weight, and every fixture-difficulty view says so - `Ratings are mostly last season's prior - 1 gameweek of results carries 14% of the weight`. That replaces the pre-season estimate warning, which stops applying the moment a gameweek completes.
 
-Ratings are tied to the season that produced them. A file carried across a season boundary is ignored rather than served, because it rates the three relegated clubs and knows nothing about the three promoted ones. Ratings that cover the wrong set of clubs are called out by name — `team_ratings.yaml is missing COV, HUL, IPS and still rates BUR, WHU, WOL` — which catches a rollover that a "days old" check cannot: a file rebuilt in early August is new by date and still describes last season's league.
+Ratings are tied to the season that produced them. A file carried across a season boundary is ignored rather than served, because it rates the three relegated clubs and knows nothing about the three promoted ones. Which season is "in progress" comes from GW1's deadline, not the July clock, so a season overrunning 1 July keeps its own ratings instead of having them discarded with a third of the run-in still to play. Ratings that cover the wrong set of clubs are called out by name — `team_ratings.yaml is missing COV, HUL, IPS and still rates BUR, WHU, WOL` — which catches a rollover that a "days old" check cannot: a file rebuilt in early August is new by date and still describes last season's league.
 
 See [Team Ratings](custom-analysis.md#team-ratings) for calculation methodology, axes, early-season blending, pre-season estimates, and manual overrides.
 
@@ -556,7 +565,7 @@ These metrics appear in `fpl player`, `fpl xg`, and gameweek reports. If Underst
 
 **When a whole club fails to join.** FPL and Understat spell some clubs differently, so a `TEAM_NAME_MAP` gap costs one club's entire squad its npxG, xGChain and every score built on them, while the other 19 look fine. The commands that enrich from the live league payload — `fpl stats --value`, `fpl player`, `fpl allocate`, `fpl xg`, `fpl targets`, `fpl differentials` — report it once per club: on stderr in table mode, and as an `understat_team_unmatched` entry in JSON `metadata.warnings`, one per club, naming both the FPL club and the Understat name it was mapped to. `fpl doctor --providers` checks the same thing ahead of time. A club missing from a *past* season's payload is not this: `fpl returnees` scores a player's current club against the season they played, so the three clubs promoted since are absent from it every year by definition, and that stays a debug line rather than a warning about a map that is fine.
 
-**When one player fails to join.** A player whose club Understat *does* carry can still fail to match on name, and that is not always a defect: Understat has not ingested the gameweek in progress, spells a transliterated name differently, or simply has no row for the player. Those read as `null` quality and value scores rather than as zeros, so the player is ranked as "no data" rather than as bad. A few percent of a club's players missing this way is normal and stays a debug line naming each one with a running rate (`No Understat row matched ... — 3 of 351 FPL players with minutes unmatched so far this run`); the rate is what to watch, since a jump in it means the two sources have stopped agreeing about names rather than that one more cameo went un-ingested. `fpl doctor --providers` reports the same rate as an `Understat name join` row, which is where to look for it without turning on debug logging. Understat serves apostrophes HTML-escaped (`O'Shea`), which used to fail every apostrophe name silently; the payload is now decoded when it is fetched.
+**When one player fails to join.** A player whose club Understat *does* carry can still fail to match on name, and that is not always a defect: Understat has not ingested the gameweek in progress, names the player outright differently (FPL's `A.Becker` is Understat's `Alisson`), or simply has no row for them. Those read as `null` quality and value scores rather than as zeros, so the player is ranked as "no data" rather than as bad. A name the two sources merely *spell* differently does join, through a last-resort pass that stays inside the player's club and needs their minutes to agree and no second candidate: a transliteration variant (`Yarmoliuk` and `Yehor Yarmolyuk`), a double-barrelled or middle name one source drops (`Gannon-Doak` and `Ben Doak`, `Walle Egeli` and `Sindre Egeli`), or a mononym inside a longer name (`Jair Cunha` and `Jair`). A shared word alone is never enough — `João Pedro` and `Pedro Neto` share one — so a player whose row is genuinely missing stays `null` rather than wearing a club-mate's numbers. A few percent of a club's players missing this way is normal and stays a debug line naming each one with a running rate (`No Understat row matched ... — 3 of 351 FPL players with minutes unmatched so far this run`); the rate is what to watch, since a jump in it means the two sources have stopped agreeing about names rather than that one more cameo went un-ingested. `fpl doctor --providers` reports the same rate as an `Understat name join` row, which is where to look for it without turning on debug logging. Understat serves apostrophes HTML-escaped (`O'Shea`), which used to fail every apostrophe name silently; the payload is now decoded when it is fetched.
 
 #### Quality and Value Scores
 
@@ -769,15 +778,24 @@ on a run with no fixture data, is reported alongside the completeness findings b
 stderr, and as a warning callout in the saved report.
 
 **Incomplete summaries:** the personal analysis is checked against the sections its own prompt
-asked for before anything is written. A response that is missing a `## ` heading, ends without
-terminal punctuation, or that the provider reports it stopped early on is retried **once** — and
-if the second attempt is no better, the first one stands and the run says so on stderr, naming
-what is missing. Under `--debug` the detail lands in `data/debug/synthesis_corrections.txt`
-alongside `research_corrections.txt`. A saved report generated from such a response carries the
-same list as a warning callout above the summary, so a verdict the model dropped never reads as
-one deliberately omitted. A verdict for a format the run has no squad data for is not counted as
+asked for before anything is written. A response that comes back empty, is missing a `## `
+heading, ends without terminal punctuation, or that the provider reports it stopped early on is
+retried **once** — and if the second attempt is no better, the less damaged of the two stands
+and the run says so on stderr, naming what is missing. Under `--debug` the detail lands in
+`data/debug/synthesis_corrections.txt` alongside `research_corrections.txt`. A saved report
+generated from such a response carries the same list as a warning callout above the summary, so
+a verdict the model dropped never reads as one deliberately omitted. The callout does not depend
+on there being a summary to qualify: a response that returned no text at all — the shape a hard
+`max_tokens` truncation takes when the model was still thinking at the ceiling — is the one that
+most needs explaining, and is reported as a single "the response is empty" finding rather than
+as every section it happens to be short of. A verdict for a format the run has no squad data for is not counted as
 missing — the prompt tells the model to analyse only the format it was given.
 
+A call that never lands at all — a timeout, a 500, a 429 that outlasted its retries, a revoked
+key — is reported through the same callout, naming the failure. The run still exits **0** with
+the rest of the review intact, but the saved report says the analysis was attempted and lost
+rather than leaving a reader to wonder whether the template ever had one.
+
 **Blanks and doubles:** a zero from a player whose club had no fixture is marked `[BGW]` rather
 than read as a choice that failed, and such a player is kept off the Blankers list entirely; a
 player whose club played twice is marked `[DGW]`. Which clubs those were is read off the
@@ -1278,7 +1296,7 @@ Rolling a setup into a new season silently invalidates IDs and per-team files: a
 
 **Data files:**
 
-- `team_ratings.yaml` — season stamp and team set vs the live league (problems here are stale, not broken: the ratings service already ignores or rebuilds bad files)
+- `team_ratings.yaml` — season stamp and team set vs the live league, judged against the same resolved season the report names (problems here are stale, not broken: the ratings service already ignores or rebuilds bad files)
 - `team_managers.yaml` — merged shipped + user copy covers exactly the current twenty clubs
 - `previews/` — optional season preview intel: a file for a club not in the current league is flagged (it loads and inflates the coverage gate), and files the loader skipped (previous season, malformed) are surfaced with `fpl intel` as the follow-up
 - `team_finances.json` — `scraped_at` falls within the current season
@@ -1291,6 +1309,8 @@ Rolling a setup into a new season silently invalidates IDs and per-team files: a
 
 **Environment** — which directory each of config/data/cache resolved to and whether an `FPL_CLI_*` override is in effect, plus whether `settings.yaml` exists.
 
+**Which season it is** — the season doctor reports in `metadata.season`, and judges "a previous season's" against, comes from GW1's `deadline_time` where the API answers and the July cutover only where it does not — the same rule `fpl status` uses, so the two commands cannot name different seasons for the same moment. A season that overruns 1 July (2019-20, COVID-delayed) therefore keeps its own label in both, and a `team_finances.json` scraped during that overrun reads as current rather than as a previous season's.
+
 Each finding is classified as **broken** (wrong answers now — fix it today), **stale** (self-corrects or needs one routine refresh), **skipped** (not configured/present), or **unchecked** (API unreachable). Exits non-zero when anything is broken, so it can gate scripts.
 
 **`--providers`** checks the external data sources instead of the local setup. None of them version anything, and the tool degrades gracefully everywhere, so upstream drift otherwise surfaces as plausible but wrong output — a renamed stat field zeroes every player's xG without an error. Each probe asserts shape and volume, not just reachability, and where a column check is not the contract it runs the parser itself:
@@ -1398,7 +1418,7 @@ llm:
     model: claude-sonnet-5
     timeout: 60
     query_defaults:
-      max_tokens: 4096
+      max_tokens: 8000
 ```
 
 ### LLM Providers

{fplkit-2.5.0 → fplkit-2.6.1}/fpl_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.5.0'
-__version_tuple__ = version_tuple = (2, 5, 0)
+__version__ = version = '2.6.1'
+__version_tuple__ = version_tuple = (2, 6, 1)
 
 __commit_id__ = commit_id = None

{fplkit-2.5.0 → fplkit-2.6.1}/fpl_cli/api/providers/_models.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 
 logger = logging.getLogger(__name__)
@@ -97,3 +98,27 @@ def log_abnormal_stop(response: LLMResponse, label: str) -> None:
         "the response may be cut off",
         label, response.stop_reason, response.usage.output_tokens,
     )
+
+
+def log_textless_response(
+    response: LLMResponse, label: str, non_text_blocks: Sequence[str],
+) -> None:
+    """Announce a response whose content was blocks, none of them text.
+
+    A model that reasons before it answers emits its thinking first, so a
+    ceiling reached mid-thought returns content with no prose block in it at
+    all. The concatenated text is then `""` -- honest, but indistinguishable
+    downstream from a model that had nothing to say. Naming the blocks that
+    did arrive is what separates the two for anyone reading stderr (#306).
+
+    `non_text_blocks` is the types of the blocks that were *not* text, so an
+    answer of nothing but an empty text block stays silent: that is a model
+    with nothing to say, which is the case this has nothing to add to.
+    `log_abnormal_stop` has already spoken if it was cut off.
+    """
+    if response.content or not non_text_blocks:
+        return
+    logger.warning(
+        "%s returned no text content -- the response carried only %s block(s)",
+        label, ", ".join(sorted(set(non_text_blocks))),
+    )

{fplkit-2.5.0 → fplkit-2.6.1}/fpl_cli/api/providers/anthropic.py

@@ -8,7 +8,13 @@ from typing import Any, ClassVar, Self
 import httpx
 
 from fpl_cli.api.providers._http import RetryPolicy, post_json_with_retry
-from fpl_cli.api.providers._models import LLMResponse, ProviderError, TokenUsage, log_abnormal_stop
+from fpl_cli.api.providers._models import (
+    LLMResponse,
+    ProviderError,
+    TokenUsage,
+    log_abnormal_stop,
+    log_textless_response,
+)
 
 _BASE_URL = "https://api.anthropic.com/v1"
 _PROVIDER_LABEL = "Anthropic"
@@ -81,10 +87,21 @@ class AnthropicProvider:
             label=_PROVIDER_LABEL, policy=self.RETRY_POLICY,
         )
 
+        # Only text blocks carry prose, but the types that were *not* text are
+        # worth keeping: a ceiling reached while the model was still thinking
+        # returns a lone `thinking` block, and the empty string that falls out
+        # of this loop is otherwise indistinguishable from a model with
+        # nothing to say (#306). Text blocks are deliberately not collected --
+        # a response of nothing but an empty text block *is* a model with
+        # nothing to say, and naming "text" as the reason there was no text
+        # would contradict itself.
         content = ""
+        non_text_blocks: list[str] = []
         for block in data.get("content", []):
             if block.get("type") == "text":
                 content += block.get("text", "")
+            else:
+                non_text_blocks.append(str(block.get("type")))
 
         # Normalise usage: Anthropic returns input_tokens/output_tokens directly
         raw_usage = data.get("usage", {})
@@ -105,6 +122,7 @@ class AnthropicProvider:
             stop_reason=data.get("stop_reason") or None,
         )
         log_abnormal_stop(response, _PROVIDER_LABEL)
+        log_textless_response(response, _PROVIDER_LABEL, non_text_blocks)
         return response
 
     def post_process(self, content: str) -> str: