CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-google-cloud-retail

Python client library for Google Cloud Retail API enabling end-to-end personalized recommendation systems

—

Pending
Overview
Eval results
Files

advanced-features.mddocs/

Advanced Features

Enhanced capabilities including business rules, serving configurations, and generative AI features. These advanced services provide sophisticated control over search and recommendation behavior, business logic implementation, and cutting-edge AI-powered features.

Capabilities

Business Rules and Controls

Management of business rules and control mechanisms that influence search and recommendation behavior.

class ControlServiceClient:
    def create_control(self, request: CreateControlRequest) -> Control:
        """
        Creates a new control for applying business rules.
        
        Args:
            request: Contains parent catalog and control configuration
            
        Returns:
            Control: The created control with generated metadata
        """

    def get_control(self, request: GetControlRequest) -> Control:
        """
        Retrieves a control by its resource name.
        
        Args:
            request: Contains control resource name
            
        Returns:
            Control: The requested control configuration
        """

    def list_controls(self, request: ListControlsRequest) -> ListControlsResponse:
        """
        Lists all controls in a catalog with pagination support.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListControlsResponse: List of controls with pagination
        """

    def update_control(self, request: UpdateControlRequest) -> Control:
        """
        Updates an existing control configuration.
        
        Args:
            request: Contains control updates and field mask
            
        Returns:
            Control: Updated control configuration
        """

    def delete_control(self, request: DeleteControlRequest) -> None:
        """
        Deletes a control and removes it from all serving configurations.
        
        Args:
            request: Contains control resource name
        """
class ControlServiceAsyncClient:
    async def create_control(self, request: CreateControlRequest) -> Control:
        """
        Creates a new control for applying business rules.
        
        Args:
            request: Contains parent catalog and control configuration
            
        Returns:
            Control: The created control with generated metadata
        """

    async def get_control(self, request: GetControlRequest) -> Control:
        """
        Retrieves a control by its resource name.
        
        Args:
            request: Contains control resource name
            
        Returns:
            Control: The requested control configuration
        """

    async def list_controls(self, request: ListControlsRequest) -> ListControlsResponse:
        """
        Lists all controls in a catalog with pagination support.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListControlsResponse: List of controls with pagination
        """

    async def update_control(self, request: UpdateControlRequest) -> Control:
        """
        Updates an existing control configuration.
        
        Args:
            request: Contains control updates and field mask
            
        Returns:
            Control: Updated control configuration
        """

    async def delete_control(self, request: DeleteControlRequest) -> None:
        """
        Deletes a control and removes it from all serving configurations.
        
        Args:
            request: Contains control resource name
        """

Serving Configuration Management

Management of serving configurations that control how search and recommendations are delivered.

class ServingConfigServiceClient:
    def create_serving_config(self, request: CreateServingConfigRequest) -> ServingConfig:
        """
        Creates a new serving configuration for search or recommendations.
        
        Args:
            request: Contains parent catalog and serving config settings
            
        Returns:
            ServingConfig: The created serving configuration
        """

    def get_serving_config(self, request: GetServingConfigRequest) -> ServingConfig:
        """
        Retrieves a serving configuration by its resource name.
        
        Args:
            request: Contains serving config resource name
            
        Returns:
            ServingConfig: The requested serving configuration
        """

    def list_serving_configs(self, request: ListServingConfigsRequest) -> ListServingConfigsResponse:
        """
        Lists all serving configurations in a catalog.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListServingConfigsResponse: List of serving configurations
        """

    def update_serving_config(self, request: UpdateServingConfigRequest) -> ServingConfig:
        """
        Updates an existing serving configuration.
        
        Args:
            request: Contains serving config updates and field mask
            
        Returns:
            ServingConfig: Updated serving configuration
        """

    def delete_serving_config(self, request: DeleteServingConfigRequest) -> None:
        """
        Deletes a serving configuration.
        
        Args:
            request: Contains serving config resource name
        """

    def add_control(self, request: AddControlRequest) -> ServingConfig:
        """
        Associates a control with a serving configuration.
        
        Args:
            request: Contains serving config and control resource names
            
        Returns:
            ServingConfig: Updated serving configuration with new control
        """

    def remove_control(self, request: RemoveControlRequest) -> ServingConfig:
        """
        Removes a control from a serving configuration.
        
        Args:
            request: Contains serving config and control resource names
            
        Returns:
            ServingConfig: Updated serving configuration without the control
        """
