turbopuffer 0.1.0 → 1.3.0

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

data/sig/turbopuffer/client.rbs

@@ -0,0 +1,41 @@
+module Turbopuffer
+  class Client < Turbopuffer::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 4
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String
+
+    attr_reader region: String?
+
+    attr_reader default_namespace: String?
+
+    def namespace: (
+      ?namespace: String
+    ) -> Turbopuffer::Namespace
+
+    def namespaces: (
+      ?cursor: String,
+      ?page_size: Integer,
+      ?prefix: String,
+      ?request_options: Turbopuffer::request_opts
+    ) -> Turbopuffer::Internal::NamespacePage[Turbopuffer::NamespaceSummary]
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?region: String?,
+      ?default_namespace: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/turbopuffer/errors.rbs

@@ -0,0 +1,117 @@
+module Turbopuffer
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < Turbopuffer::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < Turbopuffer::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < Turbopuffer::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < Turbopuffer::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < Turbopuffer::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < Turbopuffer::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/turbopuffer/file_part.rbs

@@ -0,0 +1,21 @@
+module Turbopuffer
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: String?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/turbopuffer/internal/namespace_page.rbs

@@ -0,0 +1,13 @@
+module Turbopuffer
+  module Internal
+    class NamespacePage[Elem]
+      include Turbopuffer::Internal::Type::BasePage[Elem]
+
+      attr_accessor namespaces: ::Array[Elem]?
+
+      attr_accessor next_cursor: String
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/turbopuffer/internal/transport/base_client.rbs

@@ -0,0 +1,131 @@
+module Turbopuffer
+  module Internal
+    module Transport
+      class BaseClient
+        extend Turbopuffer::Internal::Util::SorbetRuntimeSupport
+
+        type request_components =
+          {
+            method: Symbol,
+            path: String | ::Array[String],
+            query: ::Hash[String, (::Array[String] | String)?]?,
+            headers: ::Hash[String, (String
+            | Integer
+            | ::Array[(String | Integer)?])?]?,
+            body: top?,
+            unwrap: (Symbol
+            | Integer
+            | ::Array[(Symbol | Integer)]
+            | (^(top arg0) -> top))?,
+            page: Class?,
+            stream: Class?,
+            model: Turbopuffer::Internal::Type::Converter::input?,
+            options: Turbopuffer::request_opts?
+          }
+        type request_input =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            max_retries: Integer,
+            timeout: Float
+          }
+
+        MAX_REDIRECTS: 20
+
+        PLATFORM_HEADERS: ::Hash[String, String]
+
+        def self.validate!: (
+          Turbopuffer::Internal::Transport::BaseClient::request_components req
+        ) -> void
+
+        def self.should_retry?: (
+          Integer status,
+          headers: ::Hash[String, String]
+        ) -> bool
+
+        def self.follow_redirect: (
+          Turbopuffer::Internal::Transport::BaseClient::request_input request,
+          status: Integer,
+          response_headers: ::Hash[String, String]
+        ) -> Turbopuffer::Internal::Transport::BaseClient::request_input
+
+        def self.reap_connection!: (
+          Integer | Turbopuffer::Errors::APIConnectionError status,
+          stream: Enumerable[String]?
+        ) -> void
+
+        attr_reader base_url: URI::Generic
+
+        attr_reader timeout: Float
+
+        attr_reader max_retries: Integer
+
+        attr_reader initial_retry_delay: Float
+
+        attr_reader max_retry_delay: Float
+
+        attr_reader headers: ::Hash[String, String]
+
+        attr_reader idempotency_header: String?
+
+        # @api private
+        attr_reader requester: Turbopuffer::Internal::Transport::PooledNetRequester
+
+        def initialize: (
+          base_url: String,
+          ?timeout: Float,
+          ?max_retries: Integer,
+          ?initial_retry_delay: Float,
+          ?max_retry_delay: Float,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?],
+          ?idempotency_header: String?
+        ) -> void
+
+        private def auth_headers: -> ::Hash[String, String]
+
+        private def generate_idempotency_key: -> String
+
+        private def build_request: (
+          Turbopuffer::Internal::Transport::BaseClient::request_components req,
+          Turbopuffer::request_options opts
+        ) -> Turbopuffer::Internal::Transport::BaseClient::request_input
+
+        private def retry_delay: (
+          ::Hash[String, String] headers,
+          retry_count: Integer
+        ) -> Float
+
+        def send_request: (
+          Turbopuffer::Internal::Transport::BaseClient::request_input request,
+          redirect_count: Integer,
+          retry_count: Integer,
+          send_retry_header: bool
+        ) -> [Integer, top, Enumerable[String]]
+
+        def request: (
+          Symbol method,
+          String | ::Array[String] path,
+          ?query: ::Hash[String, (::Array[String] | String)?]?,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?]?,
+          ?body: top?,
+          ?unwrap: (Symbol
+          | Integer
+          | ::Array[(Symbol | Integer)]
+          | (^(top arg0) -> top))?,
+          ?page: Class?,
+          ?stream: Class?,
+          ?model: Turbopuffer::Internal::Type::Converter::input?,
+          ?options: Turbopuffer::request_opts?
+        ) -> top
+
+        def inspect: -> String
+      end
+    end
+  end
+end

data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs

@@ -0,0 +1,45 @@
+module Turbopuffer
+  module Internal
+    module Transport
+      class PooledNetRequester
+        extend Turbopuffer::Internal::Util::SorbetRuntimeSupport
+
+        type request =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            deadline: Float
+          }
+
+        KEEP_ALIVE_TIMEOUT: 30
+
+        DEFAULT_MAX_CONNECTIONS: Integer
+
+        def self.connect: (URI::Generic url) -> top
+
+        def self.calibrate_socket_timeout: (top conn, Float deadline) -> void
+
+        def self.build_request: (
+          Turbopuffer::Internal::Transport::PooledNetRequester::request request
+        ) {
+          (String arg0) -> void
+        } -> [top, (^-> void)]
+
+        private def with_pool: (
+          URI::Generic url,
+          deadline: Float
+        ) {
+          (top arg0) -> void
+        } -> void
+
+        def execute: (
+          Turbopuffer::Internal::Transport::PooledNetRequester::request request
+        ) -> [Integer, top, Enumerable[String]]
+
+        def initialize: (?size: Integer) -> void
+      end
+    end
+  end
+end