turbopuffer-ruby 0.2.6 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e68ecf643e3ef570edf2c61bfb412c27d9c2c17fbaf5e4c614c7d5aa2afa3e05
-  data.tar.gz: '095f4ccefed27b4a1479ecdb5c10a88a7a2017f1aa4f25188c321b206765aba4'
+  metadata.gz: bf1a733400e137460404c91f94f07f33c3c1689e55314cf47b50a49f77833162
+  data.tar.gz: c40716bf64042af849af0a447978ee30dbff168889a20fbcae73a02848d14b8b
 SHA512:
-  metadata.gz: febffe23d0069251a67e807e34cb502bf9a40bd819e755c72a7c6c369898143145767c6fb8362c2e66138247abc9886dd04154c37be11aeaf20cb05230249314
-  data.tar.gz: d6be41a93adaf04d4c3eacb77ff1e9efff4fe2d38ad616f5d70da99b5e8834f31c9babded64d1a1f84645d6a4fc9146bbb625647890ad1adbe1683ecaf24b41b
+  metadata.gz: a346946a966199348fd7db43d4524180db76654ae9f034f711b4585dde67f2da7182d25ae5006f963df0e52cf4b4bf157b43044dd2e35e0e598c04e4bb665e19
+  data.tar.gz: 6cd084d22d120d8ee095441d1fe8ec21bf0bed3d4c52131b7d1ef4be000f0cc6b10e4584bc93753872b41fbccef18136cd9412641c8f54b38a3ef1abc37e57fa

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.1.0 (2025-09-11)
+
+Full Changelog: [v1.0.0...v1.1.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v1.0.0...v1.1.0)
+
+### Features
+
+* spec: add dedicated type for AggregationGroup response ([e30bb79](https://github.com/turbopuffer/turbopuffer-ruby/commit/e30bb796ff91b36d3f9424674470eb84feeaad63))
+* tpuf: add include_ground_truth option to recall endpoint ([9d535c4](https://github.com/turbopuffer/turbopuffer-ruby/commit/9d535c44ce64f47a312a693d009506d635230322))
+
+## 1.0.0 (2025-08-28)
+
+Full Changelog: [v0.2.6...v1.0.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.6...v1.0.0)
+
+### Features
+
+* Make word_v2 the default FTS tokenizer ([80b7df4](https://github.com/turbopuffer/turbopuffer-ruby/commit/80b7df45beb96368a97af615330eb9bdff415577))
+
+
+### Bug Fixes
+
+* bump sorbet version and fix new type errors from the breaking change ([751bf80](https://github.com/turbopuffer/turbopuffer-ruby/commit/751bf8010f07d33521d73c40b49ca341f9d26505))
+
+
+### Chores
+
+* add json schema comment for rubocop.yml ([ce20bd0](https://github.com/turbopuffer/turbopuffer-ruby/commit/ce20bd0db6a9cead8cd66874a29a4c99c857b31e))
+
 ## 0.2.6 (2025-08-18)
 
 Full Changelog: [v0.2.5...v0.2.6](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.5...v0.2.6)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "turbopuffer-ruby", "~> 0.2.6"
+gem "turbopuffer-ruby", "~> 1.1.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/turbopuffer/internal/transport/pooled_net_requester.rb

@@ -193,15 +193,7 @@ module Turbopuffer
         end
 
         define_sorbet_constant!(:Request) do
-          T.type_alias do
-            {
-              method: Symbol,
-              url: URI::Generic,
-              headers: T::Hash[String, String],
-              body: T.anything,
-              deadline: Float
-            }
-          end
+          T.type_alias { {method: Symbol, url: URI::Generic, headers: T::Hash[String, String], body: T.anything, deadline: Float} }
         end
       end
     end

data/lib/turbopuffer/internal/type/base_model.rb

@@ -64,14 +64,7 @@ module Turbopuffer
             setter = :"#{name_sym}="
             api_name = info.fetch(:api_name, name_sym)
             nilable = info.fetch(:nil?, false)
-            const = if required && !nilable
-              info.fetch(
-                :const,
-                Turbopuffer::Internal::OMIT
-              )
-            else
-              Turbopuffer::Internal::OMIT
-            end
+            const = required && !nilable ? info.fetch(:const, Turbopuffer::Internal::OMIT) : Turbopuffer::Internal::OMIT
 
             [name_sym, setter].each { undef_method(_1) } if known_fields.key?(name_sym)
 

data/lib/turbopuffer/internal/util.rb

@@ -244,7 +244,7 @@ module Turbopuffer
         #
         # @return [String]
         def uri_origin(uri)
-          "#{uri.scheme}://#{uri.host}#{uri.port == uri.default_port ? '' : ":#{uri.port}"}"
+          "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.port == uri.default_port}"
         end
 
         # @api private

data/lib/turbopuffer/models/aggregation_group.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Turbopuffer
+  module Models
+    # @type [Turbopuffer::Internal::Type::Converter]
+    AggregationGroup = Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]
+  end
+end

data/lib/turbopuffer/models/full_text_search_config.rb

@@ -51,7 +51,8 @@ module Turbopuffer
       optional :stemming, Turbopuffer::Internal::Type::Boolean
 
       # @!attribute tokenizer
-      #   The tokenizer to use for full-text search on an attribute.
+      #   The tokenizer to use for full-text search on an attribute. Defaults to
+      #   `word_v2`.
       #
       #   @return [Symbol, Turbopuffer::Models::Tokenizer, nil]
       optional :tokenizer, enum: -> { Turbopuffer::Tokenizer }
@@ -76,7 +77,7 @@ module Turbopuffer
       #
       #   @param stemming [Boolean] Language-specific stemming for the text. Defaults to `false` (i.e., do not stem)
       #
-      #   @param tokenizer [Symbol, Turbopuffer::Models::Tokenizer] The tokenizer to use for full-text search on an attribute.
+      #   @param tokenizer [Symbol, Turbopuffer::Models::Tokenizer] The tokenizer to use for full-text search on an attribute. Defaults to `word_v2`
     end
   end
 end

data/lib/turbopuffer/models/namespace_multi_query_response.rb

@@ -34,8 +34,9 @@ module Turbopuffer
       class Result < Turbopuffer::Internal::Type::BaseModel
         # @!attribute aggregation_groups
         #
-        #   @return [Array<Turbopuffer::Models::Row>, nil]
-        optional :aggregation_groups, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
+        #   @return [Array<Hash{Symbol=>Object}>, nil]
+        optional :aggregation_groups,
+                 Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]]
 
         # @!attribute aggregations
         #
@@ -48,7 +49,7 @@ module Turbopuffer
         optional :rows, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
 
         # @!method initialize(aggregation_groups: nil, aggregations: nil, rows: nil)
-        #   @param aggregation_groups [Array<Turbopuffer::Models::Row>]
+        #   @param aggregation_groups [Array<Hash{Symbol=>Object}>]
         #   @param aggregations [Hash{Symbol=>Object}]
         #   @param rows [Array<Turbopuffer::Models::Row>]
       end

data/lib/turbopuffer/models/namespace_query_response.rb

@@ -18,8 +18,9 @@ module Turbopuffer
 
       # @!attribute aggregation_groups
       #
-      #   @return [Array<Turbopuffer::Models::Row>, nil]
-      optional :aggregation_groups, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
+      #   @return [Array<Hash{Symbol=>Object}>, nil]
+      optional :aggregation_groups,
+               Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]]
 
       # @!attribute aggregations
       #
@@ -38,7 +39,7 @@ module Turbopuffer
       #
       #   @param performance [Turbopuffer::Models::QueryPerformance] The performance information for a query.
       #
-      #   @param aggregation_groups [Array<Turbopuffer::Models::Row>]
+      #   @param aggregation_groups [Array<Hash{Symbol=>Object}>]
       #
       #   @param aggregations [Hash{Symbol=>Object}]
       #

data/lib/turbopuffer/models/namespace_recall_params.rb

@@ -18,6 +18,13 @@ module Turbopuffer
       #   @return [Object, nil]
       optional :filters, Turbopuffer::Internal::Type::Unknown
 
+      # @!attribute include_ground_truth
+      #   Include ground truth data (query vectors and true nearest neighbors) in the
+      #   response.
+      #
+      #   @return [Boolean, nil]
+      optional :include_ground_truth, Turbopuffer::Internal::Type::Boolean
+
       # @!attribute num
       #   The number of searches to run.
       #
@@ -37,7 +44,7 @@ module Turbopuffer
       #   @return [Integer, nil]
       optional :top_k, Integer
 
-      # @!method initialize(namespace: nil, filters: nil, num: nil, queries: nil, top_k: nil, request_options: {})
+      # @!method initialize(namespace: nil, filters: nil, include_ground_truth: nil, num: nil, queries: nil, top_k: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::NamespaceRecallParams} for more details.
       #
@@ -45,6 +52,8 @@ module Turbopuffer
       #
       #   @param filters [Object] Filter by attributes. Same syntax as the query endpoint.
       #
+      #   @param include_ground_truth [Boolean] Include ground truth data (query vectors and true nearest neighbors) in the resp
+      #
       #   @param num [Integer] The number of searches to run.
       #
       #   @param queries [Array<Float>] Use specific query vectors for the measurement. If omitted, sampled from the ind

data/lib/turbopuffer/models/namespace_recall_response.rb

@@ -23,7 +23,15 @@ module Turbopuffer
       #   @return [Float]
       required :avg_recall, Float
 
-      # @!method initialize(avg_ann_count:, avg_exhaustive_count:, avg_recall:)
+      # @!attribute ground_truth
+      #   Ground truth data including query vectors and true nearest neighbors. Only
+      #   included when include_ground_truth is true.
+      #
+      #   @return [Array<Turbopuffer::Models::NamespaceRecallResponse::GroundTruth>, nil]
+      optional :ground_truth,
+               -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth] }
+
+      # @!method initialize(avg_ann_count:, avg_exhaustive_count:, avg_recall:, ground_truth: nil)
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::NamespaceRecallResponse} for more details.
       #
@@ -34,6 +42,27 @@ module Turbopuffer
       #   @param avg_exhaustive_count [Float] The average number of documents retrieved by the exhaustive searches.
       #
       #   @param avg_recall [Float] The average recall of the queries.
+      #
+      #   @param ground_truth [Array<Turbopuffer::Models::NamespaceRecallResponse::GroundTruth>] Ground truth data including query vectors and true nearest neighbors. Only inclu
+
+      class GroundTruth < Turbopuffer::Internal::Type::BaseModel
+        # @!attribute nearest_neighbors
+        #   The true nearest neighbors with their distances and vectors.
+        #
+        #   @return [Array<Turbopuffer::Models::Row>]
+        required :nearest_neighbors, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
+
+        # @!attribute query_vector
+        #   The query vector used for this search.
+        #
+        #   @return [Array<Float>]
+        required :query_vector, Turbopuffer::Internal::Type::ArrayOf[Float]
+
+        # @!method initialize(nearest_neighbors:, query_vector:)
+        #   @param nearest_neighbors [Array<Turbopuffer::Models::Row>] The true nearest neighbors with their distances and vectors.
+        #
+        #   @param query_vector [Array<Float>] The query vector used for this search.
+      end
     end
   end
 end

data/lib/turbopuffer/models/tokenizer.rb

@@ -2,13 +2,15 @@
 
 module Turbopuffer
   module Models
-    # The tokenizer to use for full-text search on an attribute.
+    # The tokenizer to use for full-text search on an attribute. Defaults to
+    # `word_v2`.
     module Tokenizer
       extend Turbopuffer::Internal::Type::Enum
 
       PRE_TOKENIZED_ARRAY = :pre_tokenized_array
       WORD_V0 = :word_v0
       WORD_V1 = :word_v1
+      WORD_V2 = :word_v2
 
       # @!method self.values
       #   @return [Array<Symbol>]

data/lib/turbopuffer/models.rb

@@ -39,6 +39,9 @@ module Turbopuffer
     mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
   end
 
+  # @type [Turbopuffer::Internal::Type::Converter]
+  AggregationGroup = Turbopuffer::Models::AggregationGroup
+
   AttributeSchema = Turbopuffer::Models::AttributeSchema
 
   AttributeSchemaConfig = Turbopuffer::Models::AttributeSchemaConfig

data/lib/turbopuffer/resources/namespaces.rb

@@ -213,12 +213,14 @@ module Turbopuffer
       #
       # Evaluate recall.
       #
-      # @overload recall(namespace: nil, filters: nil, num: nil, queries: nil, top_k: nil, request_options: {})
+      # @overload recall(namespace: nil, filters: nil, include_ground_truth: nil, num: nil, queries: nil, top_k: nil, request_options: {})
       #
       # @param namespace [String] Path param: The name of the namespace.
       #
       # @param filters [Object] Body param: Filter by attributes. Same syntax as the query endpoint.
       #
+      # @param include_ground_truth [Boolean] Body param: Include ground truth data (query vectors and true nearest neighbors)
+      #
       # @param num [Integer] Body param: The number of searches to run.
       #
       # @param queries [Array<Float>] Body param: Use specific query vectors for the measurement. If omitted, sampled

data/lib/turbopuffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Turbopuffer
-  VERSION = "0.2.6"
+  VERSION = "1.1.0"
 end

data/lib/turbopuffer.rb

@@ -51,6 +51,7 @@ require_relative "turbopuffer/internal/transport/base_client"
 require_relative "turbopuffer/internal/transport/pooled_net_requester"
 require_relative "turbopuffer/client"
 require_relative "turbopuffer/internal/namespace_page"
+require_relative "turbopuffer/models/aggregation_group"
 require_relative "turbopuffer/models/attribute_schema"
 require_relative "turbopuffer/models/attribute_schema_config"
 require_relative "turbopuffer/models/attribute_type"

data/rbi/turbopuffer/errors.rbi

@@ -59,10 +59,10 @@ module Turbopuffer
     end
 
     class APIConnectionError < Turbopuffer::Errors::APIError
-      sig { void }
+      sig { returns(NilClass) }
       attr_accessor :status
 
-      sig { void }
+      sig { returns(NilClass) }
       attr_accessor :body
 
       # @api private

data/rbi/turbopuffer/models/aggregation_group.rbi

@@ -0,0 +1,13 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    AggregationGroup =
+      T.let(
+        Turbopuffer::Internal::Type::HashOf[
+          Turbopuffer::Internal::Type::Unknown
+        ],
+        Turbopuffer::Internal::Type::Converter
+      )
+  end
+end

data/rbi/turbopuffer/models/full_text_search_config.rbi

@@ -65,7 +65,8 @@ module Turbopuffer
       sig { params(stemming: T::Boolean).void }
       attr_writer :stemming
 
-      # The tokenizer to use for full-text search on an attribute.
+      # The tokenizer to use for full-text search on an attribute. Defaults to
+      # `word_v2`.
       sig { returns(T.nilable(Turbopuffer::Tokenizer::OrSymbol)) }
       attr_reader :tokenizer
 
@@ -105,7 +106,8 @@ module Turbopuffer
         # Language-specific stemming for the text. Defaults to `false` (i.e., do not
         # stem).
         stemming: nil,
-        # The tokenizer to use for full-text search on an attribute.
+        # The tokenizer to use for full-text search on an attribute. Defaults to
+        # `word_v2`.
         tokenizer: nil
       )
       end

data/rbi/turbopuffer/models/namespace_multi_query_response.rbi

@@ -74,11 +74,11 @@ module Turbopuffer
             )
           end
 
