feat(people): add ultra mode to people search (#2149)

Stainless-Generated-From: 5fe492dcbb4061b33f808123b87e3a784a0be89e

Author: stlc-bot

lib/context_dev/models/person_search_params.rb

@@ -8,13 +8,14 @@ class PersonSearchParams < ContextDev::Internal::Type::BaseModel
       include ContextDev::Internal::Type::RequestParameters
 
       # @!attribute query
-      #   Describe the people to find.
+      #   Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+      #   `ultra` mode.
       #
       #   @return [String]
       required :query, String
 
       # @!attribute cursor
-      #   Use next_cursor with the same query and filters to fetch the next page.
+      #   Use next_cursor with the same query, mode and filters to fetch the next page.
       #
       #   @return [String, nil]
       optional :cursor, String
@@ -25,19 +26,32 @@ class PersonSearchParams < ContextDev::Internal::Type::BaseModel
       #   @return [ContextDev::Models::PersonSearchParams::Filters, nil]
       optional :filters, -> { ContextDev::PersonSearchParams::Filters }
 
+      # @!attribute mode
+      #   `fast` matches people on basic criteria (e.g. their role, location or
+      #   background); `ultra` plans a deeper search, judges each candidate against every
+      #   criterion in the query and explains each match.
+      #
+      #   @return [Symbol, ContextDev::Models::PersonSearchParams::Mode, nil]
+      optional :mode, enum: -> { ContextDev::PersonSearchParams::Mode }
+
       # @!attribute tags
       #   Labels for filtering usage in the dashboard.
       #
       #   @return [Array<String>, nil]
       optional :tags, ContextDev::Internal::Type::ArrayOf[String]
 
-      # @!method initialize(query:, cursor: nil, filters: nil, tags: nil, request_options: {})
-      #   @param query [String] Describe the people to find.
+      # @!method initialize(query:, cursor: nil, filters: nil, mode: nil, tags: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {ContextDev::Models::PersonSearchParams} for more details.
       #
-      #   @param cursor [String] Use next_cursor with the same query and filters to fetch the next page.
+      #   @param query [String] Describe the people to find. Up to 500 characters in `fast` mode and 5000 in `ul
+      #
+      #   @param cursor [String] Use next_cursor with the same query, mode and filters to fetch the next page.
       #
       #   @param filters [ContextDev::Models::PersonSearchParams::Filters] Additional constraints every result must match.
       #
+      #   @param mode [Symbol, ContextDev::Models::PersonSearchParams::Mode] `fast` matches people on basic criteria (e.g. their role, location or background
+      #
       #   @param tags [Array<String>] Labels for filtering usage in the dashboard.
       #
       #   @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}]
@@ -70,6 +84,19 @@ class Filters < ContextDev::Internal::Type::BaseModel
         #
         #   @param years_of_experience_min [Integer] Minimum years of professional experience.
       end
+
+      # `fast` matches people on basic criteria (e.g. their role, location or
+      # background); `ultra` plans a deeper search, judges each candidate against every
+      # criterion in the query and explains each match.
+      module Mode
+        extend ContextDev::Internal::Type::Enum
+
+        FAST = :fast
+        ULTRA = :ultra
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

lib/context_dev/models/person_search_response.rb

@@ -97,7 +97,13 @@ class Result < ContextDev::Internal::Type::BaseModel
         #   @return [Integer, nil]
         required :years_of_experience, Integer, nil?: true
 
-        # @!method initialize(description:, is_founder:, location:, name:, profiles:, role:, schools:, skills:, years_of_experience:)
+        # @!attribute match
+        #   How well the person matches the query. Only returned in `ultra` mode.
+        #
+        #   @return [ContextDev::Models::PersonSearchResponse::Result::Match, nil]
+        optional :match, -> { ContextDev::Models::PersonSearchResponse::Result::Match }
+
+        # @!method initialize(description:, is_founder:, location:, name:, profiles:, role:, schools:, skills:, years_of_experience:, match: nil)
         #   A person matching your search; unavailable details are null or empty lists.
         #
         #   @param description [String, nil] What the person does.
@@ -117,6 +123,8 @@ class Result < ContextDev::Internal::Type::BaseModel
         #   @param skills [Array<String>] Professional skills.
         #
         #   @param years_of_experience [Integer, nil] Years of professional experience.
+        #
+        #   @param match [ContextDev::Models::PersonSearchResponse::Result::Match] How well the person matches the query. Only returned in `ultra` mode.
 
         # @see ContextDev::Models::PersonSearchResponse::Result#location
         class Location < ContextDev::Internal::Type::BaseModel
@@ -215,6 +223,20 @@ class Company < ContextDev::Internal::Type::BaseModel
             #   @param name [String, nil] Company name.
           end
         end
+
+        # @see ContextDev::Models::PersonSearchResponse::Result#match
+        class Match < ContextDev::Internal::Type::BaseModel
+          # @!attribute confidence
+          #   How well the person matches the query, from 0 to 1.
+          #
+          #   @return [Float]
+          required :confidence, Float
+
+          # @!method initialize(confidence:)
+          #   How well the person matches the query. Only returned in `ultra` mode.
+          #
+          #   @param confidence [Float] How well the person matches the query, from 0 to 1.
+        end
       end
 
       # @see ContextDev::Models::PersonSearchResponse#key_metadata

lib/context_dev/resources/people.rb

@@ -45,16 +45,21 @@ def enrich(params = {})
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {ContextDev::Models::PersonSearchParams} for more details.
+      #
       # Find people with a natural-language query.
       #
-      # @overload search(query:, cursor: nil, filters: nil, tags: nil, request_options: {})
+      # @overload search(query:, cursor: nil, filters: nil, mode: nil, tags: nil, request_options: {})
       #
-      # @param query [String] Describe the people to find.
+      # @param query [String] Describe the people to find. Up to 500 characters in `fast` mode and 5000 in `ul
       #
-      # @param cursor [String] Use next_cursor with the same query and filters to fetch the next page.
+      # @param cursor [String] Use next_cursor with the same query, mode and filters to fetch the next page.
       #
       # @param filters [ContextDev::Models::PersonSearchParams::Filters] Additional constraints every result must match.
       #
+      # @param mode [Symbol, ContextDev::Models::PersonSearchParams::Mode] `fast` matches people on basic criteria (e.g. their role, location or background
+      #
       # @param tags [Array<String>] Labels for filtering usage in the dashboard.
       #
       # @param request_options [ContextDev::RequestOptions, Hash{Symbol=>Object}, nil]

rbi/context_dev/models/person_search_params.rbi

@@ -11,11 +11,12 @@ module ContextDev
           T.any(ContextDev::PersonSearchParams, ContextDev::Internal::AnyHash)
         end
 
-      # Describe the people to find.
+      # Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+      # `ultra` mode.
       sig { returns(String) }
       attr_accessor :query
 
-      # Use next_cursor with the same query and filters to fetch the next page.
+      # Use next_cursor with the same query, mode and filters to fetch the next page.
       sig { returns(T.nilable(String)) }
       attr_reader :cursor
 
@@ -31,6 +32,15 @@ module ContextDev
       end
       attr_writer :filters
 
+      # `fast` matches people on basic criteria (e.g. their role, location or
+      # background); `ultra` plans a deeper search, judges each candidate against every
+      # criterion in the query and explains each match.
+      sig { returns(T.nilable(ContextDev::PersonSearchParams::Mode::OrSymbol)) }
+      attr_reader :mode
+
+      sig { params(mode: ContextDev::PersonSearchParams::Mode::OrSymbol).void }
+      attr_writer :mode
+
       # Labels for filtering usage in the dashboard.
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :tags
@@ -43,17 +53,23 @@ module ContextDev
           query: String,
           cursor: String,
           filters: ContextDev::PersonSearchParams::Filters::OrHash,
+          mode: ContextDev::PersonSearchParams::Mode::OrSymbol,
           tags: T::Array[String],
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
-        # Describe the people to find.
+        # Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+        # `ultra` mode.
         query:,
-        # Use next_cursor with the same query and filters to fetch the next page.
+        # Use next_cursor with the same query, mode and filters to fetch the next page.
         cursor: nil,
         # Additional constraints every result must match.
         filters: nil,
+        # `fast` matches people on basic criteria (e.g. their role, location or
+        # background); `ultra` plans a deeper search, judges each candidate against every
+        # criterion in the query and explains each match.
+        mode: nil,
         # Labels for filtering usage in the dashboard.
         tags: nil,
         request_options: {}
@@ -66,6 +82,7 @@ module ContextDev
             query: String,
             cursor: String,
             filters: ContextDev::PersonSearchParams::Filters,
+            mode: ContextDev::PersonSearchParams::Mode::OrSymbol,
             tags: T::Array[String],
             request_options: ContextDev::RequestOptions
           }
