---
title: "Python SDK changelog"
type: reference
tags: [python, sdk, changelog, versions, releases]
created: 2026-09-17
updated: 2026-09-17
confidence: high
sources:
  - raw/docs/sdk__python__changelog.md
  - raw/github/typesafe-sdk-python/docs/changelog.md
  - raw/github/typesafe-sdk-python/pyproject.toml
jev_version: "jev-1.13.0"
sdk_python: "0.6.0"
summary: "typesafe-sdk release history: 0.0.1a0 placeholder, 0.5.7 initial public release (2026-09-14), 0.6.0 (2026-09-15) with the Score.criteria breaking change."
---

# Python SDK changelog

> **TL;DR** `typesafe-sdk` has three PyPI releases: `0.0.1a0` (name placeholder), `0.5.7` — the initial public release, 2026-09-14 — and `0.6.0`, 2026-09-15, the current version. The only breaking change so far: `Score.criteria` is now an ordered sequence instead of a dictionary keyed by integers. Write new code against 0.6.0.

## Release table

| Version | Date | Kind | Headline |
|---|---|---|---|
| `0.6.0` | 2026-09-15 | minor, **breaking** | `Score.criteria` becomes an ordered sequence; abstract input types; richer errors; `RetryPolicy` validation; picklable exceptions and responses |
| `0.5.7` | 2026-09-14 | initial public release | First published SDK |
| `0.0.1a0` | — (date not captured) | pre-release placeholder | Reserves the `typesafe-sdk` name on PyPI; no documented content |

The upstream changelog (both the docs page and `docs/changelog.md` in the repo) covers only `0.6.0` and `0.5.7`. `0.0.1a0` appears in the PyPI release listing collected 2026-09-17 and has no changelog entry.

Repository state captured for this wiki: `https://github.com/typesafe-ai/typesafe-sdk-python` at commit **`420ef4ffb612d5a539a1e0f0fe883ff6770340af`**, authored 2026-09-15, subject "Release v0.6.0" (co-authored by Allie Laabs and Daniel Gafni). Tags `v0.5.7` and `v0.6.0` are both present in the clone; `v0.6.0` points at that same commit, which is also `origin/main`. `pyproject.toml` at that commit declares `version = "0.6.0"`.

## v0.6.0 (2026-09-15)

Verbatim from the upstream changelog:

**Breaking Changes**

- accept `Score.criteria` as an ordered sequence instead of a dictionary keyed by integers

**Features**

- improve type annotations on SDK inputs to accept abstract types like `Mapping` and `Sequence`
- improve error messages to include http details and metadata

**Bug fixes**

- handle invalid values in `RetryPolicy`
- make exceptions and responses picklable

**Documentation**