-        sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
+        sig { returns(T.nilable(T::Array[T::Hash[Symbol, T.anything]])) }
         attr_reader :aggregation_groups
 
         sig do
-          params(aggregation_groups: T::Array[Turbopuffer::Row::OrHash]).void
+          params(aggregation_groups: T::Array[T::Hash[Symbol, T.anything]]).void
         end
         attr_writer :aggregation_groups
 
@@ -96,7 +96,7 @@ module Turbopuffer
 
         sig do
           params(
-            aggregation_groups: T::Array[Turbopuffer::Row::OrHash],
+            aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
             aggregations: T::Hash[Symbol, T.anything],
             rows: T::Array[Turbopuffer::Row::OrHash]
           ).returns(T.attached_class)
@@ -107,7 +107,7 @@ module Turbopuffer
         sig do
           override.returns(
             {
-              aggregation_groups: T::Array[Turbopuffer::Row],
+              aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
               aggregations: T::Hash[Symbol, T.anything],
               rows: T::Array[Turbopuffer::Row]
             }

data/rbi/turbopuffer/models/namespace_query_response.rbi

@@ -25,11 +25,11 @@ module Turbopuffer
       sig { params(performance: Turbopuffer::QueryPerformance::OrHash).void }
       attr_writer :performance
 
-      sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
+      sig { returns(T.nilable(T::Array[T::Hash[Symbol, T.anything]])) }
       attr_reader :aggregation_groups
 
       sig do
-        params(aggregation_groups: T::Array[Turbopuffer::Row::OrHash]).void
+        params(aggregation_groups: T::Array[T::Hash[Symbol, T.anything]]).void
       end
       attr_writer :aggregation_groups
 
@@ -50,7 +50,7 @@ module Turbopuffer
         params(
           billing: Turbopuffer::QueryBilling::OrHash,
           performance: Turbopuffer::QueryPerformance::OrHash,
-          aggregation_groups: T::Array[Turbopuffer::Row::OrHash],
+          aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
           aggregations: T::Hash[Symbol, T.anything],
           rows: T::Array[Turbopuffer::Row::OrHash]
         ).returns(T.attached_class)
@@ -71,7 +71,7 @@ module Turbopuffer
           {
             billing: Turbopuffer::QueryBilling,
             performance: Turbopuffer::QueryPerformance,
-            aggregation_groups: T::Array[Turbopuffer::Row],
+            aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
             aggregations: T::Hash[Symbol, T.anything],
             rows: T::Array[Turbopuffer::Row]
           }

data/rbi/turbopuffer/models/namespace_recall_params.rbi

@@ -27,6 +27,14 @@ module Turbopuffer
       sig { params(filters: T.anything).void }
       attr_writer :filters
 
+      # Include ground truth data (query vectors and true nearest neighbors) in the
+      # response.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :include_ground_truth
+
+      sig { params(include_ground_truth: T::Boolean).void }
+      attr_writer :include_ground_truth
+
       # The number of searches to run.
       sig { returns(T.nilable(Integer)) }
       attr_reader :num
@@ -53,6 +61,7 @@ module Turbopuffer
         params(
           namespace: String,
           filters: T.anything,
+          include_ground_truth: T::Boolean,
           num: Integer,
           queries: T::Array[Float],
           top_k: Integer,
@@ -63,6 +72,9 @@ module Turbopuffer
         namespace: nil,
         # Filter by attributes. Same syntax as the query endpoint.
         filters: nil,
+        # Include ground truth data (query vectors and true nearest neighbors) in the
+        # response.
+        include_ground_truth: nil,
         # The number of searches to run.
         num: nil,
         # Use specific query vectors for the measurement. If omitted, sampled from the
@@ -79,6 +91,7 @@ module Turbopuffer
           {
             namespace: String,
             filters: T.anything,
+            include_ground_truth: T::Boolean,
             num: Integer,
             queries: T::Array[Float],
             top_k: Integer,

data/rbi/turbopuffer/models/namespace_recall_response.rbi

@@ -24,12 +24,37 @@ module Turbopuffer
       sig { returns(Float) }
       attr_accessor :avg_recall
 
+      # Ground truth data including query vectors and true nearest neighbors. Only
+      # included when include_ground_truth is true.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
+          )
+        )
+      end
+      attr_reader :ground_truth
+
+      sig do
+        params(
+          ground_truth:
+            T::Array[
+              Turbopuffer::Models::NamespaceRecallResponse::GroundTruth::OrHash
+            ]
+        ).void
+      end
+      attr_writer :ground_truth
+
       # The response to a successful cache warm request.
       sig do
         params(
           avg_ann_count: Float,
           avg_exhaustive_count: Float,
-          avg_recall: Float
+          avg_recall: Float,
+          ground_truth:
+            T::Array[
+              Turbopuffer::Models::NamespaceRecallResponse::GroundTruth::OrHash
+            ]
         ).returns(T.attached_class)
       end
       def self.new(
@@ -39,7 +64,10 @@ module Turbopuffer
         # The average number of documents retrieved by the exhaustive searches.
         avg_exhaustive_count:,
         # The average recall of the queries.
-        avg_recall:
+        avg_recall:,
+        # Ground truth data including query vectors and true nearest neighbors. Only
+        # included when include_ground_truth is true.
+        ground_truth: nil
       )
       end
 
@@ -48,12 +76,59 @@ module Turbopuffer
           {
             avg_ann_count: Float,
             avg_exhaustive_count: Float,
-            avg_recall: Float
+            avg_recall: Float,
+            ground_truth:
+              T::Array[
+                Turbopuffer::Models::NamespaceRecallResponse::GroundTruth
+              ]
           }
         )
       end
       def to_hash
       end
