release: 1.21.0

[stainless-app]

Automated Release PR

1.21.0 (2026-04-06)

Full Changelog: v1.20.0...v1.21.0

Features

• [TPUF-1097] tpuf: return failed IDs for conditional writes (274882a)
• add ContainsAnyToken and RankByKnn types (d099bc4)
• Add float, []float and []bool to the list of valid types in the OpenAPI spec. (bb2e629)
• Add instructions to MCP server config (efe05c6)
• Add ranking-by-attribute to the spec. (72e62a7)
• add support for limit query parameter (b1aa74f)
• add update_metadata method to configure pinning (68c6ea9)
• Add vector attribute schema to metadata endpoint (c87e6f1)
• add WithParams variant to BM25 and ContainsAllTokens (f3776a5)
• Allow for a CMEK key to be specified in copy_from_namespace (ff2c7e1)
• always install orjson, even without the [fast] extra (#192) (ae08f53)
• api: api update (67dbc25)
• api: introduce dedicated Query model (bc09dc2)
• clean up environment call outs (df0cf2f)
• client: add custom JSON encoder for extended type support (97e07e3)
• client: add support for aiohttp (a0a7b69)
• client: add support for binary request streaming (263636f)
• client: support file upload requests (656ce2a)
• ContainsAnyToken last_as_prefix docs (1b567a9)
• disable compression by default (#190) (64a459c)
• docs for glob/regex acceleration (2ff7bd7)
• improve future compat with pydantic v3 (e55b78b)
• internal: implement indices array format for query and form serialization (d7ba617)
• Make type required on AttributeSchemaConfig (9596ee0)
• Make word_v2 the default FTS tokenizer (36844eb)
• Metadata endpoint updates (e.g. to track indexing progress) (160cf02)
• Multiple Vector Columns Docs (f9c378c)
• openapi: Fix stainless warnings (d7f205b)
• openapi: name variants of NamespaceMetadata.index (a1cb762)
• Promote disable_backpressure to first-class Write property (649dd65)
• python: swap stainless to the new client edition to pick up uv (382415b)
• Remove queries from recall endpoint (dfac196)
• remove compatibility shims (#196) (b614dc4)
• required for patch_by_filter 🤦 (5edaf73)
• Response performance object (30bf271)
• sdks: add <patch|delete>_by_filter_allow_partial options (2fbc4a2)
• site: add ascii_folding to docs and SDKs (16535c4)
• spec: add dedicated type for AggregationGroup response (53459e4)
• spec: add support for cross-org CFN to SDKs (8ecd204)
• spec: clean up limit codegen (8046c93)
• spec: disable CopyFromNamespace syntax sugar in Go (08d1660)
• spec: host MCP on stainless (e4ce55d)
• spec: include pinning status in /metadata response (2bc9b76)
• stainless: add patch_by_filter (f277aa1)
• tpuf-engine: add verbose form of branch_from_namespace (ca4b577)
• tpuf: add branching to openapi spec (c21cd2c)
• tpuf: add include_ground_truth option to recall endpoint (6cec9b7)
• types: replace List[str] with SequenceNotStr in params (0283310)

Bug Fixes

• add support for $ref_new expressions (#132) (089686b)
• add support for regex filter (98940c6)
• api: add support for [Not]Contains[Any] operators (#135) (c317be2)
• api: add support for group_by query parameter (d6dcfd3)
• api: api update (4442b97)
• api: api update (4248358)
• api: api update (21ff62c)
• api: api update (eca0afb)
• api: api update (6ec2e1c)
• api: api update (93b4a37)
• api: api update (42fc34d)
• api: api update (b5b879f)
• api: api update (eb80dcd)
• api: api update (59859d0)
• api: api update (c5dd8d1)
• api: api update (bdb172e)
• api: api update (2d71653)
• api: api update (3fd547b)
• api: api update (f83ded0)
• avoid newer type syntax (c048387)
• ci: correct conditional (1226da3)
• ci: release-doctor — report correct token name (7761744)
• client: close streams without requiring full consumption (ec66734)
• client: don't send Content-Type header on GET requests (022b258)
• client: use higher retry delay precision (9ae54bd)
• compat with Python 3.14 (acdd36d)
• compat: compat with pydantic<2.8.0 when using additional fields (09b2a6a)
• compat: update signatures of model_dump and model_dump_json for Pydantic v1 (5d70dcf)
• correct name of stainless bot (#133) (27bf031)
• deps: bump minimum typing-extensions version (8c87152)
• docs: add note about attribute flattening to upgrade guide (#115) (568348d)
• docs: fix mcp installation instructions for remote servers (f9021c6)
• don't require region unless baseUrl contains {region} placeholder (#137) (f27bf12)
• don't run grouped tests in parallel (#125) (9024587)
• don't set region in tests if base URL doesn't support it (b7e8297)
• ensure streams are always closed (d3a57f9)
• explicitly omit TURBOPUFFER_BASE_URL from env when necessary (9075015)
• formatting (5c5fbfa)
• guide: add an upgrade guide (5a9e1b0)
• guide: update UPGRADING.md (c124d29)
• improve custom JSON deserialization (a874f8f)
• more precise types for filters that take arrays (dc6a2d2)
• parsing: correctly handle nested discriminated unions (ab05d54)
• parsing: ignore empty metadata (60f16d4)
• parsing: parse extra field types (ce30a1f)
• pydantic: do not pass by_alias unless set (de9ede8)
• README: add alpha notice (14aac9d)
• README: improve headline example (#131) (7314e3a)
• README: update code examples (12e9cca)
• remove 200 error code for hint_cache_warm API call (always 202 now) (05c43a7)
• sanitize endpoint path params (cde1c36)
• serialize datetime objects when orjson isn't installed (#143) (c3c83eb)
• strict types for new QueryParam type (fae8c4d)
• strict types for write conditions (#130) (0d8f6a1)
• tests: mock delete when testing namespace default params (#116) (db587e8)
• tests: mock delete whne testing namespace default params (072f33a)
• tests: use BM25 query with distinct scores (#179) (8ebe6ff)
• typing of upsert_columns tests (e08eb71)
• update tests for new metadata endpoint (8de7300)
• use async_to_httpx_files in patch method (dd4e2d4)
• use strict types for explain_query (#148) (13b9b70)
• use ThreadedResolver for default async client (#218) (a8c6084)

Performance Improvements

• skip unneeded transformations for primitive types and tuples (#178) (946ad60)

Chores

• add missing Union import in namespace_write_params.py (f16933a)
• bump httpx-aiohttp version to 0.1.9 (e637dca)
• ci: change upload type (9170d90)
• ci: only run for pushes and fork pull requests (55fd498)
• ci: skip lint on metadata-only changes (0bfdb23)
• ci: skip uploading artifacts on stainless-internal branches (ab588f5)
• ci: upgrade actions/github-script (6579e7c)
• codegen updates (c7b662d)
• configure new SDK language (621f6a2)
• Correct python types for patch by filter (and conditional writes) (#172) (caa9cf6)
• deps: mypy 1.18.1 has a regression, pin to 1.17 (093835d)
• do not install brew dependencies in ./scripts/bootstrap by default (642ecd0)
• docs: use environment variables for authentication in code snippets (7d8f0e0)
• fix automatic type regeneration (8fbf95c)
• format all api.md files (b6fdecc)
• internal/tests: avoid race condition with implicit client cleanup (c6e0010)
• internal/tests: avoid race condition with implicit client cleanup (b041c1f)
• internal: add request options to SSE classes (a7a73b1)
• internal: add Sequence related utils (a54d6e3)
• internal: bump dependencies (1e1cfd9)
• internal: bump pinned h11 dep (e3e8ffb)
• internal: change ci workflow machines (80fafa9)
• internal: codegen related update (985c78f)
• internal: codegen related update (539dd89)
• internal: codegen related update (4db3df2)
• internal: codegen related update (11319f2)
• internal: codegen related update (1fcdb49)
• internal: detect missing future annotations with ruff (6a7d4c3)
• internal: fix lint error on Python 3.14 (52c1081)
• internal: fix ruff target version (46f2aae)
• internal: grammar fix (it's -> its) (0231191)
• internal: make test_proxy_environment_variables more resilient (bd36cd0)
• internal: make test_proxy_environment_variables more resilient to env (d870a2d)
• internal: move mypy configurations to pyproject.toml file (05aecc3)
• internal: remove mock server code (557357f)
• internal: tweak CI branches (c9f5d89)
• internal: update actions/checkout version (3b408b0)
• internal: update comment in script (228c590)
• internal: update gitignore (a9d2891)
• internal: update pydantic dependency (13ecfe2)
• internal: update pyright exclude list (c9f9475)
• package: drop Python 3.8 support (a20280f)
• package: mark python 3.13 as supported (2c2d349)
• project: add settings file for vscode (df8c3fa)
• readme: fix version rendering on pypi (8468a19)
• readme: update badges (d03eb1a)
• regenerate custom types (6345281)
• speedup initial import (3686da0)
• tests: skip some failing tests on the latest python versions (18e64f5)
• types: change optional parameter type from NotGiven to Omit (2f0ae47)
• update @stainless-api/prism-cli to v5.15.0 (1389727)
• update github action (d22c67d)
• update lockfile (9fc74d5)
• update mock server docs (d29d55b)

Documentation

• add cross-region copy_from_namespace to write API docs (58433b5)
• client: fix httpx.Timeout documentation reference (320cee5)
• hint_cache_warm also update header and openapi (fda1d58)

Refactors

• types: use extra_items from PEP 728 (9b36d34)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

---

Note

Medium Risk
Touches HTTP client defaults (DNS resolver and connection keepalive) and request serialization, which can subtly affect networking behavior across environments; the new metadata/pinning API surface is additive but changes response typing/shape.

Overview
Bumps the package to v1.21.0 (manifest, pyproject.toml, _version.py) and updates the changelog/release metadata.

Extends the Namespaces API with update_metadata (sync/async + raw/stream wrappers) to configure namespace pinning, adds new pinning models (PinningConfig, NamespaceUpdateMetadataParams) and exposes pinning/status on NamespaceMetadata; also adds rank_by support to the _debug/recall endpoint params.

Improves client internals by supporting indices array query serialization, increasing connection keepalive expiry to 60s, and forcing aiohttp’s ThreadedResolver in the default async transport to avoid problematic negative-DNS caching. CI lint/build jobs now skip runs for push commits with message codegen metadata, and .gitignore adds .stdy.log.

^{Reviewed by Cursor Bugbot for commit f15e3cc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[stainless-app]

🧪 Testing

To try out this version of the SDK:

pip install 'https://pkg.stainless.com/s/turbopuffer-python/6e1517ce2f7c1f5bb769587e92500624541267e0/turbopuffer-1.20.0-py3-none-any.whl'

Expires at: Thu, 07 May 2026 06:21:12 GMT
Updated at: Tue, 07 Apr 2026 06:21:12 GMT

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 55bfc76. Configure here.}