feat(highlights): preserve Markdown structure in scrape excerpts (#1236)

Stainless-Generated-From: eb9b996

Author: stlc-bot

src/context/dev/resources/web.py

@@ -417,21 +417,21 @@ def scrape(
         is shared with Markdown, parsed fields, product data, highlights, and JSON
         extraction. Cached outputs can come from different visits within maxAgeMs; use 0
         for a fresh capture. HTML-only requests use the existing fast acquisition path.
-        Highlights return the plain-text passages most relevant to
-        highlightsParams.query. Requests with at least one successful output cost one
-        base credit, including cache hits, or two with browser actions. All-failed
-        responses are unbilled except missing pages, which retain the base price and the
-        one-credit product charge when product was requested. Highlights add 3 credits
-        when passages are returned. JSON extraction runs an LLM over nonempty page
-        Markdown and adds four credits only when its result is returned successfully.
-        PDF OCR adds one credit per recovered page on fresh extraction. Product adds one
-        credit when its successful result is returned, plus six if that result used the
-        specialized model. Original response bytes and screenshots are limited to 20 MiB
-        each, screenshots to 40 megapixels, and the combined response to 60 MiB. An
-        oversized output has success: false and data: null. If the combined response
-        exceeds its limit, the largest outputs are marked failed until the remaining
-        outputs fit. Valid captured pieces may still be cached when omitted to meet the
-        response size limit.
+        Highlights return Markdown excerpts most relevant to highlightsParams.query.
+        Requests with at least one successful output cost one base credit, including
+        cache hits, or two with browser actions. All-failed responses are unbilled
+        except missing pages, which retain the base price and the one-credit product
+        charge when product was requested. Highlights add 3 credits when passages are
+        returned. JSON extraction runs an LLM over nonempty page Markdown and adds four
+        credits only when its result is returned successfully. PDF OCR adds one credit
+        per recovered page on fresh extraction. Product adds one credit when its
+        successful result is returned, plus six if that result used the specialized
+        model. Original response bytes and screenshots are limited to 20 MiB each,
+        screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized
+        output has success: false and data: null. If the combined response exceeds its
+        limit, the largest outputs are marked failed until the remaining outputs fit.
+        Valid captured pieces may still be cached when omitted to meet the response size
+        limit.
 
         Args:
           formats: Outputs to return. Enable at least one; omitted formats are false.
@@ -1922,21 +1922,21 @@ async def scrape(
         is shared with Markdown, parsed fields, product data, highlights, and JSON
         extraction. Cached outputs can come from different visits within maxAgeMs; use 0
         for a fresh capture. HTML-only requests use the existing fast acquisition path.
-        Highlights return the plain-text passages most relevant to
-        highlightsParams.query. Requests with at least one successful output cost one
-        base credit, including cache hits, or two with browser actions. All-failed
-        responses are unbilled except missing pages, which retain the base price and the
-        one-credit product charge when product was requested. Highlights add 3 credits
-        when passages are returned. JSON extraction runs an LLM over nonempty page
-        Markdown and adds four credits only when its result is returned successfully.
-        PDF OCR adds one credit per recovered page on fresh extraction. Product adds one
-        credit when its successful result is returned, plus six if that result used the
-        specialized model. Original response bytes and screenshots are limited to 20 MiB
-        each, screenshots to 40 megapixels, and the combined response to 60 MiB. An
-        oversized output has success: false and data: null. If the combined response
-        exceeds its limit, the largest outputs are marked failed until the remaining
-        outputs fit. Valid captured pieces may still be cached when omitted to meet the
-        response size limit.
+        Highlights return Markdown excerpts most relevant to highlightsParams.query.
+        Requests with at least one successful output cost one base credit, including
+        cache hits, or two with browser actions. All-failed responses are unbilled
+        except missing pages, which retain the base price and the one-credit product
+        charge when product was requested. Highlights add 3 credits when passages are
+        returned. JSON extraction runs an LLM over nonempty page Markdown and adds four
+        credits only when its result is returned successfully. PDF OCR adds one credit
+        per recovered page on fresh extraction. Product adds one credit when its
+        successful result is returned, plus six if that result used the specialized
+        model. Original response bytes and screenshots are limited to 20 MiB each,
+        screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized
+        output has success: false and data: null. If the combined response exceeds its
+        limit, the largest outputs are marked failed until the remaining outputs fit.
+        Valid captured pieces may still be cached when omitted to meet the response size
+        limit.
 
         Args:
           formats: Outputs to return. Enable at least one; omitted formats are false.

src/context/dev/types/web_scrape_params.py

@@ -112,8 +112,9 @@ class Formats(TypedDict, total=False):
 
     highlights: bool
     """
-    Relevant passages for your question or topic, with headings included when needed
-    for context. Adds 3 credits when passages are returned.
+    Relevant Markdown excerpts for your question or topic, preserving code, lists,
+    and tables, with headings included when needed for context. Adds 3 credits when
+    passages are returned.
     """
 
     html: bool

src/context/dev/types/web_scrape_response.py

@@ -72,9 +72,9 @@ class CacheMetadata(BaseModel):
 
 
 class Highlights(BaseModel):
-    """Relevant passages for your question or topic, in page order.
+    """Relevant Markdown excerpts for your question or topic, in page order.
 
-    A heading in square brackets is included when needed to interpret a passage. Empty when the page has no text.
+    Headings in square brackets supply necessary context; ellipses mark omitted portions. Empty when the page has no text.
     """
 
     data: Optional[List[str]] = None
@@ -376,10 +376,10 @@ class WebScrapeResponse(BaseModel):
     """
 
     highlights: Highlights
-    """Relevant passages for your question or topic, in page order.
+    """Relevant Markdown excerpts for your question or topic, in page order.
 
-    A heading in square brackets is included when needed to interpret a passage.
-    Empty when the page has no text.
+    Headings in square brackets supply necessary context; ellipses mark omitted
+    portions. Empty when the page has no text.
     """
 
     html: HTML