Registry /
gcp / google-cloud-recommendations-ai
Install & Compatibility
Where this runs
tested against v0.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RecommendationsAI
✓ from google.cloud import recommendationsai
✗ from google.cloud import recommendations_ai
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()
Debug
Known issues
gotchaRecommendations 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.fixConsult 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`.
affects: All versions
breakingGoogle 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.fixEnsure 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.
affects: Future releases (likely >0.13.0 or 1.x.x)
gotchaGoogle 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.fixAlways 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"`. affects: All versions
gotchaThe 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.fixIf 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`).
affects: All versions
gotchaMany `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.fixVerify 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.
affects: All versions
Upgrade
Version history
0.13.0latest on PyPI · released Mar 26, 2026
Audit
Dependencies
google-api-corerequiredCore library for Google Cloud API clients, handling authentication, retries, and API calls.
google-authrequiredProvides authentication credentials for accessing Google Cloud services.
proto-plusrequiredProvides Pythonic wrappers around Protocol Buffer messages.