sweatstack 0.93.0__tar.gz → 0.95.0__tar.gz

{sweatstack-0.93.0 → sweatstack-0.95.0}/AGENTS.md

@@ -258,9 +258,13 @@ fields unchanged (users) is an `update` and sends only the fields given.
 
 Until 1.0, breaking changes are allowed when they ship with an upgrade path. Every one needs:
 
-1. A `### Upgrading` section in the CHANGELOG entry, with an old-to-new table.
+1. A `### Upgrading` section in the CHANGELOG entry, with an old-to-new table. Mark a row
+   whose change raises nothing as **Silent:**. Wrap the section in
+   `<!-- --8<-- [start:upgrading-X-Y] -->` / `[end:...]` markers (the docs include it), and add
+   a `## X.Y` section with that include to the docs' Upgrading page. `tests/test_changelog.py`
+   checks that every entry saying "breaking" has the section and its markers.
 2. A copy-paste migration prompt for coding agents in the same section, for any change bigger
-   than a rename or two.
+   than a rename or two. The generic prompt in `UPGRADING.md` covers the rest.
 3. For a removed method or attribute, an entry in `_renames.REMOVED_IN`, so calling it raises an
    `AttributeError` that names the replacement. Entries are permanent.
    `tests/test_renames.py` checks each one against the client, the module and the CHANGELOG.

{sweatstack-0.93.0 → sweatstack-0.95.0}/CHANGELOG.md

