feat(api): Search/Extract v1 with advanced_settings and max_results

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 23
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-44048676c9b07d49ed9dbee5fad53d145eddaea5ba682b6557681c5a7e04f8ed.yml
-openapi_spec_hash: e239787937742b1bc15e7f211fe3c518
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-7099c3aac2f0edacf413e426c176150404e1603f709cdd1f0af5c6689d33bd4f.yml
+openapi_spec_hash: eb61e027506aa339543ce33d7f052046
 config_hash: fe820a5a10ee48e143c9e49a153b23b4

src/parallel/_client.py

@@ -231,7 +231,7 @@ def extract(
         self,
         *,
         urls: SequenceNotStr[str],
-        advanced: Optional[AdvancedExtractSettingsParam] | Omit = omit,
+        advanced_settings: Optional[AdvancedExtractSettingsParam] | Omit = omit,
         client_model: Optional[str] | Omit = omit,
         max_chars_total: Optional[int] | Omit = omit,
         objective: Optional[str] | Omit = omit,
@@ -249,7 +249,7 @@ def extract(
         Args:
           urls: URLs to extract content from. Up to 20 URLs.
 
-          advanced: Advanced extract configuration.
+          advanced_settings: Advanced extract configuration.
 
           client_model: The model generating this request and consuming the results. Enables
               optimizations and tailors default settings for the model's capabilities.
@@ -278,7 +278,7 @@ def extract(
             body=maybe_transform(
                 {
                     "urls": urls,
-                    "advanced": advanced,
+                    "advanced_settings": advanced_settings,
                     "client_model": client_model,
                     "max_chars_total": max_chars_total,
                     "objective": objective,
@@ -296,7 +296,7 @@ def search(
         self,
         *,
         search_queries: SequenceNotStr[str],
-        advanced: Optional[AdvancedSearchSettingsParam] | Omit = omit,
+        advanced_settings: Optional[AdvancedSearchSettingsParam] | Omit = omit,
         client_model: Optional[str] | Omit = omit,
         max_chars_total: Optional[int] | Omit = omit,
         mode: Optional[Literal["basic", "standard"]] | Omit = omit,
@@ -316,7 +316,7 @@ def search(
               provide 2-3 for best results. Used together with objective to focus results on
               the most relevant content.
 
-          advanced: Advanced search configuration.
+          advanced_settings: Advanced search configuration.
 
           client_model: The model generating this request and consuming the results. Enables
               optimizations and tailors default settings for the model's capabilities.
@@ -327,6 +327,7 @@ def search(
           mode: Search mode preset: supported values are basic and standard. Basic mode offers
               the lowest latency and works best with 2-3 high-quality search_queries. Standard
               mode provides higher quality with more advanced retrieval and compression.
+              Defaults to standard when omitted.
 
           objective: Natural-language description of the underlying question or goal driving the
               search. Used together with search_queries to focus results on the most relevant
@@ -346,7 +347,7 @@ def search(
             body=maybe_transform(
                 {
                     "search_queries": search_queries,
-                    "advanced": advanced,
+                    "advanced_settings": advanced_settings,
                     "client_model": client_model,
                     "max_chars_total": max_chars_total,
                     "mode": mode,
@@ -556,7 +557,7 @@ async def extract(
         self,
         *,
         urls: SequenceNotStr[str],
-        advanced: Optional[AdvancedExtractSettingsParam] | Omit = omit,
+        advanced_settings: Optional[AdvancedExtractSettingsParam] | Omit = omit,
         client_model: Optional[str] | Omit = omit,
         max_chars_total: Optional[int] | Omit = omit,
         objective: Optional[str] | Omit = omit,
@@ -574,7 +575,7 @@ async def extract(
         Args:
           urls: URLs to extract content from. Up to 20 URLs.
 
-          advanced: Advanced extract configuration.
+          advanced_settings: Advanced extract configuration.
 
           client_model: The model generating this request and consuming the results. Enables
               optimizations and tailors default settings for the model's capabilities.
@@ -603,7 +604,7 @@ async def extract(
             body=await async_maybe_transform(
                 {
                     "urls": urls,
-                    "advanced": advanced,
+                    "advanced_settings": advanced_settings,
                     "client_model": client_model,
                     "max_chars_total": max_chars_total,
                     "objective": objective,
@@ -621,7 +622,7 @@ async def search(
         self,
         *,
         search_queries: SequenceNotStr[str],
-        advanced: Optional[AdvancedSearchSettingsParam] | Omit = omit,
+        advanced_settings: Optional[AdvancedSearchSettingsParam] | Omit = omit,
         client_model: Optional[str] | Omit = omit,
         max_chars_total: Optional[int] | Omit = omit,
         mode: Optional[Literal["basic", "standard"]] | Omit = omit,
@@ -641,7 +642,7 @@ async def search(
               provide 2-3 for best results. Used together with objective to focus results on
               the most relevant content.
 
-          advanced: Advanced search configuration.
+          advanced_settings: Advanced search configuration.
 
           client_model: The model generating this request and consuming the results. Enables
               optimizations and tailors default settings for the model's capabilities.
@@ -652,6 +653,7 @@ async def search(
           mode: Search mode preset: supported values are basic and standard. Basic mode offers
               the lowest latency and works best with 2-3 high-quality search_queries. Standard
               mode provides higher quality with more advanced retrieval and compression.
+              Defaults to standard when omitted.
 
           objective: Natural-language description of the underlying question or goal driving the
               search. Used together with search_queries to focus results on the most relevant
@@ -671,7 +673,7 @@ async def search(
             body=await async_maybe_transform(
                 {
                     "search_queries": search_queries,
-                    "advanced": advanced,
+                    "advanced_settings": advanced_settings,
                     "client_model": client_model,
                     "max_chars_total": max_chars_total,
                     "mode": mode,

src/parallel/resources/beta/findall.py

@@ -117,7 +117,7 @@ def create(
           match_conditions: List of match conditions for the FindAll run.
 
           match_limit: Maximum number of matches to find for this FindAll run. Must be between 5 and
-              1000 (inclusive).
+              1000 (inclusive). May return fewer results.
 
           objective: Natural language objective of the FindAll run.
 
@@ -662,7 +662,7 @@ async def create(
           match_conditions: List of match conditions for the FindAll run.
 
           match_limit: Maximum number of matches to find for this FindAll run. Must be between 5 and
-              1000 (inclusive).
+              1000 (inclusive). May return fewer results.
 
           objective: Natural language objective of the FindAll run.
 

src/parallel/types/advanced_search_settings_param.py

@@ -24,6 +24,9 @@ class AdvancedSearchSettingsParam(TypedDict, total=False):
     location: Optional[str]
     """ISO 3166-1 alpha-2 country code for geo-targeted search results."""
 
+    max_results: Optional[int]
+    """Upper bound on the number of results to return. Defaults to 10 if not provided."""
+
     source_policy: Optional[SourcePolicy]
     """Source policy for web search results.
 

src/parallel/types/beta/findall_create_params.py

@@ -25,7 +25,7 @@ class FindAllCreateParams(TypedDict, total=False):
     match_limit: Required[int]
     """Maximum number of matches to find for this FindAll run.
 
-    Must be between 5 and 1000 (inclusive).
+    Must be between 5 and 1000 (inclusive). May return fewer results.
     """
 
     objective: Required[str]

src/parallel/types/client_extract_params.py

@@ -15,7 +15,7 @@ class ClientExtractParams(TypedDict, total=False):
     urls: Required[SequenceNotStr[str]]
     """URLs to extract content from. Up to 20 URLs."""
 
-    advanced: Optional[AdvancedExtractSettingsParam]
+    advanced_settings: Optional[AdvancedExtractSettingsParam]
     """Advanced extract configuration."""
 
     client_model: Optional[str]

src/parallel/types/client_search_params.py

@@ -19,7 +19,7 @@ class ClientSearchParams(TypedDict, total=False):
     objective to focus results on the most relevant content.
     """
 
-    advanced: Optional[AdvancedSearchSettingsParam]
+    advanced_settings: Optional[AdvancedSearchSettingsParam]
     """Advanced search configuration."""
 
     client_model: Optional[str]
@@ -39,7 +39,7 @@ class ClientSearchParams(TypedDict, total=False):
 
     Basic mode offers the lowest latency and works best with 2-3 high-quality
     search_queries. Standard mode provides higher quality with more advanced
-    retrieval and compression.
+    retrieval and compression. Defaults to standard when omitted.
     """
 
     objective: Optional[str]

tests/api_resources/test_client.py

@@ -32,7 +32,7 @@ def test_method_extract(self, client: Parallel) -> None:
     def test_method_extract_with_all_params(self, client: Parallel) -> None:
         client_ = client.extract(
             urls=["string"],
-            advanced={
+            advanced_settings={
                 "excerpt_settings": {"max_chars_per_result": 0},
                 "fetch_policy": {
                     "disable_cache_fallback": True,
@@ -83,14 +83,15 @@ def test_method_search(self, client: Parallel) -> None:
     def test_method_search_with_all_params(self, client: Parallel) -> None:
         client_ = client.search(
             search_queries=["string"],
-            advanced={
+            advanced_settings={
                 "excerpt_settings": {"max_chars_per_result": 0},
                 "fetch_policy": {
                     "disable_cache_fallback": True,
                     "max_age_seconds": 86400,
                     "timeout_seconds": 60,
                 },
                 "location": "us",
+                "max_results": 0,
                 "source_policy": {
                     "after_date": parse_date("2024-01-01"),
                     "exclude_domains": ["reddit.com", "x.com", ".ai"],
@@ -145,7 +146,7 @@ async def test_method_extract(self, async_client: AsyncParallel) -> None:
     async def test_method_extract_with_all_params(self, async_client: AsyncParallel) -> None:
         client = await async_client.extract(
             urls=["string"],
-            advanced={
+            advanced_settings={
                 "excerpt_settings": {"max_chars_per_result": 0},
                 "fetch_policy": {
                     "disable_cache_fallback": True,
@@ -196,14 +197,15 @@ async def test_method_search(self, async_client: AsyncParallel) -> None:
     async def test_method_search_with_all_params(self, async_client: AsyncParallel) -> None:
         client = await async_client.search(
             search_queries=["string"],
-            advanced={
+            advanced_settings={
                 "excerpt_settings": {"max_chars_per_result": 0},
                 "fetch_policy": {
                     "disable_cache_fallback": True,
                     "max_age_seconds": 86400,
                     "timeout_seconds": 60,
                 },
                 "location": "us",
+                "max_results": 0,
                 "source_policy": {
                     "after_date": parse_date("2024-01-01"),
                     "exclude_domains": ["reddit.com", "x.com", ".ai"],