class ServingConfigServiceAsyncClient:
    async def create_serving_config(self, request: CreateServingConfigRequest) -> ServingConfig:
        """
        Creates a new serving configuration for search or recommendations.
        
        Args:
            request: Contains parent catalog and serving config settings
            
        Returns:
            ServingConfig: The created serving configuration
        """

    async def get_serving_config(self, request: GetServingConfigRequest) -> ServingConfig:
        """
        Retrieves a serving configuration by its resource name.
        
        Args:
            request: Contains serving config resource name
            
        Returns:
            ServingConfig: The requested serving configuration
        """

    async def list_serving_configs(self, request: ListServingConfigsRequest) -> ListServingConfigsResponse:
        """
        Lists all serving configurations in a catalog.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListServingConfigsResponse: List of serving configurations
        """

    async def update_serving_config(self, request: UpdateServingConfigRequest) -> ServingConfig:
        """
        Updates an existing serving configuration.
        
        Args:
            request: Contains serving config updates and field mask
            
        Returns:
            ServingConfig: Updated serving configuration
        """

    async def delete_serving_config(self, request: DeleteServingConfigRequest) -> None:
        """
        Deletes a serving configuration.
        
        Args:
            request: Contains serving config resource name
        """

    async def add_control(self, request: AddControlRequest) -> ServingConfig:
        """
        Associates a control with a serving configuration.
        
        Args:
            request: Contains serving config and control resource names
            
        Returns:
            ServingConfig: Updated serving configuration with new control
        """

    async def remove_control(self, request: RemoveControlRequest) -> ServingConfig:
        """
        Removes a control from a serving configuration.
        
        Args:
            request: Contains serving config and control resource names
            
        Returns:
            ServingConfig: Updated serving configuration without the control
        """

Generative AI Features

Advanced AI-powered features including generative questions and conversational search capabilities.

class GenerativeQuestionServiceClient:
    def get_generative_questions_feature_config(self, request: GetGenerativeQuestionsFeatureConfigRequest) -> GenerativeQuestionsFeatureConfig:
        """
        Gets the configuration for generative questions feature.
        
        Args:
            request: Contains catalog resource name
            
        Returns:
            GenerativeQuestionsFeatureConfig: Current feature configuration
        """

    def update_generative_questions_feature_config(self, request: UpdateGenerativeQuestionsFeatureConfigRequest) -> GenerativeQuestionsFeatureConfig:
        """
        Updates the generative questions feature configuration.
        
        Args:
            request: Contains config updates and field mask
            
        Returns:
            GenerativeQuestionsFeatureConfig: Updated feature configuration
        """

    def list_generative_question_configs(self, request: ListGenerativeQuestionConfigsRequest) -> ListGenerativeQuestionConfigsResponse:
        """
        Lists generative question configurations for a catalog.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListGenerativeQuestionConfigsResponse: List of question configurations
        """

    def update_generative_question_config(self, request: UpdateGenerativeQuestionConfigRequest) -> GenerativeQuestionConfig:
        """
        Updates a specific generative question configuration.
        
        Args:
            request: Contains question config updates and field mask
            
        Returns:
            GenerativeQuestionConfig: Updated question configuration
        """

    def batch_update_generative_question_configs(self, request: BatchUpdateGenerativeQuestionConfigsRequest) -> BatchUpdateGenerativeQuestionConfigsResponse:
        """
        Updates multiple generative question configurations in batch.
        
        Args:
            request: Contains multiple question config updates
            
        Returns:
            BatchUpdateGenerativeQuestionConfigsResponse: Results of batch update
        """