@@ -5,6 +5,131 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+Until 1.0 a minor release may contain breaking changes. Every one has an **Upgrading** section
+with a table from old to new. The procedure for moving across several releases, and a prompt
+for a coding agent, are in `UPGRADING.md` next to this file and at
+https://docs.sweatstack.no/learn/python/upgrading/.
+
+
+## [0.95.0] - 2026-10-13
+
+Scopes are categories now. Request what your app uses. Breaking: the default scopes change
+without an error, and the metabolic map and capability names move; see **Upgrading** below, or
+hand the migration prompt to your coding agent.
+
+### Changed
+
+- The default scope of `Client.login()`, `client.oauth.authorization_url()`, the FastAPI plugin and
+  the Streamlit helper is one constant, `sweatstack.constants.DEFAULT_SCOPE`:
+  `openid profile email activities:read offline_access`. Add `wellness:read`,
+  `reproductive_health:read`, `workouts:write` or `sharing:read` when your app uses them.
+- `client.teams.authorize()` grants `activities:read` by default; only the delegable scopes are
+  ever granted.
+- `client.oauth.userinfo()` needs the `openid` scope; the name claims need `profile`, the email
+  needs `email`.
+- `client.profile.status()` needs no scope.
+- `Application.default_scopes` and `Application.purposes` replace `capabilities` on
+  `client.applications` (the old field is still accepted and translated).
+- The metabolic map responses are the markers themselves: no `inputs`, no `markers` wrapper; the
+  VO2 map has `vo2max_relative`.
+- The `dailies` capability and its issue codes are `wellness`, `wellness_not_granted` and
+  `wellness_no_source`.
+
+### Added
+
+- `sweatstack.__version__` is the installed version.
+
+### Fixed
+
+- Token calls from the FastAPI and Streamlit integrations (login, refresh and delegated tokens)
+  now send the `python-sweatstack/<version>` User-Agent, like every other request the SDK
+  makes. Before, they identified themselves as plain httpx.
+
+<!-- --8<-- [start:upgrading-0-95] -->
+### Upgrading
+
+| 0.94 | 0.95 |
+|---|---|
+| `scope="data:read data:write profile offline_access"`, or no `scope=` at all | **Silent:** the default is `DEFAULT_SCOPE` (`openid profile email activities:read offline_access`). Add the categories you use: `wellness`, `reproductive_health`, `workouts` and `sharing`, each as `:read` or `:write` |
+| `Scope.data_read` in `teams.authorize(scopes=...)`, or no `scopes=` | **Silent:** `"activities:read"` is the default, and only the delegable categories are granted; anything else is dropped |
+| `userinfo()` with `profile` | `userinfo()` with `openid profile email`; without `openid` it raises `SweatStackAuthError` |
+| `response.markers.fatmax` on a metabolic map | `response.fatmax` |
+| `response.inputs.body_mass` on a metabolic map | not published; `response.vo2max_relative` on the VO2 map |
+| `status.capabilities["dailies"]` | `status.capabilities["wellness"]` |
+
+An app registered before the platform release keeps working with `data:read` and `data:write`
+for six months; see the platform changelog.
+
+**Migration prompt.** Paste this into your coding agent:
+
+```text
+Upgrade this codebase to sweatstack 0.95, which replaces the data:read and data:write scope
+bundles with per-category scopes. The upgrade table is the "Upgrading" section of the 0.95.0
+entry in https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md
+(also at https://docs.sweatstack.no/learn/python/upgrading/). Read it first.
+
+Find every place the app requests or grants scopes (Client.login(), oauth.authorization_url(),
+sweatstack.fastapi.configure(scopes=...), StreamlitAuth(scopes=...) and SWEATSTACK_SCOPES,
+teams.authorize(scopes=...)) and:
+
+1. Replace data:read and data:write with the categories the app uses: activities, wellness,
+   reproductive_health, workouts and sharing, each as :read or :write. Start from
+   sweatstack.constants.DEFAULT_SCOPE (openid profile email activities:read offline_access)
+   and add to it. Do not keep the old bundles.
+2. Where the app calls userinfo(), request openid, plus profile and email for the claims it
+   shows.
+3. On the metabolic maps, read response.<marker> instead of response.markers.<marker>, drop
+   any use of response.inputs, and read status.capabilities["wellness"] where the app read
+   ["dailies"].
+
+Then run the code and the tests. A category the app forgot surfaces as SweatStackAuthError
+on the first call that needs it; add that category, not a bundle.
+```
+<!-- --8<-- [end:upgrading-0-95] -->
+
+
+## [0.94.0] - 2026-10-12
+
+A client's tokens come from one source. Upgrade every app that other people sign in to.
+
+### Security
+
+- A `Client` in a process shared by several users (Streamlit, FastAPI, any server) could pick
+  up a refresh token, or a whole token pair, that another user's client had saved on that
+  machine, and act as that user. Credentials now come from a single source: the arguments you
+  pass, else the environment, else the tokens saved by `authenticate()`. A client never
+  combines halves from different sources, and writes the saved tokens only when they came from
+  there. The Streamlit and FastAPI integrations never read or write saved tokens.
+
+### Fixed
+
+- Streamlit apps behind a proxy no longer fail after the access token expires. With a proxy
+  that forwards `X-SweatStack-Refresh-Token` (the SweatStack Streamlit template does), the
+  session renews its own token and keeps the renewed pair across reruns. Streamlit apps in
+  OAuth mode refresh once per token lifetime instead of once per rerun.
+- A refresh response that carries a new refresh token replaces the old one.
+- `StreamlitAuth.select_user()` with a user that gets no refresh token (admin access) no longer
+  keeps the previous user's refresh token.
+
+### Changed
+
+- `Client(..., ambient_credentials=False)` builds a client that never reads the environment or
+  the saved tokens and never writes them. Use it for per-user clients in your own server.
+- `oauth.exchange_code()` no longer saves the tokens on the machine by default; pass
+  `persist=True` for that. `authenticate()` still saves them.
+- `StreamlitAuth.behind_proxy()` checks token expiry again. Without a forwarded refresh token,
+  calls after expiry raise `SweatStackTokenRefreshError` with a reload hint, where the API
+  returned a 401.
+
+<!-- --8<-- [start:upgrading-0-94] -->
+### Upgrading
+
+| 0.93 | 0.94 |
+|---|---|
+| `Client(api_key=...)` without a refresh token renewed with `SWEATSTACK_REFRESH_TOKEN` or the saved refresh token | **Silent:** it never borrows one, and raises `SweatStackTokenRefreshError` on expiry. Pass `refresh_token=` too, or pass neither to use the environment or the saved tokens |
+| `oauth.exchange_code(...)` saved the tokens on this machine | **Silent:** pass `persist=True` to keep that |
+| `StreamlitAuth.behind_proxy()` sent the handshake token as it was after expiry (a 401 from the API) | Forward `X-SweatStack-Refresh-Token` from the proxy and the session renews itself. Without it, calls after expiry raise `SweatStackTokenRefreshError` with a reload hint |
+<!-- --8<-- [end:upgrading-0-94] -->
 
 ## [0.93.0] - 2026-10-09
 