+
+      class GroundTruth < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::Models::NamespaceRecallResponse::GroundTruth,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The true nearest neighbors with their distances and vectors.
+        sig { returns(T::Array[Turbopuffer::Row]) }
+        attr_accessor :nearest_neighbors
+
+        # The query vector used for this search.
+        sig { returns(T::Array[Float]) }
+        attr_accessor :query_vector
+
+        sig do
+          params(
+            nearest_neighbors: T::Array[Turbopuffer::Row::OrHash],
+            query_vector: T::Array[Float]
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The true nearest neighbors with their distances and vectors.
+          nearest_neighbors:,
+          # The query vector used for this search.
+          query_vector:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              nearest_neighbors: T::Array[Turbopuffer::Row],
+              query_vector: T::Array[Float]
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/turbopuffer/models/tokenizer.rbi

@@ -2,7 +2,8 @@
 
 module Turbopuffer
   module Models
-    # The tokenizer to use for full-text search on an attribute.
+    # The tokenizer to use for full-text search on an attribute. Defaults to
+    # `word_v2`.
     module Tokenizer
       extend Turbopuffer::Internal::Type::Enum
 
@@ -13,6 +14,7 @@ module Turbopuffer
         T.let(:pre_tokenized_array, Turbopuffer::Tokenizer::TaggedSymbol)
       WORD_V0 = T.let(:word_v0, Turbopuffer::Tokenizer::TaggedSymbol)
       WORD_V1 = T.let(:word_v1, Turbopuffer::Tokenizer::TaggedSymbol)
+      WORD_V2 = T.let(:word_v2, Turbopuffer::Tokenizer::TaggedSymbol)
 
       sig { override.returns(T::Array[Turbopuffer::Tokenizer::TaggedSymbol]) }
       def self.values

data/rbi/turbopuffer/models.rbi

@@ -1,6 +1,12 @@
 # typed: strong
 
 module Turbopuffer
+  AggregationGroup =
+    T.let(
+      Turbopuffer::Models::AggregationGroup,
+      Turbopuffer::Internal::Type::Converter
+    )
+
   AttributeSchema = Turbopuffer::Models::AttributeSchema
 
   AttributeSchemaConfig = Turbopuffer::Models::AttributeSchemaConfig

data/rbi/turbopuffer/resources/namespaces.rbi

@@ -171,6 +171,7 @@ module Turbopuffer
         params(
           namespace: T.nilable(String),
           filters: T.anything,
+          include_ground_truth: T::Boolean,
           num: Integer,
           queries: T::Array[Float],
           top_k: Integer,
@@ -182,6 +183,9 @@ module Turbopuffer
         namespace: nil,
         # Body param: Filter by attributes. Same syntax as the query endpoint.
         filters: nil,
+        # Body param: Include ground truth data (query vectors and true nearest neighbors)
+        # in the response.
+        include_ground_truth: nil,
         # Body param: The number of searches to run.
         num: nil,
         # Body param: Use specific query vectors for the measurement. If omitted, sampled

data/sig/turbopuffer/models/aggregation_group.rbs

@@ -0,0 +1,7 @@
+module Turbopuffer
+  module Models
+    type aggregation_group = ::Hash[Symbol, top]
+
+    AggregationGroup: Turbopuffer::Internal::Type::Converter
+  end
+end

data/sig/turbopuffer/models/namespace_multi_query_response.rbs

@@ -28,17 +28,17 @@ module Turbopuffer
 
       type result =
         {
-          aggregation_groups: ::Array[Turbopuffer::Row],
+          aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
           aggregations: ::Hash[Symbol, top],
           rows: ::Array[Turbopuffer::Row]
         }
 
       class Result < Turbopuffer::Internal::Type::BaseModel
-        attr_reader aggregation_groups: ::Array[Turbopuffer::Row]?
+        attr_reader aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group]?
 
         def aggregation_groups=: (
-          ::Array[Turbopuffer::Row]
-        ) -> ::Array[Turbopuffer::Row]
+          ::Array[Turbopuffer::Models::aggregation_group]
+        ) -> ::Array[Turbopuffer::Models::aggregation_group]
 
         attr_reader aggregations: ::Hash[Symbol, top]?
 
