feat(api): Add /v1beta/extract

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 12
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-496d0afc77bafdc8f4208d3ddd767c3101d91ffb933b9b6bfcef5f489cc175a6.yml
-openapi_spec_hash: 730e697fec302b9310d4495c1f82802d
-config_hash: f9aa4d901581aaf70789dd0bc1b84597
+configured_endpoints: 13
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-e853fc79f3b41f00b3934fcc2e4c2813aa9f38528548f5f596e2b11ea833019b.yml
+openapi_spec_hash: 34ed7e373927037fce6fd33d9bb60389
+config_hash: ae63572e3769dcd1b11e587f039e211a

api.md

@@ -40,11 +40,19 @@ Convenience methods:
 Types:
 
 ```python
-from parallel.types.beta import SearchResult, WebSearchResult
+from parallel.types.beta import (
+    ExcerptSettings,
+    ExtractError,
+    ExtractResponse,
+    ExtractResult,
+    SearchResult,
+    WebSearchResult,
+)
 ```
 
 Methods:
 
+- <code title="post /v1beta/extract">client.beta.<a href="./src/parallel/resources/beta/beta.py">extract</a>(\*\*<a href="src/parallel/types/beta/beta_extract_params.py">params</a>) -> <a href="./src/parallel/types/beta/extract_response.py">ExtractResponse</a></code>
 - <code title="post /v1beta/search">client.beta.<a href="./src/parallel/resources/beta/beta.py">search</a>(\*\*<a href="src/parallel/types/beta/beta_search_params.py">params</a>) -> <a href="./src/parallel/types/beta/search_result.py">SearchResult</a></code>
 
 ## TaskRun

src/parallel/resources/beta/beta.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import List, Optional
 from typing_extensions import Literal
 
 import httpx
 
 from ..._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from ..._utils import maybe_transform, async_maybe_transform
+from ..._utils import is_given, maybe_transform, strip_not_given, async_maybe_transform
 from .task_run import (
     TaskRunResource,
     AsyncTaskRunResource,
@@ -33,9 +33,11 @@
     async_to_raw_response_wrapper,
     async_to_streamed_response_wrapper,
 )
-from ...types.beta import beta_search_params
+from ...types.beta import beta_search_params, beta_extract_params
 from ..._base_client import make_request_options
 from ...types.beta.search_result import SearchResult
+from ...types.beta.extract_response import ExtractResponse
+from ...types.beta.parallel_beta_param import ParallelBetaParam
 from ...types.shared_params.source_policy import SourcePolicy
 
 __all__ = ["BetaResource", "AsyncBetaResource"]
@@ -69,15 +71,89 @@ def with_streaming_response(self) -> BetaResourceWithStreamingResponse:
         """
         return BetaResourceWithStreamingResponse(self)
 
+    def extract(
+        self,
+        *,
+        urls: SequenceNotStr[str],
+        excerpts: beta_extract_params.Excerpts | Omit = omit,
+        fetch_policy: Optional[beta_extract_params.FetchPolicy] | Omit = omit,
+        full_content: beta_extract_params.FullContent | Omit = omit,
+        objective: Optional[str] | Omit = omit,
+        search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
+        betas: List[ParallelBetaParam] | 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,
+    ) -> ExtractResponse:
+        """
+        Extracts relevant content from specific web URLs.
+
+        To access this endpoint, pass the `parallel-beta` header with the value
+        `search-extract-2025-10-10`.
+
+        Args:
+          excerpts: Include excerpts from each URL relevant to the search objective and queries.
+              Note that if neither objective nor search_queries is provided, excerpts are
+              redundant with full content.
+
+          fetch_policy: Fetch policy.
+
+              Determines when to return content from the cache (faster) vs fetching live
+              content (fresher).
+
+          full_content: Include full content from each URL. Note that if neither objective nor
+              search_queries is provided, excerpts are redundant with full content.
+
+          objective: If provided, focuses extracted content on the specified search objective.
+
+          search_queries: If provided, focuses extracted content on the specified keyword search queries.
+
+          betas: Optional header to specify the beta version(s) to enable.
+
+          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
+        """
+        extra_headers = {
+            **strip_not_given({"parallel-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
+            **(extra_headers or {}),
+        }
+        return self._post(
+            "/v1beta/extract",
+            body=maybe_transform(
+                {
+                    "urls": urls,
+                    "excerpts": excerpts,
+                    "fetch_policy": fetch_policy,
+                    "full_content": full_content,
+                    "objective": objective,
+                    "search_queries": search_queries,
+                },
+                beta_extract_params.BetaExtractParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ExtractResponse,
+        )
+
     def search(
         self,
         *,
         max_chars_per_result: Optional[int] | Omit = omit,
         max_results: Optional[int] | Omit = omit,
         objective: Optional[str] | Omit = omit,
-        processor: Literal["base", "pro"] | Omit = omit,
+        processor: Optional[Literal["base", "pro"]] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
         source_policy: Optional[SourcePolicy] | Omit = omit,
+        betas: List[ParallelBetaParam] | 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,
@@ -109,6 +185,8 @@ def search(
 
               This policy governs which sources are allowed/disallowed in results.
 
+          betas: Optional header to specify the beta version(s) to enable.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -117,6 +195,10 @@ def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        extra_headers = {
+            **strip_not_given({"parallel-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
+            **(extra_headers or {}),
+        }
         return self._post(
             "/v1beta/search",
             body=maybe_transform(
@@ -165,15 +247,89 @@ def with_streaming_response(self) -> AsyncBetaResourceWithStreamingResponse:
         """
         return AsyncBetaResourceWithStreamingResponse(self)
 