class GenerativeQuestionServiceAsyncClient:
    async def get_generative_questions_feature_config(self, request: GetGenerativeQuestionsFeatureConfigRequest) -> GenerativeQuestionsFeatureConfig:
        """
        Gets the configuration for generative questions feature.
        
        Args:
            request: Contains catalog resource name
            
        Returns:
            GenerativeQuestionsFeatureConfig: Current feature configuration
        """

    async def update_generative_questions_feature_config(self, request: UpdateGenerativeQuestionsFeatureConfigRequest) -> GenerativeQuestionsFeatureConfig:
        """
        Updates the generative questions feature configuration.
        
        Args:
            request: Contains config updates and field mask
            
        Returns:
            GenerativeQuestionsFeatureConfig: Updated feature configuration
        """

    async def list_generative_question_configs(self, request: ListGenerativeQuestionConfigsRequest) -> ListGenerativeQuestionConfigsResponse:
        """
        Lists generative question configurations for a catalog.
        
        Args:
            request: Contains parent catalog and pagination parameters
            
        Returns:
            ListGenerativeQuestionConfigsResponse: List of question configurations
        """

    async def update_generative_question_config(self, request: UpdateGenerativeQuestionConfigRequest) -> GenerativeQuestionConfig:
        """
        Updates a specific generative question configuration.
        
        Args:
            request: Contains question config updates and field mask
            
        Returns:
            GenerativeQuestionConfig: Updated question configuration
        """

    async def batch_update_generative_question_configs(self, request: BatchUpdateGenerativeQuestionConfigsRequest) -> BatchUpdateGenerativeQuestionConfigsResponse:
        """
        Updates multiple generative question configurations in batch.
        
        Args:
            request: Contains multiple question config updates
            
        Returns:
            BatchUpdateGenerativeQuestionConfigsResponse: Results of batch update
        """

Data Types

Control Configuration

Business rules and control mechanisms for search and recommendation behavior.

class Control:
    name: str  # Control resource name (read-only)
    display_name: str  # Human-readable control name
    associated_serving_config_ids: List[str]  # Serving configs using this control (read-only)
    solution_types: List[SolutionType]  # Applicable solution types
    search_solution_use_case: List[SearchSolutionUseCase]  # Search use cases
    
    # Control rule specifications (one of the following)
    facet_spec: SearchRequestFacetSpec  # Faceting control
    rule: Rule  # Business rule control

class Rule:
    boost_action: RuleBoostAction  # Boost certain products
    redirect_action: RuleRedirectAction  # Redirect user to specific URL
    oneway_synonyms_action: RuleOnewaySynonymsAction  # Add one-way synonyms
    do_not_associate_action: RuleDoNotAssociateAction  # Prevent associations
    replacement_action: RuleReplacementAction  # Replace query terms
    ignore_action: RuleIgnoreAction  # Ignore certain terms
    filter_action: RuleFilterAction  # Apply additional filtering
    twoway_synonyms_action: RuleTwowaySynonymsAction  # Add bidirectional synonyms
    force_return_facet_action: RuleForceReturnFacetAction  # Force facet return
    remove_facet_action: RuleRemoveFacetAction  # Remove facets
    
    condition: Condition  # When to apply this rule

class Condition:
    query_terms: List[ConditionQueryTerm]  # Query-based conditions
    active_time_range: List[ConditionTimeRange]  # Time-based conditions
    page_categories: List[str]  # Page category conditions

# Control rule actions
class RuleBoostAction:
    boost: float  # Boost multiplier
    products_filter: str  # Filter for products to boost

class RuleRedirectAction:
    redirect_uri: str  # URL to redirect to

class RuleFilterAction:
    filter: str  # Additional filter to apply

class RuleOnewaySynonymsAction:
    query_terms: List[str]  # Query terms
    synonyms: List[str]  # One-way synonyms for the terms
    
class RuleTwowaySynonymsAction:
    synonyms: List[str]  # Bidirectional synonyms

Serving Configuration

Configuration for how search and recommendations are served to users.