@@ -49,13 +49,13 @@ module Turbopuffer
         def rows=: (::Array[Turbopuffer::Row]) -> ::Array[Turbopuffer::Row]
 
         def initialize: (
-          ?aggregation_groups: ::Array[Turbopuffer::Row],
+          ?aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
           ?aggregations: ::Hash[Symbol, top],
           ?rows: ::Array[Turbopuffer::Row]
         ) -> void
 
         def to_hash: -> {
-          aggregation_groups: ::Array[Turbopuffer::Row],
+          aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
           aggregations: ::Hash[Symbol, top],
           rows: ::Array[Turbopuffer::Row]
         }

data/sig/turbopuffer/models/namespace_query_response.rbs

@@ -4,7 +4,7 @@ module Turbopuffer
       {
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
-        aggregation_groups: ::Array[Turbopuffer::Row],
+        aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
         aggregations: ::Hash[Symbol, top],
         rows: ::Array[Turbopuffer::Row]
       }
@@ -14,11 +14,11 @@ module Turbopuffer
 
       attr_accessor performance: Turbopuffer::QueryPerformance
 
-      attr_reader aggregation_groups: ::Array[Turbopuffer::Row]?
+      attr_reader aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group]?
 
       def aggregation_groups=: (
-        ::Array[Turbopuffer::Row]
-      ) -> ::Array[Turbopuffer::Row]
+        ::Array[Turbopuffer::Models::aggregation_group]
+      ) -> ::Array[Turbopuffer::Models::aggregation_group]
 
       attr_reader aggregations: ::Hash[Symbol, top]?
 
