turbopuffer 0.1.0 → 1.2.0

data/rbi/turbopuffer/models/namespace_query_params.rbi

@@ -0,0 +1,267 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceQueryParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespaceQueryParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      # Aggregations to compute over all documents in the namespace that match the
+      # filters.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :aggregate_by
+
+      sig { params(aggregate_by: T::Hash[Symbol, T.anything]).void }
+      attr_writer :aggregate_by
+
+      # The consistency level for a query.
+      sig { returns(T.nilable(Turbopuffer::NamespaceQueryParams::Consistency)) }
+      attr_reader :consistency
+
+      sig do
+        params(
+          consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash
+        ).void
+      end
+      attr_writer :consistency
+
+      # A function used to calculate vector similarity.
+      sig { returns(T.nilable(Turbopuffer::DistanceMetric::OrSymbol)) }
+      attr_reader :distance_metric
+
+      sig do
+        params(distance_metric: Turbopuffer::DistanceMetric::OrSymbol).void
+      end
+      attr_writer :distance_metric
+
+      # List of attribute names to exclude from the response. All other attributes will
+      # be included in the response.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :exclude_attributes
+
+      sig { params(exclude_attributes: T::Array[String]).void }
+      attr_writer :exclude_attributes
+
+      # Exact filters for attributes to refine search results for. Think of it as a SQL
+      # WHERE clause.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :filters
+
+      sig { params(filters: T.anything).void }
+      attr_writer :filters
+
+      # Groups documents by the specified attributes (the "group key") before computing
+      # aggregates. Aggregates are computed separately for each group.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :group_by
+
+      sig { params(group_by: T::Array[String]).void }
+      attr_writer :group_by
+
+      # Whether to include attributes in the response.
+      sig { returns(T.nilable(Turbopuffer::IncludeAttributes::Variants)) }
+      attr_reader :include_attributes
+
+      sig do
+        params(
+          include_attributes: Turbopuffer::IncludeAttributes::Variants
+        ).void
+      end
+      attr_writer :include_attributes
+
+      # How to rank the documents in the namespace.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :rank_by
+
+      sig { params(rank_by: T.anything).void }
+      attr_writer :rank_by
+
+      # The number of results to return.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :top_k
+
+      sig { params(top_k: Integer).void }
+      attr_writer :top_k
+
+      # The encoding to use for vectors in the response.
+      sig { returns(T.nilable(Turbopuffer::VectorEncoding::OrSymbol)) }
+      attr_reader :vector_encoding
+
+      sig do
+        params(vector_encoding: Turbopuffer::VectorEncoding::OrSymbol).void
+      end
+      attr_writer :vector_encoding
+
+      sig do
+        params(
+          namespace: String,
+          aggregate_by: T::Hash[Symbol, T.anything],
+          consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash,
+          distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+          exclude_attributes: T::Array[String],
+          filters: T.anything,
+          group_by: T::Array[String],
+          include_attributes: Turbopuffer::IncludeAttributes::Variants,
+          rank_by: T.anything,
+          top_k: Integer,
+          vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        namespace: nil,
+        # Aggregations to compute over all documents in the namespace that match the
+        # filters.
+        aggregate_by: nil,
+        # The consistency level for a query.
+        consistency: nil,
+        # A function used to calculate vector similarity.
+        distance_metric: nil,
+        # List of attribute names to exclude from the response. All other attributes will
+        # be included in the response.
+        exclude_attributes: nil,
+        # Exact filters for attributes to refine search results for. Think of it as a SQL
+        # WHERE clause.
+        filters: nil,
+        # Groups documents by the specified attributes (the "group key") before computing
+        # aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
+        # Whether to include attributes in the response.
+        include_attributes: nil,
+        # How to rank the documents in the namespace.
+        rank_by: nil,
+        # The number of results to return.
+        top_k: nil,
+        # The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            namespace: String,
+            aggregate_by: T::Hash[Symbol, T.anything],
+            consistency: Turbopuffer::NamespaceQueryParams::Consistency,
+            distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+            exclude_attributes: T::Array[String],
+            filters: T.anything,
+            group_by: T::Array[String],
+            include_attributes: Turbopuffer::IncludeAttributes::Variants,
+            rank_by: T.anything,
+            top_k: Integer,
+            vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+            request_options: Turbopuffer::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Consistency < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::NamespaceQueryParams::Consistency,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The query's consistency level.
+        sig do
+          returns(
+            T.nilable(
+              Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
+            )
+          )
+        end
+        attr_reader :level
+
+        sig do
+          params(
+            level:
+              Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
+          ).void
+        end
+        attr_writer :level
+
+        # The consistency level for a query.
+        sig do
+          params(
+            level:
+              Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The query's consistency level.
+          level: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              level:
+                Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The query's consistency level.
+        module Level
+          extend Turbopuffer::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Turbopuffer::NamespaceQueryParams::Consistency::Level
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+          STRONG =
+            T.let(
+              :strong,
+              Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
+            )
+
+          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+          EVENTUAL =
+            T.let(
+              :eventual,
+              Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_query_response.rbi

@@ -0,0 +1,84 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceQueryResponse < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::Models::NamespaceQueryResponse,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      # The billing information for a query.
+      sig { returns(Turbopuffer::QueryBilling) }
+      attr_reader :billing
+
+      sig { params(billing: Turbopuffer::QueryBilling::OrHash).void }
+      attr_writer :billing
+
+      # The performance information for a query.
+      sig { returns(Turbopuffer::QueryPerformance) }
+      attr_reader :performance
+
+      sig { params(performance: Turbopuffer::QueryPerformance::OrHash).void }
+      attr_writer :performance
+
+      sig { returns(T.nilable(T::Array[T::Hash[Symbol, T.anything]])) }
+      attr_reader :aggregation_groups
+
+      sig do
+        params(aggregation_groups: T::Array[T::Hash[Symbol, T.anything]]).void
+      end
+      attr_writer :aggregation_groups
+
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :aggregations
+
+      sig { params(aggregations: T::Hash[Symbol, T.anything]).void }
+      attr_writer :aggregations
+
+      sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
+      attr_reader :rows
+
+      sig { params(rows: T::Array[Turbopuffer::Row::OrHash]).void }
+      attr_writer :rows
+
+      # The result of a query.
+      sig do
+        params(
+          billing: Turbopuffer::QueryBilling::OrHash,
+          performance: Turbopuffer::QueryPerformance::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)
+      end
+      def self.new(
+        # The billing information for a query.
+        billing:,
+        # The performance information for a query.
+        performance:,
+        aggregation_groups: nil,
+        aggregations: nil,
+        rows: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            billing: Turbopuffer::QueryBilling,
+            performance: Turbopuffer::QueryPerformance,
+            aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
+            aggregations: T::Hash[Symbol, T.anything],
+            rows: T::Array[Turbopuffer::Row]
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_recall_params.rbi

@@ -0,0 +1,106 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceRecallParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespaceRecallParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      # Filter by attributes. Same syntax as the query endpoint.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :filters
+
+      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
+
+      sig { params(num: Integer).void }
+      attr_writer :num
+
+      # Use specific query vectors for the measurement. If omitted, sampled from the
+      # index.
+      sig { returns(T.nilable(T::Array[Float])) }
+      attr_reader :queries
+
+      sig { params(queries: T::Array[Float]).void }
+      attr_writer :queries
+
+      # Search for `top_k` nearest neighbors.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :top_k
+
+      sig { params(top_k: Integer).void }
+      attr_writer :top_k
+
+      sig do
+        params(
+          namespace: String,
+          filters: T.anything,
+          include_ground_truth: T::Boolean,
+          num: Integer,
+          queries: T::Array[Float],
+          top_k: Integer,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        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
+        # index.
+        queries: nil,
+        # Search for `top_k` nearest neighbors.
+        top_k: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            namespace: String,
+            filters: T.anything,
+            include_ground_truth: T::Boolean,
+            num: Integer,
+            queries: T::Array[Float],
+            top_k: Integer,
+            request_options: Turbopuffer::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_recall_response.rbi

@@ -0,0 +1,134 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceRecallResponse < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::Models::NamespaceRecallResponse,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      # The average number of documents retrieved by the approximate nearest neighbor
+      # searches.
+      sig { returns(Float) }
+      attr_accessor :avg_ann_count
+
+      # The average number of documents retrieved by the exhaustive searches.
+      sig { returns(Float) }
+      attr_accessor :avg_exhaustive_count
+
+      # The average recall of the queries.
+      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,
+          ground_truth:
+            T::Array[
+              Turbopuffer::Models::NamespaceRecallResponse::GroundTruth::OrHash
+            ]
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The average number of documents retrieved by the approximate nearest neighbor
+        # searches.
+        avg_ann_count:,
+        # The average number of documents retrieved by the exhaustive searches.
+        avg_exhaustive_count:,
+        # The average recall of the queries.
+        avg_recall:,
+        # Ground truth data including query vectors and true nearest neighbors. Only
+        # included when include_ground_truth is true.
+        ground_truth: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            avg_ann_count: Float,
+            avg_exhaustive_count: 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/namespace_schema_params.rbi

@@ -0,0 +1,41 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceSchemaParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespaceSchemaParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      sig do
+        params(
+          namespace: String,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(namespace: nil, request_options: {})
+      end
+
+      sig do
+        override.returns(
+          { namespace: String, request_options: Turbopuffer::RequestOptions }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_schema_response.rbi

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

data/rbi/turbopuffer/models/namespace_summary.rbi

@@ -0,0 +1,28 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceSummary < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::NamespaceSummary, Turbopuffer::Internal::AnyHash)
+        end
+
+      # The namespace ID.
+      sig { returns(String) }
+      attr_accessor :id
+
+      # A summary of a namespace.
+      sig { params(id: String).returns(T.attached_class) }
+      def self.new(
+        # The namespace ID.
+        id:
+      )
+      end
+
+      sig { override.returns({ id: String }) }
+      def to_hash
+      end
+    end
+  end
+end