turbopuffer 0.1.0 → 1.2.0

data/rbi/turbopuffer/models/query_performance.rbi

@@ -0,0 +1,82 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class QueryPerformance < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::QueryPerformance, Turbopuffer::Internal::AnyHash)
+        end
+
+      # the approximate number of documents in the namespace.
+      sig { returns(Integer) }
+      attr_accessor :approx_namespace_size
+
+      # The ratio of cache hits to total cache lookups.
+      sig { returns(Float) }
+      attr_accessor :cache_hit_ratio
+
+      # A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
+      sig { returns(String) }
+      attr_accessor :cache_temperature
+
+      # The number of unindexed documents processed by the query.
+      sig { returns(Integer) }
+      attr_accessor :exhaustive_search_count
+
+      # Request time measured on the server, excluding time spent waiting due to the
+      # namespace concurrency limit.
+      sig { returns(Integer) }
+      attr_accessor :query_execution_ms
+
+      # Request time measured on the server, including time spent waiting for other
+      # queries to complete if the namespace was at its concurrency limit.
+      sig { returns(Integer) }
+      attr_accessor :server_total_ms
+
+      # The performance information for a query.
+      sig do
+        params(
+          approx_namespace_size: Integer,
+          cache_hit_ratio: Float,
+          cache_temperature: String,
+          exhaustive_search_count: Integer,
+          query_execution_ms: Integer,
+          server_total_ms: Integer
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # the approximate number of documents in the namespace.
+        approx_namespace_size:,
+        # The ratio of cache hits to total cache lookups.
+        cache_hit_ratio:,
+        # A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
+        cache_temperature:,
+        # The number of unindexed documents processed by the query.
+        exhaustive_search_count:,
+        # Request time measured on the server, excluding time spent waiting due to the
+        # namespace concurrency limit.
+        query_execution_ms:,
+        # Request time measured on the server, including time spent waiting for other
+        # queries to complete if the namespace was at its concurrency limit.
+        server_total_ms:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            approx_namespace_size: Integer,
+            cache_hit_ratio: Float,
+            cache_temperature: String,
+            exhaustive_search_count: Integer,
+            query_execution_ms: Integer,
+            server_total_ms: Integer
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/row.rbi

@@ -0,0 +1,47 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class Row < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Turbopuffer::Row, Turbopuffer::Internal::AnyHash) }
+
+      # An identifier for a document.
+      sig { returns(Turbopuffer::ID::Variants) }
+      attr_accessor :id
+
+      # A vector embedding associated with a document.
+      sig { returns(T.nilable(Turbopuffer::Vector::Variants)) }
+      attr_reader :vector
+
+      sig { params(vector: Turbopuffer::Vector::Variants).void }
+      attr_writer :vector
+
+      # A single document, in a row-based format.
+      sig do
+        params(
+          id: Turbopuffer::ID::Variants,
+          vector: Turbopuffer::Vector::Variants
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # An identifier for a document.
+        id:,
+        # A vector embedding associated with a document.
+        vector: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: Turbopuffer::ID::Variants,
+            vector: Turbopuffer::Vector::Variants
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/tokenizer.rbi

@@ -0,0 +1,24 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # The tokenizer to use for full-text search on an attribute. Defaults to
+    # `word_v2`.
+    module Tokenizer
+      extend Turbopuffer::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Turbopuffer::Tokenizer) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      PRE_TOKENIZED_ARRAY =
+        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
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/vector.rbi

@@ -0,0 +1,22 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # A vector embedding associated with a document.
+    module Vector
+      extend Turbopuffer::Internal::Type::Union
+
+      Variants = T.type_alias { T.any(T::Array[Float], String) }
+
+      sig { override.returns(T::Array[Turbopuffer::Vector::Variants]) }
+      def self.variants
+      end
+
+      FloatArray =
+        T.let(
+          Turbopuffer::Internal::Type::ArrayOf[Float],
+          Turbopuffer::Internal::Type::Converter
+        )
+    end
+  end
+end

data/rbi/turbopuffer/models/vector_encoding.rbi

@@ -0,0 +1,22 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # The encoding to use for vectors in the response.
+    module VectorEncoding
+      extend Turbopuffer::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Turbopuffer::VectorEncoding) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      FLOAT = T.let(:float, Turbopuffer::VectorEncoding::TaggedSymbol)
+      BASE64 = T.let(:base64, Turbopuffer::VectorEncoding::TaggedSymbol)
+
+      sig do
+        override.returns(T::Array[Turbopuffer::VectorEncoding::TaggedSymbol])
+      end
+      def self.values
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/write_billing.rbi