class ServingConfig:
    name: str  # Serving config resource name (read-only)
    display_name: str  # Human-readable name
    model_id: str  # Associated model ID for recommendations
    price_reranking_level: str  # Price reranking level (NO_PRICE_RERANKING, LOW, MEDIUM, HIGH)
    facet_control_ids: List[str]  # Applied facet control IDs
    dynamic_facet_spec: SearchRequestDynamicFacetSpec  # Dynamic faceting configuration
    boost_control_ids: List[str]  # Applied boost control IDs
    filter_control_ids: List[str]  # Applied filter control IDs
    redirect_control_ids: List[str]  # Applied redirect control IDs
    twoway_synonyms_control_ids: List[str]  # Applied synonym control IDs
    oneway_synonyms_control_ids: List[str]  # Applied one-way synonym control IDs
    do_not_associate_control_ids: List[str]  # Applied dissociation control IDs
    replacement_control_ids: List[str]  # Applied replacement control IDs
    ignore_control_ids: List[str]  # Applied ignore control IDs
    diversity_level: str  # Result diversity level
    diversity_type: str  # Type of diversity to apply
    enable_category_filter_level: str  # Category filtering level
    personalization_spec: SearchRequestPersonalizationSpec  # Personalization settings
    solution_types: List[SolutionType]  # Applicable solution types

Generative AI Configuration

Settings for AI-powered generative features and question generation.

class GenerativeQuestionsFeatureConfig:
    catalog: str  # Catalog resource name (read-only)
    feature_enabled: bool  # Whether generative questions are enabled
    minimum_products: int  # Minimum products required for question generation
    
class GenerativeQuestionConfig:
    catalog: str  # Catalog resource name (read-only)
    facet: str  # Facet for which questions are generated
    generated_question: str  # AI-generated question text
    final_question: str  # Final question after human review
    example_values: List[str]  # Example values for the question
    frequency: float  # Question frequency/importance score
    allowed_in_conversation: bool  # Whether question can be used in conversation

Request Types

Request configurations for advanced feature management operations.

class CreateControlRequest:
    parent: str  # Catalog resource name (required)
    control: Control  # Control configuration (required)
    control_id: str  # Control ID (required)

class GetControlRequest:
    name: str  # Control resource name (required)

class ListControlsRequest:
    parent: str  # Catalog resource name (required)
    page_size: int  # Maximum controls to return
    page_token: str  # Token for pagination
    filter: str  # Filter expression

class UpdateControlRequest:
    control: Control  # Control with updates (required)
    update_mask: FieldMask  # Fields to update

class DeleteControlRequest:
    name: str  # Control resource name (required)

class CreateServingConfigRequest:
    parent: str  # Catalog resource name (required)
    serving_config: ServingConfig  # Serving config (required)
    serving_config_id: str  # Serving config ID (required)

class AddControlRequest:
    serving_config: str  # Serving config resource name (required)
    control_id: str  # Control ID to add (required)

class RemoveControlRequest:
    serving_config: str  # Serving config resource name (required)
    control_id: str  # Control ID to remove (required)

class UpdateGenerativeQuestionConfigRequest:
    generative_question_config: GenerativeQuestionConfig  # Config with updates (required)
    update_mask: FieldMask  # Fields to update

class BatchUpdateGenerativeQuestionConfigsRequest:
    parent: str  # Catalog resource name (required)
    requests: List[UpdateGenerativeQuestionConfigRequest]  # Batch of updates

Usage Examples

Creating Business Rules with Controls

from google.cloud import retail

control_client = retail.ControlServiceClient()

# Create a boost control to promote featured products
boost_rule = retail.Rule(
    boost_action=retail.Rule.BoostAction(
        boost=2.0,  # Double the relevance score
        products_filter='(tags: ANY("featured"))'
    ),
    condition=retail.Condition(
        query_terms=[
            retail.Condition.QueryTerm(
                value="laptop",
                full_match=False
            )
        ]
    )
)

boost_control = retail.Control(
    display_name="Featured Laptop Boost",
    rule=boost_rule,
    solution_types=[retail.SolutionType.SOLUTION_TYPE_SEARCH]
)

