feat(people): publish people search in the API specification (#2094)

Stainless-Generated-From: 4dd539d6f936ea827e3bc97ba49d2e1c5555301c

Author: stlc-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 45
+configured_endpoints: 46

api.md

@@ -183,12 +183,13 @@ Methods:
 Types:
 
 ```python
-from context.dev.types import PersonEnrichResponse
+from context.dev.types import PersonEnrichResponse, PersonSearchResponse
 ```
 
 Methods:
 
 - <code title="post /people/enrich">client.people.<a href="./src/context/dev/resources/people.py">enrich</a>(\*\*<a href="src/context/dev/types/person_enrich_params.py">params</a>) -> <a href="./src/context/dev/types/person_enrich_response.py">PersonEnrichResponse</a></code>
+- <code title="post /people/search">client.people.<a href="./src/context/dev/resources/people.py">search</a>(\*\*<a href="src/context/dev/types/person_search_params.py">params</a>) -> <a href="./src/context/dev/types/person_search_response.py">PersonSearchResponse</a></code>
 
 # News
 

src/context/dev/resources/people.py

@@ -7,7 +7,7 @@
 
 import httpx
 
-from ..types import person_enrich_params
+from ..types import person_enrich_params, person_search_params
 from .._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
 from .._utils import maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -20,6 +20,7 @@
 )
 from .._base_client import make_request_options
 from ..types.person_enrich_response import PersonEnrichResponse
+from ..types.person_search_response import PersonSearchResponse
 
 __all__ = ["PeopleResource", "AsyncPeopleResource"]
 
@@ -120,6 +121,57 @@ def enrich(
             cast_to=PersonEnrichResponse,
         )
 