@@ -31,7 +31,7 @@ module Turbopuffer
       def initialize: (
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
-        ?aggregation_groups: ::Array[Turbopuffer::Row],
+        ?aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
         ?aggregations: ::Hash[Symbol, top],
         ?rows: ::Array[Turbopuffer::Row]
       ) -> void
@@ -39,7 +39,7 @@ module Turbopuffer
       def to_hash: -> {
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
-        aggregation_groups: ::Array[Turbopuffer::Row],
+        aggregation_groups: ::Array[Turbopuffer::Models::aggregation_group],
         aggregations: ::Hash[Symbol, top],
         rows: ::Array[Turbopuffer::Row]
       }

data/sig/turbopuffer/models/namespace_recall_params.rbs

@@ -4,6 +4,7 @@ module Turbopuffer
       {
         namespace: String,
         filters: top,
+        include_ground_truth: bool,
         num: Integer,
         queries: ::Array[Float],
         top_k: Integer
@@ -22,6 +23,10 @@ module Turbopuffer
 
       def filters=: (top) -> top
 
+      attr_reader include_ground_truth: bool?
+
+      def include_ground_truth=: (bool) -> bool
+
       attr_reader num: Integer?
 
       def num=: (Integer) -> Integer
@@ -37,6 +42,7 @@ module Turbopuffer
       def initialize: (
         ?namespace: String,
         ?filters: top,
+        ?include_ground_truth: bool,
         ?num: Integer,
         ?queries: ::Array[Float],
         ?top_k: Integer,
@@ -46,6 +52,7 @@ module Turbopuffer
       def to_hash: -> {
         namespace: String,
         filters: top,
+        include_ground_truth: bool,
         num: Integer,
         queries: ::Array[Float],
         top_k: Integer,

data/sig/turbopuffer/models/namespace_recall_response.rbs

@@ -1,7 +1,12 @@
 module Turbopuffer
   module Models
     type namespace_recall_response =
-      { avg_ann_count: Float, avg_exhaustive_count: Float, avg_recall: Float }
+      {
+        avg_ann_count: Float,
+        avg_exhaustive_count: Float,
+        avg_recall: Float,
+        ground_truth: ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
+      }
 
     class NamespaceRecallResponse < Turbopuffer::Internal::Type::BaseModel
       attr_accessor avg_ann_count: Float
@@ -10,17 +15,47 @@ module Turbopuffer
 
       attr_accessor avg_recall: Float
 
+      attr_reader ground_truth: ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]?
+
+      def ground_truth=: (
+        ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
+      ) -> ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
+
       def initialize: (
         avg_ann_count: Float,
         avg_exhaustive_count: Float,
-        avg_recall: Float
+        avg_recall: Float,
+        ?ground_truth: ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
       ) -> void
 
       def to_hash: -> {
         avg_ann_count: Float,
         avg_exhaustive_count: Float,
-        avg_recall: Float
+        avg_recall: Float,
+        ground_truth: ::Array[Turbopuffer::Models::NamespaceRecallResponse::GroundTruth]
       }
+
+      type ground_truth =
+        {
+          nearest_neighbors: ::Array[Turbopuffer::Row],
+          query_vector: ::Array[Float]
+        }
+
+      class GroundTruth < Turbopuffer::Internal::Type::BaseModel
+        attr_accessor nearest_neighbors: ::Array[Turbopuffer::Row]
+
+        attr_accessor query_vector: ::Array[Float]
+
+        def initialize: (
+          nearest_neighbors: ::Array[Turbopuffer::Row],
+          query_vector: ::Array[Float]
+        ) -> void
+
+        def to_hash: -> {
+          nearest_neighbors: ::Array[Turbopuffer::Row],
+          query_vector: ::Array[Float]
+        }
+      end
     end
   end
 end

data/sig/turbopuffer/models/tokenizer.rbs

@@ -1,6 +1,6 @@
 module Turbopuffer
   module Models
-    type tokenizer = :pre_tokenized_array | :word_v0 | :word_v1
+    type tokenizer = :pre_tokenized_array | :word_v0 | :word_v1 | :word_v2
 
     module Tokenizer
       extend Turbopuffer::Internal::Type::Enum
@@ -8,6 +8,7 @@ module Turbopuffer
       PRE_TOKENIZED_ARRAY: :pre_tokenized_array
       WORD_V0: :word_v0
       WORD_V1: :word_v1
+      WORD_V2: :word_v2
 
       def self?.values: -> ::Array[Turbopuffer::Models::tokenizer]
     end

data/sig/turbopuffer/models.rbs

@@ -1,4 +1,6 @@
 module Turbopuffer
+  AggregationGroup: Turbopuffer::Internal::Type::Converter
+
   module AttributeSchema = Turbopuffer::Models::AttributeSchema
 
   class AttributeSchemaConfig = Turbopuffer::Models::AttributeSchemaConfig

data/sig/turbopuffer/resources/namespaces.rbs

@@ -57,6 +57,7 @@ module Turbopuffer
       def recall: (
         ?namespace: String,
         ?filters: top,
+        ?include_ground_truth: bool,
         ?num: Integer,
         ?queries: ::Array[Float],
         ?top_k: Integer,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbopuffer-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 1.1.0
 platform: ruby
 authors:
 - Turbopuffer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-18 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -56,6 +56,7 @@ files:
 - lib/turbopuffer/internal/type/unknown.rb
 - lib/turbopuffer/internal/util.rb
 - lib/turbopuffer/models.rb
+- lib/turbopuffer/models/aggregation_group.rb
 - lib/turbopuffer/models/attribute_schema.rb
 - lib/turbopuffer/models/attribute_schema_config.rb
 - lib/turbopuffer/models/attribute_type.rb
@@ -121,6 +122,7 @@ files:
 - rbi/turbopuffer/internal/type/unknown.rbi
 - rbi/turbopuffer/internal/util.rbi
 - rbi/turbopuffer/models.rbi
+- rbi/turbopuffer/models/aggregation_group.rbi
 - rbi/turbopuffer/models/attribute_schema.rbi
 - rbi/turbopuffer/models/attribute_schema_config.rbi
 - rbi/turbopuffer/models/attribute_type.rbi
@@ -185,6 +187,7 @@ files:
 - sig/turbopuffer/internal/type/unknown.rbs
 - sig/turbopuffer/internal/util.rbs
 - sig/turbopuffer/models.rbs
+- sig/turbopuffer/models/aggregation_group.rbs
 - sig/turbopuffer/models/attribute_schema.rbs
 - sig/turbopuffer/models/attribute_schema_config.rbs
 - sig/turbopuffer/models/attribute_type.rbs