Search and Discovery

class SearchServiceClient:
    def search(self, request: SearchRequest) -> SearchResponse:
        """
        Performs product search with comprehensive filtering and ranking options.
        
        Args:
            request: Search parameters including query, filters, facets, and personalization
            
        Returns:
            SearchResponse: Search results with products, facets, corrected query, and metadata
            
        Raises:
            InvalidArgument: If search parameters are invalid
            PermissionDenied: If placement is not accessible
        """

class CompletionServiceClient:
    def complete_query(self, request: CompleteQueryRequest) -> CompleteQueryResponse:
        """
        Provides query auto-completion suggestions based on catalog data and user behavior.
        
        Args:
            request: Contains catalog path, query prefix, and completion parameters
            
        Returns:
            CompleteQueryResponse: Completion suggestions with attribution metadata
            
        Raises:
            InvalidArgument: If completion parameters are invalid
        """

class SearchServiceAsyncClient:
    async def search(self, request: SearchRequest) -> SearchResponse:
        """Async version of search."""

class CompletionServiceAsyncClient:
    async def complete_query(self, request: CompleteQueryRequest) -> CompleteQueryResponse:
        """Async version of complete_query."""

class SearchRequest:
    placement: str  # Placement resource name (required)
    branch: str  # Catalog branch to search
    query: str  # Search query text
    visitor_id: str  # Unique visitor identifier for personalization
    user_info: UserInfo  # User context information
    page_size: int  # Maximum results per page (default: 100, max: 1000)
    page_token: str  # Token for pagination
    offset: int  # Number of results to skip
    filter: str  # Filter expression for products
    canonical_filter: str  # Canonical filter for consistent results
    order_by: str  # Sort order specification
    facet_specs: List[FacetSpec]  # Faceting configuration
    dynamic_facet_spec: SearchRequestDynamicFacetSpec  # Dynamic facet generation
    boost_spec: SearchRequestBoostSpec  # Result boosting configuration
    query_expansion_spec: SearchRequestQueryExpansionSpec  # Query expansion settings
    variant_rollup_keys: List[str]  # Keys for variant product rollup
    page_categories: List[str]  # Page context categories
    search_mode: SearchMode  # PRODUCT_SEARCH_ONLY or FACETED_SEARCH_ONLY
    personalization_spec: SearchRequestPersonalizationSpec  # Personalization settings
    labels: Dict[str, str]  # Custom labels for analytics
    spell_correction_spec: SearchRequestSpellCorrectionSpec  # Spell correction settings

class SearchResponse:
    results: List[SearchResponseSearchResult]  # Search results with products
    facets: List[SearchResponseFacet]  # Facet results for filtering
    total_size: int  # Total number of matching products
    corrected_query: str  # Spell-corrected version of query
    attribution_token: str  # Token for result attribution
    next_page_token: str  # Token for next page of results
    query_expansion_info: SearchResponseQueryExpansionInfo  # Query expansion details
    redirect_uri: str  # Redirect URL if applicable
    applied_controls: List[str]  # Applied business rules/controls
    invalid_condition_boost_specs: List[SearchRequestBoostSpecConditionBoostSpec]  # Invalid boost conditions
    experiment_info: List[ExperimentInfo]  # A/B test experiment information
    personalization_info: SearchResponsePersonalizationInfo  # Personalization details

class SearchResponseSearchResult:
    id: str  # Product ID
    product: Product  # Full product information
    matching_variant_count: int  # Number of matching variants
    matching_variant_fields: Dict[str, FieldMask]  # Matching variant field details
    variant_rollup_values: Dict[str, Value]  # Rolled-up variant values
    personal_labels: List[str]  # Personalized labels for this result

class FacetSpec:
    facet_key: FacetKeySpec  # Facet key configuration
    limit: int  # Maximum facet values to return
    excluded_filter_keys: List[str]  # Filter keys to exclude from facet counts
    enable_dynamic_position: bool  # Enable dynamic facet positioning
    
class FacetKeySpec:
    key: str  # Facet key (attribute name or predefined key)
    intervals: List[Interval]  # Numeric intervals for numeric facets
    restricted_values: List[str]  # Restrict facet to specific values
    prefixes: List[str]  # Prefix matching for text facets
    contains: List[str]  # Substring matching for text facets
    case_insensitive: bool  # Case-insensitive matching
    order_by: str  # Facet value ordering
    query: str  # Query for facet value filtering
    return_min_max: bool  # Return min/max values for numeric facets

class SearchResponseFacet:
    key: str  # Facet key
    values: List[SearchResponseFacetFacetValue]  # Facet values and counts
    dynamic_facet: bool  # Whether this is a dynamically generated facet

class SearchResponseFacetFacetValue:
    value: str  # Facet value
    count: int  # Number of products with this facet value
    interval: Interval  # Interval for numeric facets
    min_value: float  # Minimum value for numeric facets
    max_value: float  # Maximum value for numeric facets

class CompleteQueryRequest:
    catalog: str  # Catalog resource name (required)
    query: str  # Query prefix for completion (required)
    visitor_id: str  # Unique visitor identifier
    language_codes: List[str]  # Preferred completion languages
    device_type: str  # Device type (DESKTOP, MOBILE, TABLET)
    dataset: str  # Dataset for completion suggestions
    max_suggestions: int  # Maximum suggestions to return (default: 20)

class CompleteQueryResponse:
    completion_results: List[CompleteQueryResponseCompletionResult]  # Completion suggestions
    attribution_token: str  # Token for attribution
    recent_search_results: List[CompleteQueryResponseRecentSearchResult]  # Recent searches