@@ -0,0 +1,49 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class WriteBilling < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::WriteBilling, Turbopuffer::Internal::AnyHash)
+        end
+
+      # The number of billable logical bytes written to the namespace.
+      sig { returns(Integer) }
+      attr_accessor :billable_logical_bytes_written
+
+      # The billing information for a query.
+      sig { returns(T.nilable(Turbopuffer::QueryBilling)) }
+      attr_reader :query
+
+      sig { params(query: Turbopuffer::QueryBilling::OrHash).void }
+      attr_writer :query
+
+      # The billing information for a write request.
+      sig do
+        params(
+          billable_logical_bytes_written: Integer,
+          query: Turbopuffer::QueryBilling::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The number of billable logical bytes written to the namespace.
+        billable_logical_bytes_written:,
+        # The billing information for a query.
+        query: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            billable_logical_bytes_written: Integer,
+            query: Turbopuffer::QueryBilling
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models.rbi

@@ -0,0 +1,72 @@
+# typed: strong
+
+module Turbopuffer
+  AggregationGroup =
+    T.let(
+      Turbopuffer::Models::AggregationGroup,
+      Turbopuffer::Internal::Type::Converter
+    )
+
+  AttributeSchema = Turbopuffer::Models::AttributeSchema
+
+  AttributeSchemaConfig = Turbopuffer::Models::AttributeSchemaConfig
+
+  AttributeType = Turbopuffer::Models::AttributeType
+
+  ClientNamespacesParams = Turbopuffer::Models::ClientNamespacesParams
+
+  Columns = Turbopuffer::Models::Columns
+
+  DistanceMetric = Turbopuffer::Models::DistanceMetric
+
+  FullTextSearch = Turbopuffer::Models::FullTextSearch
+
+  FullTextSearchConfig = Turbopuffer::Models::FullTextSearchConfig
+
+  ID = Turbopuffer::Models::ID
+
+  IncludeAttributes = Turbopuffer::Models::IncludeAttributes
+
+  Language = Turbopuffer::Models::Language
+
+  NamespaceDeleteAllParams = Turbopuffer::Models::NamespaceDeleteAllParams
+
+  NamespaceExplainQueryParams = Turbopuffer::Models::NamespaceExplainQueryParams
+
+  NamespaceHintCacheWarmParams =
+    Turbopuffer::Models::NamespaceHintCacheWarmParams
+
+  NamespaceMetadata = Turbopuffer::Models::NamespaceMetadata
+
+  NamespaceMetadataParams = Turbopuffer::Models::NamespaceMetadataParams
+
+  NamespaceMultiQueryParams = Turbopuffer::Models::NamespaceMultiQueryParams
+
+  NamespaceQueryParams = Turbopuffer::Models::NamespaceQueryParams
+
+  NamespaceRecallParams = Turbopuffer::Models::NamespaceRecallParams
+
+  NamespaceSchemaParams = Turbopuffer::Models::NamespaceSchemaParams
+
+  NamespaceSummary = Turbopuffer::Models::NamespaceSummary
+
+  NamespaceUpdateSchemaParams = Turbopuffer::Models::NamespaceUpdateSchemaParams
+
+  NamespaceWriteParams = Turbopuffer::Models::NamespaceWriteParams
+
+  Query = Turbopuffer::Models::Query
+
+  QueryBilling = Turbopuffer::Models::QueryBilling
+
+  QueryPerformance = Turbopuffer::Models::QueryPerformance
+
+  Row = Turbopuffer::Models::Row
+
+  Tokenizer = Turbopuffer::Models::Tokenizer
+
+  Vector = Turbopuffer::Models::Vector
+
+  VectorEncoding = Turbopuffer::Models::VectorEncoding
+
+  WriteBilling = Turbopuffer::Models::WriteBilling
+end

data/rbi/turbopuffer/namespace.rbi

@@ -0,0 +1,8 @@
+# typed: strong
+
+module Turbopuffer
+  class Namespace < Turbopuffer::Resources::Namespaces
+    sig { returns(String) }
+    attr_reader :id
+  end
+end

data/rbi/turbopuffer/request_options.rbi

@@ -0,0 +1,59 @@
+# typed: strong
+
+module Turbopuffer
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  # or override those provided at the client level.
+  #
+  # When making a request, you can pass an actual {RequestOptions} instance, or
+  # simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < Turbopuffer::Internal::Type::BaseModel
+    OrHash =
+      T.type_alias do
+        T.any(Turbopuffer::RequestOptions, Turbopuffer::Internal::AnyHash)
+      end
+
+    # @api private
+    sig { params(opts: Turbopuffer::RequestOptions::OrHash).void }
+    def self.validate!(opts)
+    end
+
+    # Idempotency key to send with request and all associated retries. Will only be
+    # sent for write requests.
+    sig { returns(T.nilable(String)) }
+    attr_accessor :idempotency_key
+
+    # Extra query params to send with the request. These are `.merge`’d into any
+    # `query` given at the client level.
+    sig do
+      returns(
+        T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))])
+      )
+    end
+    attr_accessor :extra_query
+
+    # Extra headers to send with the request. These are `.merged`’d into any
+    # `extra_headers` given at the client level.
+    sig { returns(T.nilable(T::Hash[String, T.nilable(String)])) }
+    attr_accessor :extra_headers
+
+    # Extra data to send with the request. These are deep merged into any data
+    # generated as part of the normal request.
+    sig { returns(T.nilable(T.anything)) }
+    attr_accessor :extra_body
+
+    # Maximum number of retries to attempt after a failed initial request.
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :max_retries
+
+    # Request timeout in seconds.
+    sig { returns(T.nilable(Float)) }
+    attr_accessor :timeout
+
+    # Returns a new instance of RequestOptions.
+    sig do
+      params(values: Turbopuffer::Internal::AnyHash).returns(T.attached_class)
+    end
+    def self.new(values = {})
+    end
+  end
+end