request = retail.CreateControlRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    control=boost_control,
    control_id="featured-laptop-boost"
)

created_control = control_client.create_control(request=request)
print(f"Created boost control: {created_control.name}")

# Create a filter control to exclude out-of-stock items
filter_rule = retail.Rule(
    filter_action=retail.Rule.FilterAction(
        filter='(availability: "IN_STOCK")'
    ),
    condition=retail.Condition()  # Apply to all queries
)

filter_control = retail.Control(
    display_name="Hide Out of Stock",
    rule=filter_rule,
    solution_types=[
        retail.SolutionType.SOLUTION_TYPE_SEARCH,
        retail.SolutionType.SOLUTION_TYPE_RECOMMENDATION
    ]
)

request = retail.CreateControlRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog", 
    control=filter_control,
    control_id="hide-out-of-stock"
)

filter_control = control_client.create_control(request=request)
print(f"Created filter control: {filter_control.name}")

Creating Serving Configurations

serving_client = retail.ServingConfigServiceClient()

# Create a serving configuration for product search
search_serving_config = retail.ServingConfig(
    display_name="Product Search Configuration",
    price_reranking_level="MEDIUM",
    diversity_level="MEDIUM",
    diversity_type="RULE_BASED_DIVERSITY",
    enable_category_filter_level="DISABLED",
    personalization_spec=retail.SearchRequest.PersonalizationSpec(
        mode=retail.SearchRequest.PersonalizationSpec.Mode.AUTO
    ),
    solution_types=[retail.SolutionType.SOLUTION_TYPE_SEARCH]
)

request = retail.CreateServingConfigRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    serving_config=search_serving_config,
    serving_config_id="product-search-config"
)

created_config = serving_client.create_serving_config(request=request)
print(f"Created serving config: {created_config.name}")

# Add controls to the serving configuration
add_boost_request = retail.AddControlRequest(
    serving_config=created_config.name,
    control_id="featured-laptop-boost"
)

updated_config = serving_client.add_control(request=add_boost_request)

add_filter_request = retail.AddControlRequest(
    serving_config=updated_config.name,
    control_id="hide-out-of-stock"
)

final_config = serving_client.add_control(request=add_filter_request)
print(f"Added controls to serving config")
print(f"Boost controls: {final_config.boost_control_ids}")
print(f"Filter controls: {final_config.filter_control_ids}")

Advanced Control Rules

# Create a synonym control for better search matching
synonym_rule = retail.Rule(
    twoway_synonyms_action=retail.Rule.TwowaySynonymsAction(
        synonyms=["laptop", "notebook", "portable computer"]
    ),
    condition=retail.Condition()  # Apply to all queries
)

synonym_control = retail.Control(
    display_name="Laptop Synonyms",
    rule=synonym_rule,
    solution_types=[retail.SolutionType.SOLUTION_TYPE_SEARCH]
)

request = retail.CreateControlRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    control=synonym_control,
    control_id="laptop-synonyms"
)

synonym_control = control_client.create_control(request=request)

# Create a redirect control for brand searches
redirect_rule = retail.Rule(
    redirect_action=retail.Rule.RedirectAction(
        redirect_uri="https://example.com/brands/apple"
    ),
    condition=retail.Condition(
        query_terms=[
            retail.Condition.QueryTerm(
                value="apple",
                full_match=True
            )
        ]
    )
)

redirect_control = retail.Control(
    display_name="Apple Brand Redirect",
    rule=redirect_rule,
    solution_types=[retail.SolutionType.SOLUTION_TYPE_SEARCH]
)

request = retail.CreateControlRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    control=redirect_control,
    control_id="apple-redirect"
)

redirect_control = control_client.create_control(request=request)
print("Created synonym and redirect controls")

Time-Based Control Rules

# Create a seasonal promotion control
from google.protobuf.timestamp_pb2 import Timestamp
import datetime

# Define holiday promotion period
start_time = Timestamp()
start_time.FromDatetime(datetime.datetime(2024, 11, 20))  # Black Friday season
end_time = Timestamp()
end_time.FromDatetime(datetime.datetime(2024, 12, 31))    # End of year