@@ -134,6 +151,29 @@ module ContextDev
         def to_hash
         end
       end
+
+      # `fast` matches people on basic criteria (e.g. their role, location or
+      # background); `ultra` plans a deeper search, judges each candidate against every
+      # criterion in the query and explains each match.
+      module Mode
+        extend ContextDev::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, ContextDev::PersonSearchParams::Mode) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        FAST = T.let(:fast, ContextDev::PersonSearchParams::Mode::TaggedSymbol)
+        ULTRA =
+          T.let(:ultra, ContextDev::PersonSearchParams::Mode::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[ContextDev::PersonSearchParams::Mode::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
     end
   end
 end

rbi/context_dev/models/person_search_response.rbi

@@ -140,6 +140,22 @@ module ContextDev
         sig { returns(T.nilable(Integer)) }
         attr_accessor :years_of_experience
 
+        # How well the person matches the query. Only returned in `ultra` mode.
+        sig do
+          returns(
+            T.nilable(ContextDev::Models::PersonSearchResponse::Result::Match)
+          )
+        end
+        attr_reader :match
+
+        sig do
+          params(
+            match:
+              ContextDev::Models::PersonSearchResponse::Result::Match::OrHash
+          ).void
+        end
+        attr_writer :match
+
         # A person matching your search; unavailable details are null or empty lists.
         sig do
           params(
@@ -153,7 +169,9 @@ module ContextDev
               ContextDev::Models::PersonSearchResponse::Result::Role::OrHash,
             schools: T::Array[String],
             skills: T::Array[String],
-            years_of_experience: T.nilable(Integer)
+            years_of_experience: T.nilable(Integer),
+            match:
+              ContextDev::Models::PersonSearchResponse::Result::Match::OrHash
           ).returns(T.attached_class)
         end
         def self.new(
@@ -174,7 +192,9 @@ module ContextDev
           # Professional skills.
           skills:,
           # Years of professional experience.
-          years_of_experience:
+          years_of_experience:,
+          # How well the person matches the query. Only returned in `ultra` mode.
+          match: nil
         )
         end
 
@@ -190,7 +210,8 @@ module ContextDev
               role: ContextDev::Models::PersonSearchResponse::Result::Role,
               schools: T::Array[String],
               skills: T::Array[String],
-              years_of_experience: T.nilable(Integer)
+              years_of_experience: T.nilable(Integer),
+              match: ContextDev::Models::PersonSearchResponse::Result::Match
             }
           )
         end