+    def search(
+        self,
+        *,
+        query: str,
+        cursor: str | Omit = omit,
+        filters: person_search_params.Filters | 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.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> PersonSearchResponse:
+        """
+        Find people with a natural-language query.
+
+        Args:
+          query: Describe the people to find.
+
+          cursor: Use next_cursor with the same query and filters to fetch the next page.
+
+          filters: Additional constraints every result must match.
+
+          tags: Labels for filtering usage in the dashboard.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/people/search",
+            body=maybe_transform(
+                {
+                    "query": query,
+                    "cursor": cursor,
+                    "filters": filters,
+                    "tags": tags,
+                },
+                person_search_params.PersonSearchParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=PersonSearchResponse,
+        )
+
 
 class AsyncPeopleResource(AsyncAPIResource):
     @cached_property
@@ -217,6 +269,57 @@ async def enrich(
             cast_to=PersonEnrichResponse,
         )
 
+    async def search(
+        self,
+        *,
+        query: str,
+        cursor: str | Omit = omit,
+        filters: person_search_params.Filters | 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.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> PersonSearchResponse:
+        """
+        Find people with a natural-language query.
+
+        Args:
+          query: Describe the people to find.
+
+          cursor: Use next_cursor with the same query and filters to fetch the next page.
+
+          filters: Additional constraints every result must match.
+
+          tags: Labels for filtering usage in the dashboard.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/people/search",
+            body=await async_maybe_transform(
+                {
+                    "query": query,
+                    "cursor": cursor,
+                    "filters": filters,
+                    "tags": tags,
+                },
+                person_search_params.PersonSearchParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=PersonSearchResponse,
+        )
+
 
 class PeopleResourceWithRawResponse:
     def __init__(self, people: PeopleResource) -> None:
@@ -225,6 +328,9 @@ def __init__(self, people: PeopleResource) -> None:
         self.enrich = to_raw_response_wrapper(
             people.enrich,
         )
+        self.search = to_raw_response_wrapper(
+            people.search,
+        )
 
 
 class AsyncPeopleResourceWithRawResponse:
@@ -234,6 +340,9 @@ def __init__(self, people: AsyncPeopleResource) -> None:
         self.enrich = async_to_raw_response_wrapper(
             people.enrich,
         )
+        self.search = async_to_raw_response_wrapper(
+            people.search,
+        )
 
 
 class PeopleResourceWithStreamingResponse:
@@ -243,6 +352,9 @@ def __init__(self, people: PeopleResource) -> None:
         self.enrich = to_streamed_response_wrapper(
             people.enrich,
         )
+        self.search = to_streamed_response_wrapper(
+            people.search,
+        )
 
 
 class AsyncPeopleResourceWithStreamingResponse:
@@ -252,3 +364,6 @@ def __init__(self, people: AsyncPeopleResource) -> None:
         self.enrich = async_to_streamed_response_wrapper(
             people.enrich,
         )
+        self.search = async_to_streamed_response_wrapper(
+            people.search,
+        )

src/context/dev/types/__init__.py

@@ -27,6 +27,7 @@
 from .monitor_run_response import MonitorRunResponse as MonitorRunResponse
 from .news_search_response import NewsSearchResponse as NewsSearchResponse
 from .person_enrich_params import PersonEnrichParams as PersonEnrichParams
+from .person_search_params import PersonSearchParams as PersonSearchParams
 from .web_answers_response import WebAnswersResponse as WebAnswersResponse
 from .batch_cancel_response import BatchCancelResponse as BatchCancelResponse
 from .batch_delete_response import BatchDeleteResponse as BatchDeleteResponse
@@ -42,6 +43,7 @@
 from .web_screenshot_params import WebScreenshotParams as WebScreenshotParams
 from .feedback_submit_params import FeedbackSubmitParams as FeedbackSubmitParams
 from .person_enrich_response import PersonEnrichResponse as PersonEnrichResponse
+from .person_search_response import PersonSearchResponse as PersonSearchResponse
 from .batch_retrieve_response import BatchRetrieveResponse as BatchRetrieveResponse
 from .brand_retrieve_response import BrandRetrieveResponse as BrandRetrieveResponse
 from .monitor_create_response import MonitorCreateResponse as MonitorCreateResponse

src/context/dev/types/person_search_params.py

@@ -0,0 +1,36 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Required, TypedDict
+
+from .._types import SequenceNotStr
+
+__all__ = ["PersonSearchParams", "Filters"]
+
+
+class PersonSearchParams(TypedDict, total=False):
+    query: Required[str]
+    """Describe the people to find."""
+
+    cursor: str
+    """Use next_cursor with the same query and filters to fetch the next page."""
+
+    filters: Filters
+    """Additional constraints every result must match."""
+
+    tags: SequenceNotStr[str]
+    """Labels for filtering usage in the dashboard."""
+
+
+class Filters(TypedDict, total=False):
+    """Additional constraints every result must match."""
+
+    countries: SequenceNotStr[str]
+    """Countries people live in as two-letter codes, such as US or GB."""
+
+    years_of_experience_max: int
+    """Maximum years of professional experience."""
+
+    years_of_experience_min: int
+    """Minimum years of professional experience."""

src/context/dev/types/person_search_response.py

@@ -0,0 +1,107 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+
+from .._models import BaseModel
+
+__all__ = ["PersonSearchResponse", "Result", "ResultLocation", "ResultRole", "ResultRoleCompany", "KeyMetadata"]
+
+
+class ResultLocation(BaseModel):
+    """Where the person lives."""
+
+    city: Optional[str] = None
+    """City."""
+
+    country_code: Optional[str] = None
+    """Country as a two-letter code, such as US or GB."""
+
+    region: Optional[str] = None
+    """State or region."""
+
+
+class ResultRoleCompany(BaseModel):
+    """Current employer, when known."""
+
+    domain: Optional[str] = None
+    """The company’s website domain."""
+
+    name: Optional[str] = None
+    """Company name."""
+
+
+class ResultRole(BaseModel):
+    """The person’s current role."""
+
+    company: Optional[ResultRoleCompany] = None
+    """Current employer, when known."""
+
+    functions: List[str]
+    """Areas of responsibility."""
+
+    seniority: Optional[str] = None
+    """Seniority level."""
+
+    started_on: Optional[str] = None
+    """Role start date (YYYY-MM-DD)."""
+
+    title: Optional[str] = None
+    """Job title."""
+
+
+class Result(BaseModel):
+    """A person matching your search; unavailable details are null or empty lists."""
+
+    description: Optional[str] = None
+    """What the person does."""
+
+    is_founder: Optional[bool] = None
+    """Whether the person is currently a founder or co-founder."""
+
+    location: ResultLocation
+    """Where the person lives."""
+
+    name: Optional[str] = None
+    """Full name."""
+
+    profiles: List[str]
+    """Public professional profile URLs."""
+
+    role: ResultRole
+    """The person’s current role."""
+
+    schools: List[str]
+    """Schools attended."""
+
+    skills: List[str]
+    """Professional skills."""
+
+    years_of_experience: Optional[int] = None
+    """Years of professional experience."""
+
+
+class KeyMetadata(BaseModel):
+    """Credits this request used and your remaining balance."""
+
+    credits_consumed: int
+    """Credits charged for this request."""
+
+    credits_remaining: int
+    """Credits remaining for your organization."""
+
+
+class PersonSearchResponse(BaseModel):
+    request_id: str
+    """Unique ID of this request, also in `X-Request-Id`.
+
+    Include it when contacting support.
+    """
+
+    results: List[Result]
+    """Up to 10 matching people, most relevant first."""
+
+    key_metadata: Optional[KeyMetadata] = None
+    """Credits this request used and your remaining balance."""
+
+    next_cursor: Optional[str] = None
+    """Pass as cursor to fetch the next page; null when there are no more results."""