holiday_boost_rule = retail.Rule(
    boost_action=retail.Rule.BoostAction(
        boost=1.5,
        products_filter='(tags: ANY("holiday_sale"))'
    ),
    condition=retail.Condition(
        active_time_range=[
            retail.Condition.TimeRange(
                start_time=start_time,
                end_time=end_time
            )
        ]
    )
)

holiday_control = retail.Control(
    display_name="Holiday Sale Boost",
    rule=holiday_boost_rule,
    solution_types=[retail.SolutionType.SOLUTION_TYPE_SEARCH]
)

request = retail.CreateControlRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    control=holiday_control,
    control_id="holiday-boost"
)

holiday_control = control_client.create_control(request=request)
print("Created time-based holiday promotion control")

Generative AI Question Configuration

question_client = retail.GenerativeQuestionServiceClient()

# Get current generative questions feature configuration
request = retail.GetGenerativeQuestionsFeatureConfigRequest(
    catalog="projects/my-project/locations/global/catalogs/default_catalog"
)

feature_config = question_client.get_generative_questions_feature_config(request=request)
print(f"Generative questions enabled: {feature_config.feature_enabled}")
print(f"Minimum products required: {feature_config.minimum_products}")

# Enable generative questions feature
if not feature_config.feature_enabled:
    updated_config = retail.GenerativeQuestionsFeatureConfig(
        catalog=feature_config.catalog,
        feature_enabled=True,
        minimum_products=10  # Require at least 10 products for question generation
    )

    request = retail.UpdateGenerativeQuestionsFeatureConfigRequest(
        generative_questions_feature_config=updated_config,
        update_mask=field_mask_pb2.FieldMask(paths=["feature_enabled", "minimum_products"])
    )

    updated = question_client.update_generative_questions_feature_config(request=request)
    print("Enabled generative questions feature")

# List existing generative question configurations
request = retail.ListGenerativeQuestionConfigsRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog"
)

response = question_client.list_generative_question_configs(request=request)

print("Existing generative question configurations:")
for config in response.generative_question_configs:
    print(f"- Facet: {config.facet}")
    print(f"  Generated question: {config.generated_question}")
    print(f"  Final question: {config.final_question}")
    print(f"  Frequency: {config.frequency}")
    print(f"  Allowed in conversation: {config.allowed_in_conversation}")

Managing Control Lifecycle

# List all controls to see what's available
request = retail.ListControlsRequest(
    parent="projects/my-project/locations/global/catalogs/default_catalog",
    page_size=50
)

response = control_client.list_controls(request=request)

print("Available controls:")
for control in response.controls:
    print(f"- {control.display_name} ({control.name})")
    print(f"  Solution types: {control.solution_types}")
    print(f"  Associated serving configs: {len(control.associated_serving_config_ids)}")

# Update an existing control
existing_control = response.controls[0]  # Get first control
existing_control.display_name = f"{existing_control.display_name} (Updated)"

request = retail.UpdateControlRequest(
    control=existing_control,
    update_mask=field_mask_pb2.FieldMask(paths=["display_name"])
)

updated_control = control_client.update_control(request=request)
print(f"Updated control display name: {updated_control.display_name}")

# Remove a control from serving configuration (if needed)
serving_configs = serving_client.list_serving_configs(
    request=retail.ListServingConfigsRequest(
        parent="projects/my-project/locations/global/catalogs/default_catalog"
    )
)

if serving_configs.serving_configs:
    serving_config = serving_configs.serving_configs[0]
    if serving_config.boost_control_ids:
        remove_request = retail.RemoveControlRequest(
            serving_config=serving_config.name,
            control_id=serving_config.boost_control_ids[0]
        )
        
        updated_serving = serving_client.remove_control(request=remove_request)
        print(f"Removed control from serving config")

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-retail

docs

advanced-features.md

ai-recommendations.md

analytics-export.md

catalog-config.md

index.md

product-management.md

search-discovery.md

user-events.md

tile.json