data/rbi/turbopuffer/resources/namespaces.rbi

@@ -0,0 +1,304 @@
+# typed: strong
+
+module Turbopuffer
+  module Resources
+    class Namespaces
+      # Delete namespace.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceDeleteAllResponse)
+      end
+      def delete_all(
+        # The name of the namespace.
+        namespace: nil,
+        request_options: {}
+      )
+      end
+
+      # Explain a query plan.
+      sig do
+        params(
+          namespace: String,
+          aggregate_by: T::Hash[Symbol, T.anything],
+          consistency:
+            Turbopuffer::NamespaceExplainQueryParams::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(Turbopuffer::Models::NamespaceExplainQueryResponse)
+      end
+      def explain_query(
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: Aggregations to compute over all documents in the namespace that
+        # match the filters.
+        aggregate_by: nil,
+        # Body param: The consistency level for a query.
+        consistency: nil,
+        # Body param: A function used to calculate vector similarity.
+        distance_metric: nil,
+        # Body param: List of attribute names to exclude from the response. All other
+        # attributes will be included in the response.
+        exclude_attributes: nil,
+        # Body param: Exact filters for attributes to refine search results for. Think of
+        # it as a SQL WHERE clause.
+        filters: nil,
+        # Body param: Groups documents by the specified attributes (the "group key")
+        # before computing aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
+        # Body param: Whether to include attributes in the response.
+        include_attributes: nil,
+        # Body param: How to rank the documents in the namespace.
+        rank_by: nil,
+        # Body param: The number of results to return.
+        top_k: nil,
+        # Body param: The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
+      # Warm the cache for a namespace.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceHintCacheWarmResponse)
+      end
+      def hint_cache_warm(
+        # The name of the namespace.
+        namespace: nil,
+        request_options: {}
+      )
+      end
+
+      # Get metadata about a namespace.
+      sig do
+        params(
+          namespace: String,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::NamespaceMetadata)
+      end
+      def metadata(
+        # The name of the namespace.
+        namespace: nil,
+        request_options: {}
+      )
+      end
+
+      # Issue multiple concurrent queries filter or search documents.
+      sig do
+        params(
+          queries: T::Array[Turbopuffer::Query::OrHash],
+          namespace: String,
+          consistency:
+            Turbopuffer::NamespaceMultiQueryParams::Consistency::OrHash,
+          vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceMultiQueryResponse)
+      end
+      def multi_query(
+        # Body param:
+        queries:,
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: The consistency level for a query.
+        consistency: nil,
+        # Body param: The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
+      # Query, filter, full-text search and vector search documents.
+      sig do
+        params(
+          namespace: T.nilable(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(Turbopuffer::Models::NamespaceQueryResponse)
+      end
+      def query(
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: Aggregations to compute over all documents in the namespace that
+        # match the filters.
+        aggregate_by: nil,
+        # Body param: The consistency level for a query.
+        consistency: nil,
+        # Body param: A function used to calculate vector similarity.
+        distance_metric: nil,
+        # Body param: List of attribute names to exclude from the response. All other
+        # attributes will be included in the response.
+        exclude_attributes: nil,
+        # Body param: Exact filters for attributes to refine search results for. Think of
+        # it as a SQL WHERE clause.
+        filters: nil,
+        # Body param: Groups documents by the specified attributes (the "group key")
+        # before computing aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
+        # Body param: Whether to include attributes in the response.
+        include_attributes: nil,
+        # Body param: How to rank the documents in the namespace.
+        rank_by: nil,
+        # Body param: The number of results to return.
+        top_k: nil,
+        # Body param: The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
+      # Evaluate recall.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          filters: T.anything,
+          include_ground_truth: T::Boolean,
+          num: Integer,
+          queries: T::Array[Float],
+          top_k: Integer,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceRecallResponse)
+      end
+      def recall(
+        # Path param: The name of the namespace.
+        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
+        # from the index.
+        queries: nil,
+        # Body param: Search for `top_k` nearest neighbors.
+        top_k: nil,
+        request_options: {}
+      )
+      end
+
+      # Get namespace schema.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig])
+      end
+      def schema(
+        # The name of the namespace.
+        namespace: nil,
+        request_options: {}
+      )
+      end
+
+      # Update namespace schema.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          schema:
+            T::Hash[
+              Symbol,
+              T.any(String, Turbopuffer::AttributeSchemaConfig::OrHash)
+            ],
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig])
+      end
+      def update_schema(
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: The desired schema for the namespace.
+        schema: nil,
+        request_options: {}
+      )
+      end
+
+      # Create, update, or delete documents.
+      sig do
+        params(
+          namespace: T.nilable(String),
+          copy_from_namespace: String,
+          delete_by_filter: T.anything,
+          delete_condition: T.anything,
+          deletes: T::Array[Turbopuffer::ID::Variants],
+          distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+          encryption: Turbopuffer::NamespaceWriteParams::Encryption::OrHash,
+          patch_columns: Turbopuffer::Columns::OrHash,
+          patch_condition: T.anything,
+          patch_rows: T::Array[Turbopuffer::Row::OrHash],
+          schema:
+            T::Hash[
+              Symbol,
+              T.any(String, Turbopuffer::AttributeSchemaConfig::OrHash)
+            ],
+          upsert_columns: Turbopuffer::Columns::OrHash,
+          upsert_condition: T.anything,
+          upsert_rows: T::Array[Turbopuffer::Row::OrHash],
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceWriteResponse)
+      end
+      def write(
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: The namespace to copy documents from.
+        copy_from_namespace: nil,
+        # Body param: The filter specifying which documents to delete.
+        delete_by_filter: nil,
+        # Body param: A condition evaluated against the current value of each document
+        # targeted by a delete write. Only documents that pass the condition are deleted.
+        delete_condition: nil,
+        # Body param:
+        deletes: nil,
+        # Body param: A function used to calculate vector similarity.
+        distance_metric: nil,
+        # Body param: The encryption configuration for a namespace.
+        encryption: nil,
+        # Body param: A list of documents in columnar format. Each key is a column name,
+        # mapped to an array of values for that column.
+        patch_columns: nil,
+        # Body param: A condition evaluated against the current value of each document
+        # targeted by a patch write. Only documents that pass the condition are patched.
+        patch_condition: nil,
+        # Body param:
+        patch_rows: nil,
+        # Body param: The schema of the attributes attached to the documents.
+        schema: nil,
+        # Body param: A list of documents in columnar format. Each key is a column name,
+        # mapped to an array of values for that column.
+        upsert_columns: nil,
+        # Body param: A condition evaluated against the current value of each document
+        # targeted by an upsert write. Only documents that pass the condition are
+        # upserted.
+        upsert_condition: nil,
+        # Body param:
+        upsert_rows: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Turbopuffer::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/turbopuffer/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module Turbopuffer
+  VERSION = T.let(T.unsafe(nil), String)
+end