release: 2.7.0

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
   lint:
     timeout-minutes: 10
     name: lint
-    runs-on: ${{ github.repository == 'stainless-sdks/turbopuffer-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -41,7 +41,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    runs-on: ${{ github.repository == 'stainless-sdks/turbopuffer-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
@@ -78,7 +78,7 @@ jobs:
   test:
     timeout-minutes: 10
     name: test
-    runs-on: ${{ github.repository == 'stainless-sdks/turbopuffer-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.6.0"
+  ".": "2.7.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 14
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/turbopuffer-benesch/turbopuffer-45f4429a37dcc469269006f05ea38ee3973087f22456b1cdb60b682902997372.yml
-openapi_spec_hash: a606206d2ac6886fe31c3392a1f590ea
-config_hash: d3fc3b93270f7ee8ae68224dafcfeb6d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/turbopuffer-benesch/turbopuffer-c0051833b669a15d2f206974c559f74189cad6df3d636ae7eb620415d7cf6eb9.yml
+openapi_spec_hash: 8459bc996ccbfcd259819e2629b7ab84
+config_hash: 7324a6da70bb03cd6ca0e8bd3ee13230

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.7.0 (2026-07-28)
+
+Full Changelog: [v2.6.0...v2.7.0](https://github.com/turbopuffer/turbopuffer-python/compare/v2.6.0...v2.7.0)
+
+### Features
+
+* spec: expose computed attributes ([8f30d04](https://github.com/turbopuffer/turbopuffer-python/commit/8f30d04b16666eaaab62e687616ad89941e2af8c))
+* spec: hide HighlightConfig.rank_fragments_by's RankBy ref from Stainless ([4499367](https://github.com/turbopuffer/turbopuffer-python/commit/4499367be3939095a589adedea9216e14d40b909))
+* spec: make compute_attributes value x-stainless-any ([bfbe79f](https://github.com/turbopuffer/turbopuffer-python/commit/bfbe79f29822e2476aede59daf6d45da50f68bec))
+* spec: rename HighlightConfig -> HighlightConfigParams ([df57c87](https://github.com/turbopuffer/turbopuffer-python/commit/df57c87315e76ec65a3ef9c72b1a050f98d8c634))
+* **stlc:** configurable CI runner and private-production-repo support in workflow templates ([6db1360](https://github.com/turbopuffer/turbopuffer-python/commit/6db13603ee86578d58a52bc599547ac4f75fee2f))
+
+
+### Bug Fixes
+
+* **internal:** resolve build failures ([53ce6dd](https://github.com/turbopuffer/turbopuffer-python/commit/53ce6ddf14884821a1d3d760badef1ec558f4e09))
+
+
+### Chores
+
+* regenerate custom types for compute attributes ([#246](https://github.com/turbopuffer/turbopuffer-python/issues/246)) ([98a9d11](https://github.com/turbopuffer/turbopuffer-python/commit/98a9d1158c7a2f9e713a31197e293f65e69aee94))
+
 ## 2.6.0 (2026-07-01)
 
 Full Changelog: [v2.5.0...v2.6.0](https://github.com/turbopuffer/turbopuffer-python/compare/v2.5.0...v2.6.0)

README.md

@@ -9,6 +9,15 @@ and offers both synchronous and asynchronous clients powered by [httpx](https://
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## MCP Server
+
+Use the Turbopuffer MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40turbopuffer%2Fturbopuffer-mcp&config=eyJuYW1lIjoiQHR1cmJvcHVmZmVyL3R1cmJvcHVmZmVyLW1jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJ1cmwiOiJodHRwczovL3R1cmJvcHVmZmVyLnN0bG1jcC5jb20iLCJoZWFkZXJzIjp7IngtdHVyYm9wdWZmZXItYXBpLWtleSI6InRwdWZfQTEuLi4ifX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40turbopuffer%2Fturbopuffer-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fturbopuffer.stlmcp.com%22%2C%22headers%22%3A%7B%22x-turbopuffer-api-key%22%3A%22tpuf_A1...%22%7D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
 ## Documentation
 
 The HTTP API documentation can be found at [turbopuffer.com/docs/api-overview](https://turbopuffer.com/docs/api-overview).

api.md

@@ -37,6 +37,9 @@ from turbopuffer.types import (
     FullTextSearchConfig,
     FuzzyMaxEditDistance,
     FuzzyParams,
+    HighlightConfigParams,
+    HighlightFragmentBy,
+    HighlightOffsetUnits,
     ID,
     IncludeAttributes,
     Language,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "turbopuffer"
-version = "2.6.0"
+version = "2.7.0"
 description = "The official Python library for the turbopuffer API"
 dynamic = ["readme"]
 license = "MIT"

scripts/gen

@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-apigen_image=ghcr.io/turbopuffer/turbopuffer-apigen:1b58f2aa9172bf7a668bf862c271b852e95a846b
+apigen_image=ghcr.io/turbopuffer/turbopuffer-apigen:50f6977f4020491663b87ecfc2650cc737f03437
 
 apigen() {
     if [[ "$TURBOPUFFER_DEV_APIGEN" ]]; then

scripts/lint

@@ -21,7 +21,7 @@ else
 fi
 
 echo "==> Running pyright"
-uv run pyright
+uv run pyright -p .
 
 echo "==> Running mypy"
 uv run mypy .

src/turbopuffer/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "turbopuffer"
-__version__ = "2.6.0"  # x-release-please-version
+__version__ = "2.7.0"  # x-release-please-version

src/turbopuffer/resources/namespaces.py

@@ -222,6 +222,7 @@ def explain_query(
         *,
         namespace: str | None = None,
         aggregate_by: Dict[str, AggregateBy] | Omit = omit,
+        compute_attributes: Dict[str, object] | Omit = omit,
         consistency: namespace_explain_query_params.Consistency | Omit = omit,
         distance_metric: DistanceMetric | Omit = omit,
         exclude_attributes: SequenceNotStr[str] | Omit = omit,
@@ -246,6 +247,10 @@ def explain_query(
           aggregate_by: Aggregations to compute over all documents in the namespace that match the
               filters.
 
+          compute_attributes: Computes additional values on documents returned by a query. Each key is the
+              name of the computed attribute; each value is an expression describing how to
+              compute it.
+
           consistency: The consistency level for a query.
 
           distance_metric: A function used to calculate vector similarity.
@@ -286,6 +291,7 @@ def explain_query(
             body=maybe_transform(
                 {
                     "aggregate_by": aggregate_by,
+                    "compute_attributes": compute_attributes,
                     "consistency": consistency,
                     "distance_metric": distance_metric,
                     "exclude_attributes": exclude_attributes,
@@ -434,6 +440,7 @@ def query(
         *,
         namespace: str | None = None,
         aggregate_by: Dict[str, AggregateBy] | Omit = omit,
+        compute_attributes: Dict[str, object] | Omit = omit,
         consistency: namespace_query_params.Consistency | Omit = omit,
         distance_metric: DistanceMetric | Omit = omit,
         exclude_attributes: SequenceNotStr[str] | Omit = omit,
@@ -458,6 +465,10 @@ def query(
           aggregate_by: Aggregations to compute over all documents in the namespace that match the
               filters.
 
+          compute_attributes: Computes additional values on documents returned by a query. Each key is the
+              name of the computed attribute; each value is an expression describing how to
+              compute it.
+
           consistency: The consistency level for a query.
 
           distance_metric: A function used to calculate vector similarity.
@@ -498,6 +509,7 @@ def query(
             body=maybe_transform(
                 {
                     "aggregate_by": aggregate_by,
+                    "compute_attributes": compute_attributes,
                     "consistency": consistency,
                     "distance_metric": distance_metric,
                     "exclude_attributes": exclude_attributes,
@@ -992,6 +1004,7 @@ async def explain_query(
         *,
         namespace: str | None = None,
         aggregate_by: Dict[str, AggregateBy] | Omit = omit,
+        compute_attributes: Dict[str, object] | Omit = omit,
         consistency: namespace_explain_query_params.Consistency | Omit = omit,
         distance_metric: DistanceMetric | Omit = omit,
         exclude_attributes: SequenceNotStr[str] | Omit = omit,
@@ -1016,6 +1029,10 @@ async def explain_query(
           aggregate_by: Aggregations to compute over all documents in the namespace that match the
               filters.
 
+          compute_attributes: Computes additional values on documents returned by a query. Each key is the
+              name of the computed attribute; each value is an expression describing how to
+              compute it.
+
           consistency: The consistency level for a query.
 
           distance_metric: A function used to calculate vector similarity.
@@ -1056,6 +1073,7 @@ async def explain_query(
             body=await async_maybe_transform(
                 {
                     "aggregate_by": aggregate_by,
+                    "compute_attributes": compute_attributes,
                     "consistency": consistency,
                     "distance_metric": distance_metric,
                     "exclude_attributes": exclude_attributes,
@@ -1204,6 +1222,7 @@ async def query(
         *,
         namespace: str | None = None,
         aggregate_by: Dict[str, AggregateBy] | Omit = omit,
+        compute_attributes: Dict[str, object] | Omit = omit,
         consistency: namespace_query_params.Consistency | Omit = omit,
         distance_metric: DistanceMetric | Omit = omit,
         exclude_attributes: SequenceNotStr[str] | Omit = omit,
@@ -1228,6 +1247,10 @@ async def query(
           aggregate_by: Aggregations to compute over all documents in the namespace that match the
               filters.
 
+          compute_attributes: Computes additional values on documents returned by a query. Each key is the
+              name of the computed attribute; each value is an expression describing how to
+              compute it.
+
           consistency: The consistency level for a query.
 
           distance_metric: A function used to calculate vector similarity.
@@ -1268,6 +1291,7 @@ async def query(
             body=await async_maybe_transform(
                 {
                     "aggregate_by": aggregate_by,
+                    "compute_attributes": compute_attributes,
                     "consistency": consistency,
                     "distance_metric": distance_metric,
                     "exclude_attributes": exclude_attributes,

src/turbopuffer/types/__init__.py

@@ -37,15 +37,18 @@
 from .namespace_metadata import NamespaceMetadata as NamespaceMetadata
 from .pinning_config_param import PinningConfigParam as PinningConfigParam
 from .attribute_embed_param import AttributeEmbedParam as AttributeEmbedParam
+from .highlight_fragment_by import HighlightFragmentBy as HighlightFragmentBy
 from .sharding_config_param import ShardingConfigParam as ShardingConfigParam
 from .attribute_embed_config import AttributeEmbedConfig as AttributeEmbedConfig
 from .attribute_schema_param import AttributeSchemaParam as AttributeSchemaParam
 from .full_text_search_param import FullTextSearchParam as FullTextSearchParam
+from .highlight_offset_units import HighlightOffsetUnits as HighlightOffsetUnits
 from .namespace_query_params import NamespaceQueryParams as NamespaceQueryParams
 from .namespace_write_params import NamespaceWriteParams as NamespaceWriteParams
 from .sparse_distance_metric import SparseDistanceMetric as SparseDistanceMetric
 from .attribute_schema_config import AttributeSchemaConfig as AttributeSchemaConfig
 from .full_text_search_config import FullTextSearchConfig as FullTextSearchConfig
+from .highlight_config_params import HighlightConfigParams as HighlightConfigParams
 from .namespace_recall_params import NamespaceRecallParams as NamespaceRecallParams
 from .client_namespaces_params import ClientNamespacesParams as ClientNamespacesParams
 from .include_attributes_param import IncludeAttributesParam as IncludeAttributesParam

src/turbopuffer/types/custom.py

@@ -8,12 +8,23 @@
 from .fuzzy_params import FuzzyParams
 from .saturate_params import SaturateParams
 from .bm25_clause_params import Bm25ClauseParams
+from .highlight_config_params import HighlightConfigParams
 from .contains_any_token_filter_params import ContainsAnyTokenFilterParams
 from .contains_all_tokens_filter_params import ContainsAllTokensFilterParams
 
 AggregateBy = Union[Tuple[Literal["Count"]], Tuple[Literal["Sum"], str], Tuple[Literal["Count"], str]]
+ComputeAttributesVectorDist = Tuple[str, Literal["VectorDist"], Sequence[float]]
+ComputeAttributesHighlight = Tuple[Literal["Highlight"], str]
+ComputeAttributesHighlightWithConfig = Tuple[Literal["Highlight"], str, HighlightConfigParams]
+RankByAnn = Tuple[str, Literal["ANN"], Sequence[float]]
+RankByAnnMulti = Tuple[str, Literal["ANN"], Sequence[Sequence[float]]]
 ExprRefNew = TypedDict("ExprRefNew", {"$ref_new": str})
 Expr = Union[ExprRefNew, Tuple[Literal["Embed"], str], Tuple[Literal["Embed"], str, EmbedParams]]
+RankByAnnExpr = Tuple[str, Literal["ANN"], Expr]
+RankByKnn = Tuple[str, Literal["kNN"], Sequence[float]]
+RankByKnnMulti = Tuple[str, Literal["kNN"], Sequence[Sequence[float]]]
+RankByKnnExpr = Tuple[str, Literal["kNN"], Expr]
+RankBySparseKnn = Tuple[str, Literal["SparseKNN"], Mapping[str, float]]
 Filter = Union[
     Tuple[str, Literal["Eq"], Any],
     Tuple[str, Literal["NotEq"], Any],
@@ -51,15 +62,6 @@
     Tuple[Literal["And"], Sequence["Filter"]],
     Tuple[Literal["Or"], Sequence["Filter"]],
 ]
-GroupByFunction = Tuple[Literal["ForEachUnique"], str]
-GroupBy = Union[str, Mapping[str, GroupByFunction]]
-RankByAnn = Tuple[str, Literal["ANN"], Sequence[float]]
-RankByAnnMulti = Tuple[str, Literal["ANN"], Sequence[Sequence[float]]]
-RankByAnnExpr = Tuple[str, Literal["ANN"], Expr]
-RankByKnn = Tuple[str, Literal["kNN"], Sequence[float]]
-RankByKnnMulti = Tuple[str, Literal["kNN"], Sequence[Sequence[float]]]
-RankByKnnExpr = Tuple[str, Literal["kNN"], Expr]
-RankBySparseKnn = Tuple[str, Literal["SparseKNN"], Mapping[str, float]]
 RankByText = Union[
     Tuple[str, Literal["BM25"], str],
     Tuple[str, Literal["BM25"], Sequence[str]],
@@ -90,4 +92,12 @@
     RankByAttribute,
     RankByAttributes,
 ]
+ComputeAttributes = Union[
+    ComputeAttributesVectorDist,
+    ComputeAttributesHighlight,
+    ComputeAttributesHighlightWithConfig,
+    RankBy,
+]
+GroupByFunction = Tuple[Literal["ForEachUnique"], str]
+GroupBy = Union[str, Mapping[str, GroupByFunction]]
 RerankBy = Union[Tuple[Literal["RRF"]], Tuple[Literal["RRF"], RrfParams]]

src/turbopuffer/types/highlight_config_params.py

@@ -0,0 +1,29 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+from .highlight_fragment_by import HighlightFragmentBy
+from .highlight_offset_units import HighlightOffsetUnits
+
+__all__ = ["HighlightConfigParams"]
+
+
+class HighlightConfigParams(TypedDict, total=False):
+    """Additional (optional) parameters for the Highlight compute expression."""
+
+    fragment_by: HighlightFragmentBy
+    """How to split a text attribute into fragments for highlighting."""
+
+    fragment_limit: int
+    """The maximum number of fragments to return. Defaults to `3`."""
+
+    include_offsets: HighlightOffsetUnits
+    """The units to report highlighted fragment offsets in."""
+
+    rank_fragments_by: object
+    """
+    How to rank candidate fragments within the attribute before selecting the top
+    `fragment_limit`. Defaults to the query's `rank_by`.
+    """

src/turbopuffer/types/highlight_fragment_by.py

@@ -0,0 +1,7 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal, TypeAlias
+
+__all__ = ["HighlightFragmentBy"]
+
+HighlightFragmentBy: TypeAlias = Literal["none", "sentence", "paragraph", "word"]

src/turbopuffer/types/highlight_offset_units.py

@@ -0,0 +1,7 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal, TypeAlias
+
+__all__ = ["HighlightOffsetUnits"]
+
+HighlightOffsetUnits: TypeAlias = Literal["utf-8", "utf-16", "codepoints"]

src/turbopuffer/types/namespace_explain_query_params.py

@@ -5,7 +5,7 @@
 from typing import Dict, Union, Iterable
 from typing_extensions import Literal, TypeAlias, TypedDict
 
-from .custom import GroupBy
+from .custom import GroupBy, ComputeAttributes
 from .._types import SequenceNotStr
 from .limit_param import LimitParam
 from .distance_metric import DistanceMetric
@@ -24,6 +24,13 @@ class NamespaceExplainQueryParams(TypedDict, total=False):
     filters.
     """
 
+    compute_attributes: Dict[str, ComputeAttributes]
+    """Computes additional values on documents returned by a query.
+
+    Each key is the name of the computed attribute; each value is an expression
+    describing how to compute it.
+    """
+
     consistency: Consistency
     """The consistency level for a query."""
 

src/turbopuffer/types/namespace_multi_query_params.py

@@ -5,7 +5,7 @@
 from typing import Dict, Union, Iterable
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-from .custom import GroupBy
+from .custom import GroupBy, ComputeAttributes
 from .._types import SequenceNotStr
 from .limit_param import LimitParam
 from .distance_metric import DistanceMetric
@@ -42,6 +42,13 @@ class Query(TypedDict, total=False):
     filters.
     """
 
+    compute_attributes: Dict[str, ComputeAttributes]
+    """Computes additional values on documents returned by a query.
+
+    Each key is the name of the computed attribute; each value is an expression
+    describing how to compute it.
+    """
+
     distance_metric: DistanceMetric
     """A function used to calculate vector similarity."""