class CompleteQueryResponseCompletionResult:
    suggestion: str  # Completion suggestion text
    attributes: Dict[str, CustomAttribute]  # Additional attributes

class CompleteQueryResponseRecentSearchResult:
    recent_search: str  # Recent search query

class UserInfo:
    user_id: str  # Persistent user identifier
    ip_address: str  # User IP address for geo-targeting
    user_agent: str  # User agent string
    direct_user_request: bool  # Whether request is directly from user

class SearchRequestPersonalizationSpec:
    mode: PersonalizationSpecMode  # AUTO, DISABLED
    
class SearchResponsePersonalizationInfo:
    personalization_mode: PersonalizationSpecMode  # Applied personalization mode
    user_id: str  # User ID used for personalization

class SearchRequestBoostSpec:
    condition_boost_specs: List[SearchRequestBoostSpecConditionBoostSpec]  # Conditional boosting
    skip_boost_spec_validation: bool  # Skip boost validation

class SearchRequestBoostSpecConditionBoostSpec:
    condition: str  # Boost condition expression
    boost: float  # Boost multiplier

class SearchRequestQueryExpansionSpec:
    condition: QueryExpansionSpecCondition  # AUTO, DISABLED
    pin_unexpanded_results: bool  # Pin original results

class SearchRequestSpellCorrectionSpec:
    mode: SpellCorrectionSpecMode  # AUTO, DISABLED

class SearchResponseQueryExpansionInfo:
    expanded_query: bool  # Whether query was expanded
    pinned_result_count: int  # Number of pinned unexpanded results

from google.cloud import retail

client = retail.SearchServiceClient()

# Basic search with query
request = retail.SearchRequest(
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
    query="gaming laptop",
    page_size=20,
    visitor_id="visitor-123"
)

response = client.search(request=request)

print(f"Found {response.total_size} products")
for result in response.results:
    product = result.product
    print(f"- {product.title} (${product.price_info.price})")

# Advanced search with filters, facets, and personalization
request = retail.SearchRequest(
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
    query="laptop",
    filter='(categories: ANY("Electronics", "Computers")) AND (price_info.price: [200, 2000])',
    facet_specs=[
        retail.SearchRequest.FacetSpec(
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
                key="brands"
            ),
            limit=10
        ),
        retail.SearchRequest.FacetSpec(
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
                key="price_info.price",
                intervals=[
                    retail.Interval(minimum=0, maximum=500),
                    retail.Interval(minimum=500, maximum=1000),
                    retail.Interval(minimum=1000, maximum=2000),
                    retail.Interval(minimum=2000)
                ]
            )
        ),
        retail.SearchRequest.FacetSpec(
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
                key="attributes.screen_size"
            ),
            limit=5
        )
    ],
    order_by="price_info.price desc",
    visitor_id="visitor-123",
    user_info=retail.UserInfo(
        user_id="user-456",
        ip_address="192.168.1.100"
    )
)

response = client.search(request=request)

print(f"Search Results: {len(response.results)} of {response.total_size}")
print(f"Corrected query: {response.corrected_query}")

# Display products
for result in response.results:
    product = result.product
    print(f"- {product.title}")
    print(f"  Price: ${product.price_info.price}")
    print(f"  Brand: {', '.join(product.brands)}")
    print(f"  Categories: {', '.join(product.categories)}")

# Display facets
print("\nFacets:")
for facet in response.facets:
    print(f"\n{facet.key}:")
    for value in facet.values[:5]:  # Show top 5 values
        print(f"  {value.value} ({value.count})")

# Search with conditional boosting for promoted products
boost_spec = retail.SearchRequest.BoostSpec(
    condition_boost_specs=[
        retail.SearchRequest.BoostSpec.ConditionBoostSpec(
            condition='(tags: ANY("promoted"))',
            boost=2.0  # Double the relevance score
        ),
        retail.SearchRequest.BoostSpec.ConditionBoostSpec(
            condition='(brands: ANY("TechBrand"))',
            boost=1.5  # 1.5x boost for preferred brand
        )
    ]
)

request = retail.SearchRequest(
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
    query="laptop",
    boost_spec=boost_spec,
    visitor_id="visitor-123"
)

response = client.search(request=request)

completion_client = retail.CompletionServiceClient()

# Get query suggestions
request = retail.CompleteQueryRequest(
    catalog="projects/my-project/locations/global/catalogs/default_catalog",
    query="gam",  # User has typed "gam"
    max_suggestions=10,
    visitor_id="visitor-123"
)

response = completion_client.complete_query(request=request)

print("Completion suggestions:")
for result in response.completion_results:
    print(f"- {result.suggestion}")

print("\nRecent searches:")
for recent in response.recent_search_results:
    print(f"- {recent.recent_search}")

# Search with enhanced personalization
personalization_spec = retail.SearchRequest.PersonalizationSpec(
    mode=retail.SearchRequest.PersonalizationSpec.Mode.AUTO
)

request = retail.SearchRequest(
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
    query="laptop",
    visitor_id="visitor-123",
    user_info=retail.UserInfo(
        user_id="user-456",
        ip_address="192.168.1.100",
        user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    ),
    personalization_spec=personalization_spec
)

response = client.search(request=request)

# Check personalization details
if response.personalization_info:
    print(f"Personalization mode: {response.personalization_info.personalization_mode}")
    print(f"User ID: {response.personalization_info.user_id}")