Google Cloud Recommendations AI Client Library

Warnings

• gotcha Recommendations AI offers several clients (`RecommendationsAiClient`, `CatalogServiceClient`, `UserEventServiceClient`, `PredictionServiceClient`). Use the appropriate client for your specific operation (e.g., `CatalogServiceClient` for managing items, `PredictionServiceClient` for recommendations). `RecommendationsAiClient` often acts as an orchestrator but direct access to specific service clients is common.
  Fix: Consult the official documentation for the specific API method you intend to use to determine which client object provides it. For basic catalog/event management, use `CatalogServiceClient` or `UserEventServiceClient`.
• breaking Google Cloud Python client libraries are progressively dropping support for older Python versions. While version `0.13.0` currently supports Python 3.9, future minor or major releases will likely drop support for Python 3.9 (and potentially 3.10) in alignment with Python's EOL schedule, potentially causing compatibility issues for older environments.
  Fix: Ensure your development and deployment environments use Python 3.11 or newer to maintain compatibility with future updates. Regularly check the `requires_python` field on PyPI for the latest supported versions.
• gotcha Google Cloud APIs use strict resource name formats (e.g., `projects/{project}/locations/{location}/catalogs/{catalog}`). Incorrectly formatted resource names are a common source of `InvalidArgument` or `NotFound` errors.
  Fix: Always construct resource names carefully following the pattern specified in the API documentation for each method. Use f-strings for clarity, e.g., `parent = f"projects/{project_id}/locations/{location_id}/catalogs/default_catalog"`.
• gotcha The library provides both synchronous and asynchronous client versions (e.g., `CatalogServiceClient` and `AsyncCatalogServiceClient`). Using the incorrect client in an asynchronous context (e.g., calling synchronous methods with `await`) will lead to `TypeError` or unexpected behavior.
  Fix: If working with `asyncio`, ensure you import and use the `Async*Client` variants (e.g., `from google.cloud.recommendations_ai_v1beta1.services.catalog_service.async_client import AsyncCatalogServiceClient`).
• gotcha Many `list` or `get` operations for Recommendations AI will return empty results or `NotFound` errors if the underlying catalog, user events, or models have not been properly populated and ingested through the API or console.
  Fix: Verify that your Recommendations AI instance has the necessary data (catalog items, user events) and potentially trained models if you are using prediction functionality. Consult the Recommendations AI setup guide for ingestion steps.

Install

• pip install google-cloud-recommendations-ai Install stable version

Imports

• RecommendationsAiClient

  from google.cloud.recommendations_ai_v1beta1 import RecommendationsAiClient

  Clients are typically nested under their API version module (e.g., `_v1beta1`).
• CatalogServiceClient

  from google.cloud.recommendations_ai_v1beta1 import CatalogServiceClient

  Specific service clients like CatalogServiceClient are available for granular control over resources.

Quickstart

This quickstart demonstrates how to instantiate the `CatalogServiceClient` and list existing catalog items. Replace 'your-gcp-project-id' and 'global' with your actual Google Cloud project ID and the relevant location, or set them via environment variables. This requires the Recommendations AI API to be enabled and your service account to have appropriate permissions (e.g., `Recommendations AI Admin`).

import os
from google.cloud.recommendations_ai_v1beta1 import CatalogServiceClient

project_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')
location_id = os.environ.get('GCP_LOCATION_ID', 'global') # Recommendations AI often uses 'global'

def list_first_five_catalog_items():
    """Lists the first five catalog items in the default catalog."""
    client = CatalogServiceClient()
    # The parent for listing catalog items is a catalog resource.
    # 'default_catalog' is the common default for Recommendations AI.
    parent = f"projects/{project_id}/locations/{location_id}/catalogs/default_catalog"

    request = {
        "parent": parent,
        "page_size": 5
    }

    print(f"Listing catalog items for parent: {parent}")
    try:
        page_iterator = client.list_catalog_items(request=request)

        found_items = False
        for item in page_iterator:
            print(f"Catalog Item ID: {item.id}, Title: {item.title}")
            found_items = True
        
        if not found_items:
            print("No catalog items found. Ensure your catalog is populated.")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Make sure 'GCP_PROJECT_ID' and 'GCP_LOCATION_ID' environment variables are set or replaced.")
        print("Also, ensure the Recommendations AI API is enabled and your service account has permissions.")

if __name__ == '__main__':
    list_first_five_catalog_items()