feat(search): add highlights to web search and bill page reads per 10 results (#1387)

Stainless-Generated-From: ab671f0

Author: stlc-bot

src/context/dev/resources/web.py

@@ -1025,6 +1025,7 @@ def search(
         | Omit = omit,
         exclude_domains: SequenceNotStr[str] | Omit = omit,
         freshness: Literal["last_24_hours", "last_week", "last_month", "last_year"] | Omit = omit,
+        highlights_options: web_search_params.HighlightsOptions | Omit = omit,
         include_domains: SequenceNotStr[str] | Omit = omit,
         markdown_options: web_search_params.MarkdownOptions | Omit = omit,
         num_results: int | Omit = omit,
@@ -1040,7 +1041,8 @@ def search(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> WebSearchResponse:
         """
-        Search the web and optionally return page content with each result.
+        Search the web and optionally return page content or relevant passages with each
+        result.
 
         Args:
           query: Search query. Accepts natural language as well as Google-style search operators
@@ -1054,6 +1056,9 @@ def search(
 
           freshness: Restrict results to content published within this window.
 
+          highlights_options: Passages from each result page that are relevant to the query. Pages are read
+              with the `markdownOptions` settings.
+
           include_domains: Allowlist — only return results from these domains. Example: ["arxiv.org",
               "github.com"].
 
@@ -1086,6 +1091,7 @@ def search(
                     "country": country,
                     "exclude_domains": exclude_domains,
                     "freshness": freshness,
+                    "highlights_options": highlights_options,
                     "include_domains": include_domains,
                     "markdown_options": markdown_options,
                     "num_results": num_results,
@@ -2425,6 +2431,7 @@ async def search(
         | Omit = omit,
         exclude_domains: SequenceNotStr[str] | Omit = omit,
         freshness: Literal["last_24_hours", "last_week", "last_month", "last_year"] | Omit = omit,
+        highlights_options: web_search_params.HighlightsOptions | Omit = omit,
         include_domains: SequenceNotStr[str] | Omit = omit,
         markdown_options: web_search_params.MarkdownOptions | Omit = omit,
         num_results: int | Omit = omit,
@@ -2440,7 +2447,8 @@ async def search(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> WebSearchResponse:
         """
-        Search the web and optionally return page content with each result.
+        Search the web and optionally return page content or relevant passages with each
+        result.
 
         Args:
           query: Search query. Accepts natural language as well as Google-style search operators
@@ -2454,6 +2462,9 @@ async def search(
 
           freshness: Restrict results to content published within this window.
 
+          highlights_options: Passages from each result page that are relevant to the query. Pages are read
+              with the `markdownOptions` settings.
+
           include_domains: Allowlist — only return results from these domains. Example: ["arxiv.org",
               "github.com"].
 
@@ -2486,6 +2497,7 @@ async def search(
                     "country": country,
                     "exclude_domains": exclude_domains,
                     "freshness": freshness,
+                    "highlights_options": highlights_options,
                     "include_domains": include_domains,
                     "markdown_options": markdown_options,
                     "num_results": num_results,

src/context/dev/types/web_search_params.py

@@ -7,7 +7,14 @@
 from .._types import SequenceNotStr
 from .._utils import PropertyInfo
 
-__all__ = ["WebSearchParams", "MarkdownOptions", "MarkdownOptionsPdf", "MarkdownOptionsTimeoutOpts", "TimeoutOpts"]
+__all__ = [
+    "WebSearchParams",
+    "HighlightsOptions",
+    "MarkdownOptions",
+    "MarkdownOptionsPdf",
+    "MarkdownOptionsTimeoutOpts",
+    "TimeoutOpts",
+]
 
 
 class WebSearchParams(TypedDict, total=False):
@@ -273,6 +280,12 @@ class WebSearchParams(TypedDict, total=False):
     freshness: Literal["last_24_hours", "last_week", "last_month", "last_year"]
     """Restrict results to content published within this window."""
 
+    highlights_options: Annotated[HighlightsOptions, PropertyInfo(alias="highlightsOptions")]
+    """Passages from each result page that are relevant to the query.
+
+    Pages are read with the `markdownOptions` settings.
+    """
+
     include_domains: Annotated[SequenceNotStr[str], PropertyInfo(alias="includeDomains")]
     """Allowlist — only return results from these domains.
 
@@ -301,6 +314,19 @@ class WebSearchParams(TypedDict, total=False):
     """
 
 
+class HighlightsOptions(TypedDict, total=False):
+    """Passages from each result page that are relevant to the query.
+
+    Pages are read with the `markdownOptions` settings.
+    """
+
+    enabled: bool
+    """Return relevant passages for each result. Adds 1 credit per 10 results."""
+
+    max_characters: Annotated[int, PropertyInfo(alias="maxCharacters")]
+    """Maximum combined length of passages per result."""
+
+
 class MarkdownOptionsPdf(TypedDict, total=False):
     """PDF handling. Use start/end to bound text extraction and OCR to a page range."""
 
@@ -335,7 +361,7 @@ class MarkdownOptions(TypedDict, total=False):
     """Inline Markdown scraping for each result. Set `enabled: true` to activate."""
 
     enabled: bool
-    """Scrape each result to Markdown. Off by default to keep search cheap and fast."""
+    """Scrape each result to Markdown. Adds 1 credit per 10 results."""
 
     include_frames: Annotated[bool, PropertyInfo(alias="includeFrames")]
     """Render iframe contents into the Markdown."""
@@ -349,7 +375,7 @@ class MarkdownOptions(TypedDict, total=False):
     max_age_ms: Annotated[int, PropertyInfo(alias="maxAgeMs")]
     """Cache TTL in ms for scraped Markdown keyed by URL + options.
 
-    Default 1 day, max 30 days. Set to 0 to force a fresh scrape.
+    Default 15 days, max 30 days. Set to 0 to force a fresh scrape.
     """
 
     pdf: MarkdownOptionsPdf

src/context/dev/types/web_search_response.py

@@ -7,7 +7,7 @@
 
 from .._models import BaseModel
 
-__all__ = ["WebSearchResponse", "CacheMetadata", "Result", "ResultMarkdown", "KeyMetadata"]
+__all__ = ["WebSearchResponse", "CacheMetadata", "Result", "ResultHighlights", "ResultMarkdown", "KeyMetadata"]
 
 
 class CacheMetadata(BaseModel):
@@ -23,6 +23,19 @@ class CacheMetadata(BaseModel):
     """
 
 
+class ResultHighlights(BaseModel):
+    """Highlights status and passages for this result."""
+
+    code: Literal["SUCCESS", "NOT_REQUESTED", "TIMEOUT", "CONTENT_TOO_LARGE", "WEBSITE_ACCESS_ERROR", "ERROR"]
+    """Per-result highlights outcome. Inspect this before reading `highlights`."""
+
+    highlights: Optional[List[str]] = None
+    """Passages relevant to the query, in page order.
+
+    Null unless highlightsOptions.enabled is true and the page was read.
+    """
+
+
 class ResultMarkdown(BaseModel):
     """Markdown scrape status and content for this result."""
 
@@ -49,6 +62,9 @@ class Result(BaseModel):
     Empty string when the search provider does not supply a snippet.
     """
 
+    highlights: ResultHighlights
+    """Highlights status and passages for this result."""
+
     markdown: ResultMarkdown
     """Markdown scrape status and content for this result."""
 

tests/api_resources/test_web.py

@@ -430,6 +430,10 @@ def test_method_search_with_all_params(self, client: ContextDev) -> None:
             country="af",
             exclude_domains=["string"],
             freshness="last_24_hours",
+            highlights_options={
+                "enabled": True,
+                "max_characters": 100,
+            },
             include_domains=["string"],
             markdown_options={
                 "enabled": True,
@@ -967,6 +971,10 @@ async def test_method_search_with_all_params(self, async_client: AsyncContextDev
             country="af",
             exclude_domains=["string"],
             freshness="last_24_hours",
+            highlights_options={
+                "enabled": True,
+                "max_characters": 100,
+            },
             include_domains=["string"],
             markdown_options={
                 "enabled": True,