+    async def extract(
+        self,
+        *,
+        urls: SequenceNotStr[str],
+        excerpts: beta_extract_params.Excerpts | Omit = omit,
+        fetch_policy: Optional[beta_extract_params.FetchPolicy] | Omit = omit,
+        full_content: beta_extract_params.FullContent | Omit = omit,
+        objective: Optional[str] | Omit = omit,
+        search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
+        betas: List[ParallelBetaParam] | 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,
+    ) -> ExtractResponse:
+        """
+        Extracts relevant content from specific web URLs.
+
+        To access this endpoint, pass the `parallel-beta` header with the value
+        `search-extract-2025-10-10`.
+
+        Args:
+          excerpts: Include excerpts from each URL relevant to the search objective and queries.
+              Note that if neither objective nor search_queries is provided, excerpts are
+              redundant with full content.
+
+          fetch_policy: Fetch policy.
+
+              Determines when to return content from the cache (faster) vs fetching live
+              content (fresher).
+
+          full_content: Include full content from each URL. Note that if neither objective nor
+              search_queries is provided, excerpts are redundant with full content.
+
+          objective: If provided, focuses extracted content on the specified search objective.
+
+          search_queries: If provided, focuses extracted content on the specified keyword search queries.
+
+          betas: Optional header to specify the beta version(s) to enable.
+
+          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
+        """
+        extra_headers = {
+            **strip_not_given({"parallel-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
+            **(extra_headers or {}),
+        }
+        return await self._post(
+            "/v1beta/extract",
+            body=await async_maybe_transform(
+                {
+                    "urls": urls,
+                    "excerpts": excerpts,
+                    "fetch_policy": fetch_policy,
+                    "full_content": full_content,
+                    "objective": objective,
+                    "search_queries": search_queries,
+                },
+                beta_extract_params.BetaExtractParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ExtractResponse,
+        )
+
     async def search(
         self,
         *,
         max_chars_per_result: Optional[int] | Omit = omit,
         max_results: Optional[int] | Omit = omit,
         objective: Optional[str] | Omit = omit,
-        processor: Literal["base", "pro"] | Omit = omit,
+        processor: Optional[Literal["base", "pro"]] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
         source_policy: Optional[SourcePolicy] | Omit = omit,
+        betas: List[ParallelBetaParam] | 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,
@@ -205,6 +361,8 @@ async def search(
 
               This policy governs which sources are allowed/disallowed in results.
 
+          betas: Optional header to specify the beta version(s) to enable.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -213,6 +371,10 @@ async def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        extra_headers = {
+            **strip_not_given({"parallel-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
+            **(extra_headers or {}),
+        }
         return await self._post(
             "/v1beta/search",
             body=await async_maybe_transform(
@@ -237,6 +399,9 @@ class BetaResourceWithRawResponse:
     def __init__(self, beta: BetaResource) -> None:
         self._beta = beta
 
+        self.extract = to_raw_response_wrapper(
+            beta.extract,
+        )
         self.search = to_raw_response_wrapper(
             beta.search,
         )
@@ -254,6 +419,9 @@ class AsyncBetaResourceWithRawResponse:
     def __init__(self, beta: AsyncBetaResource) -> None:
         self._beta = beta
 
+        self.extract = async_to_raw_response_wrapper(
+            beta.extract,
+        )
         self.search = async_to_raw_response_wrapper(
             beta.search,
         )
@@ -271,6 +439,9 @@ class BetaResourceWithStreamingResponse:
     def __init__(self, beta: BetaResource) -> None:
         self._beta = beta
 
+        self.extract = to_streamed_response_wrapper(
+            beta.extract,
+        )
         self.search = to_streamed_response_wrapper(
             beta.search,
         )
@@ -288,6 +459,9 @@ class AsyncBetaResourceWithStreamingResponse:
     def __init__(self, beta: AsyncBetaResource) -> None:
         self._beta = beta
 
+        self.extract = async_to_streamed_response_wrapper(
+            beta.extract,
+        )
         self.search = async_to_streamed_response_wrapper(
             beta.search,
         )

src/parallel/types/beta/__init__.py

@@ -6,18 +6,23 @@
 from .mcp_server import McpServer as McpServer
 from .task_group import TaskGroup as TaskGroup
 from .error_event import ErrorEvent as ErrorEvent
+from .extract_error import ExtractError as ExtractError
 from .mcp_tool_call import McpToolCall as McpToolCall
 from .search_result import SearchResult as SearchResult
 from .webhook_param import WebhookParam as WebhookParam
 from .beta_run_input import BetaRunInput as BetaRunInput
+from .extract_result import ExtractResult as ExtractResult
 from .task_run_event import TaskRunEvent as TaskRunEvent
+from .extract_response import ExtractResponse as ExtractResponse
 from .mcp_server_param import McpServerParam as McpServerParam
 from .task_group_status import TaskGroupStatus as TaskGroupStatus
 from .web_search_result import WebSearchResult as WebSearchResult
 from .beta_search_params import BetaSearchParams as BetaSearchParams
+from .beta_extract_params import BetaExtractParams as BetaExtractParams
 from .parallel_beta_param import ParallelBetaParam as ParallelBetaParam
 from .beta_run_input_param import BetaRunInputParam as BetaRunInputParam
 from .beta_task_run_result import BetaTaskRunResult as BetaTaskRunResult
+from .excerpt_settings_param import ExcerptSettingsParam as ExcerptSettingsParam
 from .task_run_create_params import TaskRunCreateParams as TaskRunCreateParams
 from .task_run_result_params import TaskRunResultParams as TaskRunResultParams
 from .task_group_run_response import TaskGroupRunResponse as TaskGroupRunResponse