fix(api): guarantee search descriptions and align response types (#1089)

Stainless-Generated-From: fc09ddd

Author: stlc-bot

src/context/dev/types/brand_retrieve_response.py

@@ -7,7 +7,6 @@
 
 __all__ = [
     "BrandRetrieveResponse",
-    "CacheMetadata",
     "Brand",
     "BrandAddress",
     "BrandBackdrop",
@@ -23,26 +22,11 @@
     "BrandLogoResolution",
     "BrandSocial",
     "BrandStock",
+    "CacheMetadata",
     "KeyMetadata",
 ]
 
 
-class CacheMetadata(BaseModel):
-    """Cache outcome for this response.
-
-    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
-    """
-
-    age_ms: int
-    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
-
-    status: Literal["hit", "miss", "zdr"]
-    """
-    Whether the response was served from cache, required fresh work, or honored
-    zero-data-retention cache bypass.
-    """
-
-
 class BrandAddress(BaseModel):
     """Physical address of the brand"""
 
@@ -693,6 +677,22 @@ class Brand(BaseModel):
     """The title or name of the brand"""
 
 
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
+
+
 class KeyMetadata(BaseModel):
     """Credit usage, included whenever a valid API key is provided."""
 
@@ -704,24 +704,27 @@ class KeyMetadata(BaseModel):
 
 
 class BrandRetrieveResponse(BaseModel):
+    brand: Brand
+    """Detailed brand information"""
+
     cache_metadata: CacheMetadata
     """Cache outcome for this response.
 
     Composite responses are hits only when every cache-controlled fetch contributing
     to the output was a hit; age_ms is the oldest contributing hit.
     """
 
+    code: int
+    """HTTP status code"""
+
     request_id: str
     """Unique id of this API call, also sent in the X-Request-Id response header.
 
     Quote it when contacting support about a failed request.
     """
 
-    brand: Optional[Brand] = None
-    """Detailed brand information"""
-
-    code: Optional[int] = None
-    """HTTP status code"""
+    status: str
+    """Status of the response, e.g., 'ok'"""
 
     key_metadata: Optional[KeyMetadata] = None
     """Credit usage, included whenever a valid API key is provided."""
@@ -731,6 +734,3 @@ class BrandRetrieveResponse(BaseModel):
     True when the timeout ended processing and this response contains the usable
     data completed so far. Unfinished fields are omitted.
     """
-
-    status: Optional[str] = None
-    """Status of the response, e.g., 'ok'"""

src/context/dev/types/brand_retrieve_simplified_response.py

@@ -7,7 +7,6 @@
 
 __all__ = [
     "BrandRetrieveSimplifiedResponse",
-    "CacheMetadata",
     "Brand",
     "BrandBackdrop",
     "BrandBackdropColor",
@@ -16,26 +15,11 @@
     "BrandLogo",
     "BrandLogoColor",
     "BrandLogoResolution",
+    "CacheMetadata",
     "KeyMetadata",
 ]
 
 
-class CacheMetadata(BaseModel):
-    """Cache outcome for this response.
-
-    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
-    """
-
-    age_ms: int
-    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
-
-    status: Literal["hit", "miss", "zdr"]
-    """
-    Whether the response was served from cache, required fresh work, or honored
-    zero-data-retention cache bypass.
-    """
-
-
 class BrandBackdropColor(BaseModel):
     hex: Optional[str] = None
     """Color in hexadecimal format"""
@@ -144,6 +128,22 @@ class Brand(BaseModel):
     """The title or name of the brand"""
 
 
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
+
+
 class KeyMetadata(BaseModel):
     """Credit usage, included whenever a valid API key is provided."""
 
@@ -155,24 +155,27 @@ class KeyMetadata(BaseModel):
 
 
 class BrandRetrieveSimplifiedResponse(BaseModel):
+    brand: Brand
+    """Simplified brand information"""
+
     cache_metadata: CacheMetadata
     """Cache outcome for this response.
 
     Composite responses are hits only when every cache-controlled fetch contributing
     to the output was a hit; age_ms is the oldest contributing hit.
     """
 
+    code: int
+    """HTTP status code of the response"""
+
     request_id: str
     """Unique id of this API call, also sent in the X-Request-Id response header.
 
     Quote it when contacting support about a failed request.
     """
 
-    brand: Optional[Brand] = None
-    """Simplified brand information"""
-
-    code: Optional[int] = None
-    """HTTP status code of the response"""
+    status: str
+    """Status of the response, e.g., 'ok'"""
 
     key_metadata: Optional[KeyMetadata] = None
     """Credit usage, included whenever a valid API key is provided."""
@@ -182,6 +185,3 @@ class BrandRetrieveSimplifiedResponse(BaseModel):
     True when the timeout ended processing and only completed brand data is
     returned.
     """
-
-    status: Optional[str] = None
-    """Status of the response, e.g., 'ok'"""

src/context/dev/types/web_search_response.py

@@ -51,7 +51,10 @@ class ResultMarkdown(BaseModel):
 
 class Result(BaseModel):
     description: str
-    """Snippet excerpt from the page."""
+    """Snippet excerpt from the page.
+
+    Empty string when the search provider does not supply a snippet.
+    """
 
     markdown: ResultMarkdown
     """Markdown scrape status and content for this result."""