@@ -379,6 +400,32 @@ module ContextDev
             end
           end
         end
+
+        class Match < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::PersonSearchResponse::Result::Match,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # How well the person matches the query, from 0 to 1.
+          sig { returns(Float) }
+          attr_accessor :confidence
+
+          # How well the person matches the query. Only returned in `ultra` mode.
+          sig { params(confidence: Float).returns(T.attached_class) }
+          def self.new(
+            # How well the person matches the query, from 0 to 1.
+            confidence:
+          )
+          end
+
+          sig { override.returns({ confidence: Float }) }
+          def to_hash
+          end
+        end
       end
 
       class KeyMetadata < ContextDev::Internal::Type::BaseModel

rbi/context_dev/resources/people.rbi

@@ -53,17 +53,23 @@ module ContextDev
           query: String,
           cursor: String,
           filters: ContextDev::PersonSearchParams::Filters::OrHash,
+          mode: ContextDev::PersonSearchParams::Mode::OrSymbol,
           tags: T::Array[String],
           request_options: ContextDev::RequestOptions::OrHash
         ).returns(ContextDev::Models::PersonSearchResponse)
       end
       def search(
-        # Describe the people to find.
+        # Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+        # `ultra` mode.
         query:,
-        # Use next_cursor with the same query and filters to fetch the next page.
+        # Use next_cursor with the same query, mode and filters to fetch the next page.
         cursor: nil,
         # Additional constraints every result must match.
         filters: nil,
+        # `fast` matches people on basic criteria (e.g. their role, location or
+        # background); `ultra` plans a deeper search, judges each candidate against every
+        # criterion in the query and explains each match.
+        mode: nil,
         # Labels for filtering usage in the dashboard.
         tags: nil,
         request_options: {}