- link more concepts from main [docs](https://docs.typesafe.ai/)

### What the breaking change means in code

```python
from typesafe_sdk import Score

# 0.6.0 and later
Score(instructions="How urgent is this ticket?", criteria=["can wait", "this week", "today"])

# pre-0.6.0 shape — an int-keyed dict; no longer the documented form
# Score(instructions="How urgent is this ticket?",
#       criteria={0: "can wait", 1: "this week", 2: "today"})
```

Migration steps when upgrading from 0.5.7:

1. Find every `Score(...)` construction and every `{"type": "score", ...}` dictionary.
2. Replace the int-keyed dict with a list (or tuple) ordered from score `0` upward. `sorted(old.items())` then `[value for _, value in ...]` reproduces the order.
3. Leave answer-reading code alone: `ScoreAnswer.legend` and `ScoreAnswer.probabilities` are still keyed by **integer** score. Only the question side changed.
4. Re-check `RetryPolicy(...)` arguments — invalid values now raise `TypeSafeError` at construction instead of being accepted silently.

See [[reference/python-sdk-questions]] for the full 0.6.0 question contract and [[reference/python-sdk-responses]] for the answer side.

### Where each change is visible in the API

| Change | Observable effect | Page |
|---|---|---|
| `Score.criteria` sequence | `Score(criteria=Sequence[JSONContent])`; empty sequence raises `TypeSafeError` | [[reference/python-sdk-questions]] |
| Abstract input types | `state`, `questions`, `criteria`, `headers` accept `Mapping`/`Sequence`, not just `dict`/`list` | [[reference/python-sdk]] |
| Richer error messages | `TypeSafeAPIError.endpoint`, and `__str__` renders `endpoint: status message (request_id=…)` | [[reference/python-sdk-retries-errors]] |
| `RetryPolicy` validation | `__post_init__` raises `TypeSafeError` for bad `max_retries`, backoff values, jitter, or timeout | [[reference/python-sdk-retries-errors]] |
| Picklable exceptions and responses | `Response.__copy__` / `__reduce__` carry `request_id` and the raw HTTP response; `TypeSafeAPIResponseValidationError.args` is set explicitly | [[reference/python-sdk-responses]] |

## v0.5.7 (2026-09-14)

Verbatim: "This is the initial public release of TypeSafe Python SDK. Learn more in the [documentation](https://docs.typesafe.ai/sdk/python)."

No itemized changes are published for this release. The version number starting at `0.5.7` rather than `0.1.0` is not explained upstream; the Python and JavaScript SDKs share the `0.5.7` → `0.6.0` sequence, which suggests a shared internal release train (inferred).

## v0.0.1a0

Listed on PyPI among the `typesafe-sdk` releases (`0.0.1a0`, `0.5.7`, `0.6.0`) as collected on 2026-09-17. No changelog entry, no release date captured, and no documentation references it. Treat it as a name-reservation pre-release; do not install it.

## Related packages

| Package | Version | Note |
|---|---|---|
| `typesafe-sdk` | 0.6.0 | The SDK. Import as `typesafe_sdk`. |
| `typesafe-ai` | 0.1.0 | Redirect shim that simply depends on `typesafe-sdk`. |
| `typesafe` | 0.9.1 | Unrelated third-party package — **not** TypeSafe AI. |
| `@typesafe-ai/sdk` (npm) | 0.6.0 (2026-09-15); 0.5.7 on 2026-09-12 | The JavaScript SDK, on the same version line — see [[reference/javascript-sdk-changelog]]. |

## Version pinning

The SDK is pre-1.0, and 0.6.0 already shipped a breaking change in a minor bump, so pin conservatively:

```toml
# pyproject.toml
dependencies = ["typesafe-sdk>=0.6.0,<0.7"]
```

```sh
uv add "typesafe-sdk>=0.6.0,<0.7"
```

Check the installed version at runtime:

```python
from typesafe_sdk import __version__

print(__version__)  # resolved via importlib.metadata.version("typesafe-sdk")
```

## Related

- [[reference/python-sdk]] — install, clients, `system_one()`
- [[reference/python-sdk-questions]] — the 0.6.0 `Score.criteria` contract
- [[reference/python-sdk-responses]] — answers, usage, models
- [[reference/python-sdk-retries-errors]] — `RetryPolicy` validation and richer errors
- [[reference/javascript-sdk-changelog]] — the JS SDK's parallel release line
- [[syntheses/version-timeline]] — models, SDKs, API and company timeline
- [[entities/github-repos]] — the `typesafe-ai` GitHub organisation

## Sources

- raw/docs/sdk__python__changelog.md (https://docs.typesafe.ai/sdk/python/changelog.md)
- raw/github/typesafe-sdk-python/docs/changelog.md, pyproject.toml, git tags v0.5.7 / v0.6.0 (https://github.com/typesafe-ai/typesafe-sdk-python @ 420ef4ffb612d5a539a1e0f0fe883ff6770340af, 2026-09-15)
- PyPI release listing for `typesafe-sdk` (0.0.1a0, 0.5.7, 0.6.0) and the `typesafe-ai` shim, collected 2026-09-17 and recorded in CLAUDE.md