@@ -24,6 +149,17 @@ Issues are only about the data your app uses. Requires the SweatStack API releas
   app declares it uses (`list[Capability]`; omit it for the default, `activities` and
   `activity_history`). SweatStack reports issues only for these.
 
+<!-- --8<-- [start:upgrading-0-93] -->
+### Upgrading
+
+| 0.92 | 0.93 |
+|---|---|
+| `issue.status` is a `CapabilityStatus` | `IssueStatus`: `action_required` or `syncing`. The `.value` strings are unchanged |
+| Branching on `issue.code` being `activity_history_unavailable`, `dailies_unavailable` or `workouts_unavailable` | **Silent:** these codes are never sent. Read `profile.status().capabilities` instead, where `unavailable` means no connected source provides it |
+| Only the known issue codes | Also `activities_blocked_upstream`, `dailies_no_source` and `workouts_no_source`: each `action_required` with a `destination`; handle them like any other issue |
+| An app that uses dailies or workouts | Declare them in the app's `capabilities` (`ApplicationCreate.capabilities`); issues are reported only for declared capabilities |
+<!-- --8<-- [end:upgrading-0-93] -->
+
 ## [0.92.0] - 2026-10-08
 
 Portal links are created with the user's token, when the user acts. Requires the SweatStack API
@@ -43,12 +179,15 @@ release that replaces `action_url` with `destination` (see the platform changelo
   close the page. `return_url` must equal or sit under one of your app's registered redirect
   URIs.
 
+<!-- --8<-- [start:upgrading-0-92] -->
 ### Upgrading
 
-| Before | After |
+| 0.91 | 0.92 |
 |---|---|
 | `user.issue.action_url` | `client.portal.sessions.create(user.issue.destination, return_url=...).url` |
 | `Client(client_id=..., client_secret=...).portal.sessions.create(...)` | the same call on the client holding the user's token |
+| `portal.sessions.create(destination)` without `return_url` linking back to your app | **Silent:** the Portal tells the user to close the page; pass `return_url=` (under a registered redirect URI) to link back |
+<!-- --8<-- [end:upgrading-0-92] -->
 
 ## [0.91.0] - 2026-10-08
 
@@ -143,7 +282,8 @@ removed name raises an `AttributeError` that names its replacement.
 
 Removed names raise an `AttributeError` naming the replacement, so running your code points at
 each change. The module-level functions moved the same way: `sweatstack.get_activities()` is
-`sweatstack.activities.list()`.
+`sweatstack.activities.list()`. Only `from sweatstack import get_activities` fails with Python's
+plain `ImportError`; look the name up in the table.
 
 | 0.90 | 0.91 |
 |---|---|
@@ -294,6 +434,17 @@ and TypeError (a renamed or keyword-only argument). Do not add compatibility shi
 - **BREAKING:** `by` on `get_longitudinal_mean_max`, and its `DeprecationWarning`. Every curve is
   duration-oriented.
 
+<!-- --8<-- [start:upgrading-0-90] -->
+### Upgrading
+
+| 0.89 | 0.90 |
+|---|---|
+| A mean-max frame with one row per intensity: the metric value, and the `duration` it was held | **Silent:** one row per duration, 19 by default: `duration`, the metric (`power` or `speed`) and `start`; the longitudinal curve adds `activity_id`, `sport` and `after`. The column names still exist, so code keeps running with the axes swapped: `df[df.power >= 300]` becomes `df[df.duration == 300]` |
+| The full curve | `durations="all"`, or a list of seconds |
+| `get_activity_mean_max(id, "power", True)` or `segmentation=True` | Drop the argument |
+| `get_longitudinal_mean_max(..., by="duration")` or `by="intensity"` | Drop `by=`; every curve is by duration |
+<!-- --8<-- [end:upgrading-0-90] -->
+
 ## [0.89.0] - 2026-09-28
 
 Frames on your terms. Every method that returns a collection takes `output=`:
@@ -359,6 +510,7 @@ Four breaking changes come with it; the upgrade is mechanical, see **Upgrading**
   previously re-indexed by the client.
 - pandas frames keep the float64 / nanosecond dtype policy. Polars and Arrow do not upcast.
 
+<!-- --8<-- [start:upgrading-0-89] -->
 ### Upgrading
 
 1. Change the install line: `uv add "sweatstack[pandas]"` (or `[polars]`, or `[arrow]` for
@@ -370,6 +522,10 @@ Four breaking changes come with it; the upgrade is mechanical, see **Upgrading**
 4. Search for `.index`, `.loc[<timestamp>]`, `.resample(`, `.plot()` on frames from the
    time-series, mean-max, AWD and dailies methods. Where the index mattered, add
    `.set_index("timestamp")` (or the metric name, or `"date"`) right after the call.
+5. **Silent:** `as_dataframe=True` on `get_activities` and `get_traces` kept nested fields as
+   dict columns (`df["summary"][0]["power"]`). `output="pandas"` flattens them to dotted
+   columns (`df["summary.power.mean"]`); Polars and Arrow give structs (`df.unnest("summary")`).
+<!-- --8<-- [end:upgrading-0-89] -->
 
 ## [0.88.0] - 2026-08-06
 
@@ -383,12 +539,30 @@ Four breaking changes come with it; the upgrade is mechanical, see **Upgrading**
 
 - Token refresh no longer sends a `tz` field. The server derives all timezone information from the offsets stored with each record, so the client has nothing to pass.
 
+<!-- --8<-- [start:upgrading-0-88] -->
+### Upgrading
+
+| 0.87 | 0.88 |
+|---|---|
+| `create_trace(timestamp=datetime(2026, 1, 1, 10, 0))`, and `start`/`end` on `create_test`, `update_test`, `update_trace` | Aware: `datetime(2026, 1, 1, 10, 0, tzinfo=ZoneInfo("Europe/Amsterdam"))` or `datetime.now(timezone.utc)`. Naive raises `ValueError` |
+| `activity.start`, `trace.timestamp` shown as the athlete's wall-clock time | **Silent:** these are UTC now. Show `start_local`, `end_local` and `timestamp_local`, which are always present |
+<!-- --8<-- [end:upgrading-0-88] -->
+
 ## [0.87.0] - 2026-06-30
 
 ### Changed
 
 - **Breaking:** the codec previously named NLEC is now AISC (Adaptive Intensity Segmentation Codec), and its parameters are renamed: `nlec_on` is now `segmentation_on` (on `get_activity_data`, `get_latest_activity_data`, `get_longitudinal_data`) and `nlec` is now `segmentation` (on `get_activity_mean_max`, `get_latest_activity_mean_max`). No backwards-compatible aliases.
 
+<!-- --8<-- [start:upgrading-0-87] -->
+### Upgrading
+
+| 0.86 | 0.87 |
+|---|---|
+| `nlec_on=` on `get_activity_data`, `get_latest_activity_data`, `get_longitudinal_data` | `segmentation_on=` |
+| `nlec=` on `get_activity_mean_max`, `get_latest_activity_mean_max` | `segmentation=` (removed in 0.90) |
+<!-- --8<-- [end:upgrading-0-87] -->
+
 
 ## [0.86.0] - 2026-06-18
 
@@ -396,6 +570,15 @@ Four breaking changes come with it; the upgrade is mechanical, see **Upgrading**
 
 - **Breaking:** renamed the adaptive-sampling parameters to NLEC (near-lossless effort codec). `adaptive_sampling_on` is now `nlec_on` (on `get_activity_data`, `get_latest_activity_data`, `get_longitudinal_data`) and `adaptive_sampling` is now `nlec` (on `get_activity_mean_max`, `get_latest_activity_mean_max`). No backwards-compatible aliases; requires the SweatStack server 0.107.0 or later.
 
+<!-- --8<-- [start:upgrading-0-86] -->
+### Upgrading
+
+| 0.85 | 0.86 |
+|---|---|
+| `adaptive_sampling_on=` on `get_activity_data`, `get_latest_activity_data`, `get_longitudinal_data` | `nlec_on=` (`segmentation_on=` from 0.87) |
+| `adaptive_sampling=` on `get_activity_mean_max`, `get_latest_activity_mean_max` | `nlec=` (`segmentation=` from 0.87; removed in 0.90) |
+<!-- --8<-- [end:upgrading-0-86] -->
+
 
 ## [0.85.0] - 2026-06-17
 
@@ -457,8 +640,21 @@ This is a **breaking change** for code that uses `Sport`.
 - `open-sport-taxonomy[pydantic]` is now a runtime dependency. Response models consume `sport` via OST's
   permissive `SportField`, so sports newer than the bundled taxonomy are preserved rather than rejected.
 
-### Migration
-Hand the following prompt to a coding agent, or apply it by hand:
+<!-- --8<-- [start:upgrading-0-81] -->
+### Upgrading
+
+| 0.80 | 0.81 |
+|---|---|
+| `Sport.cycling_road` and other enum members | `Sport("cycling.road")`; `Sport.parse(value)` for external input |
+| `sport.value` | `str(sport)` (with modifiers) or `sport.code` |
+| `sport.display_name()` | `sport.label` |
+| `sport.parent_sport()` | `sport.parent` |
+| `sport.is_sub_sport_of(x)` | `sport.is_subsport_of(x)` (one `Sport`; `any(...)` for a list) |
+| `sport.root_sport()`, `sport.is_root_sport()` | `Sport(sport.code.split(".")[0])`, `"." not in sport.code and not sport.modifiers` |
+| `for s in Sport` | `for s in Sport.all()` |
+| Hardcoded `cycling.trainer`, `running.treadmill`, `rowing.ergometer`, `cycling.tt`, `cycling.mountainbike`, `cross_country_skiing[.classic\|.skate]`, `unknown` | **Silent** in string comparisons: `cycling+stationary`, `running+stationary`, `rowing+stationary`, `cycling.time_trial`, `cycling.mountain`, `xc_skiing[.classic\|.skate]`, `generic` |
+
+**Migration prompt.** Paste this into your coding agent:
 
 ```text
 Migrate this codebase to sweatstack 0.81.0, which replaces its custom `Sport` enum with the
@@ -492,6 +688,7 @@ OpenSportTaxonomy type (`open_sport_taxonomy.Sport`). `from sweatstack import Sp
 After editing, run the test suite and fix any remaining references. Do not add a compatibility shim;
 migrate call sites to the OST API directly.
 ```
+<!-- --8<-- [end:upgrading-0-81] -->
 
 
 ## [0.80.0] - 2026-06-12
@@ -521,6 +718,17 @@ migrate call sites to the OST API directly.
 ### Changed
 - Minimum Python version is now declared as `>=3.10` (the code already required 3.10+ syntax; the previous `>=3.9` declaration was incorrect).
 - Exception types in docstrings now reference the typed hierarchy introduced in 0.76.0 (`SweatStackAPIError`, `SweatStackNotFoundError`, `SweatStackAuthError`, `SweatStackBadRequestError`) instead of the now-incorrect `HTTPStatusError`.
+- **Breaking:** with `__all__` in place, the helpers that leaked to the top level by accident are no longer there: `sweatstack.make_dataframe_streamlit_compatible`, `convert_to_standard_dtypes` and `decode_jwt_body` live in `sweatstack.utils`, `DEFAULT_URL` in `sweatstack.constants`.
+
+<!-- --8<-- [start:upgrading-0-78] -->
+### Upgrading
+
+| 0.77 | 0.78 |
+|---|---|
+| `from sweatstack import make_dataframe_streamlit_compatible` (also `convert_to_standard_dtypes`, `decode_jwt_body`) | `from sweatstack.utils import make_dataframe_streamlit_compatible` |
+| `sweatstack.DEFAULT_URL` | `sweatstack.constants.DEFAULT_URL` |
+| Python 3.9 | Python 3.10 or later |
+<!-- --8<-- [end:upgrading-0-78] -->
 
 
 ## [0.77.1] - 2026-05-19
@@ -566,6 +774,18 @@ migrate call sites to the OST API directly.
 ### Removed
 - `httpx` is no longer part of the public error surface. Consumers do not need to import `httpx` to handle errors.
 
+<!-- --8<-- [start:upgrading-0-76] -->
+### Upgrading
+
+| 0.75 | 0.76 |
+|---|---|
+| `except httpx.HTTPStatusError as e` | `except SweatStackAPIError as e`, or a subclass: `SweatStackNotFoundError` (404), `SweatStackAuthError` (401, 403), `SweatStackRateLimitError` (429), `SweatStackBadRequestError` (other 4xx), `SweatStackServerError` (5xx) |
+| `e.response.status_code`, `e.request.url` | `e.status_code`, `e.url`; also `e.method`, `e.request_id`, `e.body` |
+| `except ValueError` around a call, for a 422 | `except SweatStackBadRequestError` |
+| `except httpx.ConnectError`, `httpx.TimeoutException` | `except SweatStackConnectionError` |
+| `from sweatstack import TokenRefreshError` | `from sweatstack import SweatStackTokenRefreshError` |
+<!-- --8<-- [end:upgrading-0-76] -->
+
 
 ## [0.75.0] - 2026-04-23
 
@@ -600,7 +820,16 @@ migrate call sites to the OST API directly.
 - `AttributeError` on Python <3.11 when the API returns an error response (`add_note` is a Python 3.11+ feature).
 
 ### Removed
-- `SWEATSTACK_LOCAL_CACHE` and `SWEATSTACK_CACHE_DIR` environment variables. Use `sweatstack.enable_cache()` instead.
+- **Breaking:** `SWEATSTACK_LOCAL_CACHE` and `SWEATSTACK_CACHE_DIR` environment variables. Use `sweatstack.enable_cache()` instead.
+
+<!-- --8<-- [start:upgrading-0-72] -->
+### Upgrading
+
+| 0.71 | 0.72 |
+|---|---|
+| `SWEATSTACK_LOCAL_CACHE=true` in the environment | `sweatstack.enable_cache()` in code. **Silent:** the variable is ignored, so nothing is cached until you call it |
+| `SWEATSTACK_CACHE_DIR=/some/dir` | `sweatstack.enable_cache("/some/dir")` |
+<!-- --8<-- [end:upgrading-0-72] -->
 
 
 ## [0.71.0] - 2026-03-13

{sweatstack-0.93.0 → sweatstack-0.95.0}/DEVELOPMENT.md

@@ -156,7 +156,9 @@ minimal feature delta. Commit, then handle the remainder separately.
 ## Releasing
 
 1. Bump `version` in `pyproject.toml` (SemVer).
-2. Add a CHANGELOG entry — see [AGENTS.md → CHANGELOG](AGENTS.md#changelog).
+2. Add a CHANGELOG entry — see [AGENTS.md → CHANGELOG](AGENTS.md#changelog). A breaking
+   change also needs its `### Upgrading` section
+   ([AGENTS.md → Breaking changes](AGENTS.md#breaking-changes)).
 3. `gitleaks git .` reports no leaks (`brew install gitleaks`). Known false
    positives go in `.gitleaks.toml`, each with the reason it's safe.
 4. `make publish`: runs `make check`, builds, and uploads with twine.

{sweatstack-0.93.0 → sweatstack-0.95.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.5
 Name: sweatstack
-Version: 0.93.0
+Version: 0.95.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://docs.sweatstack.no/learn/python/
 Project-URL: Repository, https://github.com/SweatStack/sweatstack-python
 Project-URL: Issues, https://github.com/SweatStack/sweatstack-python/issues
 Project-URL: Changelog, https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md
+Project-URL: Upgrading, https://github.com/SweatStack/sweatstack-python/blob/main/UPGRADING.md
 Author-email: Aart Goossens <aart@sweatstack.no>
 License-Expression: MIT
 License-File: LICENSE
@@ -97,7 +98,9 @@ npx skills add SweatStack/sweatstack-python
 - [Python SDK guide](https://docs.sweatstack.no/learn/python/): authentication,
   clients, data output, errors, Streamlit and FastAPI
 - [API reference](https://docs.sweatstack.no/learn/api-reference/): every endpoint and model
-- [Changelog](https://docs.sweatstack.no/learn/python/changelog/) and [upgrade notes](https://docs.sweatstack.no/learn/python/upgrading/)
+- [Changelog](https://docs.sweatstack.no/learn/python/changelog/)
+- [Upgrading](UPGRADING.md): moving from an older release, from any version, with a prompt for
+  your coding agent. Also at [docs.sweatstack.no](https://docs.sweatstack.no/learn/python/upgrading/).
 
 Sports follow [OpenSportTaxonomy](https://open-sport-taxonomy.sweatstack.no): `sweatstack.Sport`
 is its `Sport` type.

{sweatstack-0.93.0 → sweatstack-0.95.0}/README.md

@@ -53,7 +53,9 @@ npx skills add SweatStack/sweatstack-python
 - [Python SDK guide](https://docs.sweatstack.no/learn/python/): authentication,
   clients, data output, errors, Streamlit and FastAPI
 - [API reference](https://docs.sweatstack.no/learn/api-reference/): every endpoint and model
-- [Changelog](https://docs.sweatstack.no/learn/python/changelog/) and [upgrade notes](https://docs.sweatstack.no/learn/python/upgrading/)
+- [Changelog](https://docs.sweatstack.no/learn/python/changelog/)
+- [Upgrading](UPGRADING.md): moving from an older release, from any version, with a prompt for
+  your coding agent. Also at [docs.sweatstack.no](https://docs.sweatstack.no/learn/python/upgrading/).
 
 Sports follow [OpenSportTaxonomy](https://open-sport-taxonomy.sweatstack.no): `sweatstack.Sport`
 is its `Sport` type.

sweatstack-0.95.0/UPGRADING.md

@@ -0,0 +1,62 @@
+# Upgrading
+
+How to move a project to a newer `sweatstack` release, from any older one. Until 1.0 a minor
+release may contain breaking changes, and every one ships with its upgrade path in the
+[CHANGELOG](CHANGELOG.md): an **Upgrading** section with a table from old to new, and for the
+larger releases a prompt for a coding agent. This page is also at
+https://docs.sweatstack.no/learn/python/upgrading/, with every release's section inline.
+
+<!-- --8<-- [start:procedure] -->
+## Procedure
+
+1. **Find your version.** `uv pip show sweatstack`, or your lockfile.
+2. **Inventory your SDK usage** before changing anything: every call on a `Client` or on the
+   `sweatstack` module (`import sweatstack as ss` is common), `StreamlitAuth` and
+   `sweatstack.fastapi`, the model fields you read, the frame columns and indexes you rely on,
+   the exceptions you catch, and the install line with its extras.
+3. **Read the Upgrading section of every release** between your version and the target; a
+   release without one has nothing to do. Work oldest first: each table uses the names of the
+   release before it.
+   `adaptive_sampling_on` became `nlec_on` in 0.86 and `segmentation_on` in 0.87, so a name may
+   change more than once; follow the chain.
+4. **Change the pin and run your code and tests.** A removed name raises an `AttributeError`
+   naming its replacement, a renamed or keyword-only argument raises `TypeError`, and
+   `from sweatstack import <removed name>` raises Python's plain `ImportError`. The rows marked
+   **Silent** don't fail at all: check each one by hand.
+5. **Don't add compatibility shims.** Move every call site to the new name.
+
+The install line changes too: Python 3.10 or later (0.78), the frame library as an extra
+(`sweatstack[pandas]`, `[polars]` or `[arrow]`; `[streamlit]` includes pandas) and pyarrow 20 or
+later (0.84, 0.89), and no `[jupyter]` extra (0.91).
+<!-- --8<-- [end:procedure] -->
+
+<!-- --8<-- [start:prompt] -->
+## Prompt for a coding agent
+
+Fill in the two versions and paste it into your agent. It works for any distance between them.
+
+```text
+Upgrade this project from sweatstack <OLD> to sweatstack <NEW>.
+
+1. Inventory. Before changing anything, list every use of the SDK: calls on a Client or on the
+   sweatstack module (also as "ss"), StreamlitAuth and sweatstack.fastapi, model fields read
+   from responses, frame columns and indexes, exceptions caught, and the dependency line with
+   its extras.
+2. Plan. Read https://docs.sweatstack.no/learn/python/upgrading/ (the same content is
+   UPGRADING.md and the "Upgrading" sections of CHANGELOG.md in
+   https://github.com/SweatStack/sweatstack-python). Take every release between <OLD> and <NEW>
+   that has an Upgrading section, oldest first, and map each row of its table onto the
+   inventory. A name may be renamed more than once across releases; follow the chain to the
+   final name.
+3. Apply the changes, oldest release first. Do not add compatibility shims.
+4. Install: uv add "sweatstack[<extras>]==<NEW>". The frame library is an extra ([pandas],
+   [polars] or [arrow]); [streamlit] includes pandas.
+5. Run the code and the tests. Fix every AttributeError (its message names the replacement),
+   ImportError and TypeError. Then check every row marked "Silent" against the inventory:
+   those change behaviour without raising.
+6. For the current API, install the SDK's agent skill (npx skills add
+   SweatStack/sweatstack-python) or read https://docs.sweatstack.no/llms.txt.
+
+Report what you changed, and every item of the inventory you could not map to a table row.
+```
+<!-- --8<-- [end:prompt] -->