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

Stainless-Generated-From: 6741289d8fddd4ebeb2ccab1f17c4f37f6a4d04a

Author: stlc-bot

src/context/dev/resources/people.py

@@ -127,6 +127,7 @@ def search(
         query: str,
         cursor: str | Omit = omit,
         filters: person_search_params.Filters | Omit = omit,
+        mode: Literal["fast", "ultra"] | Omit = omit,
         tags: SequenceNotStr[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -139,12 +140,17 @@ def search(
         Find people with a natural-language query.
 
         Args:
-          query: Describe the people to find.
+          query: Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+              `ultra` mode.
 
-          cursor: Use next_cursor with the same query and filters to fetch the next page.
+          cursor: Use next_cursor with the same query, mode and filters to fetch the next page.
 
           filters: Additional constraints every result must match.
 
+          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.
+
           tags: Labels for filtering usage in the dashboard.
 
           extra_headers: Send extra headers
@@ -162,6 +168,7 @@ def search(
                     "query": query,
                     "cursor": cursor,
                     "filters": filters,
+                    "mode": mode,
                     "tags": tags,
                 },
                 person_search_params.PersonSearchParams,
@@ -275,6 +282,7 @@ async def search(
         query: str,
         cursor: str | Omit = omit,
         filters: person_search_params.Filters | Omit = omit,
+        mode: Literal["fast", "ultra"] | Omit = omit,
         tags: SequenceNotStr[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -287,12 +295,17 @@ async def search(
         Find people with a natural-language query.
 
         Args:
-          query: Describe the people to find.
+          query: Describe the people to find. Up to 500 characters in `fast` mode and 5000 in
+              `ultra` mode.
 
-          cursor: Use next_cursor with the same query and filters to fetch the next page.
+          cursor: Use next_cursor with the same query, mode and filters to fetch the next page.
 
           filters: Additional constraints every result must match.
 
+          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.
+
           tags: Labels for filtering usage in the dashboard.
 
           extra_headers: Send extra headers
@@ -310,6 +323,7 @@ async def search(
                     "query": query,
                     "cursor": cursor,
                     "filters": filters,
+                    "mode": mode,
                     "tags": tags,
                 },
                 person_search_params.PersonSearchParams,

src/context/dev/types/person_search_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 from .._types import SequenceNotStr
 
@@ -11,14 +11,24 @@
 
 class PersonSearchParams(TypedDict, total=False):
     query: Required[str]
-    """Describe the people to find."""
+    """Describe the people to find.
+
+    Up to 500 characters in `fast` mode and 5000 in `ultra` mode.
+    """
 
     cursor: str
-    """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."""
 
     filters: Filters
     """Additional constraints every result must match."""
 
+    mode: Literal["fast", "ultra"]
+    """`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.
+    """
+
     tags: SequenceNotStr[str]
     """Labels for filtering usage in the dashboard."""
 

src/context/dev/types/person_search_response.py

@@ -4,7 +4,15 @@
 
 from .._models import BaseModel
 
-__all__ = ["PersonSearchResponse", "Result", "ResultLocation", "ResultRole", "ResultRoleCompany", "KeyMetadata"]
+__all__ = [
+    "PersonSearchResponse",
+    "Result",
+    "ResultLocation",
+    "ResultRole",
+    "ResultRoleCompany",
+    "ResultMatch",
+    "KeyMetadata",
+]
 
 
 class ResultLocation(BaseModel):
@@ -49,6 +57,13 @@ class ResultRole(BaseModel):
     """Job title."""
 
 
+class ResultMatch(BaseModel):
+    """How well the person matches the query. Only returned in `ultra` mode."""
+
+    confidence: float
+    """How well the person matches the query, from 0 to 1."""
+
+
 class Result(BaseModel):
     """A person matching your search; unavailable details are null or empty lists."""
 
@@ -79,6 +94,9 @@ class Result(BaseModel):
     years_of_experience: Optional[int] = None
     """Years of professional experience."""
 
+    match: Optional[ResultMatch] = None
+    """How well the person matches the query. Only returned in `ultra` mode."""
+
 
 class KeyMetadata(BaseModel):
     """Credits this request used and your remaining balance."""

tests/api_resources/test_people.py

@@ -103,6 +103,7 @@ def test_method_search_with_all_params(self, client: ContextDev) -> None:
                 "years_of_experience_max": 0,
                 "years_of_experience_min": 0,
             },
+            mode="fast",
             tags=["production", "team-alpha"],
         )
         assert_matches_type(PersonSearchResponse, person, path=["response"])
@@ -225,6 +226,7 @@ async def test_method_search_with_all_params(self, async_client: AsyncContextDev
                 "years_of_experience_max": 0,
                 "years_of_experience_min": 0,
             },
+            mode="fast",
             tags=["production", "team-alpha"],
         )
         assert_matches_type(PersonSearchResponse, person, path=["response"])